API reference

Autocomplete

Suggest addresses and places while a user types.

GET/v1/autocomplete

Send the text a user has typed so far to get matching suggestions. Autocomplete returns the same GeoJSON results as search, including full address fields and coordinates, so you can usually use a suggestion directly without a second request. To fetch a result again later from a stored id, use place lookup.

Headers

Header	Required	Value
apikey	Yes	Your primary API key, or a public browser token

Query parameters

qstringrequired

The text typed so far. The last word can be partial, e.g. 11 Wall.

countrystring

2- or 3-letter country code to restrict suggestions, e.g. US.

nearstring

lat,lon to prefer suggestions near a point, such as the user's location.

bboxstring

minLon,minLat,maxLon,maxLat to restrict suggestions to a box.

typesstring

Comma-separated result types to include, e.g. address.

limitinteger

Maximum suggestions, 1–40. Default 10.

exclude_sourcesstring

Comma-separated source names to omit. See data sources.

The SDKs require country and accept limit from 1 to 10; sessionToken / session_token is SDK-only. See address autocomplete.

Request example

cURL

curl --get "$GEOCODING_BASE_URL/v1/autocomplete" \
  --header "apikey: $GEOCODING_API_KEY" \
  --data-urlencode "q=11 Wall" \
  --data-urlencode "country=US" \
  --data-urlencode "limit=5"

Success response

Show properties.label to the user.

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {"type": "Point", "coordinates": [-74.0113, 40.7074]},
      "properties": {"id": "openaddresses:address:us/ny:1", "label": "11 Wall Street, New York, NY, USA", "type": "address", "...": "..."}
    }
  ]
}

No suggestions returns "features": []. Successful responses include X-Geocoding-Outcome: matched or no_match. Authentication, account rate limits, usage metering, and standard errors apply. Each successful request is metered, so every keystroke you send can add usage. See usage and billing.

Public browser tokens

Use the browser autocomplete client in any frontend library. Workspace admins create pub_ tokens with 1–20 exact allowed origins in the account portal. They work only on GET /v1/autocomplete and GET /v1/place, and require an allowed Origin plus the token in the apikey header. Missing or unlisted origins and other operations return HTTP 403. CORS preflight requests do not need credentials. Bare domains mean HTTPS; list each subdomain and development port separately. No wildcard domains are accepted.

Tokens are public and requests still count toward your rate limits and billing. Non-browser callers can forge Origin headers, so domain restrictions do not make tokens secret. Keep backend and third-party credentials on the server.