> For the complete documentation index, see [llms.txt](https://docs.pullbay.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pullbay.com/api-reference/endpoints/google-maps.md). # 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** ```bash 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** ```bash 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** ```json { "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": "(212) 966-4100", "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** ```bash 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** ```bash curl -G "https://api.pullbay.com/google-maps/place/0x47e671d877937b0f:0xb975fcfa192f84d4" \ -H "Authorization: Bearer YOUR_API_KEY" \ -d languageCode=en ``` **Response** ```json { "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": "+33 1 40 20 53 17", "phoneUnformatted": "+33140205317", "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** ```bash 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** ```bash 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** ```json { "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: ```json { "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.