List nearby stores

curl --request GET \
  --url https://firespark.cloud/api/storefront/v1/stores/nearby \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://firespark.cloud/api/storefront/v1/stores/nearby', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://firespark.cloud/api/storefront/v1/stores/nearby",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://firespark.cloud/api/storefront/v1/stores/nearby"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://firespark.cloud/api/storefront/v1/stores/nearby")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "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" }] }
]
              }
            }
          }
        }
      }
    }
  ]
}

GET

stores

nearby

List nearby stores

curl --request GET \
  --url https://firespark.cloud/api/storefront/v1/stores/nearby \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://firespark.cloud/api/storefront/v1/stores/nearby', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://firespark.cloud/api/storefront/v1/stores/nearby",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://firespark.cloud/api/storefront/v1/stores/nearby"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://firespark.cloud/api/storefront/v1/stores/nearby")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "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" }] }
]
              }
            }
          }
        }
      }
    }
  ]
}

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.
`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",
      "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

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.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

brand_id

string

Filter stores by brand. When omitted, all stores for the merchant are returned.

Required string length: 1 - 64

Pattern: ^[a-zA-Z0-9_-]+$

latitude

number

required

Required range: -90 <= x <= 90

longitude

number

required

Required range: -180 <= x <= 180

limit

integer

Required range: x <= 50

Response

200 - application/json

data

object[]

Show child attributes

List stores Get store

API Documentation

Endpoints

Guides

Resources

List nearby stores

Query parameters

Request

Response

How matching and distance work

Store fields

Error responses

Authorizations

Query Parameters

Response

​Query parameters

​Request

​Response

​How matching and distance work

​Store fields

​Error responses

Authorizations

Query Parameters

Response

Query parameters

Request

Response

How matching and distance work

Store fields

Error responses