Reverse Geocoding API
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