pelias
/
documentation
mirror of https://github.com/pelias/documentation.git
1
0
Fork 0
Code Issues Releases Activity
Browse Source

added reverse documentation

pull/4/head^2^2^2
Stephen Hess 9 years ago
parent
9c6afab8b1
commit
70121af61e
1 changed files with 112 additions and 0 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 112
      getting-started/003-reverse.md

112
getting-started/003-reverse.md
Unescape View File

@ -1,2 +1,114 @@
Reverse Geocoding
==================
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.
With reverse geocoding, you can lookup all sorts of information about a point on a map, including:
* addresses
* points of interest (businesses, museums, parks, etc)
* neighborhoods
* cities
* states
* postal areas
* countries
So [go get an API key](https://mapzen.com/developers) and let's get started.
## 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:
>[/v1/reverse?api\_key={YOUR-KEY}&___point.lat=48.858268___&___point.lon=2.294471___](https://search.mapzen.com/v1/reverse?api_key={YOUR_API_KEY}&point.lat=48.858268&point.lon=2.294471)
Notice that the first result is the Eiffel Tower (well, Tour Eiffel). It's as easy as that! The output is the standard GeoJSON format.
## Advanced Usage
Like other entry points, reverse geocoding can use additional parameters to refine results.
### 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:
>[/v1/reverse?api\_key={YOUR-KEY}&point.lat=48.858268&point.lon=2.294471&___size=1___](https://search.mapzen.com/v1/reverse?api_key={YOUR_API_KEY}&point.lat=48.858268&point.lon=2.294471&size=1)
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
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:
>[/v1/reverse?api\_key={YOUR-KEY}&point.lat=48.858268&point.lon=2.294471&___sources=osm___](https://search.mapzen.com/v1/reverse?api_key={YOUR_API_KEY}&point.lat=48.858268&point.lon=2.294471&sources=osm)
For more information on the data each source provides, see [this link](http://source link).
### 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):
>[/v1/reverse?api\_key={YOUR-KEY}&point.lat=48.858268&point.lon=2.294471&___layers=locality___](https://search.mapzen.com/v1/reverse?api_key={YOUR_API_KEY}&point.lat=48.858268&point.lon=2.294471&layers=locality)
For more information on what the different layers mean, see [this link](http://layers link).
### 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:
>[/v1/reverse?api\_key={YOUR-KEY}&point.lat=47.270521&point.lon=9.530846&___boundary.country=LIE___](https://search.mapzen.com/v1/reverse?api_key={YOUR_API_KEY}&point.lat=47.270521&point.lon=9.530846&boundary.country=LIE)
[ISO 3166-1 alpha-2 and alpha-3 country codes](https://en.wikipedia.org/wiki/ISO_3166-1)
Please note that `UK` is not a valid ISO 3166-1 alpha-2 country code.
## Confidence Scores
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`.
| meters from `point.lat`/`point.lon` | Confidence Score |
| < 1 | 1.0 |
| < 10 | 0.9 |
| < 100 | 0.8 |
| < 250 | 0.7 |
| < 1000 | 0.6 |
| >= 1000 | 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.
parameter | value | required | default | example |
--- | --- | --- | --- |
`api_key` | string | yes | none | [get yours here](https://mapzen.com/developers) |
`point.lat` | floating point number | yes | none | 48.858268 |
`point.lon` | floating point number | yes | none | 2.294471 |
`size` | integer | no | 10 | 3 |
`layers` | comma-delimited string array | no | none (all layers) | `oa,gn` |
`sources` | comma-delimited string array | no | none (all sources) | `address,locality` |
`boundary.country` | ISO-3166 alpha-2 or alpha-3 | no | none | `FR`
## Example Requests
This section shows how the various parameters can be combined to form complex use cases.
### 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
>[/v1/reverse?api\_key={YOUR-KEY}&point.lat=51.5081124&point.lon=-0.0759493&sources=osm](https://search.mapzen.com/v1/reverse?api_key={YOUR_API_KEY}&point.lat=51.5081124&point.lon=-0.0759493&sources=osm)
### Only street addresses near the Tower of London
>[/v1/reverse?api\_key={YOUR-KEY}&point.lat=51.5081124&point.lon=-0.0759493&layers=address](https://search.mapzen.com/v1/reverse?api_key={YOUR_API_KEY}&point.lat=51.5081124&point.lon=-0.0759493&layers=address)
### Only OpenStreetMap street addresses near the Tower of London
>[/v1/reverse?api\_key={YOUR-KEY}&point.lat=51.5081124&point.lon=-0.0759493&layers=address&sources=osm](https://search.mapzen.com/v1/reverse?api_key={YOUR_API_KEY}&point.lat=51.5081124&point.lon=-0.0759493&layers=address&sources=osm)
### Only the first OpenStreetMap address near the Tower of London
>[/v1/reverse?api\_key={YOUR-KEY}&point.lat=51.5081124&point.lon=-0.0759493&layers=address&sources=osm&size=1](https://search.mapzen.com/v1/reverse?api_key={YOUR_API_KEY}&point.lat=51.5081124&point.lon=-0.0759493&layers=address&sources=osm&size=1)

Write Preview
Loading…
Cancel
Save