Google Maps

Google Maps: place search, place details, and place reviews. All endpoints are read-only GET requests and return public Google Maps data.

Base URL: https://api.pullbay.com/

Endpoints

Endpoint	Description	Pagination
GET /google-maps/place/search	Search Google Maps places by free-text query	Offset / maxItems
GET /google-maps/place/{fid}	Get full details for a place by FID	—
GET /google-maps/place/reviews	Get reviews for a place by Google Maps URL	Cursor / maxItems

---

Search Places

Search Google Maps for places by free-text query. Optional geo filters (latitude, longitude, zoom) bias results toward a specific map viewport.

Request

GET /google-maps/place/search
Authorization: Bearer YOUR_API_KEY

Parameters

Parameter	Type	Required	Description
query	string	Yes	Free-text search term, 1–200 characters (e.g. pizza near soho new york)
countryCode	string	No	2–5 character country code to bias results
languageCode	string	No	2–10 character language code for localized text
latitude	string	No	Latitude to center the search viewport (numeric string)
longitude	string	No	Longitude to center the search viewport (numeric string)
zoom	string	No	Map zoom level to use alongside latitude/longitude (numeric string)
offset	string	No	Numeric offset string to paginate results. Mutually exclusive with maxItems
maxItems	integer	No	One-shot bulk pull, 1–500 results. Mutually exclusive with offset

Example

curl -G "https://api.pullbay.com/google-maps/place/search" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d query="pizza near soho new york" \
  -d countryCode=us \
  -d offset=0

Response

{
  "status": 200,
  "message": "OK",
  "success": true,
  "data": [
    {
      "url": "https://www.google.com/maps/place/data=!3m1!4b1!4m2!3m1!1s0x89c25985f7ec1beb:0x3c39f655da433d9d",
      "title": "Prince Street Pizza",
      "description": null,
      "address": "27 Prince St, New York, NY 10012",
      "neighborhood": "Manhattan",
      "street": "27 Prince St",
      "district": "New York",
      "postalCode": "10012",
      "city": "New York",
      "country": "United States",
      "location": { "lat": 40.7230777, "lng": -73.9945444 },
      "website": "https://locations.princestreetpizza.com/new-york",
      "phone": "[phone]",
      "price": "$10–20",
      "totalScore": 4.4,
      "placeId": "ChIJ6xvs94VZwokRnT1D2lX2OTw",
      "fid": "0x89c25985f7ec1beb:0x3c39f655da433d9d",
      "reviewsCount": 9039,
      "categories": ["Pizza restaurant"],
      "openingHours": [],
      "additionalInfo": {}
    }
  ],
  "pagination": { "page": 1, "hasNextPage": null, "cursor": null, "offset": null },
  "pricing": { "creditsCharged": 1 }
}

Credit cost: dynamic, returned in pricing.creditsCharged. Using maxItems to pull more results in one call costs proportionally more than a single page.

---

Get Place

Returns full details for a Google Maps place identified by its FID.

Request

GET /google-maps/place/{fid}
Authorization: Bearer YOUR_API_KEY

Parameters

Parameter	Type	Required	Description
fid	string	Yes	Google Maps feature ID, of the form 0x...:0x... (e.g. 0x47e671d877937b0f:0xb975fcfa192f84d4) — path parameter
countryCode	string	No	2–5 character country code
languageCode	string	No	2–10 character language code for localized text

Example

curl -G "https://api.pullbay.com/google-maps/place/0x47e671d877937b0f:0xb975fcfa192f84d4" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d languageCode=en

Response

