---
title: "List stores"
method: GET
path: "/v1/stores"
---

# List stores

`GET /v1/stores`

## Request

- Base URL: `https://supermcp.co.il`
- URL: `https://supermcp.co.il/v1/stores`
- Auth: none required

## Query parameters

- `chain` string
- `city` string
- `near` string
- `location` string
- `radius_km` number

## Response `200`

OK

- object
  - `data` object
    - `stores` object[]
      - `id` string, uuid
      - `chainId` string
      - `chainName` string
      - `storeCode` string
      - `name` string
      - `address` string, nullable
      - `city` string, nullable
      - `zip` string, nullable
      - `lat` number, nullable
      - `lng` number, nullable
      - `geoSource` string, nullable: Provenance of lat/lng: address, feed, city_centroid, or null.
      - `storeKind` 'branch' | 'online' | 'pickup' | 'warehouse', nullable: Fulfilment kind. Only 'branch' is somewhere a shopper can walk in; online/pickup/warehouse rows carry prices but are excluded from basket store recommendations.
      - `distanceKm` number, nullable
    - `location` object
      - `scope` 'unscoped' | 'city' | 'near' | 'city_near'
      - `precision` 'none' | 'city' | 'radius'
      - `fallbackApplied` boolean
      - `warning` string, nullable
      - `distanceReliable` boolean: False only when distance cannot order the candidates at all — every matching store collapses onto one shared coordinate. A city-level origin no longer clears this: distances stay usable but coarse (see distanceApproximate).
      - `distanceApproximate` boolean: True when distances are usable but coarse — a city-level origin, or stores placed by city centroid rather than branch address. Present them as approximate.
      - `requested` object
        - `city` string, nullable
        - `near` object, nullable
          - `lat` number
          - `lng` number
        - `radiusKm` number, nullable
      - `origin` object, nullable: Provenance of the resolved user origin point (never includes raw location text).
        - `precision` 'address' | 'street' | 'neighborhood' | 'city' | 'coordinates'
        - `provider` 'nominatim' | 'city_centroid' | 'coordinates'
        - `cached` boolean
        - `fallbackApplied` boolean
        - `displayName` string, nullable
        - `attribution` string, nullable

## Other responses

- `400`: Bad request. Query parameters are validated strictly: a parameter this document does not list is rejected, and `details[].keys` names it. A misspelled filter used to be dropped silently, which answered a question nobody asked with a plausible list of products.
- `401`: Unauthorized
- `404`: Not found
- `429`: Rate limited

---

[API](https://skmtc.dev/supermcp/apis/super-mcp-api.md) · [All operations](https://skmtc.dev/supermcp/apis/super-mcp-api/llms.txt) · [OpenAPI document](https://skmtc.dev/supermcp/apis/super-mcp-api/revisions/f0dea9415b1c?raw)