List nearby stores

Returns stores that can serve a reference point — an ACTIVE store with at least one ACTIVE coverage zone covering the coordinates (RADIUS or POLYGON) — sorted nearest-first by store location. Use this for a map view or a “nearest location” picker after the customer shares GPS or a geocoded address.

Requires a Fire spark access token obtained through token exchange. For a full paginated catalog, use list stores.

Query parameters

Parameter	Required	Description
`latitude`	Yes	Reference latitude. Between -90 and 90.
`longitude`	Yes	Reference longitude. Between -180 and 180.
`brand_id`	No	Filter stores by brand. External brand identifier — alphanumeric characters, `_`, and `-` only. 1–64 characters. When omitted, all stores for the merchant are returned.
`channel_id`	No	Only returns stores that have this channel enabled in `channel_ids`.
`fulfillment_id`	No	Only returns stores that have this fulfillment enabled in `fulfillment_ids`.
`limit`	Yes	Maximum number of stores to return. 1–100.

Request

curl "https://firespark.cloud/api/storefront/v1/stores/nearby?brand_id=0001&latitude=-2.1894&longitude=-79.8891&limit=10" \
  -H "Authorization: Bearer ACCESS_TOKEN"

Response

The response wraps an array of store objects in data, ordered from nearest to farthest. Each object uses the same shape as list stores, including cms_template_id and cms when a CMS template is assigned. Only ACTIVE stores are included.

{
  "data": [
    {
      "id": "downtown-kitchen",
      "uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "merchant_id": "22222222-2222-2222-2222-222222222222",
      "brand_id": "0001",
      "name": "Downtown Kitchen",
      "status": "ACTIVE",
      "timezone": "America/Guayaquil",
      "contact": {
        "email": "downtown@merchant.com",
        "phone": "+593991234567",
        "name": "Downtown Kitchen"
      },
      "location": {
        "latitude": -2.1894,
        "longitude": -79.8891,
        "address_line_1": "Av. 9 de Octubre 123",
        "city": "Guayaquil",
        "country": "Ecuador",
        "postal_code": "090101",
        "business_name": "Downtown Kitchen S.A."
      },
      "instructions": null,
      "coverage_zones": [],
      "availability": {
        "schedules": null,
        "temporary_closed_reason": null,
        "temporary_closed_until": null,
        "status": "OPEN"
      },
      "channel_ids": ["web", "app"],
      "fulfillment_ids": ["delivery", "pickup"],
      "labels": [],
      "tags": {},
      "cms_template_id": null,
      "cms": null
    }
  ]
}

How matching and distance work

Coverage filter — Only stores with an ACTIVE coverage zone that contains the point are returned. RADIUS zones use distance-to-center within radius (meters). POLYGON zones use point-in-polygon.
Ranking — Matching stores are ordered by straight-line distance from the query coordinates to the store’s location (PostGIS geography on the store point).

Stores without a geocoded location or without covering zones are omitted.

Pair this endpoint with the device GPS or a geocoded address. Pass a low limit (for example 5) for compact pickers, or a higher value when rendering a map with more pins.

Store fields

See list stores for the full store schema.

Error responses

Status	Description
`400`	Missing or invalid `latitude`, `longitude`, or `limit`.
`401`	Missing or invalid access token.
`403`	Token does not have access to this merchant’s stores.

API Documentation

Endpoints

Guides

Resources

Query parameters

Request

Response

How matching and distance work

Store fields

Error responses

​Query parameters

​Request

​Response

​How matching and distance work

​Store fields

​Error responses

Query parameters

Request

Response

How matching and distance work

Store fields

Error responses