curl --request POST \
--url https://api.airscale.io/v1/google-maps \
--max-time 100 \
--header "Authorization: Bearer $AIRSCALE_API_KEY" \
--header "Content-Type: application/json" \
--data '{"query":"cafes","address":"Lyon, France","radius_km":20,"limit":20,"include_contacts":false,"location":{"lat":45.764,"lng":4.8357,"display_name":"Lyon"}}'const url = 'https://api.airscale.io/v1/google-maps';
const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({query: 'cafes', address: 'Lyon, France'})
};
fetch(url, options)
.then(res => res.json())
.then(json => console.log(json))
.catch(err => console.error(err));import requests
url = "https://api.airscale.io/v1/google-maps"
payload = {
"query": "cafes",
"address": "Lyon, France"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)Google Maps
Find businesses around an address or coordinates. Rate limit: 15 admitted searches per rolling minute and five active searches per workspace, shared across API keys and MCP.
curl --request POST \
--url https://api.airscale.io/v1/google-maps \
--max-time 100 \
--header "Authorization: Bearer $AIRSCALE_API_KEY" \
--header "Content-Type: application/json" \
--data '{"query":"cafes","address":"Lyon, France","radius_km":20,"limit":20,"include_contacts":false,"location":{"lat":45.764,"lng":4.8357,"display_name":"Lyon"}}'const url = 'https://api.airscale.io/v1/google-maps';
const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({query: 'cafes', address: 'Lyon, France'})
};
fetch(url, options)
.then(res => res.json())
.then(json => console.log(json))
.catch(err => console.error(err));import requests
url = "https://api.airscale.io/v1/google-maps"
payload = {
"query": "cafes",
"address": "Lyon, France"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)Search area and result limit
Send a business category or search phrase inquery 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. Havelimit × 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 containsstatus, total_results, credits_used, data, and warnings. Every business in data includes these fields:
| Fields | Meaning |
|---|---|
id, google_id, place_id | Business identifiers. id is unique within the response. |
name, type, subtypes | Business name, primary category, and an array of additional categories. |
business_status, verified | Business status and a boolean verification value, or null when unknown. |
phone_number, website, domain, place_link | Business contact details and Google Maps link. |
full_address, address, city, state, country | Address details. |
latitude, longitude | Coordinates as numbers, or null. |
rating, review_count | Rating and integer review count, or null. |
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 returns400, 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.”
Next step
Use the same inputs withairscale_google_maps from an MCP client.Authorizations
Use an Airscale workspace API key. Never expose the key in client-side code.
Body
Business category or search phrase. Trimmed before validation.
1 - 160\SAddress or locality; still required with location. Trimmed before validation.
1 - 240\SStrict circle radius in kilometers. Defaults only when omitted.
1 <= x <= 100Maximum unique businesses. Defaults only when omitted.
1 <= x <= 500Must be false; website contact extraction is unavailable.
Optional authoritative center, used instead of address geocoding.
Show child attributes
Show child attributes
Response
Unique businesses within the search circle and their final credit charge.
"success"Number of businesses in data.
0 <= x <= 500total_results × 0.1 credits.
0 <= x <= 50500Show child attributes
Show child attributes
4096