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.
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.
latnumberLatitude in degrees, from -90 to 90. Omission uses 0.
lonnumberLongitude in degrees, from -180 to 180. Omission uses 0.
radiusMintegerSearch radius in metres. Omitted or 0 uses 500.
Default:
500. Range: 0–2000.sizeintegerMaximum 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.
resultsReverseResult[]Nearest first. Empty or omitted when nothing is in range.
Nested fields
addressFullAddressNested fields
addressDetailsAddressDetailsNested fields
aerialwaystringaerowaystringallotmentsstringamenitystringboroughstringboundarystringbridgestringcitystringcityBlockstringcityDistrictstringclubstringcommercialstringcontinentstringcountrystringcountryCodestringcountystringcraftstringcroftstringdistrictstringemergencystringfarmstringfarmyardstringhamletstringhighwaystringhistoricstringhouseNamestringhouseNumberstringindustrialstringisolatedDwellingstringlandusestringleisurestringmanMadestringmilitarystringmountainPassstringmunicipalitystringnaturalstringneighbourhoodstringofficestringplacestringpostcodestringprovincestringquarterstringrailwaystringregionstringregionCodesISO3166_2[]ISO 3166-2 codes for the address.
Nested fields
adminLevelintegerAdministrative level.
Range: 0–4294967295.
codestringISO 3166-2 region code.
regionsRegion[]Administrative regions for the address.
Nested fields
adminCodestringISO 3166-2 administrative region code.
adminLevelintegerAdministrative level.
Range: 0–4294967295.
countryCodestringISO 3166-1 alpha-2 country code.
countryNamestringCountry name.
enNamestringEnglish region name.
localNamestringLocal region name.
parentAdminCodestringParent administrative region code, when available.
residentialstringretailstringroadstringshopstringstatestringstateDistrictstringsubdivisionstringsuburbstringtourismstringtownstringtunnelstringvillagestringwaterwaystring
displayNamestringHuman-readable address or place name.
geoCoordinatesGeoCoordinatesNested fields
boundingBoxBoundingBoxNested fields
maxLatnumberNorthern latitude in degrees.
maxLonnumberEastern longitude in degrees.
minLatnumberSouthern latitude in degrees.
minLonnumberWestern longitude in degrees.
latnumberLatitude in degrees, from -90 to 90. Omission uses the protobuf default of 0.
lonnumberLongitude in degrees, from -180 to 180. Omission uses the protobuf default of 0.
goodMatchbooleanTrue for a good match. False or omitted for a partial match, such as a street without the requested house number.
interpolatedbooleanTrue when the house number is not in the data and the point is estimated along the address range its street publishes (United States only). Expect it within a few hundred metres of the real building. Never set together with goodMatch.
distanceMnumberDistance from the requested point, in metres.
layerstringaddress: 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. |