Google Maps Search
Google Maps Search turns a business, category, or place query and a required location into structured public place records. Each stored result uses the provider-independent PlaceItem schema, so available identity, address, contact, rating, review-count, and coordinate fields can flow into research and enrichment systems without binding clients to source-specific response keys.
Google Maps Search API Features
- Query and location discoveryThe Google Maps Search API combines a required non-empty query such as coffee with a required location such as New York, NY to discover matching public places.
- Optional geographic controlsAdd country, a latitude-longitude pair, and zoom_level when the search needs more explicit geographic context; omitted optional fields are not fabricated.
- Normalized place identity and contact dataReceive stable PlaceItem fields for IDs, source URLs, names, categories, addresses, public phone numbers, websites, and collection time when available.
- Ratings and geographic coordinatesKeep available ratings, review counts, city, region, country, latitude, and longitude with each place while safely handling source fields that are absent.
Google Maps Search API Parameters
| Parameters | Required | Description |
|---|---|---|
query | Required | Required non-empty search term for a place, business, or category. |
location | Required | Required non-empty human-readable search area, such as a city, region, or address. When both coordinates are omitted, it is combined with the query for discovery. |
country | Optional | Optional non-empty country name or code forwarded as geographic context. |
latitude | Optional | Optional latitude from -90 through 90. It must be supplied together with longitude. |
longitude | Optional | Optional longitude from -180 through 180. It must be supplied together with latitude. |
zoom_level | Optional | Optional integer map zoom level from 0 through 21. |
results_limit | Optional | Maximum place records to store; defaults to 100 and accepts integers from 1 through 2,000. |
How to Use the Google Maps Search API
Submit a query and location to the Google Maps Search API, track the asynchronous task, then read normalized place records with cursor pagination.
- Prepare a non-empty query and location; optionally add country, coordinates, zoom_level, and a results_limit from 1 through 2,000.
- POST the request to /v1/google-maps/search and save the returned task_id.
- Poll /v1/tasks/{task_id} until the task succeeds or reports a failure.
- Read data.results.items and pass next_cursor to the task endpoint while has_more remains true.
curl -X POST "https://api.socq.ai/v1/google-maps/search" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"coffee","location":"New York, NY","country":"US","results_limit":3}'
# Poll GET /v1/tasks/{task_id}
# Read data.results.items and follow next_cursor while has_more is trueGoogle Maps Search API Use Cases
- Local business discovery: Use the Google Maps Search API to build a bounded list of public businesses matching a category or service in a specified city, district, or address area.
- Location data enrichment: Add available names, categories, addresses, phones, websites, and coordinates to place candidates already present in a CRM or research queue.
- Market and coverage research: Compare collected place counts, categories, ratings, and review volumes across independently submitted geographic searches.
- Place shortlist preparation: Use public URLs, contact fields, rating context, and coordinates to select places for a separate verification or detail workflow.
Google Maps Search API Pro Tips
- Use a specific category or business term and a clear city, district, or address in location; vague combinations can produce broad or ambiguous matches.
- Only send country, coordinates, or zoom_level when they provide verified geographic context. Supply latitude and longitude together and keep both values within their documented ranges.
- Keep results_limit close to the number of records you need from the Google Maps Search API. It controls the collection ceiling, while the task GET limit controls how many stored records are returned per response page.
- Continue with next_cursor until has_more is false when stored results exceed the first task response page.
- Treat descriptions, contact fields, ratings, review counts, and coordinates as optional public data, and retain collected_at for point-in-time comparisons.
Related APIs
Beyond the Google Maps Search API, use these APIs when you need a different type of public Google Maps data.