Reverse Geocoding API
Deprecated — do not use for new development
This is the v1 reverse geocoding endpoint. It is still served and existing integrations keep working, but it is no longer the recommended API and will not receive new features.
For anything new, use v2. v2 adds session-based billing (materially cheaper for as-you-type search), richer results, and a suggest → retrieve flow.
The easiest path is one of the geocoding SDKs, which handle sessions, debouncing and error typing for you.
The Reverse Geocoding API takes a latitude/longitude point and returns the closest address or place.
| Parameter | Type | Req | Example | Description |
|---|---|---|---|---|
point.lat | float | ✅ | 48.858268 | Latitude of the point to reverse geocode. |
point.lon | float | ✅ | 2.294471 | Longitude of the point to reverse geocode. |
token | string (auth token) | ✅ | abcd1234 | Required authentication token, otherwise request returns 401 Token required. |
boundary.circle.lat | float | ❌ | 48.858268 | Circle boundary center latitude. |
boundary.circle.lon | float | ❌ | 2.294471 | Circle boundary center longitude. |
boundary.circle.radius | float | ❌ | 35 | Circle radius (in kilometers). (Note: ignored for coarse reverse lookups) |
sources | string (comma-separated) | ❌ | oa,gn | Data sources to include (oa=openaddresses, gn=geonames). |
layers | string (comma-separated) | ❌ | address,locality | Feature layers to include. |
boundary.country | string (comma-separated) | ❌ | FR,GBR | ISO country codes to limit search. |
boundary.gid | Pelias gid | ❌ | whosonfirst:region:85683497 | Restrict results to a specific boundary by gid. |
size | integer | ❌ | 3 | Number of results to return. |
Example
bash
GET https://gateway.mapmetrics-atlas.net/reverse-geocode/?point.lat=48.858268&point.lon=2.294471&boundary.circle.radius=7&size=3&layers=locality,address&sources=oa,gn&boundary.country=FR&boundary.gid=whosonfirst:region:85683497&token=YOUR_API_KEYExample Response
json
{
"geocoding": {
"version": "0.2",
"attribution": "http://localhost:4000/attribution",
"query": {
"layers": [
"locality",
"address"
],
"sources": [
"openaddresses",
"geonames"
],
"size": 3,
"private": false,
"point.lat": 48.858268,
"point.lon": 2.294471,
"boundary.circle.radius": 5,
"boundary.circle.lat": 48.858268,
"boundary.circle.lon": 2.294471,
"boundary.country": [
"FRA"
],
"boundary.gid": "85683497",
"lang": {
"name": "English",
"iso6391": "en",
"iso6393": "eng",
"via": "default",
"defaulted": true
},
"querySize": 6
},
"engine": {
"name": "Pelias",
"author": "Mapzen",
"version": "1.0"
},
"timestamp": 1755669190951
},
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
2.294511,
48.857747
]
},
"properties": {
"id": "fr/countrywide:3edd29e1f32d7408",
"gid": "openaddresses:address:fr/countrywide:3edd29e1f32d7408",
"layer": "address",
"source": "openaddresses",
"source_id": "fr/countrywide:3edd29e1f32d7408",
"country_code": "FR",
"name": "12 Avenue Pierre Loti",
"housenumber": "12",
"street": "Avenue Pierre Loti",
"postalcode": "75007",
"confidence": 0.8,
"distance": 0.058,
"accuracy": "point",
"country": "France",
"country_gid": "whosonfirst:country:85633147",
"country_a": "FRA",
"macroregion": "Ile-of-France",
"macroregion_gid": "whosonfirst:macroregion:404227465",
"macroregion_a": "IF",
"region": "Paris",
"region_gid": "whosonfirst:region:85683497",
"region_a": "VP",
"localadmin": "Paris",
"localadmin_gid": "whosonfirst:localadmin:1159322569",
"locality": "Paris",
"locality_gid": "whosonfirst:locality:101751119",
"borough": "7th Arrondissement",
"borough_gid": "whosonfirst:borough:1158894245",
"neighbourhood": "Gros Caillou",
"neighbourhood_gid": "whosonfirst:neighbourhood:85873841",
"continent": "Europe",
"continent_gid": "whosonfirst:continent:102191581",
"label": "12 Avenue Pierre Loti, Paris, France"
}
},
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
2.293651,
48.858317
]
},
"properties": {
"id": "fr/countrywide:afc231c551e25607",
"gid": "openaddresses:address:fr/countrywide:afc231c551e25607",
"layer": "address",
"source": "openaddresses",
"source_id": "fr/countrywide:afc231c551e25607",
"country_code": "FR",
"name": "2 Avenue Pierre Loti",
"housenumber": "2",
"street": "Avenue Pierre Loti",
"postalcode": "75007",
"confidence": 0.8,
"distance": 0.06,
"accuracy": "point",
"country": "France",
"country_gid": "whosonfirst:country:85633147",
"country_a": "FRA",
"macroregion": "Ile-of-France",
"macroregion_gid": "whosonfirst:macroregion:404227465",
"macroregion_a": "IF",
"region": "Paris",
"region_gid": "whosonfirst:region:85683497",
"region_a": "VP",
"localadmin": "Paris",
"localadmin_gid": "whosonfirst:localadmin:1159322569",
"locality": "Paris",
"locality_gid": "whosonfirst:locality:101751119",
"borough": "7th Arrondissement",
"borough_gid": "whosonfirst:borough:1158894245",
"neighbourhood": "Gros Caillou",
"neighbourhood_gid": "whosonfirst:neighbourhood:85873841",
"continent": "Europe",
"continent_gid": "whosonfirst:continent:102191581",
"label": "2 Avenue Pierre Loti, Paris, France"
}
},
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
2.294373,
48.858816
]
},
"properties": {
"id": "fr/countrywide:c15503f350dea57a",
"gid": "openaddresses:address:fr/countrywide:c15503f350dea57a",
"layer": "address",
"source": "openaddresses",
"source_id": "fr/countrywide:c15503f350dea57a",
"country_code": "FR",
"name": "3 Avenue Anatole France",
"housenumber": "3",
"street": "Avenue Anatole France",
"postalcode": "75007",
"confidence": 0.8,
"distance": 0.061,
"accuracy": "point",
"country": "France",
"country_gid": "whosonfirst:country:85633147",
"country_a": "FRA",
"macroregion": "Ile-of-France",
"macroregion_gid": "whosonfirst:macroregion:404227465",
"macroregion_a": "IF",
"region": "Paris",
"region_gid": "whosonfirst:region:85683497",
"region_a": "VP",
"localadmin": "Paris",
"localadmin_gid": "whosonfirst:localadmin:1159322569",
"locality": "Paris",
"locality_gid": "whosonfirst:locality:101751119",
"borough": "7th Arrondissement",
"borough_gid": "whosonfirst:borough:1158894245",
"neighbourhood": "Gros Caillou",
"neighbourhood_gid": "whosonfirst:neighbourhood:85873841",
"continent": "Europe",
"continent_gid": "whosonfirst:continent:102191581",
"label": "3 Avenue Anatole France, Paris, France"
}
}
],
"bbox": [
2.293651,
48.857747,
2.294511,
48.858816
]
}Description
With reverse geocoding with Pelias, you can look up all sorts of information about points on a map,
Size
A basic parameter for filtering is size, which is used to limit the number of results returned. In the earlier request that returned the Eiffel Tower (or 'Tour Eiffel', to be exact), notice that other results were returned including "Bureau de Gustave Eiffel" (a museum) and "Le Jules Verne" (a restaurant). To limit a reverse geocode to only the first result, pass the size parameter:
/reverse?point.lat=48.858268&point.lon=2.294471&size=1