Skip to main content
GET
/
stores
/
nearby
List nearby stores
curl --request GET \
  --url https://api.example.com/stores/nearby
{
  "data": [
    {
      "id": "downtown-kitchen",
      "uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Downtown Kitchen",
      "status": "ACTIVE",
      "timezone": "America/Guayaquil",
      "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."
      },
      "channels": {
        "APP": {
          "id": "app",
          "uid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
          "name": "Mobile app",
          "fulfillment": {
            "DELIVERY": {
              "uid": "c3d4e5f6-a7b8-9012-cdef-123456789012",
              "id": "delivery",
              "type": "DELIVERY",
              "name": "Delivery",
              "availability": {
                "status": "OPEN",
                "schedules": [{
                  "monday": { "start_time": "10:00:00", "end_time": "23:00:00" },
                  "tuesday": { "start_time": "10:00:00", "end_time": "23:00:00" },
                  "wednesday": { "start_time": "10:00:00", "end_time": "23:00:00" },
                  "thursday": { "start_time": "10:00:00", "end_time": "23:00:00" },
                  "friday": { "start_time": "10:00:00", "end_time": "23:00:00" }
                }]
              }
            }
          }
        }
      }
    },
    {
      "id": "north-plaza",
      "uid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "name": "North Plaza",
      "status": "ACTIVE",
      "timezone": "America/Guayaquil",
      "location": {
        "latitude": -2.1523,
        "longitude": -79.9021,
        "address_line_1": "Av. Francisco de Orellana 890",
        "city": "Guayaquil",
        "country": "Ecuador",
        "postal_code": "090150",
        "business_name": "North Plaza S.A."
      },
      "channels": {
        "APP": {
          "id": "app",
          "uid": "c3d4e5f6-a7b8-9012-cdef-123456789012",
          "name": "Mobile app",
          "fulfillment": {
            "PICKUP": {
              "uid": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
              "id": "pickup",
              "type": "PICKUP",
              "name": "Pickup",
              "availability": {
                "status": "OPEN",
                "schedules": [{
                  "monday": { "start_time": "09:00:00", "end_time": "21:00:00" },
                  "saturday": { "start_time": "10:00:00", "end_time": "20:00:00" },
                  "sunday": { "start_time": "10:00:00", "end_time": "20:00:00" }
                }]
              }
            }
          }
        }
      }
    }
  ]
}
Returns stores sorted by distance from a reference point. Use this endpoint when the customer shares their location and you need the closest stores up to a given limit — for example, a map view or a “nearest location” picker.
Requires a Fire spark access token obtained through token exchange. For a full paginated catalog, use list stores.

​
Headers

HeaderRequiredDescription
x-brand-idNoFilter stores by brand. External brand identifier — alphanumeric characters, _, and - only. 1–64 characters. When omitted, all stores for the merchant are returned.

​
Query parameters

ParameterRequiredDescription
latitudeYesReference latitude. Between -90 and 90.
longitudeYesReference longitude. Between -180 and 180.
limitYesMaximum number of stores to return. 1–100.

​
Request

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

​
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",
      "name": "Downtown Kitchen",
      "status": "ACTIVE",
      "timezone": "America/Guayaquil",
      "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."
      },
      "channels": {
        "APP": {
          "id": "app",
          "uid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
          "name": "Mobile app",
          "fulfillment": {
            "DELIVERY": {
              "uid": "c3d4e5f6-a7b8-9012-cdef-123456789012",
              "id": "delivery",
              "type": "DELIVERY",
              "name": "Delivery",
              "availability": {
                "status": "OPEN",
                "schedules": [{
                  "monday": { "start_time": "10:00:00", "end_time": "23:00:00" },
                  "tuesday": { "start_time": "10:00:00", "end_time": "23:00:00" },
                  "wednesday": { "start_time": "10:00:00", "end_time": "23:00:00" },
                  "thursday": { "start_time": "10:00:00", "end_time": "23:00:00" },
                  "friday": { "start_time": "10:00:00", "end_time": "23:00:00" }
                }]
              }
            }
          }
        }
      }
    },
    {
      "id": "north-plaza",
      "uid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "name": "North Plaza",
      "status": "ACTIVE",
      "timezone": "America/Guayaquil",
      "location": {
        "latitude": -2.1523,
        "longitude": -79.9021,
        "address_line_1": "Av. Francisco de Orellana 890",
        "city": "Guayaquil",
        "country": "Ecuador",
        "postal_code": "090150",
        "business_name": "North Plaza S.A."
      },
      "channels": {
        "APP": {
          "id": "app",
          "uid": "c3d4e5f6-a7b8-9012-cdef-123456789012",
          "name": "Mobile app",
          "fulfillment": {
            "PICKUP": {
              "uid": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
              "id": "pickup",
              "type": "PICKUP",
              "name": "Pickup",
              "availability": {
                "status": "OPEN",
                "schedules": [{
                  "monday": { "start_time": "09:00:00", "end_time": "21:00:00" },
                  "saturday": { "start_time": "10:00:00", "end_time": "20:00:00" },
                  "sunday": { "start_time": "10:00:00", "end_time": "20:00:00" }
                }]
              }
            }
          }
        }
      }
    }
  ]
}

​
How distance is calculated

Fire spark ranks stores by straight-line distance from the provided coordinates to each store’s location.latitude and location.longitude. Delivery coverage zones are not applied at this stage — check channels[channel].fulfillment[type].coverage_zones after the customer selects a store.
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

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