Skip to main content
GET
/
location
Find Merchant Locations
curl --request GET \
  --url https://api.satsuma.ai/location \
  --header 'Authorization: <api-key>'
{
  "data": [
    {
      "id": "<string>",
      "merchant_id": "<string>",
      "name": "<string>",
      "description": "<string>",
      "type": "Store",
      "address": {
        "street_number": "<string>",
        "street_name": "<string>",
        "street_address": "<string>",
        "street_address_detail": "<string>",
        "city": "<string>",
        "region": "<string>",
        "postal_code": "<string>",
        "country": "<string>"
      },
      "phone_number": "<string>"
    }
  ],
  "messages": [
    {
      "context": "<string>",
      "level": "Information",
      "text": "<string>",
      "data": {}
    }
  ]
}

Authorizations

​
Authorization
string
header
required

API Key authentication

Query Parameters

​
query
string

Free-text search query to match against location names, addresses, merchant names, or location identifiers

Example:

"Whole Foods Market"

​
type
enum<string>[]

List of location types to filter search results. Restricts search to specified location types only. Types include Store (retail locations) and Warehouse (fulfillment centers).

​
size
integer
default:25

Maximum number of locations to return in a single response. Used for pagination control

Required range: 1 <= x <= 100
Example:

25

​
page
integer
default:1

Page number for paginated results, starting from 1. Used with 'size' parameter for pagination

Required range: x >= 1
Example:

1

​
latitude
number
required

Geographic latitude coordinate for proximity search. Must be a valid latitude between -90 and 90 degrees

Required range: -90 <= x <= 90
Example:

37.7749

​
longitude
number
required

Geographic longitude coordinate for proximity search. Must be a valid longitude between -180 and 180 degrees

Required range: -180 <= x <= 180
Example:

-122.4194

​
distance
string
default:10mi

Search radius distance from the provided coordinates. Format: number followed by unit (mi for miles, km for kilometers)

Example:

"10mi"

Response

200 - application/json

OK

​
data
object[]
​
messages
object[]
⌘I