Reverse Geocoding API
Send a latitude and longitude and get the nearest address, with the street, city, region, postcode and country broken out, plus how far the address is from the point you sent. Ask for a coarser answer with level when you only want the city or the country.
Example
$ curl -H "X-API-Key: YOUR_KEY" "https://api.mygeocode.com/v1/reverse?lat=48.8584&lon=2.2945"The point is a few metres from the Eiffel Tower's base. The response is the nearest postal address, and distance_m tells you it is 47 metres away. If the nearest address were 400 metres away, say from a point in a park, you would see that too and could decide to show the district instead.
Add level=city to skip the address and get the locality directly, or level=country for a fast country lookup.
{
"status": "ok",
"lat": 48.8584,
"lon": 2.2945,
"result": {
"formatted": "5 Avenue Anatole France, 75007 Paris, France",
"lat": 48.858821,
"lon": 2.294596,
"distance_m": 47,
"type": "address",
"precision": "house",
"confidence": 0.85,
"place_id": "uaOpXczzaHCkNCaNUcKLUz6vyUB3_IjkyQ",
"components": {
"house_number": "5",
"road": "Avenue Anatole France",
"suburb": "7e arrondissement",
"city": "Paris",
"postcode": "75007",
"country": "France",
"country_code": "fr"
},
"bounds": { "north": 48.859321, "south": 48.858318, "east": 2.295098, "west": 2.294096 },
"codes": {
"plus_code": "8FW4V75V+GR",
"geohash": "u09tunqz7bqg",
"mgrs": "31UDQ4825912001",
"maidenhead": "JN18du56",
"dms": {
"lat": "48° 51' 31.8\" N",
"lon": "2° 17' 40.5\" E"
},
"mapcode": "FRA 4H.QX",
"mapcode_international": "VHPM8.QYF6"
}
}
}What you get back
| Field | Meaning |
|---|---|
result.formatted | The nearest address in that country's format. |
result.lat, result.lon | The position of the address itself, not the point you sent. |
result.distance_m | Metres between your point and the address. A large number means you are not really at an address. |
result.precision | house, street, postcode, city, region or country, depending on what exists near the point in that country. |
result.components | Address parts with the same keys as forward geocoding. |
result.timezone, result.elevation_m, country_info, codes, sun, regions and more | Off by default, each behind its own flag: the time zone (timezone=1), ground height (elevation=1), country facts, sun times, the areas the point lies in and more, or all of them with annotations=1. A house, street or point of interest always carries its location codes, and a city, region or country its population. See annotations. |
result is null | Nothing within 5 km of the point. Open ocean, Antarctica. The status is still ok. |
Where it is used
Labelling GPS points
Turn a device's location into "near 5 Avenue Anatole France" for a log, a receipt or a photo caption. Use distance_m to switch between "at" and "near".
Local defaults
Pre-fill a country, currency or language from the visitor's location with level=country. Pair with IP lookup when you do not have coordinates.
Delivery and field work
Convert where a driver actually stopped into an address and compare it with where the order said to go.
Price and limits
One call, one request. Every account has 2,500 free requests a day, shared by all of its keys; past that, €0.0001 each from prepaid credit, or nothing on an Unlimited key (€50 a month). Pricing. Drop-in hosts answer reverse requests in the Google, Nominatim, Mapbox and other formats.