API reference
Autocomplete
Complete an address or place while the last word is still unfinished. Free of credit charges, authenticated and rate-limited, including with zero credits. Returns labels and opaque IDs without coordinates or bounding boxes. Call /v1/retrieve with a selected ID to get its location for one credit. Filter by country, bias toward a position, or include notable landmarks linked to Wikidata.
No credits consumed · Authentication and account rate limit apply.
Request body
application/json · Up to 64 KiB. Unknown fields are
rejected. Send your key in x-api-key.
text string requiredAddress or place prefix. The last word may be unfinished. Trimmed; cannot be blank.
Up to 500 characters.
countryCode string Optional ISO 3166-1 alpha-2 country filter, for example dk.
focus SuggestFocus Optional: the user's position. Places near it rank higher.
Nested fields
lat number Latitude of the position to bias results toward.
lon number Longitude of the position to bias results toward.
scaleKm integer Distance scale of the location bias, in kilometres. Omitted or 0 uses 100.
Default: 100. Range: 0–20000.
includeLandmarks boolean Include notable OSM landmarks linked to Wikidata. Coverage is uneven; this is not a general business directory.
Default: false.
limit integer Maximum suggestions. Omitted or 0 uses the default of 5.
Default: 5. Range: 0–15.
Response 200
Default scalar values and empty lists may be omitted. Treat absent lists as empty and absent scalars as their protobuf defaults.
suggestions Suggestion[] Ranked suggestions.
Nested fields
category string Landmarks only: airport, station, attraction, museum, university, hospital or stadium. Empty or omitted otherwise.
countryCode string ISO 3166-1 alpha-2 country code.
displayName string Human-readable label.
id string Opaque identifier, stable for one index.
type string country, region, county, municipality, city, town, village, neighbourhood, street, address, postcode or landmark.
unverifiedSuffix string User-entered floor/unit text, also kept in display_name. Not verified: id and point still identify the building. Empty when no suffix interpretation was needed.
Errors
| HTTP | Code | Meaning |
|---|---|---|
| 400 | invalid_argument | Invalid JSON, unknown fields, unsupported Connect protocol version, oversized body, invalid query or unverifiable client address. |
| 401 | unauthenticated | The API key is missing, invalid or revoked. |
| 404 | not_found | The suggestion ID is unknown or belongs to an older index. Request autocomplete suggestions again. |
| 429 | resource_exhausted | The per-second limit was reached, a billable operation has no remaining credits, or the client IP is temporarily locked after failed API authentication. Autocomplete and regions remain available with zero credits. IP lockouts include Retry-After and also block valid keys from that IP until expiry. |
| 503 | unavailable | The API is starting or the geocoder is temporarily unavailable. |