> ## Documentation Index > Fetch the complete documentation index at: https://docs.airscale.io/llms.txt > Use this file to discover all available pages before exploring further. # 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. 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](/api-reference/authentication.md). ## 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: | 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 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." > [!WARNING] > > 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`](/mcp/tools#airscale-google-maps) from an MCP client. ## OpenAPI ````yaml openapi.json POST /v1/google-maps openapi: 3.1.0 info: title: Airscale Public API version: '2026-09-11' description: Search, enrich, and resolve public business data with Airscale. x-airscale-source-repository: ViceScale/airscale-code x-airscale-source-sha: 1de19e1b70a052a4b8d9c2075021a7e5e7a94d51 servers: - url: https://api.airscale.io description: Production security: - bearerAuth: [] tags: - name: Search and discovery description: Search people, companies, and the web. - name: Contact data description: Find professional and personal contact data. - name: Profiles and reverse lookup description: Extract profiles or resolve a person from known contact data. - name: Post engagement description: Retrieve and enrich people who liked or commented on LinkedIn posts. - name: LinkedIn content description: >- Search LinkedIn posts, read profile and company feeds, and retrieve profile comments and comment reactions. - name: Account description: Inspect workspace account state. - name: Miscellaneous description: >- Find website technologies and check WhatsApp availability, Meta ads, and email deliverability. paths: /v1/google-maps: post: tags: - Miscellaneous summary: Search Google Maps description: >- Search businesses within a strict circle around an address or supplied coordinates. Returns up to 500 unique businesses synchronously. Allow at least 100 seconds for the client timeout. Contact extraction is unavailable. Do not automatically retry after a timeout, disconnect, or uncertain result: repeating a search can cause another charge. operationId: searchGoogleMaps requestBody: required: true content: application/json: schema: type: object properties: query: type: string minLength: 1 maxLength: 160 pattern: \S description: >- Business category or search phrase. Trimmed before validation. address: type: string minLength: 1 maxLength: 240 pattern: \S description: >- Address or locality; still required with location. Trimmed before validation. radius_km: type: integer minimum: 1 maximum: 100 default: 20 description: >- Strict circle radius in kilometers. Defaults only when omitted. limit: type: integer minimum: 1 maximum: 500 default: 20 description: Maximum unique businesses. Defaults only when omitted. include_contacts: type: boolean const: false default: false description: Must be false; website contact extraction is unavailable. location: type: object properties: lat: type: number minimum: -90 maximum: 90 lng: type: number minimum: -180 maximum: 180 display_name: type: string minLength: 1 maxLength: 240 pattern: \S description: Human-readable center name; trimmed before validation. required: - lat - lng - display_name additionalProperties: false description: >- Optional authoritative center, used instead of address geocoding. required: - query - address additionalProperties: false example: query: cafes address: Lyon, France radius_km: 20 limit: 20 include_contacts: false location: lat: 45.764 lng: 4.8357 display_name: Lyon responses: '200': description: >- Unique businesses within the search circle and their final credit charge. content: application/json: schema: type: object properties: status: type: string const: success total_results: type: integer minimum: 0 maximum: 500 description: Number of businesses in data. credits_used: type: number minimum: 0 maximum: 50 description: total_results × 0.1 credits. data: type: array maxItems: 500 items: type: object properties: id: type: string minLength: 1 maxLength: 4096 name: type: string minLength: 1 maxLength: 4096 google_id: type: - string - 'null' maxLength: 4096 place_id: type: - string - 'null' maxLength: 4096 type: type: - string - 'null' maxLength: 4096 business_status: type: - string - 'null' maxLength: 4096 phone_number: type: - string - 'null' maxLength: 4096 website: type: - string - 'null' maxLength: 4096 domain: type: - string - 'null' maxLength: 4096 full_address: type: - string - 'null' maxLength: 4096 address: type: - string - 'null' maxLength: 4096 city: type: - string - 'null' maxLength: 4096 state: type: - string - 'null' maxLength: 4096 country: type: - string - 'null' maxLength: 4096 place_link: type: - string - 'null' maxLength: 4096 subtypes: type: array maxItems: 30 items: type: string maxLength: 240 verified: type: - boolean - 'null' latitude: type: - number - 'null' longitude: type: - number - 'null' rating: type: - number - 'null' review_count: type: - integer - 'null' minimum: 0 required: - id - name - google_id - place_id - type - business_status - phone_number - website - domain - full_address - address - city - state - country - place_link - subtypes - verified - latitude - longitude - rating - review_count additionalProperties: false warnings: type: array items: type: string maxLength: 4096 required: - status - total_results - credits_used - data - warnings additionalProperties: false examples: success: summary: Synthetic business result value: status: success total_results: 1 credits_used: 0.1 data: - id: place-1 google_id: google-1 place_id: place-1 name: Example Cafe type: cafe subtypes: - food business_status: OPERATIONAL verified: true phone_number: '+12025550147' website: https://cafe.example.com domain: cafe.example.com full_address: 1 Example Street, Lyon address: 1 Example Street city: Lyon state: null country: FR place_link: '' rating: 4.5 review_count: 10 latitude: 45.76 longitude: 4.83 warnings: [] empty: summary: No matching businesses value: status: success total_results: 0 credits_used: 0 data: [] warnings: [] '400': description: >- Invalid JSON, unknown fields, or invalid search input. An optional detail explains validation failures. content: application/json: schema: type: object properties: error: type: string code: type: string detail: type: string maxLength: 300 required: - error - code additionalProperties: false '401': description: Missing or invalid workspace API key. content: application/json: schema: type: object properties: error: type: string code: type: string required: - error - code additionalProperties: false '402': description: Insufficient available credits for limit × 0.1 credits. content: application/json: schema: type: object properties: error: type: string code: type: string required: - error - code additionalProperties: false '404': description: >- No Google Maps businesses were found. Successful empty searches can also return 200 with an empty data array. content: application/json: schema: type: object properties: error: type: string code: type: string required: - error - code additionalProperties: false '409': description: The search operation state changed; do not automatically retry. content: application/json: schema: type: object properties: error: type: string code: type: string required: - error - code additionalProperties: false '413': description: The request body exceeds 128 KiB. content: application/json: schema: type: object properties: error: type: string code: type: string required: - error - code additionalProperties: false '422': description: >- The location could not be resolved. An ambiguous location can include candidate locations to select from. content: application/json: schema: type: object properties: error: type: string code: type: string locations: type: array minItems: 1 maxItems: 20 items: type: object properties: lat: type: number minimum: -90 maximum: 90 lng: type: number minimum: -180 maximum: 180 display_name: type: string minLength: 1 maxLength: 240 pattern: \S description: >- Human-readable center name; trimmed before validation. required: - lat - lng - display_name additionalProperties: false description: Candidates when code is google_maps_location_ambiguous. required: - error - code additionalProperties: false '429': description: >- The workspace reached 15 admitted searches per rolling minute or already has five active searches, or shared search capacity is busy. Honor Retry-After when present. headers: Retry-After: description: Seconds to wait before starting a new search. schema: type: integer minimum: 1 content: application/json: schema: type: object properties: error: type: string code: type: string required: - error - code additionalProperties: false '499': description: The search was cancelled. content: application/json: schema: type: object properties: error: type: string code: type: string required: - error - code additionalProperties: false '502': description: The search failed or returned an invalid response. content: application/json: schema: type: object properties: error: type: string code: type: string required: - error - code additionalProperties: false '503': description: >- Search, authentication, storage, or credit settlement is temporarily unavailable. Do not automatically retry an uncertain result. content: application/json: schema: type: object properties: error: type: string code: type: string required: - error - code additionalProperties: false '504': description: The search deadline was exceeded. Do not automatically retry. content: application/json: schema: type: object properties: error: type: string code: type: string required: - error - code additionalProperties: false x-codeSamples: - label: cURL lang: bash source: |- 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"}}' components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API key description: >- Use an Airscale workspace API key. Never expose the key in client-side code. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.