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 \___/ \_______________/\__/\_____/\__________/\___________________/ | | / | | |