Reverse geocoding

Coordinates in, the nearest address out, or the locality, region or country if that is all you want.

Parameters

Example

$ curl -H "X-API-Key: YOUR_KEY" "https://api.mygeocode.com/v1/reverse?lat=41.8902&lon=12.4922&lang=it"

const url = new URL("https://api.mygeocode.com/v1/reverse");
url.searchParams.set("lat", 41.8902);
url.searchParams.set("lon", 12.4922);
url.searchParams.set("lang", "it");

const { result } = await (await fetch(url, { headers: { "X-API-Key": "YOUR_KEY" } })).json();
console.log(result ? result.formatted : "nothing nearby");

import requests

r = requests.get("https://api.mygeocode.com/v1/reverse",
                 params={"lat": 41.8902, "lon": 12.4922, "lang": "it"}, headers={"X-API-Key": "YOUR_KEY"}, timeout=10)
result = r.json()["result"]
print(result["formatted"] if result else "nothing nearby")

{
  "status": "ok",
  "lat": 41.8902,
  "lon": 12.4922,
  "result": {
    "formatted": "Piazza del Colosseo 23, 00118 Roma, Italia",
    "lat": 41.891367,
    "lon": 12.491512,
    "distance_m": 142,
    "type": "address",
    "precision": "house",
    "confidence": 0.7,
    "place_id": "oHvVTPHTmCutza8QQ_Vz4W1M_PHkbXNzDA",
    "components": {
      "house_number": "23",
      "road": "Piazza del Colosseo",
      "city": "Roma",
      "state": "Lazio",
      "postcode": "00118",
      "country": "Italia",
      "country_code": "it"
    },
    "bounds": { "north": 41.891867, "south": 41.890869, "east": 12.492014, "west": 12.491015 },
    "codes": {
      "plus_code": "8FHJVFRR+GJ",
      "geohash": "sr2yk604ckf3",
      "mgrs": "33TTG9189240757",
      "maidenhead": "JN61fv83",
      "dms": {
        "lat": "41° 53' 28.9\" N",
        "lon": "12° 29' 29.4\" E"
      },
      "mapcode": "ITA HJ.PV",
      "mapcode_international": "TJLFM.J2LH"
    }
  }
}

Response fields

Notes

• A large distance_m is a signal. A point in a park may be 300 m from the nearest address; in that case showing the neighbourhood is usually better than showing the address.
• level=country answers in about a millisecond and is the cheapest way to answer "which country is this point in".
• Points at sea return the nearest named place while one is a few tens of kilometres away (a city result with a large distance_m, or the country at country level), and null further out at every level.

The same lookup in other providers' formats

If you already have code written against one of these providers, keep it: the drop-in host accepts the same path and parameters and answers in that provider's response shape, with this endpoint behind it. See how the drop-ins work.

Bulk lookups

Post a JSON body to the same path with coords, an array of up to 100 [lat, lon] pairs, and the answer carries a results array with one entry per pair in the order sent. Each entry counts as one request, and a batch larger than what is left of the allowance is refused whole.

$ curl -X POST "https://api.mygeocode.com/v1/reverse" -H "Content-Type: application/json" -d '{"coords": [[52.5163, 13.3777], [47.3769, 8.5417]]}'

Errors

400 invalid_request when lat or lon is missing or out of range, level is not one of the listed values, radius is not 1 to 5000, or a bulk body has more than 100 pairs or an entry that is not a [lat, lon] pair.