API reference

Retrieve suggestion

Retrieve the exact suggestion selected from autocomplete. A successful response costs one credit. IDs are opaque and tied to an index snapshot; a stale or unknown ID returns 404. Request suggestions again after an index update. Unverified floor or unit suffixes are not part of the retrieved building.

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

1 credit per successful call · Authentication and account rate limit apply.

POST GET /v1/retrieve

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.

id string required

Opaque ID returned by autocomplete. Do not parse or construct it.

Up to 256 characters.

Response 200

Default scalar values and empty lists may be omitted. Treat absent lists as empty and absent scalars as their protobuf defaults.

category string

Landmarks only: airport, station, attraction, museum, university, hospital or stadium. Empty for every other type.
countryCode string
displayName string
geoCoordinates GeoCoordinates

The point of the place, street, house, postcode or landmark. Places also carry their bounding box.
Nested fields
- boundingBox BoundingBox
  Nested fields
  
  maxLat number
  
  Northern latitude in degrees.
  
  maxLon number
  
  Eastern longitude in degrees.
  
  minLat number
  
  Southern latitude in degrees.
  
  minLon number
  
  Western longitude in degrees.
- lat number
  
  Latitude in degrees, from -90 to 90. Omission uses the protobuf default of 0.
- lon number
  
  Longitude in degrees, from -180 to 180. Omission uses the protobuf default of 0.
id string

Stable for one index, and opaque: a place, street, house, postcode or landmark.
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 →