From bbdf753c0fa4a2b55c99b14414c96606c17c5445 Mon Sep 17 00:00:00 2001 From: Julian Simioni Date: Tue, 29 Sep 2015 15:53:02 -0400 Subject: [PATCH 01/10] Whitespace --- place.md | 8 ++++---- reverse.md | 12 ++++++------ search.md | 2 +- 3 files changed, 11 insertions(+), 11 deletions(-) diff --git a/place.md b/place.md index 15b2771..82a84c7 100644 --- a/place.md +++ b/place.md @@ -1,6 +1,6 @@ # Search an ID to get details on a place -When you know an identification number and the source it came from, you can use Mapzen Search to get details on the location. +When you know an identification number and the source it came from, you can use Mapzen Search to get details on the location. To get started with a place search, you need a [free, developer API key](https://mapzen.com/developers) and these three pieces of information: @@ -8,7 +8,7 @@ To get started with a place search, you need a [free, developer API key](https:/ * layer - the type of place, such as a venue, address, country. * id - the identification number of the item -If you have all of those, join them together with semicolon and pass them in with the `ids` parameter. +If you have all of those, join them together with semicolon and pass them in with the `ids` parameter. For example, this `/place` query looks up the Eiffel Tower in OSM: @@ -24,11 +24,11 @@ To search for more than one `/place` in a request, join multiple values together https://search.mapzen.com/v1/place?api_key=search-XXXXXXX&ids=osm:country:5013364,oa:address:65cf57e4eb5548eca9bb548fb1461633 -The results are returned in the order requested. +The results are returned in the order requested. ***From Rhonda -- is there another example where you might do multiple requests at the same time...in other words, more related locations?*** -Keep in mind that if you enter a `source:layer:id` combination that cannot be found, then the `features` array in the response contains a different number of elements than the number of requests. This will be most noticeable in requests with multiple IDs, as your request may have three IDs requested but only two 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 exception conditions. +Keep in mind that if you enter a `source:layer:id` combination that cannot be found, then the `features` array in the response contains a different number of elements than the number of requests. This will be most noticeable in requests with multiple IDs, as your request may have three IDs requested but only two 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 exception conditions. ## Valid combinations of place searches diff --git a/reverse.md b/reverse.md index ad3b9fe..fa47b7f 100644 --- a/reverse.md +++ b/reverse.md @@ -1,6 +1,6 @@ # 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. +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 with Mapzen Search, you can look up all sorts of information about points on a map, including: @@ -20,7 +20,7 @@ Notice that the first result is the Eiffel Tower (well, Tour Eiffel). The output reverse geocoding -Similar to other queries with Mapzen Search, reverse geocoding has optional, additional parameters you can use to refine results. +Similar to other queries with Mapzen Search, reverse geocoding has optional, additional parameters you can use to refine results. Parameter | Type | Required | Default | Example --- | --- | --- | --- | --- @@ -38,7 +38,7 @@ A basic parameter for filtering is `size`, which is used to limit the number of >[/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. +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. ### Filter by data source @@ -62,11 +62,11 @@ If you are performing a reverse geocode near a country boundary, and are only in >[/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) -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 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`. Confidence scoring for reverse geocode results is likely to change with different data sources and layers. +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 --- | --- @@ -79,7 +79,7 @@ Distance from `point.lat`/`point.lon` | Confidence score ## Example requests -This section shows how the various parameters can be combined to form complex use cases. +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=search-XXXXXXX&point.lat=51.5081124&point.lon=-0.0759493](https://search.mapzen.com/v1/reverse?api_key=search-XXXXXXX&point.lat=51.5081124&point.lon=-0.0759493) diff --git a/search.md b/search.md index 76cd8a7..a52dd0b 100644 --- a/search.md +++ b/search.md @@ -8,7 +8,7 @@ Making the leap from text to coordinates is an intricate and challenging process All Mapzen Search requests share the same format: - ``` +``` https://search.mapzen.com/v1/search?text=London&api_key=search-xxxxxx \___/ \_______________/\__/\_____/\__________/\___________________/ | | / | | | From 9e2b47a4ba78fffc3a49b299af976eba3ba652f9 Mon Sep 17 00:00:00 2001 From: Julian Simioni Date: Tue, 29 Sep 2015 15:53:26 -0400 Subject: [PATCH 02/10] Remove an extra comma --- api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api.md b/api.md index e7c58b3..107d7b7 100644 --- a/api.md +++ b/api.md @@ -2,7 +2,7 @@ ## Obtain an API key -To use the Mapzen Search service, you must first obtain a free, developer API key. Sign in at https://mapzen.com/developers to create and manage your API keys. +To use the Mapzen Search service, you must first obtain a free developer API key. Sign in at https://mapzen.com/developers to create and manage your API keys. 1. Go to https://mapzen.com/developers. 2. Sign in with your GitHub account. If you have not done this before, you need to agree to the terms first. From 4d99c3d3260a959f734a56e29386d952499eff86 Mon Sep 17 00:00:00 2001 From: Julian Simioni Date: Tue, 29 Sep 2015 15:53:47 -0400 Subject: [PATCH 03/10] Fix typo (mininum -> minimum) --- search.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/search.md b/search.md index a52dd0b..c9c4d49 100644 --- a/search.md +++ b/search.md @@ -109,7 +109,7 @@ Results in the United States: ![](/getting-started/images/world_rect.png) -To specify the boundary using a rectangle, you need latitude, longitude coordinates for two diagonals of the bounding box (the mininum and the maximum latitude, longitude). +To specify the boundary using a rectangle, you need latitude, longitude coordinates for two diagonals of the bounding box (the minimum and the maximum latitude, longitude). For example, to find a YMCA within the state of Texas, you can set the `boundary.rect.*` parameter to values representing the bounding box around Texas: min_lon=-106.65 min_lat=25.84 max_lon=-93.51 max_lat=36.5 From 4305ff5c1bf774fe2f5d7bd5eb25c33ec4f19869 Mon Sep 17 00:00:00 2001 From: Julian Simioni Date: Tue, 29 Sep 2015 15:54:55 -0400 Subject: [PATCH 04/10] Remove extra asterisks These mess up the syntax highlighting for Markdown --- reverse.md | 4 ++-- search.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/reverse.md b/reverse.md index fa47b7f..8096143 100644 --- a/reverse.md +++ b/reverse.md @@ -46,7 +46,7 @@ By default, reverse geocoding returns results from any source available to Mapze >[/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) -***TO DO: Add correct link**** 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). ### Filter by layers @@ -54,7 +54,7 @@ Without specifying further, reverse geocoding doesn't restrict results to a part >[/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) -***TO DO: Add correct link**** 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). ### Filter by country diff --git a/search.md b/search.md index c9c4d49..a57a8a8 100644 --- a/search.md +++ b/search.md @@ -113,7 +113,7 @@ To specify the boundary using a rectangle, you need latitude, longitude coordina For example, to find a YMCA within the state of Texas, you can set the `boundary.rect.*` parameter to values representing the bounding box around Texas: min_lon=-106.65 min_lat=25.84 max_lon=-93.51 max_lat=36.5 - Tip: You can look up a bounding box for a known region with this [web tool](http://boundingbox.klokantech.com/)* + Tip: You can look up a bounding box for a known region with this [web tool](http://boundingbox.klokantech.com/) [/v1/search?api_key=search-XXXXXXX&text=YMCA&___boundary.rect.min_lat=25.84&boundary.rect.min_lon=-106.65&boundary.rect.max_lat=36.5&boundary.rect.max_lon=-93.51___](https://search.mapzen.com/v1/search?api_key=search-XXXXXXX&text=YMCA&boundary.rect.min_lat=25.84&boundary.rect.min_lon=-106.65&boundary.rect.max_lat=36.5&boundary.rect.max_lon=-93.51) From a0fd73629188218691ae161ebe8f155b18a24c37 Mon Sep 17 00:00:00 2001 From: Julian Simioni Date: Tue, 29 Sep 2015 15:55:13 -0400 Subject: [PATCH 05/10] Add title Markdown --- reverse.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reverse.md b/reverse.md index 8096143..49f2500 100644 --- a/reverse.md +++ b/reverse.md @@ -18,7 +18,7 @@ To get started with reverse geocoding, you need a [free, developer API key](http Notice that the first result is the Eiffel Tower (well, Tour Eiffel). The output is the standard GeoJSON format. -reverse geocoding +## Reverse geocoding parameters Similar to other queries with Mapzen Search, reverse geocoding has optional, additional parameters you can use to refine results. From 83b6c6ad4eda8d923c8e74f7381785d6f95a8609 Mon Sep 17 00:00:00 2001 From: Julian Simioni Date: Tue, 29 Sep 2015 15:56:28 -0400 Subject: [PATCH 06/10] Fix a gramatically incorrect sentence --- search.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/search.md b/search.md index a57a8a8..d2dd3c3 100644 --- a/search.md +++ b/search.md @@ -179,7 +179,7 @@ Many use cases call for the ability to promote nearby results to the top of the By specifying a `focus.point`, nearby places will be scored higher depending on how close they are to the `focus.point` so that places with higher scores will appear higher in the results list. The effect of this scoring boost diminishes to zero after 100 kilometers away from the `focus.point`. After all the nearby results have been found, additional results will come from the rest of the world, without any further location-based prioritization. -To find YMCA again, but this time near the a specific coordinate location (representing the Sydney Opera House) in Sydney, Australia. +To find YMCA again, but this time near a specific coordinate location (representing the Sydney Opera House) in Sydney, Australia, use `focus.point`. > [/v1/search?api_key=search-XXXXXXX&text=YMCA&___focus.point.lat=-33.856680&focus.point.lon=151.215281___](https://search.mapzen.com/v1/search?api_key=search-XXXXXXX&text=YMCA&focus.point.lat=-33.856680&focus.point.lon=151.215281) From 94601b556a641fd3fee9447cf072282a3d40a8c2 Mon Sep 17 00:00:00 2001 From: Julian Simioni Date: Tue, 29 Sep 2015 15:57:00 -0400 Subject: [PATCH 07/10] Whitespace --- response.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/response.md b/response.md index 90967b8..ec74fba 100644 --- a/response.md +++ b/response.md @@ -22,9 +22,9 @@ The `features` property of the result is where you will find the list of results Each item in this list will contain all the information needed to identify it in human-readable format in the `properties` block, as well as computer friendly coordinates in the `geometry` property. Note the `label` property, which is a human-friendly representation of the place, ready to be displayed to an end-user. ```json -{ +{ "type":"Feature", - "properties":{ + "properties":{ "gid":"...", "layer":"address", "source":"osm", @@ -43,9 +43,9 @@ Each item in this list will contain all the information needed to identify it in "confidence":0.9624939994613662, "label":"30 West 26th Street, Manhattan, NY" }, - "geometry":{ + "geometry":{ "type":"Point", - "coordinates":[ + "coordinates":[ -73.990342, 40.744243 ] From 9f18eaac2e98697f5ab5ea7420d2c992a2599f18 Mon Sep 17 00:00:00 2001 From: Julian Simioni Date: Tue, 29 Sep 2015 16:23:56 -0400 Subject: [PATCH 08/10] Remove note for fixed issue This was fixed by pelias/api#307 --- place.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/place.md b/place.md index 82a84c7..767b3e1 100644 --- a/place.md +++ b/place.md @@ -14,8 +14,6 @@ For example, this `/place` query looks up the Eiffel Tower in OSM: https://search.mapzen.com/v1/place?api_key=search-XXXXXXX&ids=osm:venue:5013364 -***From Rhonda -- looks like this returns a radio station in Michigan? Also need to redo the query to include production server and the reader's API key*** - *** From Rhonda -- what are some examples of when you would use a /place search? When would you have this info and need to get the details? What would you do with it.*** ## Search for multiple places in a query From 50356cc9d06255b85c032f5f6ac704f6eb3e2282 Mon Sep 17 00:00:00 2001 From: Julian Simioni Date: Tue, 29 Sep 2015 16:24:44 -0400 Subject: [PATCH 09/10] Remove answered note And as a reminder, the answer in brief is that we expect to add more data to our records in the future that we may not want to return for every item in a search result, for example polygon data. --- place.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/place.md b/place.md index 767b3e1..2f2a930 100644 --- a/place.md +++ b/place.md @@ -14,8 +14,6 @@ For example, this `/place` query looks up the Eiffel Tower in OSM: https://search.mapzen.com/v1/place?api_key=search-XXXXXXX&ids=osm:venue:5013364 -*** From Rhonda -- what are some examples of when you would use a /place search? When would you have this info and need to get the details? What would you do with it.*** - ## Search for multiple places in a query To search for more than one `/place` in a request, join multiple values together and separate them with a comma. For example, this /place query looks up the Eiffel Tower in OSM and `30 West 26th St, New York, NY` in OpenAddresses: From c014570fc2599a1ad1b0482d065e84f938b10f1e Mon Sep 17 00:00:00 2001 From: Julian Simioni Date: Tue, 29 Sep 2015 16:39:39 -0400 Subject: [PATCH 10/10] Capitalization --- transition-from-beta.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/transition-from-beta.md b/transition-from-beta.md index 826ee6c..23705b4 100644 --- a/transition-from-beta.md +++ b/transition-from-beta.md @@ -171,7 +171,7 @@ https://search.mapzen.com/v1/place?ids=geonames:3544:adm1:fr:fra:paris&api_key=s ``` # In-Browser Cross-Site Scripting -If you were using Pelias from within a browser with client-side javascript (using Pelias on a domain that is different mapzen.com), you should know that Mapzen Search does not support JSONP requests to get around cross-site scripting limitations. +If you were using Pelias from within a browser with client-side Javascript (using Pelias on a domain that is different mapzen.com), you should know that Mapzen Search does not support JSONP requests to get around cross-site scripting limitations. Instead, Mapzen Search supports [Cross-Origin Resource Sharing](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS) (CORS), which enables secure cross-site data transfers. @@ -188,4 +188,4 @@ Let us know. Words go to: [search@mapzen.com](mailto:search@mapzen.com) -Issues go to [Github](https://github.com/pelias/pelias-doc/issues) +Issues go to [GitHub](https://github.com/pelias/pelias-doc/issues)