Maps Search

Search for businesses on maps with advanced filtering options. Returns business details including name, address, phone, website, ratings, and more.

[!NOTE] See the API Guide for the shared request lifecycle (sync, async polling, async webhook), error envelope, rate limits, custom_vars, and deduplication. This page documents only the fields and behaviour unique to this endpoint.

Try it

Pricing

Endpoint

Input Parameters

Default Fields

When fields is not specified, the following fields are returned:

name,website,phone_numbers,type,rating,review_count,full_address,business_id,place_id,zip_code

Note: business_id is always included regardless of the fields parameter (required for deduplication).

Available Fields

Field	Type	Description
`name`	string	Business name
`business_id`	string	Unique business identifier (always included)
`place_id`	string	Place identifier
`rating`	number	Average rating (0-5)
`review_count`	integer	Number of reviews
`price_level`	string	Price indicator (e.g., "€", "€€", "€€€")
`price_level_text`	string	Price description (e.g., "Moderately expensive")
`website`	string	Business website URL
`domain`	string	Website domain
`phone_numbers`	array	List of phone numbers
`full_address`	string	Complete address
`street_address_full`	string	Street address
`city`	string	City name
`zip_code`	string	Postal/ZIP code
`state`	string	State/province
`country_code`	string	ISO country code
`district`	string	District/neighborhood
`latitude`	number	Location latitude
`longitude`	number	Location longitude
`type`	string	Business category (e.g., "cafe", "restaurant")
`subtypes`	array	Subcategories (e.g., ["Coffee shop", "Cafe"])
`short_description`	string	Brief business description
`full_description`	string	Detailed business description
`timezone`	string	Business timezone
`owner_id`	string	Owner account ID
`owner_name`	string	Owner name
`owner_link`	string	Link to owner profile
`order_link`	string	Online ordering URL
`google_mid`	string	Maps identifier
`photos_sample`	array	Sample photos with URLs
`attributes`	object	Business attributes (see below)

Attributes Object

The attributes field contains detailed business information:

{
    "service_options": {
        "Outdoor seating": true,
        "Takeaway": true,
        "Dine-in": true,
        "Delivery": false
    },
    "highlights": {
        "Great coffee": true,
        "Live music": true
    },
    "accessibility": {
        "Wheelchair-accessible entrance": true
    },
    "offerings": {
        "Coffee": true,
        "Vegetarian options": true
    },
    "atmosphere": {
        "Casual": true,
        "Cosy": true
    },
    "crowd": {
        "Family friendly": true,
        "LGBTQ+ friendly": true
    },
    "payments": {
        "Credit cards": ["Mastercard"],
        "NFC mobile payments": true
    }
}

Examples

Output Fields

Error Responses

Validation Error (422)

{
    "message": "The query field is required.",
    "errors": {
        "query": ["The query field is required."]
    }
}

Common validation errors:

query is required
zoom must be between 3 and 21
limit must be between 1 and 2000
lat must be between -90 and 90
lon must be between -180 and 180
fields format must be alphanumeric with commas

Failed Enrichment (422 Unprocessable Entity)

When the enrichment fails, the HTTP status code is 422 and the response body contains "status": "failed" with an error_message:

{
    "id": 123,
    "type": "maps_search",
    "status": "failed",
    "error_message": "Maps search service is temporarily unavailable"
}

Rate Limit (429)

{
    "message": "Maps search rate limit exceeded"
}

Zoom Level Guide

Zoom	Area Coverage	Use Case
3-5	Country/Region	National chains, broad searches
6-8	State/Province	Regional businesses
9-11	City	Recommended default - city-wide searches
12-14	District	Neighborhood-level searches
15-17	Street	Block-level precision
18-21	Building	Very precise location searches

Typical Response Times

1-200 results: 5-15 seconds
201-1000 results: 15-45 seconds
1001-2000 results: 45-90 seconds

Use async mode with webhooks for large result sets to avoid timeout issues.

Integration Examples

JavaScript/Node.js

const response = await fetch(
    'https://api.skael.de/api/enrichments/maps_search',
    {
        method: 'POST',
        headers: {
            Authorization: 'Bearer eak_your_api_key_here',
            'Content-Type': 'application/json',
        },
        body: JSON.stringify({
            query: 'restaurants in Tokyo',
            limit: 500,
            fields: 'name,rating,website,phone_numbers,full_address',
        }),
    },
);

const result = await response.json();
console.log(`Found ${result.output.total} businesses`);

for (const business of result.output.items) {
    console.log(
        `${business.name}: ${business.rating}★ - ${business.phone_numbers[0]}`,
    );
}

Python

import requests

response = requests.post(
    'https://api.skael.de/api/enrichments/maps_search',
    headers={
        'Authorization': 'Bearer eak_your_api_key_here',
        'Content-Type': 'application/json'
    },
    json={
        'query': 'restaurants in Tokyo',
        'limit': 500,
        'fields': 'name,rating,website,phone_numbers,full_address'
    }
)

result = response.json()
print(f"Found {result['output']['total']} businesses")

for business in result['output']['items']:
    phones = ', '.join(business.get('phone_numbers', []))
    print(f"{business['name']}: {business.get('rating')}★ - {phones}")

PHP

$client = new GuzzleHttp\Client();

$response = $client->post('https://api.skael.de/api/enrichments/maps_search', [
    'headers' => [
        'Authorization' => 'Bearer eak_your_api_key_here',
        'Content-Type' => 'application/json',
    ],
    'json' => [
        'query' => 'restaurants in Tokyo',
        'limit' => 500,
        'fields' => 'name,rating,website,phone_numbers,full_address',
    ],
]);

$result = json_decode($response->getBody(), true);
echo "Found {$result['output']['total']} businesses\n";

foreach ($result['output']['items'] as $business) {
    $phones = implode(', ', $business['phone_numbers'] ?? []);
    echo "{$business['name']}: {$business['rating']}★ - {$phones}\n";
}