Datasets API endpoint
Searches the worldwide Starbucks store directory (dataset id `starbucks-stores`), built by grid-tiling the store locator around its 50-result cap. Each store has its store number, name, phone, full address, coordinates, weekly hours, amenity codes, and pick-up options. Store discovery is global, but hours, amenities, and phone numbers are populated per market and are largely absent outside the US, Canada, Europe, and the Gulf; an empty schedule means "not published for this market", not "closed". `country` is the store's true country while `market` is crawl provenance (the US host geocodes worldwide). Supports full-text `q`, `country`/`state`/`city`/`market`/`amenity` filters, `lat`/`lon`/`radius_m` radius filtering, and `sort` (relevance, distance_asc). 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/starbucks-stores/searchSearches the worldwide Starbucks store directory, built by grid-tiling the store locator around its hard 50-result cap and storing every store in a search index.
Dataset id enum:
starbucks-storesQuery parameters:
q: optional full-text search over store name, city, and address, max 256 characters.country: optional ISO-3166-1 alpha-2 country filter, e.g. US, GB, JP.state: optional state/region code filter, e.g. WA.city: optional exact city filter.market: optional crawl-provenance market filter. One of us, ca — the Starbucks host the store was discovered through, not its geography.amenity: optional amenity code filter, e.g. DT (Drive-Thru), XO (Mobile Order and Pay).lat, lon: optional coordinate for radius filtering or distance sort; supply together.radius_m: optional radius in meters, 1 through 50000; requires lat and lon.sort: optional sort order. One of relevance, distance_asc. Defaults to store-number order.page: 1-based page number, default 1.page_size: default 20, max 100; page * page_size must not exceed 10000.Notable response behavior:
country is the store's true country; market is crawl provenance (the US host geocodes worldwide, so a Tokyo store has country: JP, market: us). A record stored before the field was written has no market in its body; it was read through the US host, so market=us matches it and the market facet counts it under us.schedule (hours), amenities, and phone are populated per market and are largely absent outside the US, Canada, Europe, and the Gulf. An empty schedule means "not published for this market", not "closed".total: 0), not an error.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 | Filled in, of 20 checked | Values in the sample |
|---|---|---|
| id | 20 | |
| store_number | 20 | |
| store_id | 20 | |
| name | 20 | |
| phone | 20 | |
| address | 20 | |
| city | 20 | |
| state | 20 | |
| postal_code | 20 | |
| country | 20 | |
| location | 20 | |
| latitude | 20 | |
| longitude | 20 | |
| time_zone | 20 | |
| ownership_type_code | 20 | |
| mobile_ordering_availability | 20 | |
| amenities | 20 | median 9 entries |
| amenity_names | 20 | median 9 entries |
| pick_up_options | 20 | median 2 entries |
| first_seen_at | 20 | 2026-08-31 to 2026-09-25 |
| last_seen_at | 20 | 2026-09-25 to 2026-10-03 |
| crawled_at | 20 | 2026-09-25 to 2026-10-03 |
| schema_version | 20 |
| Parameter | Type | Required | Default | Description | Example |
|---|---|---|---|---|---|
| q | string | No | Full-text search over store name, city, and address, max 256 characters | ||
| country | string | No | ISO-3166-1 alpha-2 country filter, e.g. US, GB, JP | ||
| state | string | No | State/region code filter, e.g. WA | ||
| city | string | No | Exact city filter | ||
| market | string | No | Crawl-provenance market filter. One of: us, ca Allowed values: us, ca. | ||
| amenity | string | No | Amenity code filter, e.g. DT (Drive-Thru), XO (Mobile Order and Pay) | ||
| 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 | Sort enum: relevance, distance_asc Allowed values: relevance, 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/starbucks-stores/search?q=coffee&country=us&market=us&sort=relevance&page=1" \ -H "x-api-key: $CRAWLORA_API_KEY"
{
"code": 200,
"msg": "OK",
"data": {
"dataset": "starbucks-stores",
"items": [
{
"store_number": "101-54",
"name": "Columbia Center - 4th & Cherry",
"city": "Seattle",
"state": "WA",
"country": "US",
"latitude": 47.60422,
"longitude": -122.33078,
"amenities": [
"16",
"XO",
"DT"
],
"market": "us"
}
],
"page": 1,
"page_size": 20,
"total": 1,
"sort": ""
}
}Request schema
No body schema
Response schema
#/definitions/datasets.starbucksStoresSearchResponseDoc
| Field | Type | Required | Enum | Bounds | Example | Description |
|---|---|---|---|---|---|---|
| code | integer | No | 200 | |||
| data | datasets.StarbucksStoreSearchResponse | No | ||||
| data.dataset | string | No | ||||
| data.items | array | No | StarbucksStoreDatasetItem record, 28 fields: address, amenities, amenity_names, city, country, crawled_at, distance_meters, first_seen_at, id, last_seen_at, latitude, location and 14 more. Described under Find nearby stored Starbucks stores 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/starbucks-stores/search?q=coffee&country=us&market=us&sort=relevance&page=1" \
-H "x-api-key: $CRAWLORA_API_KEY"