Suggest addresses

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/address/suggest' \
--header 'Locally-Api-Token: {{API_TOKEN}}' \
--data-urlencode 'query=720 South Michigan Avenue, Chicago, Illinois'

const response = await fetch(
  'https://www.locally.com/headless/api/1.0/location/address/suggest?query=720+South+Michigan+Avenue,+Chicago,+Illinois',
  {
    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/address/suggest",
    params={"query": "720 South Michigan Avenue, Chicago, Illinois"},
    headers={"Locally-Api-Token": "{{API_TOKEN}}"},
)

print(response.json())

The query value must be URL-encoded. Only results that resolve to a full street address are returned — partial matches such as cities or postal codes are filtered out of suggestions.

Example Response

{
  "success": true,
  "data": {
    "query": "720 South Michigan Avenue, Chicago, Illinois",
    "suggestions": [
      {
        "value": "720 South Michigan Avenue, Chicago, Illinois 60605, United States",
        "postcode": "60605",
        "data": {
          "lat": 41.872985,
          "lng": -87.624588,
          "relevance": 1,
          "address": {
            "address_1": "720 South Michigan Avenue",
            "postcode": "60605",
            "city": "Chicago",
            "state": "Illinois",
            "country": {
              "short_code": "US",
              "name": "United States"
            }
          }
        }
      },
      {
        "value": "720 North Michigan Avenue, Chicago, Illinois 60611, United States",
        "postcode": "60611",
        "data": {
          "lat": 41.895482,
          "lng": -87.624726,
          "relevance": 1,
          "address": {
            "address_1": "720 North Michigan Avenue",
            "postcode": "60611",
            "city": "Chicago",
            "state": "Illinois",
            "country": {
              "short_code": "US",
              "name": "United States"
            }
          }
        }
      }
    ],
    "from": [
      41.8756719,
      -87.6243469
    ],
    "session": {
      "id": "abc999"
    }
  },
  "msg": ""
}

Response Explanation

data.suggestions[].data.relevance — Always 1 on this endpoint: results are pre-filtered to exact street-address matches (rooftop, point, or interpolated geocoding accuracy) rather than ranked by score.
data.suggestions[].data.address — Parsed components of the matched address — address_1, city, state, postcode, and country (ISO short_code plus name) — ready to prefill a delivery-address form.
data.suggestions[].postcode — The suggestion's postal code, duplicated at data.suggestions[].data.address.postcode; an empty string when Mapbox does not return one.
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.
msg — Human-readable envelope message: an empty string on success, the error text when success is false (which also adds an error_code field).