{
  "status": 200,
  "message": "OK",
  "success": true,
  "data": [
    {
      "url": "https://www.google.com/maps/preview/place/Louvre+Museum",
      "title": "Louvre Museum",
      "address": "Louvre Museum, 75001 Paris, France",
      "neighborhood": null,
      "street": null,
      "district": "Paris",
      "postalCode": "75001",
      "city": null,
      "location": { "lat": 40.7230777, "lng": -73.9945444 },
      "website": "https://www.louvre.fr/",
      "phone": "[phone]",
      "phoneUnformatted": "[phone]",
      "plusCode": "V86Q+63 Paris, France",
      "price": null,
      "totalScore": 4.7,
      "placeId": "ChIJD3uTd9hx5kcR1IQvGfr8dbk",
      "cid": "-5082878453323168556",
      "fid": "0x47e671d877937b0f:0xb975fcfa192f84d4",
      "reviewsCount": 366153,
      "reviewsDistribution": {
        "oneStar": 5180,
        "twoStar": 3447,
        "threeStar": 13286,
        "fourStar": 52471,
        "fiveStar": 291769
      },
      "categories": ["Art museum", "Museum", "Tourist attraction"],
      "additionalInfo": {}
    }
  ],
  "pricing": { "creditsCharged": 1 }
}

Credit cost: dynamic, returned in pricing.creditsCharged.

---

Get Place Reviews

Returns reviews for a place identified by its full Google Maps URL.

Request

GET /google-maps/place/reviews
Authorization: Bearer YOUR_API_KEY

Parameters

Parameter	Type	Required	Description
placeUrl	string	Yes	Full Google Maps place URL, 10–1000 characters
maxItems	integer	No	One-shot bulk pull, 1–500 results. Mutually exclusive with cursor
cursor	string	No	Opaque pagination cursor. Mutually exclusive with maxItems

Example

curl -G "https://api.pullbay.com/google-maps/place/reviews" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d placeUrl="https://www.google.com/maps/place/data=!3m1!4b1!4m2!3m1!1s0x89c25985f7ec1beb:0x3c39f655da433d9d" \
  -d maxItems=20

Response

{
  "status": 200,
  "message": "OK",
  "success": true,
  "data": [
    {
      "id": "Ci9DQUlRQUNvZENodHljRjlvT25OdmExZHZVSEJPYjJkRGIxVXpiRFIzYXpWUmFFRRAB",
      "link": "https://www.google.com/maps/reviews/data=!4m8!14m7!1m6!2m5!1sCi9DQUlRQUNvZENodHljRjlvT25OdmExZHZVSEJPYjJkRGIxVXpiRFIzYXpWUmFFRRAB",
      "text": "Loved the experience",
      "stars": 5,
      "date": 1777380220000,
      "dateIso": "2026-04-28T12:43:40.000Z",
      "likes": null,
      "photos": [],
      "reviewer": {
        "name": "Jane Doe",
        "photo": "https://example.com/reviewer-photo.jpg",
        "url": "https://www.google.com/maps/contrib/000000000000000000000?hl=en-US",
        "totalReviews": 2,
        "totalPhotos": 7
      },
      "ownersResponse": {},
      "details": {
        "Visited on": "Weekend",
        "Wait time": "10–30 min",
        "Reservation recommended": true
      }
    }
  ],
  "pagination": { "page": null, "hasNextPage": null, "cursor": null, "offset": null },
  "pricing": { "creditsCharged": 1 }
}

Credit cost: dynamic, returned in pricing.creditsCharged. Cost scales with the number of reviews returned, not the number of requests.

---

Object schemas

Place search result object

Field	Type	Description
url	string	Google Maps URL for the place
title	string	Place name
description	string, nullable	Short description, if available
address	string	Full formatted address
neighborhood	string, nullable	Neighborhood name
street	string, nullable	Street address
district	string, nullable	District or city-level area
postalCode	string, nullable	Postal code
city	string, nullable	City name
country	string, nullable	Country name
location	object	Latitude/longitude pair — see Location object
website	string, nullable	Place's website URL
phone	string, nullable	Formatted phone number
price	string, nullable	Price range indicator (e.g. $10–20)
totalScore	number	Average rating
placeId	string	Google Place ID
fid	string	Google Maps feature ID, of the form 0x...:0x... — use this to fetch full place details
reviewsCount	integer	Total number of reviews
categories	array	Place category labels
openingHours	array	Opening hours per weekday
additionalInfo	object	Grouped feature flags (e.g. Service options, Accessibility, Offerings)

