From 70121af61ef12b34f66941f1189439355f668e2a Mon Sep 17 00:00:00 2001 From: Stephen Hess Date: Wed, 23 Sep 2015 16:37:18 -0400 Subject: [PATCH 1/7] added reverse documentation --- getting-started/003-reverse.md | 112 +++++++++++++++++++++++++++++++++ 1 file changed, 112 insertions(+) diff --git a/getting-started/003-reverse.md b/getting-started/003-reverse.md index 298c165..6be785f 100644 --- a/getting-started/003-reverse.md +++ b/getting-started/003-reverse.md @@ -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) From 383909daa8852d16ec8066d7f585478eed0bf037 Mon Sep 17 00:00:00 2001 From: Stephen Hess Date: Wed, 23 Sep 2015 16:43:10 -0400 Subject: [PATCH 2/7] cleaned up reverse doc --- getting-started/003-reverse.md | 33 +++++++++++++++++---------------- 1 file changed, 17 insertions(+), 16 deletions(-) diff --git a/getting-started/003-reverse.md b/getting-started/003-reverse.md index 6be785f..36f6751 100644 --- a/getting-started/003-reverse.md +++ b/getting-started/003-reverse.md @@ -29,7 +29,7 @@ Like other entry points, reverse geocoding can use additional parameters to refi ### 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: +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) @@ -65,13 +65,14 @@ Please note that `UK` is not a valid ISO 3166-1 alpha-2 country code. 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 | +distance from `point.lat`/`point.lon` | Confidence Score | +--- | --- | +| < 1m | 1.0 | +| < 10m | 0.9 | +| < 100m | 0.8 | +| < 250m | 0.7 | +| < 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. @@ -82,9 +83,9 @@ This section provides a quick reference for parameters applicable to reverse geo 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 | +`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` @@ -93,22 +94,22 @@ parameter | value | required | default | example | This section shows how the various parameters can be combined to form complex use cases. -### All 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 +#### 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 +#### 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 +#### 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 +#### 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) From 9deadd18273c62b08918ed2c1ec7d2e71a96ce9b Mon Sep 17 00:00:00 2001 From: Stephen Hess Date: Wed, 23 Sep 2015 16:45:42 -0400 Subject: [PATCH 3/7] cleaned up tables --- getting-started/003-reverse.md | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/getting-started/003-reverse.md b/getting-started/003-reverse.md index 36f6751..01d60d6 100644 --- a/getting-started/003-reverse.md +++ b/getting-started/003-reverse.md @@ -65,14 +65,14 @@ Please note that `UK` is not a valid ISO 3166-1 alpha-2 country code. 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`. -distance from `point.lat`/`point.lon` | Confidence Score | ---- | --- | -| < 1m | 1.0 | -| < 10m | 0.9 | -| < 100m | 0.8 | -| < 250m | 0.7 | -| < 1km | 0.6 | -| >= 1km | 0.5 | +distance from `point.lat`/`point.lon` | Confidence Score +--- | --- +< 1m | 1.0 +< 10m | 0.9 +< 100m | 0.8 +< 250m | 0.7 +< 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. @@ -80,14 +80,14 @@ Confidence scoring for reverse geocode results is likely to change to take into 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` | +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 From 2f4b36bcff8dc129292066bb0ca44d34d7a3146d Mon Sep 17 00:00:00 2001 From: Stephen Hess Date: Wed, 23 Sep 2015 16:46:38 -0400 Subject: [PATCH 4/7] another attempt at table cleanup --- getting-started/003-reverse.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/getting-started/003-reverse.md b/getting-started/003-reverse.md index 01d60d6..26e18fe 100644 --- a/getting-started/003-reverse.md +++ b/getting-started/003-reverse.md @@ -81,7 +81,7 @@ Confidence scoring for reverse geocode results is likely to change to take into 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` From 6217c93035d88234b56dc5e971ae0b03335831dc Mon Sep 17 00:00:00 2001 From: Stephen Hess Date: Wed, 23 Sep 2015 16:55:11 -0400 Subject: [PATCH 5/7] cleaned up wikipedia links to open new tab --- getting-started/003-reverse.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/getting-started/003-reverse.md b/getting-started/003-reverse.md index 26e18fe..a2cc666 100644 --- a/getting-started/003-reverse.md +++ b/getting-started/003-reverse.md @@ -57,9 +57,9 @@ Let's say you're reverse geocoding close a country boundary but you are only int >[/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 click here for the full list of ISO 3166-1 alpha-2 and alpha-3 country codes. -Please note that `UK` is not a valid ISO 3166-1 alpha-2 country code. +Also note that `UK` is not a valid ISO 3166-1 alpha-2 country code. ## Confidence Scores @@ -80,7 +80,7 @@ Confidence scoring for reverse geocode results is likely to change to take into This section provides a quick reference for parameters applicable to reverse geocoding requests. -parameter | value | required | default | example +parameter | type | required | default | example --- | --- | --- | --- | --- `api_key` | string | yes | none | [get yours here](https://mapzen.com/developers) `point.lat` | floating point number | yes | none | `48.858268` @@ -88,7 +88,7 @@ parameter | value | required | default | example `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` +`boundary.country` | ISO-3166 alpha-2 or alpha-3 | no | none | `FR` ## Example Requests From 6036024c588ffed603f21b34551fe30f89e7f76a Mon Sep 17 00:00:00 2001 From: Stephen Hess Date: Wed, 23 Sep 2015 23:19:37 -0400 Subject: [PATCH 6/7] standardized capitalization --- getting-started/003-reverse.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/getting-started/003-reverse.md b/getting-started/003-reverse.md index a2cc666..45ee1f6 100644 --- a/getting-started/003-reverse.md +++ b/getting-started/003-reverse.md @@ -82,7 +82,7 @@ This section provides a quick reference for parameters applicable to reverse geo parameter | type | required | default | example --- | --- | --- | --- | --- -`api_key` | string | yes | none | [get yours here](https://mapzen.com/developers) +`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` @@ -94,11 +94,11 @@ parameter | type | required | default | example This section shows how the various parameters can be combined to form complex use cases. -#### All 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 +#### 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) From 05e713e02df1b74e9076a04ca7b699fe7d145179 Mon Sep 17 00:00:00 2001 From: Stephen Hess Date: Fri, 25 Sep 2015 17:48:52 -0400 Subject: [PATCH 7/7] added /place documentation --- getting-started/005-place.md | 42 ++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/getting-started/005-place.md b/getting-started/005-place.md index 3db0a70..0d63910 100644 --- a/getting-started/005-place.md +++ b/getting-started/005-place.md @@ -1,2 +1,44 @@ Places ======= + +Place search is for when you have an ID and the source it came from and now you just need the details. + +Once you have [an API key](https://mapzen.com/developers), continue on. + +## The Basics + +A place search requires 3 pieces of information: + +1. source +2. layer +3. id + +Once you have all 3 of those, simply join them together with semicolon and pass in on the ids parameter. + +For example, this /place query looks up the Eiffel Tower in OSM: + +http://pelias.bigdev.mapzen.com/v1/place?api_key=pelias-M7dcnto&ids=osm:venue:5013364 + +## Advanced Usage + +To request more than 1 /place lookup in one request, simply join multiple values together delimited by comma. +For example, this /place query looks up the Eiffel Tower in OSM and `30 West 26th St, New York, NY` in OpenAddresses: + +http://pelias.bigdev.mapzen.com/v1/place?api_key=pelias-M7dcnto&ids=osm:country:5013364,oa:address:65cf57e4eb5548eca9bb548fb1461633 + +The results are returned in the order requested. + +## Caveats + +If you enter a `source:layer:id` combination that cannot be found then the `features` array in the response will continue a different number of elements than the number of requests. This will be most noticeable in multi-id requests since your request may have 3 ids requested but only 2 results returned. The reason for this is that the `features` section of the response is GeoJSON-compliant and there is currently no way to convey an exception condition (not even an empty JSON element, `{}`). For this reason, if your application is dependent upon the results mapping directly to the individual input requests in order, then you'll have to do your own bookkeeping to handle with exception conditions. + +## Valid combinations + +Some combinations of `sources` and `layers` are valid while others aren't. Please use the following table for reference: + +source | layers +--- | --- +`osm` or `openstreetmap` | `venue`, `address` +`oa` or `openaddresses` | `address` +`gn` or `geonames` | `venue`, `address`, `neighbourhood`, `locality`, `county`, `region`, `country`, `coarse` +`qs` or `quattroshapes` | `neighbourhood`, `locality`, `county`, `region`, `country`, `coarse`