> 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://dashboard.pullbay.com/api` ## 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://dashboard.pullbay.com/api/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://dashboard.pullbay.com/api/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://dashboard.pullbay.com/api/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. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.pullbay.com/api-reference/endpoints/google-maps.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.