pelias
/
documentation
mirror of https://github.com/pelias/documentation.git
1
0
Fork 0
Code Issues Releases Activity
Browse Source

Merge pull request #219 from pelias/mapzen-cleanup 

Mapzen cleanup
pull/221/head
Julian Simioni 7 years ago committed by GitHub
parent
30f3f14e9e 0a203f3a0b
commit
0982b7a8de
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
17 changed files with 156 additions and 379 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 1
      README.md
  2. 20
      README.md
  3. 28
      add-search-to-a-map.md
  4. 2
      addresses.md
  5. 10
      api-keys-rate-limits.md
  6. 13
      autocomplete.md
  7. 16
      glossary.md
  8. 14
      index.md
  9. 4
      place.md
  10. 6
      release-notes.md
  11. 10
      response.md
  12. 29
      reverse.md
  13. 2
      search-workflows.md
  14. 108
      search.md
  15. 44
      structured-geocoding.md
  16. 203
      transition-from-beta.md
  17. 1
      transition.md
  18. 8
      use-cors.md

1
README.md
Unescape View File

@ -1 +0,0 @@
index.md

20
README.md
Unescape View File

@ -0,0 +1,20 @@
# Pelias Documentation
Here is where you can find all documentation for the [Pelias geocoder](https://github.com/pelias/pelias/).
## Table of Contents
### Core Features and API Documentation
- [Forward geocoding](search.md) to find a place by searching for an address or name
- [Reverse geocoding](reverse.md) to find what is located at a certain coordinate location
- [Autocomplete](autocomplete.md) to give real-time result suggestions without having to type the whole location
- [Global coverage with prioritized local results](search.md#prioritize-results-by-proximity)
- [Structured Geocoding](structured-geocoding.md) to find a place with data already separated into housenumber, street, city, etc
- [Glossary of common terms](glossary.md)
### Data Sources
- [Pelias data sources](data-sources.md)
- [Tools for embedding search](https://mapzen.com/documentation/mapzen-js/search/) in a map
### Running your own Pelias
- [Pelias installation guide](https://github.com/pelias/pelias/blob/master/INSTALL.md)

28
add-search-to-a-map.md
Unescape View File

@ -1,8 +1,8 @@
# Add the Mapzen Search geocoder to a map # Add the Pelias geocoder to a map
[Mapzen Search](https://mapzen.com/products/search/) is a modern, geographic search service based entirely on open-source tools and open data. Use this functionality to enhance any app that has a geographic context, such as ones that help in delivering goods, locating hotels or venues, or providing local weather forecasts. [Pelias](https://mapzen.com/products/search/) is a modern, geographic search service based entirely on open-source tools and open data. Use this functionality to enhance any app that has a geographic context, such as ones that help in delivering goods, locating hotels or venues, or providing local weather forecasts.
Through a process known as [geocoding](https://en.wikipedia.org/wiki/Geocoding), Mapzen Search allows you to enter an address or the name of a landmark or business, and the service translates the result into geographic coordinates for mapping. Mapzen Search is built on [Pelias](pelias.io), an open-source geocoding project. Through a process known as [geocoding](https://en.wikipedia.org/wiki/Geocoding), Pelias allows you to enter an address or the name of a landmark or business, and the service translates the result into geographic coordinates for mapping. Pelias is built on [Pelias](pelias.io), an open-source geocoding project.
## Get ready for the tutorial ## Get ready for the tutorial
@ -230,15 +230,15 @@ Now, you will test your search box by finding a few locations. As you type, the
## Customize the geocoder ## Customize the geocoder
From a technical perspective, Mapzen Search is a web service with that has various API endpoints that allow you to access web resources through a URL. Behind the scenes, the geocoder is constructing a URL with the parameters you specify and sending it to the Mapzen Search web service. The service returns [human-readable JSON](https://en.wikipedia.org/wiki/JSON), short for JavaScript Object Notation. From a technical perspective, Pelias is a web service with that has various API endpoints that allow you to access web resources through a URL. Behind the scenes, the geocoder is constructing a URL with the parameters you specify and sending it to the Pelias web service. The service returns [human-readable JSON](https://en.wikipedia.org/wiki/JSON), short for JavaScript Object Notation.
Mapzen.js provides options for customizing the way you interact with the map, and Mapzen Search is also very flexible. Now that you have a map on your page with a Search box, you can add more features to it. You need to modify the line defining the geocoder to include additional parameters. Mapzen.js provides options for customizing the way you interact with the map, and Pelias is also very flexible. Now that you have a map on your page with a Search box, you can add more features to it. You need to modify the line defining the geocoder to include additional parameters.
Up to this point, you have been using the Mapzen Search [\autocomplete](https://mapzen.com/documentation/search/autocomplete/) endpoint, which searches on text as you type it. In this section, you will switch to the [\search](https://mapzen.com/documentation/search/search/) endpoint to see how it behaves. The `autocomplete` functionality helps you find partial matches, whereas `search` prioritizes exact words because it assumes you have finished typing when you perform the query. Up to this point, you have been using the Pelias [\autocomplete](https://mapzen.com/documentation/search/autocomplete/) endpoint, which searches on text as you type it. In this section, you will switch to the [\search](https://mapzen.com/documentation/search/search/) endpoint to see how it behaves. The `autocomplete` functionality helps you find partial matches, whereas `search` prioritizes exact words because it assumes you have finished typing when you perform the query.
If you look at your browser's developer tools console as you are doing this, you can see the query URL changes from `https://search.mapzen.com/v1/autocomplete?text=` to `https://search.mapzen.com/v1/search?text=` to reflect the `search` endpoint. If you look at your browser's developer tools console as you are doing this, you can see the query URL changes from `https://search.mapzen.com/v1/autocomplete?text=` to `https://search.mapzen.com/v1/search?text=` to reflect the `search` endpoint.
Although you will not be using it in this tutorial, [\reverse](https://mapzen.com/documentation/search/reverse/) is another common Mapzen Search endpoint. It performs reverse geocoding to find the address at a given coordinate location. You can find a listing of all the endpoints and parameters in the [Mapzen Search documentation](https://mapzen.com/documentation/search/). Although you will not be using it in this tutorial, [\reverse](https://mapzen.com/documentation/search/reverse/) is another common Pelias endpoint. It performs reverse geocoding to find the address at a given coordinate location. You can find a listing of all the endpoints and parameters in the [Pelias documentation](https://mapzen.com/documentation/search/).
1. Add a variable to allow you to set options for the geocoder. Inside the script tags, and above the geocoder line, add this block. 1. Add a variable to allow you to set options for the geocoder. Inside the script tags, and above the geocoder line, add this block.
@ -283,11 +283,11 @@ _Tip: You can install a plug-in for your browser to display JSON in a more forma
## Choose which data sources to search ## Choose which data sources to search
Mapzen Search uses a [variety of open data sources](https://mapzen.com/documentation/search/data-sources/), including OpenStreetMap. Part of the power of open data is that anyone can change the source data and improve the quality for everyone. If you are unable to find a location, the place could be missing or incorrect in the source datasets. Pelias uses a [variety of open data sources](https://mapzen.com/documentation/search/data-sources/), including OpenStreetMap. Part of the power of open data is that anyone can change the source data and improve the quality for everyone. If you are unable to find a location, the place could be missing or incorrect in the source datasets.
You can choose which data sources to search by passing a parameter for the `sources`. In addition, you need to enclose with single quotation marks any parameter names that use the dot notation (such as `boundary.country`) to make sure JavaScript can parse the text correctly. You can choose which data sources to search by passing a parameter for the `sources`. In addition, you need to enclose with single quotation marks any parameter names that use the dot notation (such as `boundary.country`) to make sure JavaScript can parse the text correctly.
As you were searching, you might have noticed results that looked similar. Mapzen Search does perform some elimination, but the differing data sources may still cause seemingly matching results to appear. Choosing a particular data source can reduce the occurrence of duplicated entries. As you were searching, you might have noticed results that looked similar. Pelias does perform some elimination, but the differing data sources may still cause seemingly matching results to appear. Choosing a particular data source can reduce the occurrence of duplicated entries.
1. Within the `geocoderOptions` block, add the `params:` list and a parameter for `sources:`. Be sure to add a `,` at the end of the `autocomplete: false` line. 1. Within the `geocoderOptions` block, add the `params:` list and a parameter for `sources:`. Be sure to add a `,` at the end of the `autocomplete: false` line.
@ -305,7 +305,7 @@ As you were searching, you might have noticed results that looked similar. Mapze
## Prioritize nearby places and filter search results ## Prioritize nearby places and filter search results
Mapzen Search provides options for customizing your search parameters, such as limiting the search to the map's extent or prioritizing results near the current view. Right now, you may notice that results from around the world appear in the list. Pelias provides options for customizing your search parameters, such as limiting the search to the map's extent or prioritizing results near the current view. Right now, you may notice that results from around the world appear in the list.
Mapzen.js automatically provides a [focus point](https://mapzen.com/documentation/search/search/#prioritize-around-a-point) for you based on the current map view extent. You can add other parameters to filter the search results, such as to limit the results to a particular country or type of result. Mapzen.js automatically provides a [focus point](https://mapzen.com/documentation/search/search/#prioritize-around-a-point) for you based on the current map view extent. You can add other parameters to filter the search results, such as to limit the results to a particular country or type of result.
@ -327,11 +327,11 @@ Mapzen.js automatically provides a [focus point](https://mapzen.com/documentatio
## Filter the results by type of place ## Filter the results by type of place
In Mapzen Search, types of places are referred to as `layers`, and you can use these to filter your results. For example, if your app has an input form where your users should only be able to enter a city, you can use Mapzen Search to limit the results to show only matching city names. This is common in travel apps, such as searching for a hotel or flight, where you enter a destination city. In Pelias, types of places are referred to as `layers`, and you can use these to filter your results. For example, if your app has an input form where your users should only be able to enter a city, you can use Pelias to limit the results to show only matching city names. This is common in travel apps, such as searching for a hotel or flight, where you enter a destination city.
In this section, you will filter the results to search only addresses and venues, which include point of interest, landmarks, and businesses. In this section, you will filter the results to search only addresses and venues, which include point of interest, landmarks, and businesses.
You can review the [Mapzen Search documentation](https://mapzen.com/documentation/search/search/#filter-by-data-type) to learn the types of `layers` you can use in a search. You can review the [Pelias documentation](https://mapzen.com/documentation/search/search/#filter-by-data-type) to learn the types of `layers` you can use in a search.
1. Within the `geocoderOptions` block, add add a `,` at the end of the `'boundary.country: 'USA'` line and then a parameter for `layers: 'address,venue'` on the next line. 1. Within the `geocoderOptions` block, add add a `,` at the end of the `'boundary.country: 'USA'` line and then a parameter for `layers: 'address,venue'` on the next line.
@ -350,9 +350,9 @@ You can review the [Mapzen Search documentation](https://mapzen.com/documentatio
## Tutorial summary ## Tutorial summary
In this tutorial, you learned the basics of adding the Mapzen Search geocoding engine to a map using [Mapzen.js](https://mapzen.com/documentation/mapzen-js/), and making some customizations to improve the search results. In this tutorial, you learned the basics of adding the Pelias geocoding engine to a map using [Mapzen.js](https://mapzen.com/documentation/mapzen-js/), and making some customizations to improve the search results.
If you want to learn more about Mapzen Search, review the [documentation](https://mapzen.com/documentation/search). If you want to learn more about Pelias, review the [documentation](https://mapzen.com/documentation/search).
Because the geocoder is still under development and considered experimental, if you are getting unexpected search results, please add an issue to the [Pelias GitHub repository](https://github.com/pelias/pelias/issues). The developers can investigate and decide if the problem is caused by software or data, and work to fix it either way. Because the geocoder is still under development and considered experimental, if you are getting unexpected search results, please add an issue to the [Pelias GitHub repository](https://github.com/pelias/pelias/issues). The developers can investigate and decide if the problem is caused by software or data, and work to fix it either way.

2
addresses.md
Unescape View File

@ -32,7 +32,7 @@ When you search for an address and and there is not a precise match, the interpo
One form of address interpolation involves drawing a line that connects between the nearest known house numbers and placing the interpolated address within a range on that line. This process may work if the road is straight, but often results in the interpolated point being placed at a distance offset from the road network on curved sections. One form of address interpolation involves drawing a line that connects between the nearest known house numbers and placing the interpolated address within a range on that line. This process may work if the road is straight, but often results in the interpolated point being placed at a distance offset from the road network on curved sections.
To improve upon the straight line technique, the Mapzen Search interpolation implementation considers the actual shape of the street when locating a point without a matching address. This results in more accurate location estimation because the interpolated addresses points are placed on the road itself, which also makes it easier for routing and turn-by-turn navigation services to calculate directions for that location. To improve upon the straight line technique, the Pelias interpolation implementation considers the actual shape of the street when locating a point without a matching address. This results in more accurate location estimation because the interpolated addresses points are placed on the road itself, which also makes it easier for routing and turn-by-turn navigation services to calculate directions for that location.
If the address was derived using this technique, you see `interpolated` for the `match_type`. If the address was derived using this technique, you see `interpolated` for the `match_type`.

10
api-keys-rate-limits.md
Unescape View File

@ -4,17 +4,17 @@ _Note: This page is deprecated and has been removed from the documentation on ht
## Get started ## Get started
The Mapzen Search service requires an API key. In a request, you must append your own API key to the URL, following `?api_key=`. The Pelias service requires an API key. In a request, you must append your own API key to the URL, following `?api_key=`.
See the [Mapzen developer overview](https://mapzen.com/documentation/overview/) for more on API keys and rate limits. See the [Mapzen developer overview](https://mapzen.com/documentation/overview/) for more on API keys and rate limits.
## Caching to improve performance ## Caching to improve performance
Mapzen Search uses caching to serve commonly requested content as quickly as possible. An edge cache, also known as a content delivery network (CDN), is a network of computers, geographically spread across the world, designed to shorten the physical distance data must travel to you so it can get there faster. If you have ever tried to access a common service and found that it is slow, it may be because the information must travel a large physical distance. Mapzen Search uses a CDN to help reduce this effect and limit the impact of common queries on its application servers. Pelias uses caching to serve commonly requested content as quickly as possible. An edge cache, also known as a content delivery network (CDN), is a network of computers, geographically spread across the world, designed to shorten the physical distance data must travel to you so it can get there faster. If you have ever tried to access a common service and found that it is slow, it may be because the information must travel a large physical distance. Pelias uses a CDN to help reduce this effect and limit the impact of common queries on its application servers.
When you send a request to Mapzen Search, it first goes to the CDN server that is the closest path from your internet service provider before it is forwarded onto a Mapzen Search application server. Mapzen Search uses [Fastly](https://www.fastly.com) for its CDN; you can look at this [network map](https://www.fastly.com/network-map) to see where your requests are likely being sent. When you send a request to Pelias, it first goes to the CDN server that is the closest path from your internet service provider before it is forwarded onto a Pelias application server. Mapzen Search uses [Fastly](https://www.fastly.com) for its CDN; you can look at this [network map](https://www.fastly.com/network-map) to see where your requests are likely being sent.
If your request is not found in the current CDN cache, the CDN server then passes it to one of the Mapzen Search application servers. When it comes back with a response to your API call, the CDN server keeps a copy of that response (minus any personal data to your application, including your API key). If you or another nearby user makes the identical API call, you will likely be sent to the same CDN server, which has the response in its local cache. From tests in the Mapzen offices in New York, this has the effect of shortening a query from 190ms to 21ms. Your speed improvements may vary, as requests from other locations and internet providers may be served by different edge cache servers. If your request is not found in the current CDN cache, the CDN server then passes it to one of the Pelias application servers. When it comes back with a response to your API call, the CDN server keeps a copy of that response (minus any personal data to your application, including your API key). If you or another nearby user makes the identical API call, you will likely be sent to the same CDN server, which has the response in its local cache. From tests in the Mapzen offices in New York, this has the effect of shortening a query from 190ms to 21ms. Your speed improvements may vary, as requests from other locations and internet providers may be served by different edge cache servers.
Through edge caching, common searches, such as `/v1/search?text=new york`, often come back quickly for most users. This is especially useful with Autocomplete, where many places start with the same few root letters, such as the `new` in `new york`, `newark`, and `new jersey`. Through edge caching, common searches, such as `/v1/search?text=new york`, often come back quickly for most users. This is especially useful with Autocomplete, where many places start with the same few root letters, such as the `new` in `new york`, `newark`, and `new jersey`.
@ -22,5 +22,5 @@ Unless you have recently made a particular API call, you will not know ahead of
These header entries are most helpful to determine whether caching was used: These header entries are most helpful to determine whether caching was used:
- `X-Cache` indicates if your request was served from the Mapzen Search application server (`MISS`) or the cache server (`HIT`). This header should be there for any query you make to the Mapzen Search API. Any query with `X-Cache: MISS` is a query that counts toward your rate limit. - `X-Cache` indicates if your request was served from the Pelias application server (`MISS`) or the cache server (`HIT`). This header should be there for any query you make to the Pelias API. Any query with `X-Cache: MISS` is a query that counts toward your rate limit.
- `X-ApiaxleProxy-Qps-Left` is the number of queries per second remaining on your API key, and `X-ApiaxleProxy-Qpd-Left` is the remaining queries per day. These headers are only present when you see `X-Cache: MISS`. - `X-ApiaxleProxy-Qps-Left` is the number of queries per second remaining on your API key, and `X-ApiaxleProxy-Qpd-Left` is the remaining queries per day. These headers are only present when you see `X-Cache: MISS`.

13
autocomplete.md
Unescape View File

@ -18,8 +18,7 @@ To focus your search based upon a geographical area, such as the center of the u
From San Francisco: From San Francisco:
> > /v1/autocomplete?__focus.point.lat=37.7&focus.point.lon=-122.4__&text=union square
[/v1/autocomplete?api_key=your-mapzen-api-key&__focus.point.lat=37.7&focus.point.lon=-122.4&text=union square__](https://mapzen.com/search/explorer/?query=autocomplete&focus.point.lat=37.7&focus.point.lon=-122.4&text=union square)
``` ```
1) Union Square, San Francisco County, CA 1) Union Square, San Francisco County, CA
@ -28,8 +27,7 @@ From San Francisco:
From New York City: From New York City:
> > /v1/autocomplete?__focus.point.lat=40.7&focus.point.lon=-73.9__&text=union square
[/v1/autocomplete?api_key=your-mapzen-api-key&__focus.point.lat=40.7&focus.point.lon=-73.9&text=union square__](https://mapzen.com/search/explorer/?query=autocomplete&focus.point.lat=40.7&focus.point.lon=-73.9&text=union square)
``` ```
1) Union Square, New York County, NY 1) Union Square, New York County, NY
@ -38,7 +36,7 @@ From New York City:
The `/autocomplete` endpoint can promote nearby results to the top of the list, while still allowing important matches from farther away to be visible. For example, searching `hard rock cafe` with a focus on Berlin: The `/autocomplete` endpoint can promote nearby results to the top of the list, while still allowing important matches from farther away to be visible. For example, searching `hard rock cafe` with a focus on Berlin:
> [/v1/autocomplete?api_key=your-mapzen-api-key&__focus.point.lat=52.5&focus.point.lon=13.3&text=hard rock cafe__](https://mapzen.com/search/explorer/?query=autocomplete&focus.point.lat=52.5&focus.point.lon=13.3&text=hard rock cafe) > /v1/autocomplete?__focus.point.lat=52.5&focus.point.lon=13.3__&text=hard rock cafe
with `focus.point` you will find the Berlin restaurant first: with `focus.point` you will find the Berlin restaurant first:
``` ```
@ -65,7 +63,7 @@ The `sources` parameter allows you to specify from which data sources you'd like
* `geonames` or `gn` * `geonames` or `gn`
* `whosonfirst` or `wof` * `whosonfirst` or `wof`
> [/v1/autocomplete?api_key=your-mapzen-api-key&__sources=openaddresses__&text=pennsylvania](https://mapzen.com/search/explorer/?query=autocomplete&sources=openaddresses&text=pennsylvania) > /v1/autocomplete?__sources=openaddresses__&text=pennsylvania
with `sources=openaddresses` you will only find addresses on Pennsylvania Ave or Street: with `sources=openaddresses` you will only find addresses on Pennsylvania Ave or Street:
``` ```
@ -101,7 +99,7 @@ The type of record is referred to as its `layer`. All records are indexed into t
|`neighbourhood`|social communities, neighbourhoods| |`neighbourhood`|social communities, neighbourhoods|
|`coarse`|alias for simultaneously using all administrative layers (everything except `venue` and `address`)| |`coarse`|alias for simultaneously using all administrative layers (everything except `venue` and `address`)|
> [/v1/autocomplete?api_key=your-mapzen-api-key&__layers=coarse__&text=starbuck](https://mapzen.com/search/explorer/?query=autocomplete&layers=coarse&text=starbuck) > /v1/autocomplete?__layers=coarse__&text=starbuck
with `layers=coarse` you will see only administrative areas with names containing Starbuck with `layers=coarse` you will see only administrative areas with names containing Starbuck
@ -129,7 +127,6 @@ Sometimes your work might require that all the search results be from a particul
| Parameter | Type | Required | Default | Example | | Parameter | Type | Required | Default | Example |
| --- | --- | --- | --- | --- | | --- | --- | --- | --- | --- |
| `api_key` | string | yes | none | [get yours here](https://mapzen.com/developers) |
| `text` | string | yes | none | `Union Square` | | `text` | string | yes | none | `Union Square` |
| `focus.point.lat` | floating point number | no | none | `48.581755` | | `focus.point.lat` | floating point number | no | none | `48.581755` |
| `focus.point.lon` | floating point number | no | none | `7.745843` | | `focus.point.lon` | floating point number | no | none | `7.745843` |

16
glossary.md
Unescape View File

@ -1,4 +1,4 @@
# Mapzen Search glossary # Pelias glossary
## Common search and geocoding terms ## Common search and geocoding terms
@ -7,14 +7,14 @@
- **coarse geocoding** - adds regions and administrative boundaries to the geocoding process. Coarse forward geocoding limits a search to a particular region, while coarse reverse geocoding converts a geographic coordinate pair into the administrative boundary hierarchy containing it, such as from the neighbourhood to the local administrative area, and on up to the country level. - **coarse geocoding** - adds regions and administrative boundaries to the geocoding process. Coarse forward geocoding limits a search to a particular region, while coarse reverse geocoding converts a geographic coordinate pair into the administrative boundary hierarchy containing it, such as from the neighbourhood to the local administrative area, and on up to the country level.
- **gazetteer** - a directory of geographical places, with a stable identifier and some number of descriptive properties about that location. - **gazetteer** - a directory of geographical places, with a stable identifier and some number of descriptive properties about that location.
## Mapzen Search API and developer terms ## Pelias API and developer terms
- **API endpoint** - an architectural style for accessing web resources through a URL. In Mapzen Search, available endpoints include `search`, `reverse`, and `autocomplete`. You can construct a URL to send queries and receive responses from Mapzen Search. - **API endpoint** - an architectural style for accessing web resources through a URL. In Pelias, available endpoints include `search`, `reverse`, and `autocomplete`. You can construct a URL to send queries and receive responses from Pelias.
- **API key** - a code that identifies the developer account without providing a password. Mapzen Search requires an API key to interact with the search service. Sign up for an API key at https://mapzen.com/developers. - **API key** - a code that identifies the developer account without providing a password. Pelias requires an API key to interact with the search service. Sign up for an API key at https://mapzen.com/developers.
- **autocomplete** - enables real-time feedback when entering text for a search, typically, where users start typing and a drop-down list appears where they can choose the term from the list below. Use the `autocomplete` endpoint to do this. - **autocomplete** - enables real-time feedback when entering text for a search, typically, where users start typing and a drop-down list appears where they can choose the term from the list below. Use the `autocomplete` endpoint to do this.
- **data source** - the datasets available to Mapzen Search. Only data sources that have open-source licenses are used. - **data source** - the datasets available to Pelias. Only data sources that have open-source licenses are used.
- **focus** - option to make places closer to a particular location be prioritized and appear higher in the search results list. After all nearby results have been found, additional results will come from the rest of the world, without any further location-based prioritization. - **focus** - option to make places closer to a particular location be prioritized and appear higher in the search results list. After all nearby results have been found, additional results will come from the rest of the world, without any further location-based prioritization.
- **layer** - types of places available to Mapzen Search and arranged in a hierarchy, such as an address, a venue, a neighbourhood, or a country. - **layer** - types of places available to Pelias and arranged in a hierarchy, such as an address, a venue, a neighbourhood, or a country.
- **`place` search** - get details on a place if you know the data source, the type of place (such as a venue or address), and the identification number. - **`place` search** - get details on a place if you know the data source, the type of place (such as a venue or address), and the identification number.
- **structured geocoding** - Assigns geographical coordinates to an address, venue, or other location type that has been broken up into its constituent parts. Use the `search/structured` endpoint to do this. - **structured geocoding** - Assigns geographical coordinates to an address, venue, or other location type that has been broken up into its constituent parts. Use the `search/structured` endpoint to do this.
@ -22,5 +22,5 @@
- **bounding box** - a rectangular area defined by two longitudes and two latitudes (the minimum and the maximum latitude, longitude). - **bounding box** - a rectangular area defined by two longitudes and two latitudes (the minimum and the maximum latitude, longitude).
- **cross-origin resource sharing (CORS)** - standard allowing a web browser and server to accept requests across domains. Without CORS, browsers may not allow cross-site requests because they could be malicious. - **cross-origin resource sharing (CORS)** - standard allowing a web browser and server to accept requests across domains. Without CORS, browsers may not allow cross-site requests because they could be malicious.
- **latitude** - the distance of a point north or south of the equator. In Mapzen Search, latitudes are expressed in decimal degrees. - **latitude** - the distance of a point north or south of the equator. In Pelias, latitudes are expressed in decimal degrees.
- **longitude** - the distance of a point east or west. In Mapzen Search, longitudes are in relation to the Prime Meridian and expressed in decimal degrees. - **longitude** - the distance of a point east or west. In Pelias, longitudes are in relation to the Prime Meridian and expressed in decimal degrees.

14
index.md
Unescape View File

@ -1,14 +0,0 @@
[Mapzen Search](https://mapzen.com/projects/search) is a modern, geographic search service based entirely on open-source tools and powered entirely by open data. Through a process known as [geocoding](search.md), Mapzen Search allows you to use natural language to find a particular place by entering an address or the name of a landmark or business, and then translates the result in to the geographic coordinates used by computers.
Mapzen Search accesses [global databases](data-sources.md) of place names and locations, but you can receive more locally relevant search results by limiting the search to a particular radius around a location (such as a cell phone), region, or country. With text [autocompletion capabilities](autocomplete.md), you can search for places and match against Mapzen Search data in real-time.
Mapzen Search also enables the opposite workflow, known as [reverse geocoding](reverse.md), to transform latitude and longitude values in to a list of places. This process attempts to find the name and address of the place nearest a longitude and latitude pair. For example, you can click a position on the map to learn which business is located there.
## Features of Mapzen Search
- [Forward geocoding](search.md) to find a place by searching for an address or name
- [Reverse geocoding](reverse.md) to find what is located at a certain coordinate location
- [Autocomplete](autocomplete.md) to give real-time result suggestions without having to type the whole location
- [Global coverage with prioritized local results](search.md#prioritize-results-by-proximity)
- Open-source software using [open data sources](data-sources.md)
- [Tools for embedding search](https://mapzen.com/documentation/mapzen-js/search/) in a map

4
place.md
Unescape View File

@ -1,8 +1,8 @@
# Search an ID to get details on a place # 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 Pelias to get details on the location.
The `/place` endpoint accepts Mapzen Search `gid` strings that get returned for every exactly matched record in query responses. These `gid` strings should not be built manually, but rather used directly as-is to lookup additional details on the location that `gid` refers to. The `/place` endpoint accepts Pelias `gid` strings that get returned for every exactly matched record in query responses. These `gid` strings should not be built manually, but rather used directly as-is to lookup additional details on the location that `gid` refers to.
For example, this `/place` query looks up the Eiffel Tower in OpenStreetMap (OSM): For example, this `/place` query looks up the Eiffel Tower in OpenStreetMap (OSM):

6
release-notes.md
Unescape View File

@ -94,7 +94,7 @@ This release is just a data refresh since it's hard to keep up with the leaps an
## 27 January 2017 ## 27 January 2017
Thanks to some wild activity in the [openaddresses](http://openaddresses.io) project, this is the first Mapzen Search build with over 400 million documents! Thanks to some wild activity in the [openaddresses](http://openaddresses.io) project, this is the first Pelias build with over 400 million documents!
We are excited to see open data continue to grow and improve and looking forward to the big half billion milestone. :) We are excited to see open data continue to grow and improve and looking forward to the big half billion milestone. :)
@ -157,7 +157,7 @@ Another data-only release. Stay tuned for next week!
## 12 September 2016 ## 12 September 2016
* Get excited for the addition of ✨ __STREETS__ ✨! That's right, with this release Mapzen Search gets a brand new `street` layer, which contains OSM street centroids. With this addition, if we can't find the exact address you're looking for we'll return the street record. Stay tuned for an in-depth blog post in the next few days. 👏 * Get excited for the addition of ✨ __STREETS__ ✨! That's right, with this release Pelias gets a brand new `street` layer, which contains OSM street centroids. With this addition, if we can't find the exact address you're looking for we'll return the street record. Stay tuned for an in-depth blog post in the next few days. 👏
## 7 September 2016 ## 7 September 2016
@ -253,7 +253,7 @@ We also have two **known issues** in this build:
## 08 April 2016 ## 08 April 2016
This release marks the official integration of the Mapzen `Who's on First` data set into Mapzen Search. This data is replacing `Quattroshapes` across the entire service. Any forward usage or references to `Quattroshapes` will be replaced with `WhosOnFirst`. This substitution allows us to fix long-standing encoding issues in administrative hierarchy place-names. We've also added a bounding box for individual features in the results, not only the all-encompassing bounding box at the top level of the geojson results. Also, the all-encompassing bounding box will extend to include the bounding boxes of all the features in the results, not only their centroids. This release marks the official integration of the Mapzen `Who's on First` data set into Pelias. This data is replacing `Quattroshapes` across the entire service. Any forward usage or references to `Quattroshapes` will be replaced with `WhosOnFirst`. This substitution allows us to fix long-standing encoding issues in administrative hierarchy place-names. We've also added a bounding box for individual features in the results, not only the all-encompassing bounding box at the top level of the geojson results. Also, the all-encompassing bounding box will extend to include the bounding boxes of all the features in the results, not only their centroids.
Another major improvement that many have been waiting for is the addition of more filters for the `/autocomplete` endpoint. Users can now ask `/autocomplete` to filter by `layers` and `sources`, as documented [here](https://mapzen.com/documentation/search/autocomplete/#available-autocomplete-parameters). Another major improvement that many have been waiting for is the addition of more filters for the `/autocomplete` endpoint. Users can now ask `/autocomplete` to filter by `layers` and `sources`, as documented [here](https://mapzen.com/documentation/search/autocomplete/#available-autocomplete-parameters).
See the detailed list of changes below for more specifics. See the detailed list of changes below for more specifics.

10
response.md
Unescape View File

@ -1,6 +1,6 @@
# Search results # Search results
When requesting results from Mapzen Search, you will always get back GeoJSON results, unless something goes terribly wrong, in which case you'll get an error message. When requesting results from Pelias, you will always get back GeoJSON results, unless something goes terribly wrong, in which case you'll get an error message.
Tip: You can go to https://tools.ietf.org/html/rfc7946 to learn more about the GeoJSON data format specification. Tip: You can go to https://tools.ietf.org/html/rfc7946 to learn more about the GeoJSON data format specification.
@ -65,11 +65,11 @@ Additionally, [/reverse](reverse.md) queries will have a `distance` parameter, w
## `coordinates` ## `coordinates`
All results returned from Mapzen Search are points, and can be found in the `coordinates` array. Following the [GeoJSON specification](http://geojson.org/geojson-spec.html#positions), these coordinates are in **longitude, latitude** order. All results returned from Pelias are points, and can be found in the `coordinates` array. Following the [GeoJSON specification](http://geojson.org/geojson-spec.html#positions), these coordinates are in **longitude, latitude** order.
### `gid` ### `gid`
All places in Mapzen Search have a global identifier, known as a `gid`. Each matching record returned from a [/search](search.md), [/autocomplete](autocomplete.md), or [/reverse](reverse.md) geocoding request has a `gid` field. All places in Pelias have a global identifier, known as a `gid`. Each matching record returned from a [/search](search.md), [/autocomplete](autocomplete.md), or [/reverse](reverse.md) geocoding request has a `gid` field.
The `gid` consists of a `layer` (such as `address` or `country`), an identifier for the original data source (such as `openstreetmap` or `openaddresses`), and an `id` for the individual record corresponding to the original source identifier, where possible. This information is also available as properties on the individual results as `layer`, `source`, and `source_id`. The `gid` consists of a `layer` (such as `address` or `country`), an identifier for the original data source (such as `openstreetmap` or `openaddresses`), and an `id` for the individual record corresponding to the original source identifier, where possible. This information is also available as properties on the individual results as `layer`, `source`, and `source_id`.
@ -97,7 +97,7 @@ For the [/reverse](reverse.md) endpoint, the confidence score is determined sole
For the [/search](search.md) endpoint, it primarily takes into account how well properties in the result match what was expected from parsing the input text. For example, if the input text looks like an address, but the house number of the result doesn't match the house number that was parsed from the input text, the confidence score will be lower. For the [/search](search.md) endpoint, it primarily takes into account how well properties in the result match what was expected from parsing the input text. For example, if the input text looks like an address, but the house number of the result doesn't match the house number that was parsed from the input text, the confidence score will be lower.
Additionally, the confidence score can optionally be biased along with other results, like test scores in a classroom might be graded on a curve. This takes into account both the property matches described above and the distance between results. This relative scoring is enabled on Mapzen Search, but can be turned off when hosting your own Pelias instance. Additionally, the confidence score can optionally be biased along with other results, like test scores in a classroom might be graded on a curve. This takes into account both the property matches described above and the distance between results. This relative scoring is enabled on Pelias, but can be turned off when hosting your own Pelias instance.
### `bbox` ### `bbox`
@ -105,7 +105,7 @@ Features from Who's on First and OpenStreetMap often have their own `bbox` eleme
## Result count ## Result count
By default, Mapzen Search results 10 places, unless otherwise specified. If you want a different number of results, set the `size` parameter to the desired number. This example shows returning only the first result. By default, Pelias results 10 places, unless otherwise specified. If you want a different number of results, set the `size` parameter to the desired number. This example shows returning only the first result.
| parameter | value | | parameter | value |
| :--- | :--- | | :--- | :--- |

29
reverse.md
Unescape View File

@ -2,7 +2,7 @@
Reverse geocoding is used for finding places or addresses near a latitude, longitude pair—like 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—like 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 Pelias, you can look up all sorts of information about points on a map, including:
* addresses * addresses
* points of interest (businesses, museums, parks, and so on) * points of interest (businesses, museums, parks, and so on)
@ -14,17 +14,16 @@ With reverse geocoding with Mapzen Search, you can look up all sorts of informat
To get started with reverse geocoding, you need a latitude, longitude pair in decimal degrees specified with the parameters `point.lat` and `point.lon`, respectively. For example, the Eiffel Tower in Paris, France, is located at `48.858268,2.294471`. The reverse geocode query for this would be: To get started with reverse geocoding, you need a latitude, longitude pair in decimal degrees specified with the parameters `point.lat` and `point.lon`, respectively. For example, the Eiffel Tower in Paris, France, is located at `48.858268,2.294471`. The reverse geocode query for this would be:
>[/v1/reverse?api_key=your-mapzen-api-key&___point.lat=48.858268___&___point.lon=2.294471___](https://mapzen.com/search/explorer/?query=reverse&point.lat=48.858268&point.lon=2.294471) >/v1/reverse?__point.lat=48.858268__&__point.lon=2.294471__
The output is the standard GeoJSON format. The output is the standard GeoJSON format.
## Reverse geocoding parameters ## Reverse geocoding parameters
Like other queries with Mapzen Search, reverse geocoding has optional, additional parameters you can use to refine results. Like other queries with Pelias, reverse geocoding has optional, additional parameters you can use to refine results.
Parameter | Type | 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` `point.lat` | floating point number | yes | none | `48.858268`
`point.lon` | floating point number | yes | none | `2.294471` `point.lon` | floating point number | yes | none | `2.294471`
`boundary.circle.radius` | floating point number | no | 1 | `35` `boundary.circle.radius` | floating point number | no | 1 | `35`
@ -37,28 +36,28 @@ Parameter | Type | Required | Default | Example
A basic parameter for filtering is `size`, which is used to limit the number of results returned. In the earlier 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, pass the `size` parameter: A basic parameter for filtering is `size`, which is used to limit the number of results returned. In the earlier 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, pass the `size` parameter:
>[/v1/reverse?api_key=your-mapzen-api-key&point.lat=48.858268&point.lon=2.294471&___size=1___](https://mapzen.com/search/explorer/?query=reverse&point.lat=48.858268&point.lon=2.294471&size=1) > /v1/reverse?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 ### Filter by data source
By default, reverse geocoding returns results from any [data source](data-sources.md) available to Mapzen Search. 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 OpenStreetMap: By default, reverse geocoding returns results from any [data source](data-sources.md) available to Pelias. 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 OpenStreetMap:
| source | name | short name | | source | name | short name |
|---|---|---| |---|---|---|
| [OpenStreetMap](http://www.openstreetmap.org/) | `openstreetmap` | `osm` | | [OpenStreetMap](http://www.openstreetmap.org/) | `openstreetmap` | `osm` |
| [OpenAddresses](http://openaddresses.io/) | `openaddresses` | `oa` | | [OpenAddresses](http://openaddresses.io/) | `openaddresses` | `oa` |
| [Who's on First](https://whosonfirst.mapzen.com) | `whosonfirst` | `wof` | | [Who's on First](https://whosonfirst.org) | `whosonfirst` | `wof` |
| [GeoNames](http://www.geonames.org/) | `geonames` | `gn` | | [GeoNames](http://www.geonames.org/) | `geonames` | `gn` |
>[/v1/reverse?api_key=your-mapzen-api-key&point.lat=48.858268&point.lon=2.294471&___sources=osm___](https://mapzen.com/search/explorer/?query=reverse&point.lat=48.858268&point.lon=2.294471&sources=osm) >/v1/reverse?point.lat=48.858268&point.lon=2.294471&___sources=osm___
### Filter by layers (data type) ### Filter by layers (data type)
Without specifying further, reverse geocoding doesn't restrict results to a particular type (street, venue, neighbourhood, and so on). 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): Without specifying further, reverse geocoding doesn't restrict results to a particular type (street, venue, neighbourhood, and so on). 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-mapzen-api-key&point.lat=48.858268&point.lon=2.294471&___layers=locality___](https://mapzen.com/search/explorer/?query=reverse&point.lat=48.858268&point.lon=2.294471&layers=locality) > /v1/reverse?point.lat=48.858268&point.lon=2.294471&___layers=locality___
Here are all the supported layers and their meanings. Here are all the supported layers and their meanings.
@ -82,7 +81,7 @@ Here are all the supported layers and their meanings.
If you are performing a reverse geocode near a country boundary, and are only interested in results from one country and not the other, you can specify a country code. You can set the `boundary.country` parameter value to the alpha-2 or alpha-3 [ISO-3166 country code](https://en.wikipedia.org/wiki/ISO_3166-1). For example, the latitude,longitude pair `47.270521,9.530846` is on the boundary of Austria, Liechtenstein, and Switzerland. Without specifying a `boundary.country`, the first 10 results returned may come from all three countries. By including `boundary.country=LIE`, all 10 results will be from Liechtenstein. Here's the request in action: If you are performing a reverse geocode near a country boundary, and are only interested in results from one country and not the other, you can specify a country code. You can set the `boundary.country` parameter value to the alpha-2 or alpha-3 [ISO-3166 country code](https://en.wikipedia.org/wiki/ISO_3166-1). For example, the latitude,longitude pair `47.270521,9.530846` is on the boundary of Austria, Liechtenstein, and Switzerland. Without specifying a `boundary.country`, the first 10 results returned may come from all three countries. By including `boundary.country=LIE`, all 10 results will be from Liechtenstein. Here's the request in action:
>[/v1/reverse?api_key=your-mapzen-api-key&point.lat=47.270521&point.lon=9.530846&___boundary.country=LIE___](https://mapzen.com/search/explorer/?query=reverse&point.lat=47.270521&point.lon=9.530846&boundary.country=LIE) > /v1/reverse?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.
@ -104,16 +103,16 @@ Distance from `point.lat`/`point.lon` | Confidence score
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 * All results near the Tower of London
>[/v1/reverse?api_key=your-mapzen-api-key&point.lat=51.5081124&point.lon=-0.0759493](https://mapzen.com/search/explorer/?query=reverse&point.lat=51.5081124&point.lon=-0.0759493) >[/v1/reverse?point.lat=51.5081124&point.lon=-0.0759493](https://mapzen.com/search/explorer/?query=reverse&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-mapzen-api-key&point.lat=51.5081124&point.lon=-0.0759493&sources=osm](https://mapzen.com/search/explorer/?query=reverse&point.lat=51.5081124&point.lon=-0.0759493&sources=osm) >[/v1/reverse?point.lat=51.5081124&point.lon=-0.0759493&sources=osm](https://mapzen.com/search/explorer/?query=reverse&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-mapzen-api-key&point.lat=51.5081124&point.lon=-0.0759493&layers=address](https://mapzen.com/search/explorer/?query=reverse&point.lat=51.5081124&point.lon=-0.0759493&layers=address) >[/v1/reverse?point.lat=51.5081124&point.lon=-0.0759493&layers=address](https://mapzen.com/search/explorer/?query=reverse&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-mapzen-api-key&point.lat=51.5081124&point.lon=-0.0759493&layers=address&sources=osm](https://mapzen.com/search/explorer/?query=reverse&point.lat=51.5081124&point.lon=-0.0759493&layers=address&sources=osm) >[/v1/reverse?point.lat=51.5081124&point.lon=-0.0759493&layers=address&sources=osm](https://mapzen.com/search/explorer/?query=reverse&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-mapzen-api-key&point.lat=51.5081124&point.lon=-0.0759493&layers=address&sources=osm&size=1](https://mapzen.com/search/explorer/?query=reverse&point.lat=51.5081124&point.lon=-0.0759493&layers=address&sources=osm&size=1) >[/v1/reverse?point.lat=51.5081124&point.lon=-0.0759493&layers=address&sources=osm&size=1](https://mapzen.com/search/explorer/?query=reverse&point.lat=51.5081124&point.lon=-0.0759493&layers=address&sources=osm&size=1)

2
search-workflows.md
Unescape View File

@ -1,6 +1,6 @@
# Common geocoding workflows # Common geocoding workflows
Mapzen Search provides several API endpoints, and each is best suited for a particular geocoding workflow. Match your use case to these common scenarios to determine which endpoint to use for tasks in your app. Pelias provides several API endpoints, and each is best suited for a particular geocoding workflow. Match your use case to these common scenarios to determine which endpoint to use for tasks in your app.
## You have a single address field that needs geographic coordinates (`/search`) ## You have a single address field that needs geographic coordinates (`/search`)

108
search.md
Unescape View File

@ -1,24 +1,16 @@
# Mapzen Search: Finding places # Pelias: Finding places
Geospatial search, commonly referred to as geocoding, is the process of matching an address to its corresponding geographic coordinates. Geocoding is the process of matching an address or other text to its corresponding geographic coordinates.
There's nothing inherent in the language we use to describe a physical address that allows us to convert that human readable sentence in to a format that a computer can understand, such as latitude & longitude. All Pelias requests share the same format:
Making the leap from text to coordinates is an intricate and challenging process. Lucky for you, Mapzen has done all the hard work and made it accessible though a web service.
All Mapzen Search requests share the same format:
``` ```
https://search.mapzen.com/v1/search?text=London&api_key= https://search.mapzen.com/v1/search?text=London
\___/ \_______________/\__/\_____/\__________/\_______/ \___/ \_______________/\__/\_____/\_________/
| | / | | | | | / | |
scheme domain version path query authentication token scheme domain version path query
``` ```
In addition, you can search at `https://search.mapzen.com/v1/search/structured` to look for individual components of a location.
Mapzen Search works over HTTPS and HTTP. You are strongly encouraged to use HTTPS for all requests, especially for queries involving potentially sensitive information, such as a user's location or search query.
## Search the world ## Search the world
![Searching globally](/images/world_all.png) ![Searching globally](/images/world_all.png)
@ -27,20 +19,19 @@ In the simplest search, you can provide only one parameter, the text you want to
For example, if you want to find a [YMCA](https://en.wikipedia.org/wiki/YMCA) facility, here's what you'd need to append to the base URL of the service, `search.mapzen.com`. For example, if you want to find a [YMCA](https://en.wikipedia.org/wiki/YMCA) facility, here's what you'd need to append to the base URL of the service, `search.mapzen.com`.
> [/v1/search?api_key=your-mapzen-api-key&___text=YMCA___](https://mapzen.com/search/explorer/?query=search&text=YMCA) > [/v1/search?__text=YMCA__](http://pelias.github.io/compare/#/v1/search%3Ftext=YMCA)
Note the parameter values are set as follows: Note the parameter values are set as follows:
| parameter | value | | parameter | value |
| :--- | :--- | | :--- | :--- |
| `api_key` | [get yours here](https://mapzen.com/developers) |
| `text` | YMCA | | `text` | YMCA |
Clicking the link above will open a file containing the best matching results for the text `YMCA`. You will notice the data is in a computer-friendly format called [GeoJSON](http://geojson.org/), which may be hard for humans to read in some browsers. Clicking the link above will open a file containing the best matching results for the text `YMCA`. You will notice the data is in a computer-friendly format called [GeoJSON](http://geojson.org/), which may be hard for humans to read in some browsers.
You can install a plug-in for your browser to display JSON in a more formatted manner. You can search the web store for your browser to find and install applicable products. You can install a plug-in for your browser to display JSON in a more formatted manner. You can search the web store for your browser to find and install applicable products.
In the example above, you will find the name of each matched locations in a property named `'label'`. The top 10 labels returned were: In the example above, you will find the name of each matched locations in a property named `'label'`. The top 10 labels returned at the time of writing were:
* YMCA, Bargoed Community, United Kingdom * YMCA, Bargoed Community, United Kingdom
* YMCA, Nunspeet, Gelderland * YMCA, Nunspeet, Gelderland
@ -53,15 +44,15 @@ In the example above, you will find the name of each matched locations in a prop
* YMCA, Jefferson, OH * YMCA, Jefferson, OH
* YMCA, Belleville, IL * YMCA, Belleville, IL
Spelling matters, but not capitalization when performing a query with Mapzen Search. You can type `ymca`, `YMCA`, or even `yMcA`. See for yourself by comparing the results of the earlier search to the following: Spelling matters, but not capitalization when performing a query with Pelias. You can type `ymca`, `YMCA`, or even `yMcA`. See for yourself by comparing the results of the earlier search to the following:
> [/v1/search?api_key=your-mapzen-api-key&___text=yMcA___](https://mapzen.com/search/explorer/?query=search&text=yMcA) > [/v1/search?__text=yMcA__](http://pelias.github.io/compare/#/v1/search%3Ftext=yMcA)
Note that the results are spread out throughout the world because you have not given your current location or provided any other geographic context in which to search. Note that the results are spread out throughout the world because you have not given your current location or provided any other geographic context in which to search.
## Search for a component of a location ## Search for a component of a location
With the `text` parameter, your search is composed of all the items in one string. With [structured geocoding](http://search.mapzen.com/v1/search/structured), you can search for individual components of a location. With the `text` parameter, your search is composed of all the items in one string. With [structured geocoding](structured-geocoding.md), you can search for individual components of a location.
Structured geocoding accepts one or more of the following parameters: Structured geocoding accepts one or more of the following parameters:
@ -80,23 +71,22 @@ For more information on how to search this way, see [Structured geocoding](struc
## Set the number of results returned ## Set the number of results returned
By default, Mapzen Search results 10 places, unless otherwise specified. If you want a different number of results, set the `size` parameter to the desired number. This example shows returning only the first result. By default, Pelias results up to 10 places, unless otherwise specified. If you want a different number of results, set the `size` parameter to the desired number. This example shows returning only the first result.
| parameter | value | | parameter | value |
| :--- | :--- | | :--- | :--- |
| `api_key` | [get yours here](https://mapzen.com/developers) |
| `text` | YMCA | | `text` | YMCA |
| `size` | 1 | | `size` | 1 |
> [/v1/search?api_key=your-mapzen-api-key&text=YMCA&___size=1___](https://mapzen.com/search/explorer/?query=search&text=YMCA&size=1) > [/v1/search?text=YMCA&__size=1__](https://mapzen.com/search/explorer/?query=search&text=YMCA&size=1)
If you want 25 results, you can build the query where `size` is 25. If you want 25 results, you can build the query where `size` is 25.
> [/v1/search?api_key=your-mapzen-api-key&text=YMCA&___size=25___](https://mapzen.com/search/explorer/?query=search&text=YMCA&size=25) > [/v1/search?text=YMCA&__size=25__](https://mapzen.com/search/explorer/?query=search&text=YMCA&size=25)
## Narrow your search ## Narrow your search
If you are looking for places in a particular region, or country, or only want to look in the immediate vicinity of a user with a known location, you can narrow your search to an area. There are different ways of including a region in your query. Mapzen Search supports three types: country, rectangle, and circle. If you are looking for places in a particular region, or country, or only want to look in the immediate vicinity of a user with a known location, you can narrow your search to an area. There are different ways of including a region in your query. Pelias supports three types: country, rectangle, and circle.
### Search within a particular country ### Search within a particular country
@ -106,11 +96,10 @@ Sometimes your work might require that all the search results be from a particul
Now, you want to search for YMCA again, but this time only in Great Britain. To do this, you will need to know that the alpha-3 code for Great Britain is GBR and set the parameters like this: Now, you want to search for YMCA again, but this time only in Great Britain. To do this, you will need to know that the alpha-3 code for Great Britain is GBR and set the parameters like this:
> [/v1/search?api_key=your-mapzen-api-key&text=YMCA&___boundary.country=GBR___](https://mapzen.com/search/explorer/?query=search&text=YMCA&boundary.country=GBR) > [/v1/search?text=YMCA&__boundary.country=GBR__](https://mapzen.com/search/explorer/?query=search&text=YMCA&boundary.country=GBR)
| parameter | value | | parameter | value |
| :--- | :--- | | :--- | :--- |
| `api_key` | [get yours here](https://mapzen.com/developers) |
| `text` | YMCA | | `text` | YMCA |
| `boundary.country` | GBR | | `boundary.country` | GBR |
@ -129,7 +118,7 @@ Note that all the results are within Great Britain:
If you try the same search request with different country codes, the results change to show YMCA locations within this region. If you try the same search request with different country codes, the results change to show YMCA locations within this region.
> [/v1/search?api_key=your-mapzen-api-key&text=YMCA&___boundary.country=USA___](https://mapzen.com/search/explorer/?query=search&text=YMCA&boundary.country=USA) > [/v1/search?text=YMCA&__boundary.country=USA__](https://mapzen.com/search/explorer/?query=search&text=YMCA&boundary.country=USA)
Results in the United States: Results in the United States:
@ -154,11 +143,10 @@ For example, to find a YMCA within the state of Texas, you can set the `boundary
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=your-mapzen-api-key&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://mapzen.com/search/explorer/?query=search&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) > [/v1/search?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://mapzen.com/search/explorer/?query=search&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)
| parameter | value | | parameter | value |
| :--- | :--- | | :--- | :--- |
| `api_key` | [get yours here](https://mapzen.com/developers) |
| `text` | YMCA | | `text` | YMCA |
| `boundary.rect.min_lat` | 25.84 | | `boundary.rect.min_lat` | 25.84 |
| `boundary.rect.min_lon` | -106.65 | | `boundary.rect.min_lon` | -106.65 |
@ -184,11 +172,10 @@ Sometimes you don't have a rectangle to work with, but rather you have a point o
In this example, you want to find all YMCA locations within a 35-kilometer radius of a location in Ontario, Canada. This time, you can use the `boundary.circle.*` parameter group, where `boundary.circle.lat` and `boundary.circle.lon` is your location in Ontario and `boundary.circle.radius` is the acceptable distance from that location. Note that the `boundary.circle.radius` parameter is always specified in kilometers. In this example, you want to find all YMCA locations within a 35-kilometer radius of a location in Ontario, Canada. This time, you can use the `boundary.circle.*` parameter group, where `boundary.circle.lat` and `boundary.circle.lon` is your location in Ontario and `boundary.circle.radius` is the acceptable distance from that location. Note that the `boundary.circle.radius` parameter is always specified in kilometers.
> [/v1/search?api_key=your-mapzen-api-key&text=YMCA&__boundary.circle.lon=-79.186484&boundary.circle.lat=43.818156&boundary.circle.radius=35__](https://mapzen.com/search/explorer/?query=search&text=YMCA&boundary.circle.lon=-79.186484&boundary.circle.lat=43.818156&boundary.circle.radius=35) > [/v1/search?text=YMCA&__boundary.circle.lon=-79.186484&boundary.circle.lat=43.818156&boundary.circle.radius=35__](https://mapzen.com/search/explorer/?query=search&text=YMCA&boundary.circle.lon=-79.186484&boundary.circle.lat=43.818156&boundary.circle.radius=35)
| parameter | value | | parameter | value |
| :--- | :--- | | :--- | :--- |
| `api_key` | [get yours here](https://mapzen.com/developers) |
| `text` | YMCA | | `text` | YMCA |
| `boundary.circle.lat` | 43.818156 | | `boundary.circle.lat` | 43.818156 |
| `boundary.circle.lon` | -79.186484 | | `boundary.circle.lon` | -79.186484 |
@ -210,7 +197,7 @@ You can see the results have fewer than the standard 10 items because there are
If you're going to try using multiple boundary types in a single search request, be aware that the results will come from the intersection of all the boundaries. So, if you provide regions that don't overlap, you'll be looking at an empty set of results. If you're going to try using multiple boundary types in a single search request, be aware that the results will come from the intersection of all the boundaries. So, if you provide regions that don't overlap, you'll be looking at an empty set of results.
## Prioritize results by proximity ## Prioritize results by proximity
Many use cases call for the ability to promote nearby results to the top of the list, while still allowing important matches from farther away to be visible. Mapzen Search allows you to prioritize results within geographic boundaries, including around a point, within a country, or within a region. Many use cases call for the ability to promote nearby results to the top of the list, while still allowing important matches from farther away to be visible. Pelias allows you to prioritize results within geographic boundaries, including around a point, within a country, or within a region.
### Prioritize around a point ### Prioritize around a point
@ -220,16 +207,15 @@ By specifying a `focus.point`, nearby places will be scored higher depending on
To find YMCA again, but this time near a specific coordinate location (representing the Sydney Opera House) in Sydney, Australia, use `focus.point`. 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=your-mapzen-api-key&text=YMCA&___focus.point.lat=-33.856680&focus.point.lon=151.215281___](https://mapzen.com/search/explorer/?query=search&text=YMCA&focus.point.lat=-33.856680&focus.point.lon=151.215281) > [/v1/search?text=YMCA&__focus.point.lat=-33.856680&focus.point.lon=151.215281__](https://mapzen.com/search/explorer/?query=search&text=YMCA&focus.point.lat=-33.856680&focus.point.lon=151.215281)
| parameter | value | | parameter | value |
| :--- | :--- | | :--- | :--- |
| `api_key` | [get yours here](https://mapzen.com/developers) |
| `text` | YMCA | | `text` | YMCA |
| `focus.point.lat` | -33.856680 | | `focus.point.lat` | -33.856680 |
| `focus.point.lon` | 151.215281 | | `focus.point.lon` | 151.215281 |
Looking at the results, you can see that the few locations closer to this location show up at the top of the list, sorted by distance. You also still get back a significant amount of remote locations, for a well balanced mix. Because you provided a focus point, Mapzen Search can compute distance from that point for each resulting feature. Looking at the results, you can see that the few locations closer to this location show up at the top of the list, sorted by distance. You also still get back a significant amount of remote locations, for a well balanced mix. Because you provided a focus point, Pelias can compute distance from that point for each resulting feature.
* YMCA, Redfern, New South Wales [distance: 3.836] * YMCA, Redfern, New South Wales [distance: 3.836]
* YMCA, St Ives (NSW), New South Wales [distance: 14.844] * YMCA, St Ives (NSW), New South Wales [distance: 14.844]
@ -250,11 +236,10 @@ Now that you have seen how to use boundary and focus to narrow and sort your res
Going back to the YMCA search you conducted with a focus around a point in Sydney, the results came back from distant parts of the world, as expected. But say you wanted to only see results from the country in which your focus point lies. You can combine that same focus point in Sydney with the country boundary of Australia like this. Going back to the YMCA search you conducted with a focus around a point in Sydney, the results came back from distant parts of the world, as expected. But say you wanted to only see results from the country in which your focus point lies. You can combine that same focus point in Sydney with the country boundary of Australia like this.
> [/v1/search?api_key=your-mapzen-api-key&text=YMCA&___focus.point.lat=-33.856680&focus.point.lon=151.215281___](https://mapzen.com/search/explorer/?query=search&text=YMCA&focus.point.lat=-33.856680&focus.point.lon=151.215281) > [/v1/search?text=YMCA&__focus.point.lat=-33.856680&focus.point.lon=151.215281__](https://mapzen.com/search/explorer/?query=search&text=YMCA&focus.point.lat=-33.856680&focus.point.lon=151.215281)
| parameter | value | | parameter | value |
| :--- | :--- | | :--- | :--- |
| `api_key` | [get yours here](https://mapzen.com/developers) |
| `text` | YMCA | | `text` | YMCA |
| `focus.point.lat` | -33.856680 | | `focus.point.lat` | -33.856680 |
| `focus.point.lon` | 151.215281 | | `focus.point.lon` | 151.215281 |
@ -277,11 +262,10 @@ The results below look different from the ones you saw before with only a focus
If you are looking for the nearest YMCA locations, and are willing to travel no farther than 50 kilometers from your current location, you likely would want the results to be sorted by distance from current location to make your selection process easier. You can get this behavior by using `focus.point` in combination with `boundary.circle.*`. You can use the `focus.point.*` values as the `boundary.circle.lat` and `boundary.circle.lon`, and add the required `boundary.circle.radius` value in kilometers. If you are looking for the nearest YMCA locations, and are willing to travel no farther than 50 kilometers from your current location, you likely would want the results to be sorted by distance from current location to make your selection process easier. You can get this behavior by using `focus.point` in combination with `boundary.circle.*`. You can use the `focus.point.*` values as the `boundary.circle.lat` and `boundary.circle.lon`, and add the required `boundary.circle.radius` value in kilometers.
> [/v1/search?api_key=your-mapzen-api-key&text=YMCA&focus.point.lat=-33.856680&focus.point.lon=151.215281&___boundary.circle.lat=-33.856680&boundary.circle.lon=151.215281&boundary.circle.radius=50___](https://mapzen.com/search/explorer/?query=search&text=YMCA&focus.point.lat=-33.856680&focus.point.lon=151.215281&boundary.circle.lat=-33.856680&boundary.circle.lon=151.215281&boundary.circle.radius=50) > [/v1/search?text=YMCA&focus.point.lat=-33.856680&focus.point.lon=151.215281&__boundary.circle.lat=-33.856680&boundary.circle.lon=151.215281&boundary.circle.radius=50__](https://mapzen.com/search/explorer/?query=search&text=YMCA&focus.point.lat=-33.856680&focus.point.lon=151.215281&boundary.circle.lat=-33.856680&boundary.circle.lon=151.215281&boundary.circle.radius=50)
| parameter | value | | parameter | value |
| :--- | :--- | | :--- | :--- |
| `api_key` | [get yours here](https://mapzen.com/developers) |
| `text` | YMCA | | `text` | YMCA |
| `focus.point.lat` | -33.856680 | | `focus.point.lat` | -33.856680 |
| `focus.point.lon` | 151.215281 | | `focus.point.lon` | 151.215281 |
@ -300,60 +284,58 @@ Looking at these results, they are all less than 50 kilometers away from the foc
## Filter your search ## Filter your search
Mapzen Search brings together data from multiple open sources and combines a variety of place types into a single database, allowing you options for selecting the dataset you want to search. Pelias brings together data from multiple open sources and combines a variety of place types into a single database, allowing you options for selecting the dataset you want to search.
With Mapzen Search, you can filter by: With Pelias, you can filter by:
* `sources`: the originating source of the data * `sources`: the originating source of the data
* `layers`: the kind of place you want to find * `layers`: the kind of place you want to find
### Filter by data source ### Filter by data source
The search examples so far have returned a mix of results from all the data sources available to Mapzen Search. Here are the sources being searched: The search examples so far have returned a mix of results from all the data sources available to Pelias. Here are the sources being searched:
| source | name | short name | | source | name | short name |
|---|---|---| |---|---|---|
| [OpenStreetMap](http://www.openstreetmap.org/) | `openstreetmap` | `osm` | | [OpenStreetMap](http://www.openstreetmap.org/) | `openstreetmap` | `osm` |
| [OpenAddresses](http://openaddresses.io/) | `openaddresses` | `oa` | | [OpenAddresses](http://openaddresses.io/) | `openaddresses` | `oa` |
| [Who's on First](https://whosonfirst.mapzen.com) | `whosonfirst` | `wof` | | [Who's on First](https://whosonfirst.org) | `whosonfirst` | `wof` |
| [GeoNames](http://www.geonames.org/) | `geonames` | `gn` | | [GeoNames](http://www.geonames.org/) | `geonames` | `gn` |
If you use the `sources` parameter, you can choose which of these data sources to include in your search. So if you're only interested in finding a YMCA in data from OpenAddresses, for example, you can build a query specifying that data source. If you use the `sources` parameter, you can choose which of these data sources to include in your search. So if you're only interested in finding a YMCA in data from OpenAddresses, for example, you can build a query specifying that data source.
> [/v1/search?api_key=your-mapzen-api-key&text=YMCA&___sources=oa___](https://mapzen.com/search/explorer/?query=search&text=YMCA&sources=oa) > [/v1/search?text=YMCA&__sources=oa__](https://mapzen.com/search/explorer/?query=search&text=YMCA&sources=oa)
| parameter | value | | parameter | value |
| :--- | :--- | | :--- | :--- |
| `api_key` | [get yours here](https://mapzen.com/developers) |
| `text` | YMCA | | `text` | YMCA |
| `sources` | oa | | `sources` | oa |
Because OpenAddresses is, as the name suggests, only address data, here's what you can expect to find: Because OpenAddresses is, as the name suggests, only address data, here's what you can expect to find:
* 0 Ymca, New Brunswick * 20 Ymca Drive, Niagara, ON, Canada
* 0 Ymca Drive, Cary, NC * 341 Ymca Rd, New Hope, AL, USA
* 14843 Ymca Lane, Cormorant, MN * 318 Ymca Rd, New Hope, AL, USA
* 14660 Ymca Lane, Cormorant, MN * 138 Ymca Rd, New Hope, AL, USA
* 6221 Ymca Lane, Northampton County, VA * 304 Ymca Rd, New Hope, AL, USA
* 6223 Ymca Lane, Northampton County, VA * 1919 Ymca Lane, Minnetonka, MN, USA
* 74 Ymca Road, Wairoa District, Hawke's Bay Region * 101 Ymca Dr, Kannapolis, NC, USA
* 108 Ymca Drive, Clinton, SC * 2121 Ymca Camp Road, Stokes County, NC, USA
* 101 Ymca Drive, Kannapolis, NC * 1110 Ymca Camp Road, Stokes County, NC, USA
* 31440 Ymca Road, Washington, OH * 1581 Ymca Camp Road, Stokes County, NC, USA
If you wanted to combine several data sources together, set `sources` to a comma separated list of desired source names. Note that the order of the comma separated values does not impact sorting order of the results; they are still sorted based on the linguistic match quality to `text` and distance from `focus`, if you specified one. If you wanted to combine several data sources together, set `sources` to a comma separated list of desired source names. Note that the order of the comma separated values does not impact sorting order of the results; they are still sorted based on the linguistic match quality to `text` and distance from `focus`, if you specified one.
> [/v1/search?api_key=your-mapzen-api-key&text=YMCA&___sources=osm,gn___](https://mapzen.com/search/explorer/?query=search&text=YMCA&sources=oa) > [/v1/search?text=YMCA&__sources=osm,gn__](https://mapzen.com/search/explorer/?query=search&text=YMCA&sources=oa)
| parameter | value | | parameter | value |
| :--- | :--- | | :--- | :--- |
| `api_key` | [get yours here](https://mapzen.com/developers) |
| `text` | YMCA | | `text` | YMCA |
| `sources` | osm,gn | | `sources` | osm,gn |
Each of these data sources has properties, licenses, and strengths. You can learn more about the [data sources for Mapzen Search](data-sources.md). Each of these data sources has properties, licenses, and strengths. You can learn more about the [data sources for Pelias](data-sources.md).
### Filter by data type ### Filter by data type
In Mapzen Search, place types are referred to as `layers`, ranging from fine to coarse. The Mapzen Search layers are derived from the hierarchy created by the gazetteer [Who's on First](https://github.com/whosonfirst/whosonfirst-placetypes/blob/master/README.md) and can be used to help coarse geocoding. Here's a list of the types of places you could find in the results, sorted by granularity: In Pelias, place types are referred to as `layers`, ranging from fine to coarse. The Pelias layers are derived from the hierarchy created by the gazetteer [Who's on First](https://github.com/whosonfirst/whosonfirst-placetypes/blob/master/README.md) and can be used to help coarse geocoding. Here's a list of the types of places you could find in the results, sorted by granularity:
|layer|description| |layer|description|
|----|----| |----|----|
@ -371,11 +353,10 @@ In Mapzen Search, place types are referred to as `layers`, ranging from fine to
|`country`|places that issue passports, nations, nation-states| |`country`|places that issue passports, nations, nation-states|
|`coarse`|alias for simultaneously using all administrative layers (everything except `venue` and `address`)| |`coarse`|alias for simultaneously using all administrative layers (everything except `venue` and `address`)|
> [/v1/search?api_key=your-mapzen-api-key&text=YMCA&___layers=venue,address___](https://mapzen.com/search/explorer/?query=search&text=YMCA&layers=venue,address) > [/v1/search?text=YMCA&__layers=venue,address__](https://mapzen.com/search/explorer/?query=search&text=YMCA&layers=venue,address)
| parameter | value | | parameter | value |
| :--- | :--- | | :--- | :--- |
| `api_key` | [get yours here](https://mapzen.com/developers) |
| `text` | YMCA | | `text` | YMCA |
| `layers` | venue,address | | `layers` | venue,address |
@ -383,7 +364,6 @@ In Mapzen Search, place types are referred to as `layers`, ranging from fine to
| Parameter | Type | Required | Default | Example | | Parameter | Type | Required | Default | Example |
| --- | --- | --- | --- | --- | | --- | --- | --- | --- | --- |
| `api_key` | string | yes | none | [get yours here](https://mapzen.com/developers) |
| `text` | string | yes | none | `Union Square` | | `text` | string | yes | none | `Union Square` |
| `focus.point.lat` | floating point number | no | none | `48.581755` | | `focus.point.lat` | floating point number | no | none | `48.581755` |
| `focus.point.lon` | floating point number | no | none | `7.745843` | | `focus.point.lon` | floating point number | no | none | `7.745843` |

44
structured-geocoding.md
Unescape View File

@ -1,6 +1,6 @@
# Structured geocoding # Structured geocoding
With structured geocoding, you can search for the individual parts of a location. Structured geocoding is an option on the [`search` endpoint](search.md), where a query takes the form of https://search.mapzen.com/v1/search/structured. With structured geocoding, you can search for the individual parts of a location. Structured geocoding is an option on the [`search` endpoint](search.md), where a query takes the form of `/v1/search/structured`.
For example, you want to find `30 West 26th Street, New York, NY`. With the geocoding parameter for `search`, you can only enter the entire location as one string, such as `text=30 West 26th Street, New York, NY`. However, with `search/structured`, you can specify that this location is composed of a street address, a locality, and a region. For example, you want to find `30 West 26th Street, New York, NY`. With the geocoding parameter for `search`, you can only enter the entire location as one string, such as `text=30 West 26th Street, New York, NY`. However, with `search/structured`, you can specify that this location is composed of a street address, a locality, and a region.
@ -52,7 +52,7 @@ _Examples_
### neighbourhood ### neighbourhood
[Neighbourhoods](https://whosonfirst.mapzen.com/spelunker/placetypes/neighbourhood/) are vernacular geographic entities that may not necessarily be official administrative divisions but are important nonetheless. [Neighbourhoods](https://spelunker.whosonfirst.org/placetypes/neighbourhood/) are vernacular geographic entities that may not necessarily be official administrative divisions but are important nonetheless.
_Examples_ _Examples_
@ -62,7 +62,7 @@ _Examples_
### borough ### borough
[Boroughs](https://whosonfirst.mapzen.com/spelunker/placetypes/borough/) are mostly known in the context of New York City, even though they may exist in other cities, such as [Mexico City](https://whosonfirst.mapzen.com/spelunker/id/857683023/descendants/?exclude=nullisland&placetype=borough). [Boroughs](https://spelunker.whosonfirst.org/placetypes/borough/) are mostly known in the context of New York City, even though they may exist in other cities, such as [Mexico City](https://spelunker.whosonfirst.org/id/857683023/descendants/?exclude=nullisland&placetype=borough).
_Examples_ _Examples_
@ -73,7 +73,7 @@ A structured geocoding request for `/v1/search/structured?locality=Manhattan&reg
### locality ### locality
[Localities](https://whosonfirst.mapzen.com/spelunker/placetypes/locality/) are equivalent to what are commonly referred to as cities. [Localities](https://spelunker.whosonfirst.org/placetypes/locality/) are equivalent to what are commonly referred to as cities.
_Examples_ _Examples_
@ -83,7 +83,7 @@ _Examples_
### county ### county
[Counties](https://whosonfirst.mapzen.com/spelunker/placetypes/county/) are administrative divisions between localities and regions. [Counties](https://spelunker.whosonfirst.org/placetypes/county/) are administrative divisions between localities and regions.
_Examples_ _Examples_
@ -95,7 +95,7 @@ Counties are not as commonly used in geocoding as localities, but can be useful
### region ### region
[Regions](https://whosonfirst.mapzen.com/spelunker/placetypes/region/) are normally the first-level administrative divisions within countries, analogous to states and provinces in the [United States](https://whosonfirst.mapzen.com/spelunker/id/85633793/descendants/?exclude=nullisland&placetype=region) and [Canada](https://whosonfirst.mapzen.com/spelunker/id/85633041/descendants/?exclude=nullisland&placetype=region), respectively, though most other countries contain regions as well. [Regions](https://spelunker.whosonfirst.org/placetypes/region/) are normally the first-level administrative divisions within countries, analogous to states and provinces in the [United States](https://spelunker.whosonfirst.org/id/85633793/descendants/?exclude=nullisland&placetype=region) and [Canada](https://spelunker.whosonfirst.org/id/85633041/descendants/?exclude=nullisland&placetype=region), respectively, though most other countries contain regions as well.
_Examples_ _Examples_
@ -103,41 +103,41 @@ _Examples_
* [Ontario](https://mapzen.com/search/explorer/?query=search/structured&region=Ontario) * [Ontario](https://mapzen.com/search/explorer/?query=search/structured&region=Ontario)
* [Ardennes](https://mapzen.com/search/explorer/?query=search/structured&region=Ardennes) * [Ardennes](https://mapzen.com/search/explorer/?query=search/structured&region=Ardennes)
Regions in the United States have [common abbreviations](https://en.wikipedia.org/wiki/List_of_U.S._state_abbreviations), such as PA for [Pennsylvania](https://whosonfirst.mapzen.com/spelunker/id/85688481/) and NM for [New Mexico](https://whosonfirst.mapzen.com/spelunker/id/85688493/). The `region` parameter can be a full name or abbreviation, so specifying `/v1/search/structured?region=NM` is functionality equivalent to `/v1/search/structured?region=New Mexico`. Regions in the United States have [common abbreviations](https://en.wikipedia.org/wiki/List_of_U.S._state_abbreviations), such as PA for [Pennsylvania](https://spelunker.whosonfirst.org/id/85688481/) and NM for [New Mexico](https://spelunker.whosonfirst.org/id/85688493/). The `region` parameter can be a full name or abbreviation, so specifying `/v1/search/structured?region=NM` is functionality equivalent to `/v1/search/structured?region=New Mexico`.
### postalcode ### postalcode
[Postal codes](https://whosonfirst.mapzen.com/spelunker/placetypes/postalcode/) are used to aid in sorting mail with the format dictated by an administrative division, which is almost always countries. Among other reasons, postal codes are unique within a country so they are useful in geocoding as a shorthand for a fairly granular geographical location. [Postal codes](https://spelunker.whosonfirst.org/placetypes/postalcode/) are used to aid in sorting mail with the format dictated by an administrative division, which is almost always countries. Among other reasons, postal codes are unique within a country so they are useful in geocoding as a shorthand for a fairly granular geographical location.
_Examples_ _Examples_
* [90210](https://whosonfirst.mapzen.com/spelunker/id/554783991/) * [90210](https://spelunker.whosonfirst.org/id/554783991/)
* [CV23 9SL](https://whosonfirst.mapzen.com/spelunker/id/454261459/) * [CV23 9SL](https://spelunker.whosonfirst.org/id/454261459/)
* [5439171](https://whosonfirst.mapzen.com/spelunker/id/538904173/) * [5439171](https://spelunker.whosonfirst.org/id/538904173/)
Keep in mind that you can search for `postalcode` exclusively. So requests like [/v1/search/structured?postalcode=87801]( https://mapzen.com/search/explorer/?query=search/structured&postalcode=87801) will return matching postalcode records. Keep in mind that you can search for `postalcode` exclusively. So requests like [/v1/search/structured?postalcode=87801]( https://mapzen.com/search/explorer/?query=search/structured&postalcode=87801) will return matching postalcode records.
### country ### country
[Countries](https://whosonfirst.mapzen.com/spelunker/placetypes/country/) are the highest-level administrative divisions supported in a search. In addition to full names, countries have common [two-](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) and [three-letter](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) abbreviations that are also supported values for the `country` parameter. [Countries](https://spelunker.whosonfirst.org/placetypes/country/) are the highest-level administrative divisions supported in a search. In addition to full names, countries have common [two-](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) and [three-letter](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) abbreviations that are also supported values for the `country` parameter.
_Examples_ _Examples_
* [Liechtenstein](https://mapzen.com/search/explorer/?query=search/structured&country=Liechtenstein) * [Liechtenstein](https://mapzen.com/search/explorer/?query=search/structured&country=Liechtenstein)
* [CMR](https://mapzen.com/search/explorer/?query=search/structured&country=CMR) ([Cameroon](https://whosonfirst.mapzen.com/spelunker/id/85632245/)) * [CMR](https://mapzen.com/search/explorer/?query=search/structured&country=CMR) ([Cameroon](https://spelunker.whosonfirst.org/id/85632245/))
* [Bermuda](https://mapzen.com/search/explorer/?query=search/structured&country=Bermuda) * [Bermuda](https://mapzen.com/search/explorer/?query=search/structured&country=Bermuda)
## Who's On First layer mappings reference ## Who's On First layer mappings reference
The [Who's on First](https://whosonfirst.mapzen.com/) gazetteer is one of the datasets used as a source of search data. Use this table is a reference between the parameters for structured geocoding and the [types of places in Who's on First](https://whosonfirst.mapzen.com/placetypes/). The [Who's on First](https://whosonfirst.org/) gazetteer is one of the datasets used as a source of search data. Use this table is a reference between the parameters for structured geocoding and the [types of places in Who's on First](https://whosonfirst.org/placetypes/).
| Structured geocoding parameter | Who's on First placetype | | Structured geocoding parameter | Who's on First placetype |
| -------------------- | ------------------------- | | -------------------- | ------------------------- |
| `neighbourhood` | [neighbourhood](https://whosonfirst.mapzen.com/spelunker/placetypes/neighbourhood/) | | `neighbourhood` | [neighbourhood](https://spelunker.whosonfirst.org/placetypes/neighbourhood/) |
| `borough` | [borough](https://whosonfirst.mapzen.com/spelunker/placetypes/borough/) | | `borough` | [borough](https://spelunker.whosonfirst.org/placetypes/borough/) |
| `locality` | [locality](https://whosonfirst.mapzen.com/spelunker/placetypes/locality/), [localadmin](https://whosonfirst.mapzen.com/spelunker/placetypes/localadmin/) (and [borough](https://whosonfirst.mapzen.com/spelunker/placetypes/borough/) if `borough` parameter is not supplied) | | `locality` | [locality](https://spelunker.whosonfirst.org/placetypes/locality/), [localadmin](https://spelunker.whosonfirst.org/placetypes/localadmin/) (and [borough](https://spelunker.whosonfirst.org/placetypes/borough/) if `borough` parameter is not supplied) |
| `county` | [county](https://whosonfirst.mapzen.com/spelunker/placetypes/county/), [macrocounty](https://whosonfirst.mapzen.com/spelunker/placetypes/macrocounty/) | | `county` | [county](https://spelunker.whosonfirst.org/placetypes/county/), [macrocounty](https://spelunker.whosonfirst.org/placetypes/macrocounty/) |
| `region` | [region](https://whosonfirst.mapzen.com/spelunker/placetypes/region/), [macroregion](https://whosonfirst.mapzen.com/spelunker/placetypes/macroregion/) | | `region` | [region](https://spelunker.whosonfirst.org/placetypes/region/), [macroregion](https://spelunker.whosonfirst.org/placetypes/macroregion/) |
| `country` | [dependency](https://whosonfirst.mapzen.com/spelunker/placetypes/dependency/), [country](https://whosonfirst.mapzen.com/spelunker/placetypes/country/) | | `country` | [dependency](https://spelunker.whosonfirst.org/placetypes/dependency/), [country](https://spelunker.whosonfirst.org/placetypes/country/) |
For example, [Peach Bottom, Pennsylvania](https://whosonfirst.mapzen.com/spelunker/id/404487863/) is only a `localadmin` place type and not a `locality` in Who's on First. For simplicity, if a structured geocoding request specifies `locality=Peach Bottom&region=Pennsylvania`, then `Peach Bottom` in both the `locality` and `localadmin` layers are searched. For example, [Peach Bottom, Pennsylvania](https://spelunker.whosonfirst.org/id/404487863/) is only a `localadmin` place type and not a `locality` in Who's on First. For simplicity, if a structured geocoding request specifies `locality=Peach Bottom&region=Pennsylvania`, then `Peach Bottom` in both the `locality` and `localadmin` layers are searched.

203
transition-from-beta.md
Unescape View File

@ -1,203 +0,0 @@
# Mapzen Search: Beta to V1 transition guide
First of all, thank you for being an early user of Mapzen Search/Pelias. You trusted the idea of a modern geocoding service built by and for the open mapping community and have helped make that happen.
This project is moving out of the beta stage and has an updated API designed to support the next several generations of progress to Pelias and Mapzen Search.
The changes aren't too drastic and should be implementable in an afternoon or a day at most for existing users.
These changes also affect self-hosted users of Pelias upgrading from the beta to 1.0 (leaving aside API key restrictions), but these users can make the upgrade on their own time.
## API keys
The first big change is the introduction of API keys. Like all other Mapzen APIs, Search now requires an API key. You can register at the [Mapzen Developer Portal](https://mapzen.com/developers) and generate one (or more) for all your search needs.
Mapzen Search API keys allow you:
* 6 requests per second
* 30,000 requests per day
To start using an API key, append `&api_key=mapzen-xxxxxx` to all API calls to all endpoints (aside from `/attribution`, which requires no key).
Your API usage limits are displayed in the HTTP headers of any API call, such as in this example:
```
X-ApiaxleProxy-Qpd-Left:4828
X-ApiaxleProxy-Qps-Left:4
```
## Changes to domain and URL structure
Mapzen Search is now hosted on the `search.mapzen.com` domain. The former domain, `pelias.mapzen.com` has been deprecated. To take advantage of the full v1 API, you must use the `search.mapzen.com` endpoint.
Additionally, all endpoints are now under the `/v1` namespace. For example, the full URI to the `/reverse` endpoint is now `https://search.mapzen.com/v1/reverse`.
Requests going to `pelias.mapzen.com` will continue to work until the end of November, 2015, at which point the servers handling pre-v1 requests will be disabled.
## Changes to response document
The response document is still plain, vanilla GeoJSON. Dots will still show up without a problem! Take a look at the [specification document](https://github.com/pelias/geocodejson-spec/blob/master/draft/README.md) or the [sample response](https://github.com/pelias/geocodejson-spec/blob/master/sample.geo.json?short_path=7cdb999) for further details.
### Metadata
The GeoJSON result object now contains a `geocoding` property that has lots of information about the request, such as how Mapzen Search parsed your query, certain explicit errors and warnings, and an attribution link.
### Features
The bulk of a valid response is still an array of `Feature` objects, ordered by result ranking (most relevant result first).
If the only property you used before was `text` for what to display, you'll have to change it to `label` and you'll be ready to process responses.
| Used to be (Beta) | Is now (V1) | Notes |
| ----------------- | ----------- | --------------- |
| `text` | `label` | The suggested display text. You can construct your own from the elements passed along, but this is Mapzen Search's best understanding of how to display it. |
| `layer` | `layer` & `source` | Some layers were not attributes, but sources the data was derived from. This has been split out into a separate field (see Search/Layers below for full explanation). |
| `admin0` | `country` | Now with Human Readable:tm: |
| `admin1` | `region` | States and provinces |
| `alpha3` | `country_a` | Three-character abbreviation for country |
| `admin1_abbr` | `region_a` | Region abbreviation (such as NY = New York, usually two characters) |
| `locality` | `locality` | No change|
| `neighborhood` | `neighbourhood` | Note change in spelling |
| `category` | Deprecated | This functionality is in progress and should be available soon. |
| `address:{}` | | Address elements are no longer grouped into their own object |
| `address:{zip}` | `postalcode` | |
| `address:{number}` | `housenumber` | |
| `address:{street}` | `street` | |
## Changes to `/search`
Most parameters (and options) for search have been renamed:
| Used to be (Beta) | New parameter (V1) | New behavior (if any) |
| ---------- | ------------- | --------------------- |
| `input` | `text` | |
| `lat` / `lon` | `focus.point.lat` / `focus.point.lon` | Biases search results toward places nearby, without excluding global matches |
| `zoom` | `focus.viewport.min_lon`, `focus.viewport.min_lat`, `focus.viewport.max_lon`, `focus.viewport.max_lat` | Passing along information about how far out an end-user is looking is now accomplished by passing along the end-user's viewport. Why judge just from a centerpoint and a zoom level when you can see what the user's seeing? |
| `size` | `count` | Number of responses. Minimum: 1, maximum: 50 |
| `layers` | `layers` (SEE BELOW) | While the parameter remains the same, the options have changed. See the table below for a description.|
| `bbox` | `boundary.rect.min_lon`, `boundary.rect.min_lat`, `boundary.rect.max_lon`, `boundary.rect.max_lat`| Bounding box parameters are now individually specified to prevent error.|
| `details` | Deprecated (for the moment) | `details=false` used to respond with a minimized set of elements. Mapzen is reevaluating which elements of the response document make most sense for minimization. If you've got opinions, let us know at [search@mapzen.com](mailto:search@mapzen.com)|
`layers` used to be opaque about many of the kinds of places they represented (particularly the administrative layers). `layers` were also used to retrieve places from a particular source. `sources` is now a separate parameter from `layers` to help improve clarity.
| Beta | V1 | Represents |
| -------------- | ------------ | ---------------- |
| `layers=geoname` | `sources=geonames` or `sources=gn` | [All manners of places](http://www.geonames.org/export/codes.html) from Geonames |
| `layers=osmnode` | `layers=venue,address&sources=openstreetmap` | Venues (points of interest) and all places with addresses from OpenStreetMap|
| `layers=osmway` | `layers=venue,address&sources=openstreetmap` | Streets and highways with addresses |
| `layers=admin0` | `layers=country` | Countries|
| `layers=admin1` | `layers=region` | Provinces and states (for the most part) |
| `layers=admin2` | `layers=county` | Things within states that often aren't cities, but sometimes are.|
| `layers=neighborhood` | `layers=neighbourhood` | Neighbourhoods (within localities, may be [macrohoods](http://whosonfirst.mapzen.com/spelunker/placetypes/macrohood/), neighbourhoods, or [microhoods](http://whosonfirst.mapzen.com/spelunker/placetypes/microhood/)) |
| `layers=locality` | `layers=locality` | |
| `layers=local_admin` | `layers=localadmin` | Local administrative areas (such as New York City, encompassing the five boroughs of NYC, which are themselves independent counties)|
| `layers=osmaddresses` | `layers=addresses&source=openstreetmap` | Addresses from OpenStreetMap|
| `layers=openaddresses` | `source=openaddresses` | Addresses from OpenAddresses |
| `layers=poi` | `layers=venue` | Places with walls |
| `layers=admin` | `layers=coarse` | Shortcut for coarse geocoding layers (see below) |
| `layers=address` | `layers=address` | |
So the new, valid `layers` values are:
* `venue`
* `address`
* `neighbourhood`
* `localadmin`
* `locality`
* `county`
* `region`
* `country`
* `coarse`
And the `sources` values are:
* `openstreetmap` or `osm`
* `geonames` or `gn`
* `openaddresses` or `oa`
* `quattroshapes` or `qs`
## Additions
| New | What's it do? |
| ------------ | ------------- |
| `sources` parameter | Pick the data source (separate from `layers`) |
| `boundary.circle` | Bounding circle. Like a bounding box, but circular. Takes, `boundary.circle.lon`, `boundary.circle.lat`, and `boundary.circle.radius` (in kilometers) |
| `boundary.country` | Search only within a particular country. Takes Alpha-2 or Alpha-3 country code abbreviations.|
## Coarse search
Coarse search (looking for countries, regions, counties, localities, neighbourhoods), were available on `/search/coarse`. This is now handled as a layer on search.
A former query for a coarse geocode may have been:
`https://pelias.mapzen.com/search/coarse?input=<search-text>`
That same query would now be written as:
`https://search.mapzen.com/v1/search?text=<search-text>&layers=coarse&api_key=<mapzen-xxxxxx>`
You can also call the coarse layers directly, namely, `country`, `region`, `county`, `locality`, `neighbourhood`, to restrict the kinds of results you'll get back.
Feel free to mix and match these layers with `boundary` parameters, particularly `boundary.country` if you want to restrict your results to a particular country.
## `/autocomplete` (formerly `/suggest`)
The `/autocomplete` endpoint serves as a renamed `/suggest` to show that these are not recommendations. It is subject to many of the same changes as `/search`:
| Used to be (Beta) | New parameter (V1) | New behavior (if any) |
| ---------- | ------------- | --------------------- |
| `input` | `text` | Required |
| `lat` / `lon` | `focus.point.lat` / `focus.point.lon` | Biases search results toward places nearby, without excluding global matches. No longer required for `/autocomplete` |
| `size` | Deprecated | Responds with 10 results every time |
| `zoom` | Deprecated | |
| `layers` | Deprecated | |
| `bbox` | Deprecated | |
| `details` | Deprecated | |
### Deprecated endpoints
- `/suggest/coarse`
- `/suggest/nearby`
## `/reverse`
Reverse geocoding finds the places closest to geospatial coordinates.
```
https://search.mapzen.com/v1/reverse?point.lon={longitude}&point.lat={latitude}&api_key=mapzen-xxxxxx
```
Used to be (Beta) | New parameter (V1) | New behavior (if any) |
| ---------- | ------------- | --------------------- |
| `lat` / `lon` | `point.lon` / `point.lat` | Required |
| `layers` | `layers` | same set of layers as for `/search` |
New parameters:
- `boundary.circle` - use `boundary.circle.radius` to set the distance for a reverse point search in kilometers
- `boundary.country` - Restricts reverse geocodes to a particular country based on alpha2 or alpha3 country codes
### Reverse coarse geocoding
Reverse coarse geocoding is not a point-in-polygon lookup (finding the hierarchy for the polygon that the point falls in), but instead looks for the hierarchy of points nearby. To use reverse coarse geocoding, use:
```https://search.mapzen.com/v1/reverse?point.lon={longitude}&point.lat={latitude}&layers=coarse&api_key=mapzen-xxxxxx
```
## `/place` (formerly `/doc`)
`/place` is used to retrieve the underlying place record behind a particular result.
If a search returns `id: "geonames:3544:adm1:fr:fra:paris"` as the matching ID for a record, the complete underlying place record can be returned with:
```
https://search.mapzen.com/v1/place?ids=geonames:3544:adm1:fr:fra:paris&api_key=mapzen-xxxxxx
```
## Security
### 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.
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.
Mapzen Search is set to allow CORS requests from all domains.
### HTTPS
Mapzen Search continues to support HTTPS and traditional HTTP. You are encouraged to use HTTPS instead of HTTP, especially when handling sensitive personal information (such as users' searches or users' location data).
## What's happening to pelias.mapzen.com?
The beta API available at pelias.mapzen.com will be available through the end of November, 2015. Starting December 1, 2015, you will only be able to use search.mapzen.com or your own hosted version of Pelias.
## Where to send comments and issues
Let us know.
Words go to: [search@mapzen.com](mailto:search@mapzen.com)
Issues go to [GitHub](https://github.com/pelias/pelias-doc/issues)

1
transition.md
Unescape View File

@ -1 +0,0 @@
008-transition-from-beta.md

8
use-cors.md
Unescape View File

@ -8,13 +8,13 @@ Fortunately, techniques have since been developed that allow developers to secur
`CORS` is the recommended standard for allowing your web browser and a web server to negotiate and allow requests to be made across domain contexts. `CORS` is supported in modern Chrome, Firefox, Safari, and Internet Explorer (10+) web browsers. It became a [W3C Recommendation](https://www.w3.org/TR/cors/) in 2014. `CORS` is the recommended standard for allowing your web browser and a web server to negotiate and allow requests to be made across domain contexts. `CORS` is supported in modern Chrome, Firefox, Safari, and Internet Explorer (10+) web browsers. It became a [W3C Recommendation](https://www.w3.org/TR/cors/) in 2014.
You don’t need to do anything special to use `CORS` with JavaScript in a modern browser. Your web browser and the Mapzen Search servers will automatically negotiate the cross-origin request. For example, to make a `CORS` request with `jQuery`, you’d make your request like you were performing it within the context of your own domain. You don’t need to do anything special to use `CORS` with JavaScript in a modern browser. Your web browser and the Pelias servers will automatically negotiate the cross-origin request. For example, to make a `CORS` request with `jQuery`, you’d make your request like you were performing it within the context of your own domain.
For a full list of supported browsers see: http://caniuse.com/#feat=cors For a full list of supported browsers see: http://caniuse.com/#feat=cors
### Add a search box to a Leaflet map ### Add a search box to a Leaflet map
You can add a Mapzen Search box to any [Leaflet](http://leafletjs.com/) map. You can add a Pelias box to any [Leaflet](http://leafletjs.com/) map.
See the [Mapzen.js documentation](https://mapzen.com/documentation/mapzen-js/search/#add-mapzen-search-box-to-a-map) for instructions. There is also a [tutorial](add-search-to-a-map.md) available. See the [Mapzen.js documentation](https://mapzen.com/documentation/mapzen-js/search/#add-mapzen-search-box-to-a-map) for instructions. There is also a [tutorial](add-search-to-a-map.md) available.
@ -68,11 +68,11 @@ Also called “JSON with Padding”, `JSONP` is a technique for fooling a web br
Instead of responding with a `JSON` object, the server responds with JavaScript code that calls a client-declared callback function, passing the data as that function’s first parameter. Instead of responding with a `JSON` object, the server responds with JavaScript code that calls a client-declared callback function, passing the data as that function’s first parameter.
`JSONP` **is disabled** by default for Mapzen Search, as `CORS` is offered as a more modern alternative. `JSONP` **is disabled** by default for Pelias, as `CORS` is offered as a more modern alternative.
You can find more information online by performing a web search for `"CORS vs JSONP"` and `"Security risks with JSONP"`. You can find more information online by performing a web search for `"CORS vs JSONP"` and `"Security risks with JSONP"`.
If you are having any issues implementing `CORS` with Mapzen Search, open an issue in the [main Pelias GitHub repository](https://github.com/pelias/pelias/issues). Please include the name of any frameworks you are using and some example code. If you are having any issues implementing `CORS` with Pelias, open an issue in the [main Pelias GitHub repository](https://github.com/pelias/pelias/issues). Please include the name of any frameworks you are using and some example code.
--- ---

Write Preview
Loading…
Cancel
Save