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. diff --git a/place.md b/place.md index 15b2771..2f2a930 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,27 +8,23 @@ 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: 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 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: 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/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 ] diff --git a/reverse.md b/reverse.md index ad3b9fe..49f2500 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: @@ -18,9 +18,9 @@ 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. +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 @@ -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 @@ -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..d2dd3c3 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 \___/ \_______________/\__/\_____/\__________/\___________________/ | | / | | | @@ -109,11 +109,11 @@ 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 - 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) @@ -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) 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)