---
title: "Search the Starbucks store directory"
method: GET
path: "/datasets/starbucks-stores/search"
tags: ["Datasets"]
---

# Search the Starbucks store directory

`GET /datasets/starbucks-stores/search`

## Request

- Base URL: `https://api.crawlora.net/api/v1`
- URL: `https://api.crawlora.net/api/v1/datasets/starbucks-stores/search`
- Auth: API key in header `x-api-key`

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).

## Query parameters

- `q` string
- `country` string
- `state` string
- `city` string
- `market` 'us' | 'ca'
- `amenity` string
- `lat` number
- `lon` number
- `radius_m` integer
- `sort` 'relevance' | 'distance_asc'
- `page` integer
- `page_size` integer

## Headers

- `x-api-key` string, required

## Response `200`

OK

- DatasetsStarbucksStoresSearchResponseDoc
  - `code` integer
  - `data` DatasetsStarbucksStoreSearchResponse
    - `dataset` string
    - `items` EsStarbucksStoreDatasetItem[]
      - `address` string
      - `amenities` string[]
      - `amenity_names` string[]
      - `city` string
      - `country` string
      - `crawled_at` string
      - `distance_meters` number
      - `first_seen_at` string
      - `id` string
      - `last_seen_at` string
      - `latitude` number
      - `location` EsGeoPoint
        - `lat` number: Latitude in decimal degrees.
        - `lon` number: Longitude in decimal degrees.
      - `longitude` number
      - `market` string: Market is crawl provenance (us/ca), not geography -- see the type doc.
      - `mobile_ordering_availability` string
      - `name` string
      - `ownership_type_code` string
      - `phone` string
      - `pick_up_options` string[]
      - `postal_code` string
      - `run_id` string
      - `schema_version` integer
      - `state` string
      - `store_id` string
      - `store_number` string
      - `time_zone` string
    - `page` integer
    - `page_size` integer
    - `sort` string
    - `total` integer
  - `msg` string

## Other responses

- `400`: Bad Request
- `429`: Too Many Requests
- `500`: Internal Server Error

---

[API](https://skmtc.dev/crawlora/apis/crawlora-api.md) · [All operations](https://skmtc.dev/crawlora/apis/crawlora-api/llms.txt) · [OpenAPI document](https://skmtc.dev/crawlora/apis/crawlora-api/revisions/0497899e2016?raw)