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.

Use cases, pricing and how it compares: Address autocomplete API →

No credits consumed · Authentication and account rate limit apply.

POST GET /v1/autocomplete

Request body

application/json · Up to 64 KiB. Unknown fields are rejected. Send your key in x-api-key. With GET, send the same fields as URL query parameters instead; nested fields use dots, such as focus.lat. Unknown or repeated parameters return 400. The key still goes in a header.

text string required

Address 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, unknown or repeated query parameters, unsupported Connect protocol version, oversized body, invalid query or unverifiable client address.
401	unauthenticated	The API key is missing, invalid, expired or revoked.
403	permission_denied	A browser key was used without an Origin header, from an origin not in its allowed list, or over gRPC.
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.

Error handling and retries →