Google Maps Search API
Find places by category and area or by name, and get a data_id for each one.
Overview
Search Google Maps for places of any kind (restaurants, cafes, attractions, shops, hotels) by free text, 20 ranked places per page.
Contract note
Sponsored results are not returned. position is the rank across pages (page 2 starts at 21). has_more is true when the page was full; a page past the end returns results: [] and has_more: false, and page 1 with no match returns 404. Pages can overlap slightly (Google re-ranks between calls), so de-duplicate results by data_id if you merge pages. open_state is Google's live status line at request time, and hours_today is today's hours in the place's local time.
Endpoint URL
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| query | string | Required | Free text: a category and area (pizza near Times Square) or a name (Eiffel Tower). |
| location | string | Optional | lat,lng to search around, a city-sized area (for example 40.758,-73.9855). Without it the query text decides the area. Invalid values return 400. |
| page | integer | Optional | 1 to 10. Default: 1. 20 results per page. |
| hl | string | Optional | UI language code. Default: en. |
| gl | string | Optional | Region or country code. Default: us. |
Response schema
| Field | Type | Description |
|---|---|---|
| query / location / page | mixed | The submitted search and page. |
| has_more | boolean | True when this page was full and Google likely has more. |
| results | array | Up to 20 places, each with position, data_id, place_id, name, categories, address, latitude, longitude, rating, reviews_count, phone, website, hours_today, open_state, and thumbnail. Fields Google does not show are null (lists are []). |
| results[].data_id | string | Google Maps data_id (0x…:0x…) for Place details or Google reviews. |
| search_metadata.provider | string | Always google_maps. |
Errors
Errors use RFC 7807 Problem Details (application/problem+json) with an error_code. Successful responses are always 2xx.
| Status | error_code | When |
|---|---|---|
| 400 | INVALID_PARAMETERS | data_id is not a Google Maps data_id, query is empty, or location is not lat,lng. |
| 404 | NO_RESULTS | Unknown data_id, or no place matches the query (page 1). |
| 422 | VALIDATION_ERROR | A required parameter is missing, or page is outside 1 to 10. |
| 502 | SCHEMA_DRIFT / UPSTREAM_ERROR | Google's answer could not be read. Retry later. |
| 503 | SERVICE_UNAVAILABLE | Temporarily unavailable. Honour the Retry-After header. |
| 504 | GATEWAY_TIMEOUT / UPSTREAM_TIMEOUT | Google did not answer in time. |
Identifier workflow
Search once, reuse the data_id
Every Search result carries a data_id. Pass it to Place for details, or to the Google Reviews endpoint (/v1/google_reviews/reviews) for the place's reviews.