Geocoding

Reverse Geocoding

Convert geographic coordinates into human-readable addresses using our geocoding engine.

Reverse geocoding converts geographic coordinates (latitude and longitude) into human-readable addresses and place names.

Try It

Enter your API key to see live map demos.

Don't have one? Get your free API key

Endpoint

GET https://maps.guru/api/v1/geocoding/reverse?point.lat={lat}&point.lon={lon}&key={api_key}

Our geocoding API uses point.lat and point.lon as parameter names — not lat/lng. Make sure to use the correct names.

Authentication

API key required via one of:

Query parameter: ?key=mapx_your_key
Header: Authorization: Bearer mapx_your_key
Header: X-API-Key: mapx_your_key

Parameters

Parameter	Type	Required	Default	Description
`point.lat`	number	Yes	—	Latitude of the point to reverse geocode (-90 to 90)
`point.lon`	number	Yes	—	Longitude of the point to reverse geocode (-180 to 180)
`size`	number	No	10	Maximum results (1–40)
`layers`	string	No	—	Filter by layer: `venue`, `address`, `street`, `neighbourhood`, `locality`, `county`, `region`, `country`, `coarse`, `postalcode`
`sources`	string	No	—	Filter by data source: `osm`, `oa`, `gn`, `wof`
`lang`	string	No	`en`	Response language (BCP 47)

Example Request

Reverse geocode the Eiffel Tower coordinates:

curl "https://maps.guru/api/v1/geocoding/reverse?point.lat=48.8584&point.lon=2.2945&size=1&key=mapx_your_key"

Example Response

Responses are GeoJSON FeatureCollection format:

{
  "geocoding": {
    "version": "0.2",
    "query": {
      "point.lat": 48.8584,
      "point.lon": 2.2945,
      "size": 1
    }
  },
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [2.2945, 48.8584]
      },
      "properties": {
        "id": "way:5013364",
        "gid": "openstreetmap:venue:way/5013364",
        "layer": "venue",
        "source": "openstreetmap",
        "name": "Tour Eiffel",
        "label": "Tour Eiffel, Paris, Île-de-France, France",
        "confidence": 0.98,
        "country": "France",
        "region": "Île-de-France",
        "locality": "Paris",
        "distance": 0.001
      }
    }
  ]
}

The distance property in each feature indicates how far (in kilometres) the result is from the queried point.

Caching

Responses are cached for 24 hours at the edge using Cloudflare KV. The X-Cache response header indicates cache status:

X-Cache: HIT — served from cache
X-Cache: MISS — fetched from the geocoding engine and cached

Layers Reference

Use the layers parameter to restrict results to specific place types:

Layer	Description
`venue`	Points of interest, businesses, landmarks
`address`	Street-level addresses
`street`	Street names
`neighbourhood`	Neighbourhoods and districts
`locality`	Cities and towns
`county`	Counties
`region`	States and provinces
`country`	Countries
`postalcode`	Postal codes
`coarse`	All administrative layers combined

Forward Geocoding (Search)

Convert addresses and place names into geographic coordinates using our geocoding search engine.

Autocomplete

Get real-time type-ahead suggestions as users type.