From e054cc484e4f2bd914a901d60603c80a2dadb5e0 Mon Sep 17 00:00:00 2001 From: Julian Simioni Date: Thu, 15 Mar 2018 16:21:35 -0400 Subject: [PATCH 01/12] s/Mapzen Search/Pelias/ --- add-search-to-a-map.md | 28 ++++++++++++++-------------- addresses.md | 2 +- api-keys-rate-limits.md | 10 +++++----- glossary.md | 16 ++++++++-------- place.md | 4 ++-- release-notes.md | 6 +++--- response.md | 10 +++++----- reverse.md | 6 +++--- search-workflows.md | 2 +- search.md | 26 +++++++++++++------------- use-cors.md | 8 ++++---- 11 files changed, 59 insertions(+), 59 deletions(-) diff --git a/add-search-to-a-map.md b/add-search-to-a-map.md index a379b17..dac3c68 100644 --- a/add-search-to-a-map.md +++ b/add-search-to-a-map.md @@ -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 @@ -230,15 +230,15 @@ Now, you will test your search box by finding a few locations. As you type, the ## 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. -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. @@ -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 -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. -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. @@ -305,7 +305,7 @@ As you were searching, you might have noticed results that looked similar. Mapze ## 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. @@ -327,11 +327,11 @@ Mapzen.js automatically provides a [focus point](https://mapzen.com/documentatio ## 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. -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. @@ -350,9 +350,9 @@ You can review the [Mapzen Search documentation](https://mapzen.com/documentatio ## 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. diff --git a/addresses.md b/addresses.md index 43f0347..e94bef4 100644 --- a/addresses.md +++ b/addresses.md @@ -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. -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`. diff --git a/api-keys-rate-limits.md b/api-keys-rate-limits.md index 24890d3..bbdb0a9 100644 --- a/api-keys-rate-limits.md +++ b/api-keys-rate-limits.md @@ -4,17 +4,17 @@ _Note: This page is deprecated and has been removed from the documentation on ht ## 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. ## 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`. @@ -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: -- `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`. diff --git a/glossary.md b/glossary.md index ca2c0cf..c822c08 100644 --- a/glossary.md +++ b/glossary.md @@ -1,4 +1,4 @@ -# Mapzen Search glossary +# Pelias glossary ## 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. - **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 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 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. 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. -- **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. -- **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. - **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). - **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. -- **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. +- **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 Pelias, longitudes are in relation to the Prime Meridian and expressed in decimal degrees. diff --git a/place.md b/place.md index fbdf3e7..94d02c7 100644 --- a/place.md +++ b/place.md @@ -1,8 +1,8 @@ # 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): diff --git a/release-notes.md b/release-notes.md index edf1823..d963672 100644 --- a/release-notes.md +++ b/release-notes.md @@ -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 -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. :) @@ -157,7 +157,7 @@ Another data-only release. Stay tuned for next week! ## 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 @@ -253,7 +253,7 @@ We also have two **known issues** in this build: ## 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). See the detailed list of changes below for more specifics. diff --git a/response.md b/response.md index c13ba5f..3d5895a 100644 --- a/response.md +++ b/response.md @@ -1,6 +1,6 @@ # 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. @@ -65,11 +65,11 @@ Additionally, [/reverse](reverse.md) queries will have a `distance` parameter, w ## `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` -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`. @@ -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. -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` @@ -105,7 +105,7 @@ Features from Who's on First and OpenStreetMap often have their own `bbox` eleme ## 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 | | :--- | :--- | diff --git a/reverse.md b/reverse.md index b78e253..aad80f8 100644 --- a/reverse.md +++ b/reverse.md @@ -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. -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 * points of interest (businesses, museums, parks, and so on) @@ -20,7 +20,7 @@ The output is the standard GeoJSON format. ## 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 --- | --- | --- | --- | --- @@ -43,7 +43,7 @@ The default value for `size` is `10` and the maximum value is `40`. Specifying a ### 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 | |---|---|---| diff --git a/search-workflows.md b/search-workflows.md index 4425b0c..eed15da 100644 --- a/search-workflows.md +++ b/search-workflows.md @@ -1,6 +1,6 @@ # 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`) diff --git a/search.md b/search.md index b379723..e86903c 100644 --- a/search.md +++ b/search.md @@ -1,4 +1,4 @@ -# 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. @@ -6,7 +6,7 @@ There's nothing inherent in the language we use to describe a physical address t 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: +All Pelias requests share the same format: ``` https://search.mapzen.com/v1/search?text=London&api_key= @@ -17,7 +17,7 @@ All Mapzen Search requests share the same format: 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. +Pelias 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 @@ -53,7 +53,7 @@ In the example above, you will find the name of each matched locations in a prop * YMCA, Jefferson, OH * 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) @@ -80,7 +80,7 @@ For more information on how to search this way, see [Structured geocoding](struc ## 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 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 | | :--- | :--- | @@ -96,7 +96,7 @@ If you want 25 results, you can build the query where `size` is 25. ## 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 @@ -210,7 +210,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. ## 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 @@ -229,7 +229,7 @@ To find YMCA again, but this time near a specific coordinate location (represent | `focus.point.lat` | -33.856680 | | `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, St Ives (NSW), New South Wales [distance: 14.844] @@ -300,15 +300,15 @@ Looking at these results, they are all less than 50 kilometers away from the foc ## 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 * `layers`: the kind of place you want to find ### 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 | |---|---|---| @@ -350,10 +350,10 @@ If you wanted to combine several data sources together, set `sources` to a comma | `text` | YMCA | | `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 -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| |----|----| diff --git a/use-cors.md b/use-cors.md index bf8c1a6..63da3e6 100644 --- a/use-cors.md +++ b/use-cors.md @@ -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. -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 ### 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. @@ -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. -`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"`. -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. --- From 71bd388e33a9febcec57427676ffaa8d7ebd3d85 Mon Sep 17 00:00:00 2001 From: Julian Simioni Date: Thu, 15 Mar 2018 16:22:40 -0400 Subject: [PATCH 02/12] Rewrite documentation index My biggest regret is that many excellent @riordan words must be removed, since most Pelias descriptions are over in pelias/pelias. --- index.md | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/index.md b/index.md index b7d2666..113b3c6 100644 --- a/index.md +++ b/index.md @@ -1,14 +1,20 @@ -[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. +# Pelias Documentation -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. +Here is where you can find all documentation for the [Pelias geocoder](https://github.com/pelias/pelias/). -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 +## 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) -- Open-source software using [open data sources](data-sources.md) +- [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) From aeae0751a05b16f004508deabf143b22c32d747f Mon Sep 17 00:00:00 2001 From: Julian Simioni Date: Thu, 15 Mar 2018 16:24:30 -0400 Subject: [PATCH 03/12] Remove Beta transition docs Everyone has moved on, right? --- transition-from-beta.md | 203 ---------------------------------------- transition.md | 1 - 2 files changed, 204 deletions(-) delete mode 100644 transition-from-beta.md delete mode 120000 transition.md diff --git a/transition-from-beta.md b/transition-from-beta.md deleted file mode 100644 index 8e23093..0000000 --- a/transition-from-beta.md +++ /dev/null @@ -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=` - -That same query would now be written as: -`https://search.mapzen.com/v1/search?text=&layers=coarse&api_key=` - -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) diff --git a/transition.md b/transition.md deleted file mode 120000 index a0f2e21..0000000 --- a/transition.md +++ /dev/null @@ -1 +0,0 @@ -008-transition-from-beta.md \ No newline at end of file From 87e8c5f22603a0f667577efef4e2ebc1987c8990 Mon Sep 17 00:00:00 2001 From: Julian Simioni Date: Thu, 15 Mar 2018 16:39:58 -0400 Subject: [PATCH 04/12] Tweak the autocomplete page --- autocomplete.md | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/autocomplete.md b/autocomplete.md index 589cdcd..5a84d57 100644 --- a/autocomplete.md +++ b/autocomplete.md @@ -18,8 +18,7 @@ To focus your search based upon a geographical area, such as the center of the u From San Francisco: -> -[/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) +> /v1/autocomplete?__focus.point.lat=37.7&focus.point.lon=-122.4__&text=union square ``` 1) Union Square, San Francisco County, CA @@ -28,8 +27,7 @@ From San Francisco: From New York City: -> -[/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) +> /v1/autocomplete?__focus.point.lat=40.7&focus.point.lon=-73.9__&text=union square ``` 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: -> [/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: ``` @@ -65,7 +63,7 @@ The `sources` parameter allows you to specify from which data sources you'd like * `geonames` or `gn` * `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: ``` @@ -101,7 +99,7 @@ The type of record is referred to as its `layer`. All records are indexed into t |`neighbourhood`|social communities, neighbourhoods| |`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 @@ -129,7 +127,6 @@ Sometimes your work might require that all the search results be from a particul | Parameter | Type | Required | Default | Example | | --- | --- | --- | --- | --- | -| `api_key` | string | yes | none | [get yours here](https://mapzen.com/developers) | | `text` | string | yes | none | `Union Square` | | `focus.point.lat` | floating point number | no | none | `48.581755` | | `focus.point.lon` | floating point number | no | none | `7.745843` | From 85032510d6e5ed306af3a02ddefd4b55c0a6bde0 Mon Sep 17 00:00:00 2001 From: Julian Simioni Date: Thu, 15 Mar 2018 16:46:53 -0400 Subject: [PATCH 05/12] Tweak Reverse --- reverse.md | 23 +++++++++++------------ 1 file changed, 11 insertions(+), 12 deletions(-) diff --git a/reverse.md b/reverse.md index aad80f8..d6a1fe2 100644 --- a/reverse.md +++ b/reverse.md @@ -14,7 +14,7 @@ With reverse geocoding with Pelias, you can look up all sorts of information abo 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. @@ -24,7 +24,6 @@ Like other queries with Pelias, reverse geocoding has optional, additional param 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.lon` | floating point number | yes | none | `2.294471` `boundary.circle.radius` | floating point number | no | 1 | `35` @@ -37,7 +36,7 @@ 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: ->[/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. @@ -49,16 +48,16 @@ By default, reverse geocoding returns results from any [data source](data-source |---|---|---| | [OpenStreetMap](http://www.openstreetmap.org/) | `openstreetmap` | `osm` | | [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` | ->[/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) 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. @@ -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: ->[/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. @@ -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. * 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 ->[/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 ->[/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 ->[/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 ->[/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) From 390b7c10a8382ee3d7c7543fff3671d960b64420 Mon Sep 17 00:00:00 2001 From: Julian Simioni Date: Thu, 15 Mar 2018 16:58:02 -0400 Subject: [PATCH 06/12] Cleanup search docs --- search.md | 84 +++++++++++++++++++++---------------------------------- 1 file changed, 32 insertions(+), 52 deletions(-) diff --git a/search.md b/search.md index e86903c..eb3c534 100644 --- a/search.md +++ b/search.md @@ -1,24 +1,16 @@ # Pelias: Finding places -Geospatial search, commonly referred to as geocoding, is the process of matching an address 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. - -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. +Geocoding is the process of matching an address or other text to its corresponding geographic coordinates. All Pelias requests share the same format: ``` - https://search.mapzen.com/v1/search?text=London&api_key= - \___/ \_______________/\__/\_____/\__________/\_______/ - | | / | | | - scheme domain version path query authentication token + https://search.mapzen.com/v1/search?text=London + \___/ \_______________/\__/\_____/\_________/ + | | / | | + 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. - -Pelias 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 ![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`. -> [/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: | parameter | value | | :--- | :--- | -| `api_key` | [get yours here](https://mapzen.com/developers) | | `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. 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, Nunspeet, Gelderland @@ -55,13 +46,13 @@ In the example above, you will find the name of each matched locations in a prop 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. ## 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: @@ -80,19 +71,18 @@ For more information on how to search this way, see [Structured geocoding](struc ## Set the number of results returned -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. +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 | | :--- | :--- | -| `api_key` | [get yours here](https://mapzen.com/developers) | | `text` | YMCA | | `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. -> [/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 @@ -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: -> [/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 | | :--- | :--- | -| `api_key` | [get yours here](https://mapzen.com/developers) | | `text` | YMCA | | `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. -> [/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: @@ -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/). -> [/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 | | :--- | :--- | -| `api_key` | [get yours here](https://mapzen.com/developers) | | `text` | YMCA | | `boundary.rect.min_lat` | 25.84 | | `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. -> [/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 | | :--- | :--- | -| `api_key` | [get yours here](https://mapzen.com/developers) | | `text` | YMCA | | `boundary.circle.lat` | 43.818156 | | `boundary.circle.lon` | -79.186484 | @@ -220,11 +207,10 @@ 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`. -> [/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 | | :--- | :--- | -| `api_key` | [get yours here](https://mapzen.com/developers) | | `text` | YMCA | | `focus.point.lat` | -33.856680 | | `focus.point.lon` | 151.215281 | @@ -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. -> [/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 | | :--- | :--- | -| `api_key` | [get yours here](https://mapzen.com/developers) | | `text` | YMCA | | `focus.point.lat` | -33.856680 | | `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. -> [/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 | | :--- | :--- | -| `api_key` | [get yours here](https://mapzen.com/developers) | | `text` | YMCA | | `focus.point.lat` | -33.856680 | | `focus.point.lon` | 151.215281 | @@ -319,34 +303,32 @@ The search examples so far have returned a mix of results from all the data sour 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 | | :--- | :--- | -| `api_key` | [get yours here](https://mapzen.com/developers) | | `text` | YMCA | | `sources` | oa | Because OpenAddresses is, as the name suggests, only address data, here's what you can expect to find: -* 0 Ymca, New Brunswick -* 0 Ymca Drive, Cary, NC -* 14843 Ymca Lane, Cormorant, MN -* 14660 Ymca Lane, Cormorant, MN -* 6221 Ymca Lane, Northampton County, VA -* 6223 Ymca Lane, Northampton County, VA -* 74 Ymca Road, Wairoa District, Hawke's Bay Region -* 108 Ymca Drive, Clinton, SC -* 101 Ymca Drive, Kannapolis, NC -* 31440 Ymca Road, Washington, OH +* 20 Ymca Drive, Niagara, ON, Canada +* 341 Ymca Rd, New Hope, AL, USA +* 318 Ymca Rd, New Hope, AL, USA +* 138 Ymca Rd, New Hope, AL, USA +* 304 Ymca Rd, New Hope, AL, USA +* 1919 Ymca Lane, Minnetonka, MN, USA +* 101 Ymca Dr, Kannapolis, NC, USA +* 2121 Ymca Camp Road, Stokes County, NC, USA +* 1110 Ymca Camp Road, Stokes County, NC, USA +* 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. -> [/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 | | :--- | :--- | -| `api_key` | [get yours here](https://mapzen.com/developers) | | `text` | YMCA | | `sources` | osm,gn | @@ -371,11 +353,10 @@ In Pelias, place types are referred to as `layers`, ranging from fine to coarse. |`country`|places that issue passports, nations, nation-states| |`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 | | :--- | :--- | -| `api_key` | [get yours here](https://mapzen.com/developers) | | `text` | YMCA | | `layers` | venue,address | @@ -383,7 +364,6 @@ In Pelias, place types are referred to as `layers`, ranging from fine to coarse. | Parameter | Type | Required | Default | Example | | --- | --- | --- | --- | --- | -| `api_key` | string | yes | none | [get yours here](https://mapzen.com/developers) | | `text` | string | yes | none | `Union Square` | | `focus.point.lat` | floating point number | no | none | `48.581755` | | `focus.point.lon` | floating point number | no | none | `7.745843` | From b69760fe7bed7a2f01b889f090efd933d57fa1cf Mon Sep 17 00:00:00 2001 From: Julian Simioni Date: Thu, 15 Mar 2018 16:59:10 -0400 Subject: [PATCH 07/12] Move index to README No more symlinks --- README.md | 21 ++++++++++++++++++++- index.md | 20 -------------------- 2 files changed, 20 insertions(+), 21 deletions(-) mode change 120000 => 100644 README.md delete mode 100644 index.md diff --git a/README.md b/README.md deleted file mode 120000 index dd0ea36..0000000 --- a/README.md +++ /dev/null @@ -1 +0,0 @@ -index.md \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..113b3c6 --- /dev/null +++ b/README.md @@ -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) diff --git a/index.md b/index.md deleted file mode 100644 index 113b3c6..0000000 --- a/index.md +++ /dev/null @@ -1,20 +0,0 @@ -# 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) From 2afebd3dd9e5f1b36ad9fa01e384948f6bbd86ae Mon Sep 17 00:00:00 2001 From: Julian Simioni Date: Thu, 15 Mar 2018 17:00:53 -0400 Subject: [PATCH 08/12] Fix spelunker URLs --- structured-geocoding.md | 40 ++++++++++++++++++++-------------------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/structured-geocoding.md b/structured-geocoding.md index dabc4e1..af3d637 100644 --- a/structured-geocoding.md +++ b/structured-geocoding.md @@ -52,7 +52,7 @@ _Examples_ ### 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_ @@ -62,7 +62,7 @@ _Examples_ ### 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://whosonfirst.mapzen.com/spelunker/id/857683023/descendants/?exclude=nullisland&placetype=borough). _Examples_ @@ -73,7 +73,7 @@ A structured geocoding request for `/v1/search/structured?locality=Manhattan® ### 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_ @@ -83,7 +83,7 @@ _Examples_ ### 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_ @@ -95,7 +95,7 @@ Counties are not as commonly used in geocoding as localities, but can be useful ### 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://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. _Examples_ @@ -103,28 +103,28 @@ _Examples_ * [Ontario](https://mapzen.com/search/explorer/?query=search/structured®ion=Ontario) * [Ardennes](https://mapzen.com/search/explorer/?query=search/structured®ion=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://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`. ### 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_ -* [90210](https://whosonfirst.mapzen.com/spelunker/id/554783991/) -* [CV23 9SL](https://whosonfirst.mapzen.com/spelunker/id/454261459/) -* [5439171](https://whosonfirst.mapzen.com/spelunker/id/538904173/) +* [90210](https://spelunker.whosonfirst.org/id/554783991/) +* [CV23 9SL](https://spelunker.whosonfirst.org/id/454261459/) +* [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. ### 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_ * [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) ## Who's On First layer mappings reference @@ -133,11 +133,11 @@ The [Who's on First](https://whosonfirst.mapzen.com/) gazetteer is one of the da | Structured geocoding parameter | Who's on First placetype | | -------------------- | ------------------------- | -| `neighbourhood` | [neighbourhood](https://whosonfirst.mapzen.com/spelunker/placetypes/neighbourhood/) | -| `borough` | [borough](https://whosonfirst.mapzen.com/spelunker/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) | -| `county` | [county](https://whosonfirst.mapzen.com/spelunker/placetypes/county/), [macrocounty](https://whosonfirst.mapzen.com/spelunker/placetypes/macrocounty/) | -| `region` | [region](https://whosonfirst.mapzen.com/spelunker/placetypes/region/), [macroregion](https://whosonfirst.mapzen.com/spelunker/placetypes/macroregion/) | -| `country` | [dependency](https://whosonfirst.mapzen.com/spelunker/placetypes/dependency/), [country](https://whosonfirst.mapzen.com/spelunker/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®ion=Pennsylvania`, then `Peach Bottom` in both the `locality` and `localadmin` layers are searched. +| `neighbourhood` | [neighbourhood](https://spelunker.whosonfirst.org/placetypes/neighbourhood/) | +| `borough` | [borough](https://spelunker.whosonfirst.org/placetypes/borough/) | +| `locality` | [locality](https://spelunker.whosonfirst.org/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) | +| `county` | [county](https://spelunker.whosonfirst.org/placetypes/county/), [macrocounty](https://whosonfirst.mapzen.com/spelunker/placetypes/macrocounty/) | +| `region` | [region](https://spelunker.whosonfirst.org/placetypes/region/), [macroregion](https://whosonfirst.mapzen.com/spelunker/placetypes/macroregion/) | +| `country` | [dependency](https://spelunker.whosonfirst.org/placetypes/dependency/), [country](https://whosonfirst.mapzen.com/spelunker/placetypes/country/) | + +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®ion=Pennsylvania`, then `Peach Bottom` in both the `locality` and `localadmin` layers are searched. From b4e45f007dffc5dc25fd5137da0ca0844e7253ad Mon Sep 17 00:00:00 2001 From: Julian Simioni Date: Thu, 15 Mar 2018 17:02:16 -0400 Subject: [PATCH 09/12] Minor formatting --- structured-geocoding.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/structured-geocoding.md b/structured-geocoding.md index af3d637..c9583f7 100644 --- a/structured-geocoding.md +++ b/structured-geocoding.md @@ -1,6 +1,6 @@ # 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. @@ -52,7 +52,7 @@ _Examples_ ### neighbourhood -[Neighbourhoods](https://spelunker.whosonfirst.org/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_ @@ -69,11 +69,11 @@ _Examples_ * [Manhattan](https://mapzen.com/search/explorer/?query=search/structured&borough=Manhattan&locality=New York) * [Iztapalapa](https://mapzen.com/search/explorer/?query=search/structured&borough=Iztapalapa&locality=Mexico City) -A structured geocoding request for `/v1/search/structured?locality=Manhattan®ion=NY`, returns boroughs along with localities. +A structured geocoding request for `/v1/search/structured?locality=Manhattan®ion=NY`, returns boroughs along with localities. ### locality -[Localities](https://spelunker.whosonfirst.org/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_ @@ -83,7 +83,7 @@ _Examples_ ### county -[Counties](https://spelunker.whosonfirst.org/placetypes/county/) are administrative divisions between localities and regions. +[Counties](https://spelunker.whosonfirst.org/placetypes/county/) are administrative divisions between localities and regions. _Examples_ @@ -91,11 +91,11 @@ _Examples_ * [Maui](https://mapzen.com/search/explorer/?query=search/structured&county=Maui®ion=HI) * [Alb-Donau-Kreis](https://mapzen.com/search/explorer/?query=search/structured&county=Alb-Donau-Kreis&country=DEU) in Germany -Counties are not as commonly used in geocoding as localities, but can be useful when attempting to disambiguate between localities. For instance, there are three cities named Red Lion in Pennsylvania but only one in each of three counties. Specifying a county disambiguates this list to a single result. +Counties are not as commonly used in geocoding as localities, but can be useful when attempting to disambiguate between localities. For instance, there are three cities named Red Lion in Pennsylvania but only one in each of three counties. Specifying a county disambiguates this list to a single result. ### region -[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://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://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. _Examples_ @@ -103,7 +103,7 @@ _Examples_ * [Ontario](https://mapzen.com/search/explorer/?query=search/structured®ion=Ontario) * [Ardennes](https://mapzen.com/search/explorer/?query=search/structured®ion=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://spelunker.whosonfirst.org/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://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`. ### postalcode @@ -119,7 +119,7 @@ Keep in mind that you can search for `postalcode` exclusively. So requests like ### country -[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. +[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_ From d11a5fea38b404298b055543f95573d12a88bb4f Mon Sep 17 00:00:00 2001 From: Julian Simioni Date: Thu, 15 Mar 2018 17:09:15 -0400 Subject: [PATCH 10/12] More spelunker URL fixes --- structured-geocoding.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/structured-geocoding.md b/structured-geocoding.md index c9583f7..a545417 100644 --- a/structured-geocoding.md +++ b/structured-geocoding.md @@ -62,7 +62,7 @@ _Examples_ ### 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://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_ @@ -95,7 +95,7 @@ Counties are not as commonly used in geocoding as localities, but can be useful ### region -[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://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_ @@ -103,7 +103,7 @@ _Examples_ * [Ontario](https://mapzen.com/search/explorer/?query=search/structured®ion=Ontario) * [Ardennes](https://mapzen.com/search/explorer/?query=search/structured®ion=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://spelunker.whosonfirst.org/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 @@ -129,15 +129,15 @@ _Examples_ ## 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.mapzen.com/placetypes/). | Structured geocoding parameter | Who's on First placetype | | -------------------- | ------------------------- | | `neighbourhood` | [neighbourhood](https://spelunker.whosonfirst.org/placetypes/neighbourhood/) | | `borough` | [borough](https://spelunker.whosonfirst.org/placetypes/borough/) | -| `locality` | [locality](https://spelunker.whosonfirst.org/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) | -| `county` | [county](https://spelunker.whosonfirst.org/placetypes/county/), [macrocounty](https://whosonfirst.mapzen.com/spelunker/placetypes/macrocounty/) | -| `region` | [region](https://spelunker.whosonfirst.org/placetypes/region/), [macroregion](https://whosonfirst.mapzen.com/spelunker/placetypes/macroregion/) | -| `country` | [dependency](https://spelunker.whosonfirst.org/placetypes/dependency/), [country](https://whosonfirst.mapzen.com/spelunker/placetypes/country/) | +| `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://spelunker.whosonfirst.org/placetypes/county/), [macrocounty](https://spelunker.whosonfirst.org/placetypes/macrocounty/) | +| `region` | [region](https://spelunker.whosonfirst.org/placetypes/region/), [macroregion](https://spelunker.whosonfirst.org/placetypes/macroregion/) | +| `country` | [dependency](https://spelunker.whosonfirst.org/placetypes/dependency/), [country](https://spelunker.whosonfirst.org/placetypes/country/) | 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®ion=Pennsylvania`, then `Peach Bottom` in both the `locality` and `localadmin` layers are searched. From 8f3c09f9aeb4d3752b3b13e666c0a09a69e0d425 Mon Sep 17 00:00:00 2001 From: Julian Simioni Date: Thu, 15 Mar 2018 17:11:33 -0400 Subject: [PATCH 11/12] s/whosonfirst.mapzen.com/whosonfirst.org/ --- search.md | 2 +- structured-geocoding.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/search.md b/search.md index eb3c534..5e9da5e 100644 --- a/search.md +++ b/search.md @@ -298,7 +298,7 @@ The search examples so far have returned a mix of results from all the data sour |---|---|---| | [OpenStreetMap](http://www.openstreetmap.org/) | `openstreetmap` | `osm` | | [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` | 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. diff --git a/structured-geocoding.md b/structured-geocoding.md index a545417..6376480 100644 --- a/structured-geocoding.md +++ b/structured-geocoding.md @@ -129,7 +129,7 @@ _Examples_ ## Who's On First layer mappings reference -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.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 | | -------------------- | ------------------------- | From 0a203f3a0bc3886da240f552cf56b3649ec281d4 Mon Sep 17 00:00:00 2001 From: Julian Simioni Date: Thu, 15 Mar 2018 17:21:09 -0400 Subject: [PATCH 12/12] Whitespace --- release-notes.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/release-notes.md b/release-notes.md index d963672..5dcd1cb 100644 --- a/release-notes.md +++ b/release-notes.md @@ -23,11 +23,11 @@ Over the last few days we have fixed [several](https://github.com/pelias/api/pul ## 14 September 2017 ### New features -* We've beefed up downloaders for OpenAddresses, OpenStreetMap, and Who's On First to download subsets of data. +* We've beefed up downloaders for OpenAddresses, OpenStreetMap, and Who's On First to download subsets of data. * The alpha3 flag for country codes have been obsolete for quite some time now but we've [removed all vestiges of it](https://github.com/pelias/model/pull/71). ### Bug fixes -* Some OpenAddresses records have lon/lat at 0/0 meaning that, unless you have a ocean-going yacht and pretty sturdy jet ski, you can't get to addresses there (note to self: start "Pelias for Yachts"). We've now [excluded those](https://github.com/pelias/openaddresses/pull/277) from the build. +* Some OpenAddresses records have lon/lat at 0/0 meaning that, unless you have a ocean-going yacht and pretty sturdy jet ski, you can't get to addresses there (note to self: start "Pelias for Yachts"). We've now [excluded those](https://github.com/pelias/openaddresses/pull/277) from the build. ## 22 August 2017 ### New features @@ -37,7 +37,7 @@ Over the last few days we have fixed [several](https://github.com/pelias/api/pul * We've added a warning when unexpected query parameters are encountered! This is a big deal because it helps catch misspellings of query parameter names, such as `layer` vs `layers`... we've all been there at least once. ### Bug fixes -* We found an invalid warning when falling back to a coarse-reverse geocoding strategy about `boundary.circle.radius` not being supported, even though the query didn't specify a value for that parameter. We removed the unwanted warning. If you see that warning going forward, consider it valid and revise your query. +* We found an invalid warning when falling back to a coarse-reverse geocoding strategy about `boundary.circle.radius` not being supported, even though the query didn't specify a value for that parameter. We removed the unwanted warning. If you see that warning going forward, consider it valid and revise your query. * We fixed our production configuration to fully enable language headers (they were only partially available previously). Ooops! ## 6 July 2017 @@ -90,7 +90,7 @@ We bring you another data update this week, but don't worry, we're busy working ## 1 February 2017 -This release is just a data refresh since it's hard to keep up with the leaps and bounds that [openaddresses](http://openaddresses.io) is growing by! +This release is just a data refresh since it's hard to keep up with the leaps and bounds that [openaddresses](http://openaddresses.io) is growing by! ## 27 January 2017 @@ -135,8 +135,8 @@ This week includes only code changes, no data updates. Our production build fail ## 18 November 2016 -* We've just released beta support for component geocoding so instead of passing in a single input to the `/v1/search` endpoint, the parts of an address can be sent to `/v1/beta/component`! An example of this is `address=201+Spear+St&locality=San+Francisco®ion=CA`. We haven't officially named this geocoding type yet, so if you have a naming suggestion, please weigh in [here](https://github.com/pelias/pelias/issues/455)! Our basic design doc for using this new beta feature is [here](https://github.com/pelias/pelias/tree/master/milestones/component_geocoding), please check it out. We're still working out the final implementation (why it's currently deployed to our `/v1/beta` test bed) so check it out and don't hesitate to [raise any issues](https://github.com/pelias/pelias/issues) you might encounter. Check out the [acceptance tests](https://github.com/pelias/acceptance-tests/blob/master/test_cases/component_geocoding.json) for some more examples. -* We're enabling support for more response scenarios from [libpostal](https://github.com/openvenues/libpostal)! This release we're adding support for city+country, so requests for Paris, France and Reykjavík, Iceland are a lot cleaner. +* We've just released beta support for component geocoding so instead of passing in a single input to the `/v1/search` endpoint, the parts of an address can be sent to `/v1/beta/component`! An example of this is `address=201+Spear+St&locality=San+Francisco®ion=CA`. We haven't officially named this geocoding type yet, so if you have a naming suggestion, please weigh in [here](https://github.com/pelias/pelias/issues/455)! Our basic design doc for using this new beta feature is [here](https://github.com/pelias/pelias/tree/master/milestones/component_geocoding), please check it out. We're still working out the final implementation (why it's currently deployed to our `/v1/beta` test bed) so check it out and don't hesitate to [raise any issues](https://github.com/pelias/pelias/issues) you might encounter. Check out the [acceptance tests](https://github.com/pelias/acceptance-tests/blob/master/test_cases/component_geocoding.json) for some more examples. +* We're enabling support for more response scenarios from [libpostal](https://github.com/openvenues/libpostal)! This release we're adding support for city+country, so requests for Paris, France and Reykjavík, Iceland are a lot cleaner. * Speaking of Reykjavík, Iceland, support for inputs containing diacritics has improved. Now whether the input is Reykjavík, Iceland or Reykjavik, Iceland, results should be the same. * Whether your input contains a 2- or 3-character ISO country code (`FRA` vs `FR`), we'll find it!