Reverse geocoding is used for finding places or addresses near a latitude, longitude pair—like clicking on a map to see what's there when the map doesn't show it otherwise. For example, picture a map showing building outlines but no labels, then clicking on a building and being shown the name of the business. That's reverse geocoding.
With reverse geocoding with Pelias, you can look up all sorts of information about points on a map, including:
- points of interest (businesses, museums, parks, and so on)
- postal areas
To get started with reverse geocoding, you need a latitude, longitude pair in decimal degrees specified with the parameters
point.lon, respectively. For example, the Eiffel Tower in Paris, France, is located at
48.858268,2.294471. The reverse geocode query for this would be:
The output is the standard GeoJSON format.
Reverse geocoding parameters
Like other queries with Pelias, reverse geocoding has optional, additional parameters you can use to refine results.
||floating point number||yes||none||
||floating point number||yes||none||
||floating point number||no||1||
||comma-delimited string array||no||none (all layers)||
||comma-delimited string array||no||none (all sources)||
||ISO-3166 alpha-2 or alpha-3||no||none||
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
The default value for
10 and the maximum value is
40. Specifying a value greater than
40 will override to
40 and return a warning in the response metadata.
Filter by data source
By default, reverse geocoding returns results from any data source available to Pelias. To filter results by source, specify one or more valid source names in a comma-delimited list using the
sources parameter. For example, the following request returns only results from OpenStreetMap:
|Who's on First||
Filter by layers (data type)
Without specifying further, reverse geocoding doesn't restrict results to a particular type (street, venue, neighbourhood, and so on). If your application is only concerned with, say, which city a latitude, longitude is closest to, then use the
layers parameter. For example, the following request returns only results that are localities (cities and towns):
Here are all the supported layers and their meanings.
||points of interest, businesses, things with walls|
||places with a street address|
||places that issue passports, nations, nation-states|
||a related group of regions. Mostly in Europe|
||states and provinces|
||a related group of counties. Mostly in Europe.|
||official governmental area; usually bigger than a locality, almost always smaller than a region|
||towns, hamlets, cities|
||local administrative boundaries|
||a local administrative boundary, currently only used for New York City|
||social communities, neighbourhoods|
||alias for simultaneously using all administrative layers (everything except
Filter by country
If you are performing a reverse geocode near a country boundary, and are only interested in results from one country and not the other, you can specify a country code. You can set the
boundary.country parameter value to the alpha-2 or alpha-3 ISO-3166 country code. For example, the latitude,longitude pair
47.270521,9.530846 is on the boundary of Austria, Liechtenstein, and Switzerland. Without specifying a
boundary.country, the first 10 results returned may come from all three countries. By including
boundary.country=LIE, all 10 results will be from Liechtenstein. Here's the request in action:
UK is not a valid ISO 3166-1 alpha-2 country code.
Distance and confidence scores for the results
Each result returned has a distance from the query point (in meters) and an associated confidence score. Confidence scores are calculated based on the distance from the result to the supplied
point.lon. Confidence scoring for reverse geocode results is likely to change with different data sources and layers.
This section shows how the various parameters can be combined to form complex use cases.
- All results near the Tower of London
- Only OpenStreetMap results near the Tower of London
- Only street addresses near the Tower of London
- Only OpenStreetMap street addresses near the Tower of London
- Only the first OpenStreetMap address near the Tower of London