Skip to content

Stores

Returns the physical-store directory: every indexed supermarket location with name, address, postal code, and coordinates. Filter by retailer, country, or city, or search around a point to get the nearest stores with distance. Requires an API key and costs 0 credits.

Coverage: 13,600+ stores across 11 retailers in AT, BE, FI, FR, GB, and NL - Carrefour FR, Morrisons, Sainsbury’s, BILLA, ASDA, S-kaupat, Jumbo, Tesco UK, PLUS, Waitrose, and Colruyt.

Request

Section titled “Request”
Terminal window
curl -H "X-API-Key: $MEALCP_API_KEY" \
  "https://api.mealcp.com/v1/stores?country=AT&city=Wien"
Section titled “Near-me search”

Pass a WGS-84 point as near=lat,lon to restrict results to radius_km (default 10, max 500) and order them nearest-first. Each hit carries its great-circle distance_km:

Terminal window
curl -H "X-API-Key: $MEALCP_API_KEY" \
  "https://api.mealcp.com/v1/stores?near=51.5074,-0.1278&radius_km=2"

Parameters

Section titled “Parameters”
Param Type Default Description
retailer string - Retailer slug (e.g. billa-at)
country string - ISO 3166-1 alpha-2 country code (e.g. AT)
city string - City name, case-insensitive (e.g. Wien)
near string - WGS-84 point as lat,lon (e.g. 48.2082,16.3738)
radius_km number 10 Near-query radius in km (0.1-500)
page int 1 1-based page number
page_size int 100 Stores per page, max 100

All filters combine with AND. Without near, results are ordered by retailer then stable id.

Response

Section titled “Response”

Near-query response (trimmed to three hits):

{
  "found": 37,
  "page": 1,
  "page_size": 100,
  "stores": [
    {
      "id": "st_8f14e45fceea167a5a36dedd4bea2543",
      "retailer_slug": "waitrose-uk",
      "chain_slug": "waitrose",
      "name": "Little Waitrose & Partners",
      "address": "62 Long Acre",
      "city": "London",
      "postal_code": "WC2E 9JD",
      "lat": 51.5122,
      "lon": -0.1223,
      "distance_km": 0.649
    },
    {
      "id": "st_c9f0f895fb98ab9159f51fd0297e236d",
      "retailer_slug": "sainsburys-uk",
      "chain_slug": "sainsburys",
      "name": "Sainsbury's Local",
      "address": "62 Buckingham Gate",
      "city": "London",
      "postal_code": "SW1E 6AJ",
      "lat": 51.499,
      "lon": -0.135,
      "distance_km": 1.063
    },
    {
      "id": "st_45c48cce2e2d7fbdea1afc51c7c6ad26",
      "retailer_slug": "tesco-uk",
      "chain_slug": "tesco",
      "name": "Tesco Express",
      "address": "48-52 Wigmore Street",
      "city": "London",
      "postal_code": "W1U 2PT",
      "lat": 51.5145,
      "lon": -0.149,
      "distance_km": 1.668
    }
  ]
}

Fields

Section titled “Fields”
Field Type Description
found number Total match count across all pages
page, page_size number Current page and requested page size
stores[].id string Opaque store id (st_ + 32 hex) - stable
stores[].retailer_slug string Retailer the store belongs to
stores[].chain_slug string Chain slug, null when no chain is recorded
stores[].name string Store display name, null when missing
stores[].address, stores[].city, stores[].postal_code string Street address, city, postal code - null when missing
stores[].lat, stores[].lon number WGS-84 decimal degrees, null when missing
stores[].distance_km number Great-circle distance from near, present only on near queries

Usage notes

Section titled “Usage notes”

The endpoint is free - no credit cost - but still requires the X-API-Key header like the other authenticated endpoints.

  • Store locations only: there is no per-store pricing here. Prices are catalogue-level per retailer; use search and price history for those.
  • Only physical supermarkets are listed - pure online shops are excluded.
  • city matching is case-insensitive because directory casing varies by source.
  • Retailer slugs match the ones returned by coverage, so you can build a retailer picker from public data and query stores with the same identifiers.
  • Walk pages by incrementing page until page * page_size >= found; page_size=100 minimizes the request count.