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.
Features
- Query and location discoveryCombine 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.
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
Submit a query and location, 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 trueBest Use Cases
- Local business discovery: 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.
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. 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
Use these APIs when you need a different type of public Google Maps data.