> ## Documentation Index
> Fetch the complete documentation index at: https://firespark.cloud/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# List nearby stores
> Find the nearest merchant locations from a latitude and longitude.
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](/docs/storefront-api/oauth/exchange/post). For a full paginated catalog,
use [list stores](/docs/storefront-api/stores/get).
## 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. |
| `limit` | Yes | Maximum number of stores to return. 1–100. |
## Request
```bash theme={null}
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](/docs/storefront-api/stores/get), including `cms_template_id` and `cms` when a CMS template is assigned. Only `ACTIVE` stores are included.
```json Success theme={null}
{
"data": [
{
"id": "downtown-kitchen",
"uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"brand_id": "0001",
"organization_id": "11111111-1111-1111-1111-111111111111",
"merchant_id": "22222222-2222-2222-2222-222222222222",
"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": [
{ "day_of_week": "monday", "periods": [{ "start_time": "10:00:00", "end_time": "23:00:00" }] },
{ "day_of_week": "tuesday", "periods": [{ "start_time": "10:00:00", "end_time": "23:00:00" }] },
{ "day_of_week": "wednesday", "periods": [{ "start_time": "10:00:00", "end_time": "23:00:00" }] },
{ "day_of_week": "thursday", "periods": [{ "start_time": "10:00:00", "end_time": "23:00:00" }] },
{ "day_of_week": "friday", "periods": [{ "start_time": "10:00:00", "end_time": "23:00:00" }] }
]
}
}
}
}
}
},
{
"id": "north-plaza",
"uid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"brand_id": "0001",
"organization_id": "11111111-1111-1111-1111-111111111111",
"merchant_id": "22222222-2222-2222-2222-222222222222",
"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": [
{ "day_of_week": "monday", "periods": [{ "start_time": "09:00:00", "end_time": "21:00:00" }] },
{ "day_of_week": "saturday", "periods": [{ "start_time": "10:00:00", "end_time": "20:00:00" }] },
{ "day_of_week": "sunday", "periods": [{ "start_time": "10:00:00", "end_time": "20:00:00" }] }
]
}
}
}
}
}
}
]
}
```
## How matching and distance work
1. **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.
2. **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](/docs/storefront-api/stores/get) 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. |
## OpenAPI
````yaml GET /stores/nearby
openapi: 3.0.1
info:
title: Fire spark Storefront API
description: Customer-facing channel endpoints for Fire spark.
version: 1.0.0
servers:
- url: https://firespark.cloud/api/storefront/v1
security:
- bearerAuth: []
paths:
/stores/nearby:
get:
summary: List nearby stores
parameters:
- in: query
name: brand_id
required: false
schema:
type: string
minLength: 1
maxLength: 64
pattern: ^[a-zA-Z0-9_-]+$
description: >-
Filter stores by brand. When omitted, all stores for the merchant
are returned.
- in: query
name: latitude
required: true
schema:
type: number
minimum: -90
maximum: 90
- in: query
name: longitude
required: true
schema:
type: number
minimum: -180
maximum: 180
- in: query
name: limit
required: false
schema:
type: integer
maximum: 50
responses:
'200':
description: Ok
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Store'
components:
schemas:
Store:
type: object
properties:
id:
type: string
minLength: 1
maxLength: 64
pattern: ^[a-zA-Z0-9_-]+$
uid:
type: string
format: uuid
name:
type: string
status:
type: string
enum:
- ACTIVE
- INACTIVE
location:
type: object
channels:
type: object
additionalProperties: true
securitySchemes:
bearerAuth:
type: http
scheme: bearer
````