Location object

Field	Type	Description
lat	number	Latitude
lng	number	Longitude

Place object

Field	Type	Description
url	string	Google Maps URL for the place
title	string	Place name
address	string	Full formatted address
neighborhood	string, nullable	Neighborhood name
street	string, nullable	Street address
district	string, nullable	District or city-level area
postalCode	string, nullable	Postal code
city	string, nullable	City name
location	object	Latitude/longitude pair — see Location object
website	string, nullable	Place's website URL
phone	string, nullable	Formatted phone number
phoneUnformatted	string, nullable	Phone number without formatting
plusCode	string, nullable	Google Plus Code
price	string, nullable	Price range indicator
totalScore	number	Average rating
placeId	string	Google Place ID
cid	string	Google Maps client ID
fid	string	Google Maps feature ID, of the form 0x...:0x...
reviewsCount	integer	Total number of reviews
reviewsDistribution	object	Review count broken down by star rating — see Reviews distribution object
categories	array	Place category labels
additionalInfo	object	Grouped feature flags (e.g. Service options, Accessibility, Amenities)

Reviews distribution object

Field	Type	Description
oneStar	integer	Count of 1-star reviews
twoStar	integer	Count of 2-star reviews
threeStar	integer	Count of 3-star reviews
fourStar	integer	Count of 4-star reviews
fiveStar	integer	Count of 5-star reviews

Place review object

Field	Type	Description
id	string	Review ID
link	string	Permalink to the review
text	string	Review body
stars	integer	Rating, 1–5
date	integer	Posted timestamp, Unix milliseconds
dateIso	string (date-time)	Posted timestamp, ISO 8601
likes	integer, nullable	Number of likes on the review
photos	array	Photo URLs attached to the review
reviewer	object	Reviewer who left the review — see Reviewer object
ownersResponse	object	Owner's response to the review (empty object when none)
details	object	Free-form key/value metadata (e.g. Visited on, Wait time)

Reviewer object

Field	Type	Description
name	string	Reviewer's display name
photo	string	Reviewer's profile photo URL
url	string	Link to the reviewer's Google Maps profile
totalReviews	integer	Total reviews the reviewer has written
totalPhotos	integer	Total photos the reviewer has uploaded

---

Errors

All non-2xx responses share the same envelope:

{
  "status": 400,
  "message": "Bad request",
  "success": false,
  "error": { "code": "BAD_REQUEST" }
}

Status	Meaning
400	Bad request — missing/invalid parameters
402	Insufficient credits
404	Place or review set not found

Finding FIDs and Place URLs

• FID: the feature ID shown in GoogleMapsPlaceSearchResult.fid and GoogleMapsPlace.fid, of the form 0x47e671d877937b0f:0xb975fcfa192f84d4. Run a search first to discover a place's FID, then pass it to /google-maps/place/{fid} for full details.

• Place URL: the full google.com/maps/place/... URL for a place, also returned as url on search and detail responses. Pass it as-is to /google-maps/place/reviews.

Pagination Notes

• /google-maps/place/search paginates by numeric offset (a string), or accepts maxItems for a one-shot bulk pull — the two are mutually exclusive.

• /google-maps/place/reviews paginates by opaque cursor, or accepts maxItems for a one-shot bulk pull — the two are mutually exclusive.

• /google-maps/place/{fid} returns a single place and has no pagination.

Country and Language Codes

• countryCode accepts a short country code (2–5 characters) used to bias search results regionally.

• languageCode accepts a 2–10 character language code for localized place names and text (e.g. en, en-us, fr).

• If omitted, both default to Google's standard locale resolution for the request.