Suggest locations

Request Parameters

🏷️ header · unmarked parameters are query params

Parameter	Type	Required	Description
`Locally-Api-Token` 🏷️	string	Yes	Locally API token must be passed in the header to authenticate the API consumer.
`query`	string	Yes	The input query for address suggestion. This parameter must be URL-encoded.

Example Request

curl --get 'https://www.locally.com/headless/api/1.0/location/suggest' \
--header 'Locally-Api-Token: {{API_TOKEN}}' \
--data-urlencode 'query=chicago'

const response = await fetch('https://www.locally.com/headless/api/1.0/location/suggest?query=chicago', {
  headers: {
    'Locally-Api-Token': '{{API_TOKEN}}'
  }
});

const data = await response.json();

import requests

response = requests.get(
    'https://www.locally.com/headless/api/1.0/location/suggest',
    params={'query': 'chicago'},
    headers={'Locally-Api-Token': '{{API_TOKEN}}'}
)

data = response.json()

Example Response

{
  "success": true,
  "data": {
    "query": "chicago",
    "suggestions": [
      {
        "value": "Chicago, Illinois, United States",
        "postcode": "",
        "data": {
          "lat": 41.875562,
          "lng": -87.624421,
          "relevance": 1
        }
      },
      {
        "value": "Chicagon, Michigan, United States",
        "postcode": "",
        "data": {
          "lat": 46.095231,
          "lng": -88.507357,
          "relevance": 0.96
        }
      }
    ],
    "from": [
      "40.0292888",
      "-105.3100174"
    ],
    "session": {
      "id": "abc999"
    }
  }
}

Response Explanation

data.suggestions[].value — Display label for the suggestion. Pass it, URL-encoded, as location_change_to_string — and its data.lat/data.lng as the path coordinates — when calling Switch session location.
data.suggestions[].data.relevance — Mapbox match confidence from 0 to 1 (1 = exact match). Exact matches are listed first; within each group, results are ordered by distance from from.
data.suggestions[].postcode — Always an empty string on this endpoint; postal codes are only populated by Suggest addresses.
data.from — [lat, lng] the API currently associates with the caller (session location or IP geolocation, defaulting to Boulder, CO when unknown); suggestions are proximity-biased toward this point. Values may be strings or numbers.
data.session.id — Session ID returned on every response. Pass it as the Locally-Api-Session-Id header on later calls to persist location and cart state; expired or missing IDs are replaced with fresh ones.