Skip to main content
POST
cURL
Search Google Maps for businesses within a strict circle around an address or supplied coordinates. The request waits for the search to finish and returns up to 500 unique businesses in one response. Authenticate with your workspace API key. See Authentication.

Search area and result limit

Send a business category or search phrase in query and an address or locality in address. Both are required. Text is trimmed before validation: query accepts 1–160 characters and address accepts 1–240. radius_km accepts an integer from 1 to 100, defaulting to 20. limit accepts an integer from 1 to 500, defaulting to 20. Results can be fewer than requested. Defaults apply only when a field is omitted; null and unknown fields are rejected. To choose the center precisely, supply location with lat, lng, and display_name. The coordinates take precedence over address lookup; address is still required. Latitude must be between -90 and 90, longitude between -180 and 180, and the trimmed display name between 1 and 240 characters. Website contact extraction is unavailable. Omit include_contacts or set it to false; true is rejected. Business phone numbers and websites can still appear in the Maps results.

Credits and limits

Each unique returned business costs 0.1 credit. Three businesses cost 0.3 credits; empty results cost zero. Have limit × 0.1 credits available before starting: 2 credits for the default limit of 20, or 50 credits for the maximum of 500. Unused reserved credits are refunded. The response’s credits_used is the final charge. Each workspace can start 15 searches per rolling minute and have five active searches at a time. These limits are shared across API keys and the airscale_google_maps MCP tool. Requests may wait briefly for shared search capacity. A rate, concurrency or capacity limit returns 429; honor Retry-After when present.

Business results

The response contains status, total_results, credits_used, data, and warnings. Every business in data includes these fields: id and name are nonempty strings. Other text fields can be empty strings or null; subtypes can be empty. Check warnings for search notices. A successful search with no matches returns data: [], total_results: 0, and credits_used: 0.

Timing and errors

Allow at least 100 seconds for your client timeout. The search has a 90-second server deadline. Invalid input returns 400, insufficient available credits returns 402, and an unresolved or ambiguous location returns 422. When code is google_maps_location_ambiguous, the response can include a locations array: select the intended candidate and submit it as location. Search failures return 502, temporary availability or billing failures return 503, and timeouts return 504. Error bodies contain error and code, with generic messages such as “Google Maps search is temporarily unavailable.”
Do not automatically retry this POST after a timeout, disconnect, or uncertain result. The search may have completed and charged credits even if its response was lost. There is no caller idempotency key; repeating the request starts another search and can cause another charge.

Next step

Use the same inputs with airscale_google_maps from an MCP client.

Authorizations

Authorization
string
header
required

Use an Airscale workspace API key. Never expose the key in client-side code.

Body

application/json
query
string
required

Business category or search phrase. Trimmed before validation.

Required string length: 1 - 160
Pattern: \S
address
string
required

Address or locality; still required with location. Trimmed before validation.

Required string length: 1 - 240
Pattern: \S
radius_km
integer
default:20

Strict circle radius in kilometers. Defaults only when omitted.

Required range: 1 <= x <= 100
limit
integer
default:20

Maximum unique businesses. Defaults only when omitted.

Required range: 1 <= x <= 500
include_contacts
boolean
default:false

Must be false; website contact extraction is unavailable.

location
object

Optional authoritative center, used instead of address geocoding.

Response

Unique businesses within the search circle and their final credit charge.

status
string
required
Allowed value: "success"
total_results
integer
required

Number of businesses in data.

Required range: 0 <= x <= 500
credits_used
number
required

total_results × 0.1 credits.

Required range: 0 <= x <= 50
data
object[]
required
Maximum array length: 500
warnings
string[]
required
Maximum string length: 4096