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.
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.
2. Sign in with your GitHub account. If you have not done this before, you need to agree to the terms first.
***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
## 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:
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 Rhonda -- is there another example where you might do multiple requests at the same time...in other words, more related locations?***
***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.
@ -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.
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
```json
{
{
"type":"Feature",
"type":"Feature",
"properties":{
"properties":{
"gid":"...",
"gid":"...",
"layer":"address",
"layer":"address",
"source":"osm",
"source":"osm",
@ -43,9 +43,9 @@ Each item in this list will contain all the information needed to identify it in
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:
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.
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
Parameter | Type | Required | Default | Example
--- | --- | --- | --- | ---
--- | --- | --- | --- | ---
@ -38,7 +38,7 @@ A basic parameter for filtering is `size`, which is used to limit the number of
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
### Filter by data source
@ -46,7 +46,7 @@ By default, reverse geocoding returns results from any source available to Mapze
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
## 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
Distance from `point.lat`/`point.lon` | Confidence score
--- | ---
--- | ---
@ -79,7 +79,7 @@ Distance from `point.lat`/`point.lon` | Confidence score
## Example requests
## 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)
* 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)
@ -109,11 +109,11 @@ Results in the United States:
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
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/)
@ -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.
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`.
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.
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)
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)
Rhonda Glennon
9 years ago