Datasets API endpoint
Searches the stored Apple Maps place directory (dataset id `apple-maps-places`), built by tiling populated areas and running category searches over each tile. Each place has its Apple place id, name, category path, address, coordinates, phone, website, opening hours, rating and price level where Apple shows them. Coverage is observed, not complete: Apple answers each search with at most 25 places, so very dense areas can hold places the directory has not reached, and a place missing from the results is not evidence that it does not exist or has closed. A `rating` of `null` means Apple shows no rating for the place (never a zero-star score); ratings and rating counts come from third-party review partners that Apple shows (for example Yelp and Foursquare), so they are not comparable across places and a few places carry a rating with no count. Supports full-text `q`, `category`/`city`/`state`/`country_code`/`postal_code` filters, `min_rating`, `min_rating_count`, `has_website`, `has_phone`, `lat`/`lon`/`radius_m` radius filtering, and `sort` (relevance, rating_desc, review_count_desc, updated_at_desc, distance_asc). Does not trigger live scraping. Billing: this search costs 1 credit per record returned, with a minimum of 2 (an empty result costs 2, a full page of 100 costs 100).
/datasets/apple-maps-places/searchDataset id enum:
apple-maps-placesQuery parameters:
q: optional full-text search over place name, category, city and address, max 256 characters. Every term must match.category: optional exact Apple category name, max 128 characters, e.g. Coffee Shop. Use facet=category to discover exact values and pass the selected value unchanged.city: optional exact city filter, max 128 characters.state: optional exact state/region filter, max 128 characters.country_code: optional ISO 3166-1 alpha-2 country filter, e.g. US, GB, JP.postal_code: optional exact postal code filter, max 128 characters.min_rating: optional minimum rating from 0 through 5. Places with no rating are returned with rating null, so any min_rating above 0 excludes them.min_rating_count: optional minimum number of ratings behind the rating, 0 or greater.has_website: optional website presence filter. true keeps only places with a website, false only places without one.has_phone: optional phone presence filter. true keeps only places with a phone number, false only places without one.lat: optional latitude for radius filtering or distance sort; supply together with lon.lon: optional longitude for radius filtering or distance sort; supply together with lat.radius_m: optional radius in meters, from 1 through 50000; requires lat and lon.sort: optional sort enum: relevance, rating_desc, review_count_desc, updated_at_desc, distance_asc.page: optional page number, defaults to 1.page_size: optional page size, defaults to 20 and maxes at 100.Response behavior:
relevance sort when q is supplied, otherwise updated_at_desc.lat and lon must be supplied together. distance_asc requires lat and lon, but not radius_m.10000; page * page_size must not exceed 10000.null rating means Apple shows no rating for the place (never a zero-star score). Ratings come from third-party review partners that Apple shows (for example Yelp and Foursquare), so rating scales and review counts are not comparable across places, and a few places carry a rating with no count.id is Apple's numeric place id and place_id the external id used in maps.apple.com URLs (starts with I).catalog_country is the Apple storefront the place was found under (it affects ranking and name language); country_code is the place's own country.first_seen_at is when the directory first observed the place and last_seen_at the latest observation. A place that is no longer observed is not necessarily closed.apple-maps-search endpoint.1 credit per record returned, minimum 2. A search that returns 20 records costs 20 credits, a full page of 100 costs 100, and an empty or one-record result costs 2. You are charged for what comes back, not for the page_size you ask for, but your balance must cover the requested page_size for the call to be accepted. The response header x-credit-cost shows what a call was charged.
| Field | In the sample | Value in the sample |
|---|---|---|
| dataset | Has a value | |
| items | Empty | |
| page | Has a value | |
| page_size | Has a value | |
| total | Has a value | 0 |
| sort | Has a value |
| Parameter | Type | Required | Default | Description | Example |
|---|---|---|---|---|---|
| q | string | No | Full-text search over place name, category, city and address; every term must match. Max 256 characters | ||
| category | string | No | Exact Apple category name, max 128 characters, e.g. Coffee Shop; use facet=category to discover values | ||
| city | string | No | Exact city filter, max 128 characters | ||
| state | string | No | Exact state/region filter, max 128 characters | ||
| country_code | string | No | ISO 3166-1 alpha-2 country filter, e.g. US, GB, JP | ||
| postal_code | string | No | Exact postal code filter, max 128 characters | ||
| min_rating | number | No | Minimum rating, from 0 through 5; any value above 0 excludes unrated places | ||
| min_rating_count | integer | No | Minimum number of ratings behind the rating, 0 or greater | ||
| has_website | boolean | No | true keeps only places with a website; false keeps only places without one | ||
| has_phone | boolean | No | true keeps only places with a phone number; false keeps only places without one | ||
| lat | number | No | Latitude for radius filtering or distance sort, requires lon | ||
| lon | number | No | Longitude for radius filtering or distance sort, requires lat | ||
| radius_m | integer | No | Radius in meters, 1 through 50000; requires lat and lon | ||
| sort | string | No | relevance with q | Sort enum: relevance, rating_desc, review_count_desc, updated_at_desc, distance_asc. Defaults to relevance with q, otherwise updated_at_desc Allowed values: relevance, rating_desc, review_count_desc, updated_at_desc, distance_asc. | |
| page | integer | No | 1 | Page number, defaults to 1 | |
| page_size | integer | No | 20 and maxes at 100 | Page size, defaults to 20 and maxes at 100; page * page_size must be <= 10000 | |
| x-api-key (header) | string | Yes | API key required |
curl -X GET "https://api.crawlora.net/api/v1/datasets/apple-maps-places/search?q=coffee&has_website=true&has_phone=true&sort=relevance&page=1" \ -H "x-api-key: $CRAWLORA_API_KEY"
{
"code": 200,
"msg": "OK",
"data": {
"dataset": "apple-maps-places",
"items": [
{
"id": "6435622567484707146",
"place_id": "I594FECA0B369D14A",
"name": "Sightglass Coffee",
"category": "Coffee Shop",
"city": "San Francisco",
"country_code": "US",
"rating": 4.5,
"rating_count": 2228
}
],
"page": 1,
"page_size": 20,
"total": 1,
"sort": "relevance"
}
}Request schema
No body schema
Response schema
#/definitions/datasets.applePlacesSearchResponseDoc
| Field | Type | Required | Enum | Bounds | Example | Description |
|---|---|---|---|---|---|---|
| code | integer | No | 200 | |||
| data | datasets.ApplePlaceSearchResponse | No | ||||
| data.dataset | string | No | ||||
| data.items | array | No | ApplePlaceDatasetItem record, 44 fields: address, alt_phones, catalog_country, categories, category, category_ids, city, country, country_code, county, crawled_at, discovery_keyword and 27 more. Described under Apple Maps Places Nearby API. | |||
| data.page | integer | No | ||||
| data.page_size | integer | No | ||||
| data.sort | string | No | ||||
| data.total | integer | No | ||||
| msg | string | No | OK |
| Status | Description | Schema |
|---|---|---|
| 400 | Bad Request | #/definitions/app.Response |
| 429 | Too Many Requests | #/definitions/app.Response |
| 500 | Internal Server Error | #/definitions/app.Response |
Use environment variables for secrets and keep Crawlora API keys server-side.
curl -X GET "https://api.crawlora.net/api/v1/datasets/apple-maps-places/search?q=coffee&has_website=true&has_phone=true&sort=relevance&page=1" \
-H "x-api-key: $CRAWLORA_API_KEY"