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.
1 credit per successful call · 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.
id string requiredOpaque 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, 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. |