---
title: "List stores, or find the nearest to a coordinate"
method: GET
path: "/api/v1/public/catalog/stores"
tags: ["Stores"]
---

# List stores, or find the nearest to a coordinate

`GET /api/v1/public/catalog/stores`

## Request

- Base URL: `https://api.shelfatlas.com`
- URL: `https://api.shelfatlas.com/api/v1/public/catalog/stores`
- Auth: HTTP bearer

Provide lat+lng (optionally radius_km) for nearest-first ordering, or chain_slug to list a chain. Not cursor-paginated: geo mode is distance-ordered and list mode caps at limit=500 (covers the full store set today) — pagination.cursor is always null here and does not mean "last page reached" the way it does on /products and /offers.

## Query parameters

- `chain_slug` string
- `postal_code` string
- `lat` number
- `lng` number
- `radius_km` number
- `limit` integer

## Response `200`

Stores (nearest-first when a coordinate is given).

- object
  - `ok` true, required
  - `data` Store[], required
    - `id` string, uuid, required
    - `name` string, required
    - `chainSlug` string, required
    - `chainName` string, required
    - `address` string, required
    - `city` string, required
    - `postalCode` string, nullable
    - `lat` number, required
    - `lng` number, required
    - `openingHours` object, nullable: Weekly opening hours keyed mon..sun; each an array of {open,close} "HH:MM" intervals (empty = closed).
    - `timezone` string, required
    - `topReporterAlias` string, nullable: "Claim to fame" (2026-08-20): the store's top approved-alias reporter over the rolling 30-day window (min 5 approved observations), or null when there is no eligible leader or the leader has no admin-approved alias.
    - `topReporterStandInNumber` number, nullable: Pending stand-in name (2026-08-21): a deterministic number (1..9999) for the qualifying leader when their alias is awaiting approval or re-pick (pending/rejected), so a chosen-but-unapproved name never appears publicly. Never set at the same time as topReporterAlias, and null when there is no eligible leader or the leader has no alias row at all.
  - `pagination` object
    - `limit` integer: The effective page size.
    - `cursor` string, nullable: Opaque cursor for the next page; null on the last page.

## Other responses

- `400`: Invalid parameters (`invalid_params`, `incompatible_params`).
- `401`: Missing, invalid, or revoked API key (`missing_api_key` / `invalid_api_key` / `revoked_api_key`).
- `429`: Rate limit or monthly limit reached (`rate_limited` / `monthly_limit_reached`).
- `503`: Temporary backend failure (`service_unavailable`).

---

[API](https://skmtc.dev/shelfatlas/apis/shelfatlas-catalog-api.md) · [All operations](https://skmtc.dev/shelfatlas/apis/shelfatlas-catalog-api/llms.txt) · [OpenAPI document](https://skmtc.dev/shelfatlas/apis/shelfatlas-catalog-api/revisions/943a8773856b?raw)