Reverse geocoding is used for finding places near a latitude/longitude pair. Think of it as clicking on a map to see what's there when the map doesn't show it otherwise. For example, picture a map in your mind with building outlines but no labels then clicking on a building and being shown what business is there. That's reverse geocoding.
Reverse geocoding is used for finding places or addresses near a latitude,longitude pair&mdashlike 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, you can lookup all sorts of information about a point on a map, including:
With reverse geocoding with Mapzen Search, you can lookup all sorts of information about points on a map, including:
* addresses
* points of interest (businesses, museums, parks, etc)
* points of interest (businesses, museums, parks, and so on)
* neighborhoods
* cities
* states
* postal areas
* countries
So [go get an API key](https://mapzen.com/developers) and let's get started.
## Basic reverse geocoding search
## The Basics
To get started with reverse geocoding, all you need is an API key and a latitude/longitude pair specified with the parameters `point.lat` and `point.lon`, respectively. For example, the Eiffel Tower in Paris, France is at the latitude/longitude pair `48.858268,2.294471`. The reverse geocode query for this would be:
To get started with reverse geocoding, you need a [free, developer API key](https://mapzen.com/developers) and a latitude,longitude pair in decimal degrees specified with the parameters `point.lat` and `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:
`boundary.country` | <ahref="https://en.wikipedia.org/wiki/ISO_3166-1"target="\_blank">ISO-3166 alpha-2 or alpha-3</a> | no | none | `FR`
### Size
The most basic parameter for filtering is `size` that is used to limit the number of results returned. In the previous 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, just pass the `size` parameter:
A basic parameter for filtering is `size`, which is used to limit the number of results returned. In the previous 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:
The default value for `size` is `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.
The default value for `size` is `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.
### Sources
### Filter by data source
By default, reverse geocoding will return results from any source. 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 OSM:
By default, reverse geocoding returns results from any source available to Mapzen Search. 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:
For more information on the data each source provides, see [this link](http://source link).
***TO DO: Add correct link**** For more information on the data each source provides, see [this link](http://source link).
### Layers
### Filter by layers
Without specifying further, reverse geocoding doesn't restrict results to a particular type (street, venue, neighbourhood, etc). 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):
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):
For more information on what the different layers mean, see [this link](http://layers link).
***TO DO: Add correct link**** For more information on what the different layers mean, see [this link](http://layers link).
### Country
### Filter by country
Let's say you're reverse geocoding close a country boundary but you are only interested in results from one country and not the other. In that case, you would specify the 2- or 3-character ISO code of the country you're interested in to only get those results back. For example, the latitude/longitude pair `47.270521,9.530846` is right on the boundary of Austria, Liechtenstein, and Switzerland. Without specifying a `boundary.country` parameter value, the first 10 results returned would be from all 3 countries. By specifying `boundary.country=LIE`, all 10 results will be from Liechtenstein. Here's the request in action:
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](https://en.wikipedia.org/wiki/ISO_3166-1). 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:
Please click <ahref="https://en.wikipedia.org/wiki/ISO_3166-1"target="\_blank">here</a> for the full list of ISO 3166-1 alpha-2 and alpha-3 country codes.
Also note that `UK` is not a valid ISO 3166-1 alpha-2 country code.
Note that `UK` is not a valid ISO 3166-1 alpha-2 country code.
## Confidence Scores
## Confidence scores for the results
Each result returned has an associated confidence score. Currently confidence scores are calculated based on the distance from the result to the supplied `point.lat` and `point.lon`.
Each result returned has an associated confidence score. Currently confidence scores are calculated based on the distance from the result to the supplied `point.lat` and `point.lon`. Confidence scoring for reverse geocode results is likely to change with different data sources and layers.
distance from `point.lat`/`point.lon` | Confidence Score
Distance from `point.lat`/`point.lon` | Confidence score
--- | ---
< 1m | 1.0
< 10m | 0.9
@ -73,42 +79,21 @@ distance from `point.lat`/`point.lon` | Confidence Score
< 1km | 0.6
>= 1km | 0.5
Confidence scoring for reverse geocode results is likely to change to take into account different data sources and layers.
## Parameters
This section provides a quick reference for parameters applicable to reverse geocoding requests.
#### Only OpenStreetMap results near the Tower of London
* All results near the Tower of London >[/v1/reverse?api\_key={YOUR-KEY}&point.lat=51.5081124&point.lon=-0.0759493](https://search.mapzen.com/v1/reverse?api_key={YOUR_API_KEY}&point.lat=51.5081124&point.lon=-0.0759493)
* Only OpenStreetMap results near the Tower of London
@ -55,15 +55,15 @@ Each item in this list will contain all the information needed to identify it in
## Result count
By default, Mapzen Search results 10 places, unless otherwise specified. If you want a different number of results, set the `size` parameter to the desired number. This example shows returning five results.
By default, Mapzen Search results 10 places, unless otherwise specified. If you want a different number of results, set the `size` parameter to the desired number. This example shows returning only the first result.
rmglennon
9 years ago