API reference

Reverse geocoding

Look up the nearest addresses from coordinates. If no house is in range, results may fall back to a street, then a nearby locality. Results are ordered nearest first.

Use cases, pricing and how it compares: Reverse geocoding API →

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

POST GET /v1/reverse

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.

lat number

Latitude in degrees, from -90 to 90. Omission uses 0.
lon number

Longitude in degrees, from -180 to 180. Omission uses 0.
radiusM integer

Search radius in metres. Omitted or 0 uses 500.

Default: 500. Range: 0–2000.
size integer

Maximum results. Omitted or 0 uses 1.

Default: 1. Range: 0–10.

Response 200

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

results ReverseResult[]

Nearest first. Empty or omitted when nothing is in range.
Nested fields
- address FullAddress
  Nested fields
  
  addressDetails AddressDetails
  
  Nested fields
  
  aerialway string
  
  aeroway string
  
  allotments string
  
  amenity string
  
  borough string
  
  boundary string
  
  bridge string
  
  city string
  
  cityBlock string
  
  cityDistrict string
  
  club string
  
  commercial string
  
  continent string
  
  country string
  
  countryCode string
  
  county string
  
  craft string
  
  croft string
  
  district string
  
  emergency string
  
  farm string
  
  farmyard string
  
  hamlet string
  
  highway string
  
  historic string
  
  houseName string
  
  houseNumber string
  
  industrial string
  
  isolatedDwelling string
  
  landuse string
  
  leisure string
  
  manMade string
  
  military string
  
  mountainPass string
  
  municipality string
  
  natural string
  
  neighbourhood string
  
  office string
  
  place string
  
  postcode string
  
  province string
  
  quarter string
  
  railway string
  
  region string
  
  regionCodes ISO3166_2[]
  
  ISO 3166-2 codes for the address.
  
  Nested fields
  
  adminLevel integer
  
  Administrative level.
  
  Range: 0–4294967295.
  
  code string
  
  ISO 3166-2 region code.
  
  regions Region[]
  
  Administrative regions for the address.
  
  Nested fields
  
  adminCode string
  
  ISO 3166-2 administrative region code.
  
  adminLevel integer
  
  Administrative level.
  
  Range: 0–4294967295.
  
  countryCode string
  
  ISO 3166-1 alpha-2 country code.
  
  countryName string
  
  Country name.
  
  enName string
  
  English region name.
  
  localName string
  
  Local region name.
  
  parentAdminCode string
  
  Parent administrative region code, when available.
  
  residential string
  
  retail string
  
  road string
  
  shop string
  
  state string
  
  stateDistrict string
  
  subdivision string
  
  suburb string
  
  tourism string
  
  town string
  
  tunnel string
  
  village string
  
  waterway string
  
  displayName string
  
  Human-readable address or place name.
  
  geoCoordinates GeoCoordinates
  
  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.
  
  goodMatch boolean
  
  True for a good match. False or omitted for a partial match, such as a street without the requested house number.
- distanceM number
  
  Distance from the requested point, in metres.
- layer string
  
  address: a house in range; street: no house in range; locality: neither, so the nearest locality within about 50 km.

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 →