├── .gitignore ├── images ├── world_all.png ├── world_rect.png ├── basic-webmap.png ├── focus_point.png ├── world_circle.png ├── boundary_london.png ├── world_country.png ├── developer-console.png ├── geocoder-blank-tab.png ├── geocoder-search-icon.png ├── overlapping_boundaries.gif └── geocoder-address-search.png ├── installing.md ├── http-status-codes.md ├── development ├── repository_list.md └── roadmap.md ├── getting_started_install.md ├── requirements.md ├── language-codes.md ├── glossary.md ├── services.md ├── place.md ├── use-cors.md ├── README.md ├── result_quality.md ├── data-sources.md ├── search-workflows.md ├── addresses.md ├── response.md ├── full_planet_considerations.md ├── reverse.md ├── structured-geocoding.md ├── autocomplete.md ├── pelias_from_scratch.md ├── LICENSE.md ├── add-search-to-a-map.md ├── search.md └── release-notes.md /.gitignore: -------------------------------------------------------------------------------- 1 | node_modules 2 | npm-debug.log 3 | .DS_Store 4 | -------------------------------------------------------------------------------- /images/world_all.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/pelias/documentation/HEAD/images/world_all.png -------------------------------------------------------------------------------- /images/world_rect.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/pelias/documentation/HEAD/images/world_rect.png -------------------------------------------------------------------------------- /images/basic-webmap.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/pelias/documentation/HEAD/images/basic-webmap.png -------------------------------------------------------------------------------- /images/focus_point.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/pelias/documentation/HEAD/images/focus_point.png -------------------------------------------------------------------------------- /images/world_circle.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/pelias/documentation/HEAD/images/world_circle.png -------------------------------------------------------------------------------- /images/boundary_london.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/pelias/documentation/HEAD/images/boundary_london.png -------------------------------------------------------------------------------- /images/world_country.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/pelias/documentation/HEAD/images/world_country.png -------------------------------------------------------------------------------- /images/developer-console.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/pelias/documentation/HEAD/images/developer-console.png -------------------------------------------------------------------------------- /images/geocoder-blank-tab.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/pelias/documentation/HEAD/images/geocoder-blank-tab.png -------------------------------------------------------------------------------- /images/geocoder-search-icon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/pelias/documentation/HEAD/images/geocoder-search-icon.png -------------------------------------------------------------------------------- /images/overlapping_boundaries.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/pelias/documentation/HEAD/images/overlapping_boundaries.gif -------------------------------------------------------------------------------- /images/geocoder-address-search.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/pelias/documentation/HEAD/images/geocoder-address-search.png -------------------------------------------------------------------------------- /installing.md: -------------------------------------------------------------------------------- 1 | See our installation guides list at [https://github.com/pelias/documentation/blob/master/getting_started_install.md](https://github.com/pelias/documentation/blob/master/getting_started_install.md) 2 | -------------------------------------------------------------------------------- /http-status-codes.md: -------------------------------------------------------------------------------- 1 | # HTTP status codes 2 | 3 | ## Geocoding 4 | 5 | The following status codes are returned from the geocoding service: 6 | 7 | - `200 OK`: The request has succeeded. 8 | - `400 Bad Request`: An input parameter was invalid. An error message is included in the response body with more details. 9 | - `404 Not Found`: The URL is invalid or the path is no longer valid. 10 | - `408 Request Timeout`: The Elasticsearch cluster took too long to respond. 11 | - `500 Internal Server Error`: Generic fatal error. 12 | - `502 Bad Gateway`: Connection was lost to the Elasticsearch cluster. 13 | 14 | In all cases above, the response body will be valid GeoJSON. 15 | -------------------------------------------------------------------------------- /development/repository_list.md: -------------------------------------------------------------------------------- 1 | # Pelias repository list 2 | 3 | This is a list of all active Pelias repositories. It can be useful for tracking changes we have to make across all our repositories 4 | 5 | ## services 6 | - [ ] api 7 | - [ ] pip-service 8 | - [ ] placeholder 9 | - [ ] interpolation 10 | - [ ] libpostal-service 11 | - [ ] spatial 12 | 13 | ## importers 14 | - [ ] whosonfirst 15 | - [ ] openaddresses 16 | - [ ] geonames 17 | - [ ] polylines 18 | - [ ] openstreetmap 19 | - [ ] transit 20 | - [ ] csv-importer 21 | 22 | ## support modules 23 | - [ ] query 24 | - [ ] pbf2json 25 | - [ ] parser 26 | - [ ] blacklist-stream 27 | - [ ] logger 28 | - [ ] dbclient 29 | - [ ] config 30 | - [ ] schema 31 | - [ ] sorting 32 | - [ ] microservice-wrapper 33 | - [ ] mock-logger 34 | - [ ] labels 35 | - [ ] wof-admin-lookup 36 | - [ ] fuzzy-tester 37 | - [ ] model 38 | - [ ] polygon-lookup 39 | - [ ] analysis 40 | - [ ] postal-cities 41 | 42 | ## testing 43 | - [ ] acceptance-tests 44 | - [ ] loadtest 45 | - [ ] fuzzy-tests 46 | 47 | ## meta 48 | - [ ] dashboard 49 | - [ ] compare 50 | - [ ] pelias 51 | - [ ] documentation 52 | - [ ] ci-tools 53 | 54 | # docker 55 | - [ ] docker 56 | - [ ] docker-baseimage 57 | - [ ] docker-libpostal_baseimage 58 | 59 | # web modules 60 | - [ ] leaflet-plugin 61 | 62 | ## deployment 63 | - [ ] kubernetes 64 | - [ ] packer-elasticsearch 65 | - [ ] terraform-elasticsearch 66 | - [ ] elasticsearch-health-logger 67 | 68 | ## misc 69 | - [ ] mars-importer 70 | - [ ] slack-search-app 71 | - [ ] ownership 72 | - [ ] scripts-geocoding-coverage 73 | - [ ] geocoder-test-suite 74 | - [ ] pelias-android-sdk 75 | - [ ] presentation 76 | - [ ] scripts-batch-search 77 | - [ ] pelias-ios-sdk 78 | - [ ] batch-search-app 79 | -------------------------------------------------------------------------------- /getting_started_install.md: -------------------------------------------------------------------------------- 1 | ## Getting started with Pelias 2 | 3 | Looking to install and set up Pelias? You've come to the right place. We have several different 4 | tools and pieces of documentation to help you. 5 | 6 | ### Installing for the first time? 7 | 8 | We _strongly_ recommend using our [Docker](http://github.com/pelias/docker/) based installation for 9 | your first install. It removes the need to deal with most of the complexity and dependencies of 10 | Pelias. On a fast internet connection you should be able to get a small city like Portland, Oregon 11 | installed in under 30 minutes. 12 | 13 | ### Want to go more in depth? 14 | 15 | The Pelias docker installation should work great for any small area, and is great for managing the 16 | different Pelias services during development. However, we understand not everyone can or wants to 17 | use Docker, and that people want more details on how things work. 18 | 19 | For this, we have our [from scratch installation guide](pelias_from_scratch.md) 20 | 21 | ### Installing in production? 22 | 23 | By far the most well tested way to install Pelias is to use [Kubernetes](https://github.com/pelias/kubernetes). 24 | Kubernetes is perfect for managing systems that have many different components, like Pelias. 25 | 26 | We would love to add additional, well tested ways to install Pelias in production. Reach out to us 27 | if you have something to share or want to get started. 28 | 29 | ### Doing a full planet build? 30 | 31 | Running Pelias for a city or small country is pretty easy. However, due to the amount of data 32 | involved, a full planet build is harder to pull off. 33 | 34 | See our [full planet build guide](full_planet_considerations.md) for some recommendations on how to 35 | make it easier and more performant. 36 | -------------------------------------------------------------------------------- /requirements.md: -------------------------------------------------------------------------------- 1 | # Pelias Software requirements 2 | 3 | This is the list of all software requirements for Pelias. We highly recommend using our 4 | [Docker images](https://hub.docker.com/r/pelias/) to avoid having to even attempt to correctly 5 | install all our dependencies yourself. 6 | 7 | ## Node.js 8 | 9 | Version 20 or newer 10 | 11 | Most Pelias code is written in Node.js, so this is one of the most core dependencies of the project. 12 | 13 | Pelias generally only adds support for even numbered [LTS](https://github.com/nodejs/Release#release-schedule) Node.js versions. 14 | However we gladly accept patches and bug reports regarding issues with any Node.js version that has not reached end-of-life. 15 | 16 | We recommend you always use the _latest_ minor and patch release of whichever major release line you 17 | choose. 18 | 19 | We strive to support any minor or patch version of our supported major release lines of Node.js, but on occasion this may not be possible and we'll offer additional guidance. 20 | 21 | ## Elasticsearch 22 | 23 | Version 7.5+ 24 | 25 | We recommend the latest in the Elasticsearch 7 release line. Elasticsearch 8 is also supported. 26 | 27 | The core data storage for Pelias is Elasticsearch, and Elasticsearch makes major breaking changes 28 | from release to release, so it's important to track these versions carefully. 29 | 30 | We generally strive to support the newest and second newest version of Elasticsearch. Due to the way Elasticsearch manages breaking changes, it's usually only possible to fully support two Elasticsearch versions at a time. 31 | 32 | ## SQLite 33 | 34 | Version 3.11 or newer 35 | 36 | Some components of Pelias need a relational database, and Elasticsearch does not provide good 37 | relational support. We use SQLite in these cases since it's simple to manage and quite performant. 38 | 39 | ## Libpostal 40 | 41 | Pelias relies heavily on the [Libpostal](https://github.com/openvenues/libpostal#installation) 42 | address parser. Libpostal requires about 4GB of disk space to download all the required data. 43 | 44 | ## Windows Support 45 | 46 | Pelias is not well tested on Windows, but we do wish to support it, and will accept patches to fix 47 | any issues with Windows support. 48 | -------------------------------------------------------------------------------- /language-codes.md: -------------------------------------------------------------------------------- 1 | # Get search results in a particular language 2 | 3 | You can get search results in another language, if available, by specifying a target language code with your request. 4 | 5 | By default, search responses are in the default locale of the dataset. However, if you include a language code, the search attempts to return place names in the language you specified. 6 | 7 | If the language you requested is unavailable, then the default language is returned. In some cases, this is the local dialect, or it may be English for other datasets. 8 | 9 | ## Request a specific language 10 | 11 | You can specify the target language code in the [BCP47 standard](http://www.rfc-editor.org/rfc/bcp/bcp47.txt) as either a query string URL parameter or an HTTP header. 12 | 13 | Note that a language code in the query string takes precedence over a code in the header. If you include an invalid language code, then you see a warning message and the search attempts to find a valid code, if one is available. Otherwise, the results fall back to default behavior. 14 | 15 | BCP47 language tags can contain three parts: 16 | 17 | 1. A language subtag (en, zh). 18 | 2. A script subtag (Hant, Latn). 19 | 3. A region subtag (US, CN). 20 | 21 | At this time, only the `language subtag` information is used to set the target language. The other options may be enabled in the future when additional data can be imported with text containing `script subtag` and `region subtag` variants. 22 | 23 | ### Set language as a query string in the URL 24 | 25 | You can specify the language code using a URL parameter named `lang`: `/v1/search?lang=de-ch`. 26 | 27 | ### Set language in the HTTP header 28 | 29 | You can include the language code in the HTTP request header with the `Accept-Language` parameter: `Accept-Language: de-ch`. 30 | 31 | ## Language properties in the response 32 | 33 | The response contains information about the language being returned, which can be helpful for debugging. 34 | 35 | ``` 36 | { 37 | "geocoding": { 38 | [...] 39 | "lang": { 40 | "name": "German", 41 | "iso6391": "de", 42 | "iso6393": "deu", 43 | "defaulted": false 44 | }, 45 | [...] 46 | }, 47 | [...] 48 | ``` 49 | 50 | The language items include: 51 | 52 | - `name`: a human-readable name for the language, in English 53 | - `iso6391` and `iso6393`: the language code as defined in the two most common standards 54 | - `defaulted`: a value of `true` or `false` to indicate if there was a fall-back to a default language property 55 | -------------------------------------------------------------------------------- /development/roadmap.md: -------------------------------------------------------------------------------- 1 | # Development Roadmap 2 | 3 | Pelias has a long list of features and improvements we wish to make. While we 4 | track most of them in [GitHub issues](https://github.com/pelias/pelias/issues), 5 | this document records high level priorities for the development of the project 6 | as a whole. 7 | 8 | As an open-source project, we don't usually have a timeline or estimate for 9 | when items on our roadmap will be completed, but this document does serve as a 10 | roughly priority order of major changes we hope to make. 11 | 12 | ## Fuzzy matching/typo correction for autocomplete 13 | 14 | The Pelias autocomplete endpoint currently supports extremely limited typo 15 | correction. However, this support is really a result of implementation details, 16 | and not a result of a concerted effort. 17 | 18 | By adding such a feature in a deliberate way we can greatly increase the 19 | usability of the autocomplete endpoint. 20 | 21 | ## Integrate the new Spatial service for improved geospatial capabilities 22 | 23 | Pelias currently has a component called the [PIP 24 | service](https://github.com/pelias/pip-service) for performing point in polygon 25 | calculations, but it's architecture and capabilities have become a huge 26 | limiting factor for Pelias. 27 | 28 | Over the past year, we have been working on a more powerful and efficient 29 | replacement, the [Spatial service](https://github.com/pelias/spatial). 30 | 31 | The spatial service will allow advanced functionality such as custom 32 | administrative areas, using administrative data from OpenStreetMap, [returning 33 | polygon data in Pelias responses](https://github.com/pelias/whosonfirst/issues/19), 34 | or [adding postalcodes to more records based on a geometry](https://github.com/pelias/pelias/issues/111). 35 | 36 | ## Expanded input language support 37 | 38 | Overall, Pelias has a solid foundation of language and internationalization 39 | support. The Pelias data schema allows for records to have multiple name 40 | values. These might include names in different languages, alternate names, 41 | colloquial names, or common abbreviations (for example airport codes). 42 | 43 | However, not all data importers currently add multiple names, even when they 44 | are available in the source data. Furthermore, not all our queries use these 45 | alternate names effectively. 46 | 47 | Pelias currently supports querying for administrative areas in many languages on 48 | the `/v1/search` endpoint. 49 | 50 | For autocomplete, the queries are not currently able to utilize multiple 51 | administrative area names. 52 | 53 | Additionally, due to limitations in the polylines data format, no streets 54 | imported from OSM include alternate names, even if they are available in OSM. 55 | -------------------------------------------------------------------------------- /glossary.md: -------------------------------------------------------------------------------- 1 | # Pelias glossary 2 | 3 | ## Common search and geocoding terms 4 | 5 | - **geocoding** - the process of converting an address or the name of a landmark or business into a latitude, longitude pair. Sometimes referred to as forward geocoding. Use the `search` endpoint to do this. 6 | - **reverse geocoding** - the process of converting a latitude, longitude pair into the name and address of the nearest place. Use the `reverse` endpoint to do this. 7 | - **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. 8 | - **administrative area** - a catch-all term for any area that might sub-divide the world, such as a city, neighbourhood, country, continent, etc. Usually, but not always, these correspond to various government administrations, hence administrative area. 9 | - **gazetteer** - a directory of geographical places, with a stable identifier and some number of descriptive properties about that location. 10 | 11 | ## Pelias API and developer terms 12 | 13 | - **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. 14 | - **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. 15 | - **data source** - the datasets available to Pelias. Only data sources that have open-source licenses are used. 16 | - **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. 17 | - **layer** - types of places available to Pelias and arranged in a hierarchy, such as an address, a venue, a neighbourhood, or a country. 18 | - **`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. 19 | - **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. 20 | 21 | ## Other mapping terms 22 | 23 | - **bounding box** - a rectangular area defined by two longitudes and two latitudes (the minimum and the maximum latitude, longitude). 24 | - **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. 25 | - **latitude** - the distance of a point north or south of the equator. In Pelias, latitudes are expressed in decimal degrees. 26 | - **longitude** - the distance of a point east or west. In Pelias, longitudes are in relation to the Prime Meridian and expressed in decimal degrees. 27 | -------------------------------------------------------------------------------- /services.md: -------------------------------------------------------------------------------- 1 | # Pelias services 2 | 3 | A running Pelias installation is composed of several different services. Each service is well suited 4 | to a particular task. 5 | 6 | ## Service Use Cases 7 | 8 | Here's a list of which services provide which features in Pelias. If you don't need everything Pelias 9 | does, you may be able to get by without installing and running all the Pelias services 10 | 11 | | Service | /v1/search | /v1/autocomplete | /v1/reverse | /v1/reverse (coarse) | Changing the display language of results (any endpoint) | 12 | | ------ | ----- | ----- | --------- | ------- | ----- | 13 | | API | **required** | **required** | **required** | **required** | **required** | 14 | | Placeholder | **required** | | | | **required** | 15 | | Libpostal | **required** | | | | | 16 | | PIP | | | recommended | **required** | | 17 | | Interpolation | optional | | | | | 18 | 19 | ## Descriptions 20 | 21 | ### [API](https://github.com/pelias/api) 22 | 23 | This is the core of Pelias. It talks to all other services (if available), Elasticsearch, and 24 | provides the interface for all queries to Pelias. 25 | 26 | ### [Placeholder](https://github.com/pelias/placeholder) 27 | 28 | Placeholder is used specifically to handle the relational component of geocoding. Placeholder 29 | understands, for example, that Paris is a city in a country called France, but that there is another 30 | city called Paris in the state of Texas, USA. 31 | 32 | Placeholder is a key component for forward geocoding on the `/v1/search` and `/v1/search/structured` endpoints. 33 | 34 | Placeholder also stores the translations of administrative areas in multiple languages. Therefore it 35 | is required if any support for multiple languages is desired. 36 | 37 | ### [Libpostal](https://github.com/pelias/libpostal-service) 38 | 39 | Libpostal is a library that provides an address parser using a statistical natural language processing 40 | model trained on OpenStreetMap, OpenAddresses, and other open data. It is quite good at parsing 41 | fully specified input, but cannot handle autocomplete very well. 42 | 43 | The data required for Libpostal to run is around 3GB, and has to be loaded into memory, so this 44 | service is fairly expensive to run, even for small installations. 45 | 46 | Unlike the other Pelias services, we didn't actually write a Pelias Libpostal service. We recommend 47 | using the [go-whosonfirst-libpostal](https://github.com/whosonfirst/go-whosonfirst-libpostal) 48 | service created by the [Who's on First](https://whosonfirst.org) team. 49 | 50 | For convenience, we've packaged the go-whosonfirst-libpostal service [using Docker](https://github.com/pelias/libpostal-service) 51 | in a way that fits in well with the rest of the Pelias Docker packages. 52 | 53 | ## [Point-in-Polygon (PIP)](https://github.com/pelias/pip-service) 54 | 55 | The PIP service loads polygon data representing the boundaries of cities, states, regions, countries 56 | etc into memory, and can perform calculations on that geometric data. Its used to determine if a 57 | given point lies in a particular polygon. Thus, it's highly recommended for reverse geocoding. 58 | 59 | ## [Interpolation](https://github.com/pelias/interpolation) 60 | 61 | The interpolation service combines street geometries with known addresses and address ranges, to 62 | allow estimating the position of addresses that might exist, but aren't in existing open 63 | data sources. It is only used by the `/v1/search` and `/v1/search/structured` endpoints. 64 | -------------------------------------------------------------------------------- /place.md: -------------------------------------------------------------------------------- 1 | # `/v1/place` endpoint for details 2 | 3 | When you know an identification number and the source it came from, you can use Pelias to get details on the location. 4 | 5 | For now, the `/place` endpoint returns exactly the same data that any other would. However, in the future, we plan to allow more information, perhaps [geometries](https://github.com/pelias/whosonfirst/issues/19#issuecomment-370545690) to be returned here. 6 | 7 | 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. 8 | 9 | For example, this `/place` query looks up the Eiffel Tower in OpenStreetMap (OSM): 10 | 11 | > [/v1/place?__ids=openstreetmap:venue:way/5013364__](https://pelias.github.io/compare/#/v1/place%3Fids=openstreetmap:venue:way/5013364) 12 | 13 | Note that you need an actual `gid` value to make a `/place` search. For example, if you search for an address and the result is [interpolated](addresses.md#address-interpolation), then there is no discrete `gid` to use for a `/place` search because interpolated results may be from multiple data sources. 14 | 15 | ## Search for multiple places in a query 16 | 17 | To search for more than one `/place` in a request, join multiple values together and separate them with a comma. For example, this `/place` query looks up the Eiffel Tower in OpenStreetMap and the borough of Manhattan in Who's on First: 18 | 19 | > [/v1/place?__ids=openstreetmap:venue:way/5013364,whosonfirst:borough:421205771__](https://pelias.github.io/compare/#/v1/place%3Fids=openstreetmap:venue:way/5013364,whosonfirst:borough:421205771) 20 | 21 | The results are returned in the order requested. 22 | 23 | ## Return categories in responses 24 | 25 | You can get some metadata from places such as categories. Categories let you know how to classify an element. For example the `Château de Versailles` (`Palace of Versailles`) in OpenStreetMap is classified as `entertainment`. 26 | 27 | > [/v1/place?__categories&ids=openstreetmap:venue:relation/1149002__](https://pelias.github.io/compare/#/v1/place%3Fcategories&ids=openstreetmap:venue:relation/1149002) 28 | 29 | ## Error handling 30 | 31 | If you enter a valid `gid` that cannot be found or has "expired" due to a newer build, you may get empty results. The request will NOT return an error. 32 | 33 | If the structure of your `gid` is invalid, an error will be returned as part of the GeoJSON structure. 34 | 35 | Keep in mind that if you enter a `gid` that cannot be found in a list of multiple IDs, then the `features` array in the response contains a different number of elements than the number of requests. For example, your request may have three IDs requested but only two results returned. The reason for this is that the `features` section of the response is GeoJSON-compliant, and JSON does not allow a way to convey an exception condition (not even an empty JSON element, `{}`). For this reason, if your application is dependent upon the results mapping directly to the individual input requests in order, then you'll have to do your own bookkeeping to handle exception conditions. 36 | 37 | ## :warning: Datasets without stable IDs 38 | 39 | Due to the ever-changing nature of most open-datasets used by Pelias, some `gids` can change merely by importing newer data. 40 | 41 | Both Geonames and Who's on First have excellent, stable IDs and should not cause trouble. However, OpenAddresses and OpenStreetMap do _not_ have stable IDs. Be careful. 42 | 43 | ## Available places parameters 44 | 45 | | Parameter | Type | Required | Default | Example | 46 | | --- | --- | --- | --- | --- | 47 | | `gid` | string | yes | none | `whosonfirst:borough:421205771` | 48 | | `categories` | none | no | none | Check only if the query parameter is present | 49 | -------------------------------------------------------------------------------- /use-cors.md: -------------------------------------------------------------------------------- 1 | # Load data from the browser 2 | 3 | For security reasons, web browsers prevent what are called cross-origin or cross-site requests from one domain to another. JavaScript `XMLHTTPRequests` (commonly called “AJAX” requests) inherit all the authentication context of the logged in user, so a malicious web page could try to make malicious requests that cross domain contexts and cause trouble. Historically, that has made it difficult for web developers to build web applications making use of third-party APIs. 4 | 5 | Fortunately, techniques have since been developed that allow developers to securely access APIs cross-domain. 6 | 7 | ## Cross-Origin Resource Sharing (CORS) 8 | 9 | `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. 10 | 11 | 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. 12 | 13 | For a full list of supported browsers see: http://caniuse.com/#feat=cors 14 | 15 | ### Add a search box to a Leaflet map 16 | 17 | You can add a Pelias box to any [Leaflet](http://leafletjs.com/) map. 18 | 19 | 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. 20 | 21 | ### Loading data with jQuery 22 | 23 | ```javascript 24 | $.ajax({ 25 | url: "https://search.mapzen.com/v1/search", 26 | method: "GET", 27 | dataType: "json", 28 | data: { 29 | "text": "London, UK", 30 | "api_key": "your-mapzen-api-key" 31 | }, 32 | success: function( data, status, jqxhr ){ 33 | console.log( "Request received:", data ); 34 | }, 35 | error: function( jqxhr, status, error ){ 36 | console.log( "Something went wrong!" ); 37 | } 38 | }); 39 | ``` 40 | 41 | interactive demo: http://jsfiddle.net/missinglink/fb6p0par/ 42 | 43 | ### Loading data with Angular 44 | 45 | ```javascript 46 | $http({ 47 | url: "https://search.mapzen.com/v1/search", 48 | method: "GET", 49 | headers: { "Accept": "application/json" }, 50 | params: { 51 | "text": "London, UK", 52 | "api_key": "your-mapzen-api-key" 53 | }, 54 | }) 55 | .success(function( data, status ) { 56 | console.log( "Request received:", data ); 57 | }) 58 | .error(function( data, status ) { 59 | console.log( "Something went wrong!" ); 60 | }); 61 | ``` 62 | 63 | interactive demo: http://jsfiddle.net/missinglink/nchh8a9j/ 64 | 65 | ## Why not JSONP? 66 | 67 | Also called “JSON with Padding”, `JSONP` is a technique for fooling a web browser into performing cross-origin requests using a special ` 74 | ``` 75 | 76 | 2. Save your edits and refresh the browser. The webpage should still appear empty because you have not added any code to interact with these references. 77 | 78 | After adding these, your index.html file should look something like this. 79 | 80 | ```html 81 | 82 | 83 | 84 | My Geocoding Map 85 | 86 | 87 | 88 | 89 | 90 | 91 | 92 | ``` 93 | 94 | Note that you are linking to a website that is serving the Mapzen.js CSS and JavaScript, but you can also [view, download, and contribute to the source code](https://github.com/mapzen/mapzen.js) if you want to access the contents of the library. 95 | 96 | ## Add a map to the page 97 | 98 | To display a Leaflet map on a page, you need a `
` element, which is a container on the page that groups elements, with an ID value. If you want to know more about initializing a Leaflet map, see the [Leaflet getting started documentation](http://leafletjs.com/examples/quick-start.html). 99 | 100 | 1. At the bottom of the `` section, after the references you added in the earlier steps, add a ` 111 | ``` 112 | 113 | 2. At the top of the `` section, add the `
`. 114 | 115 | ```html 116 |
117 | ``` 118 | 119 | 3. Directly after the `
`, add this JavaScript code within a ` 125 | ``` 126 | 127 | 4. Inside the same ` 138 | ``` 139 | 140 | `L.xxxxx` is a convention used with the Leaflet API. The `center: [47.61033,-122.31801]` parameter sets the center point of the map, in decimal degrees, at the location of a building at Seattle University. 141 | 142 | The next line sets the `zoom` level, which is like a map scale or resolution, where a smaller value shows a larger area in less detail, and a larger zoom level value depicts smaller area in great detail. 143 | 144 | 4. Save your edits and refresh the browser. 145 | 146 | Your index.html should look something like this: 147 | 148 | ```html 149 | 150 | 151 | 152 | 153 | 154 | 155 | 156 | 157 | 165 | 166 | 167 | 168 |
169 | 177 | 178 | 179 | ``` 180 | 181 | At this point, you have a map! You should see a map, zoom controls, and attribution in the bottom corner. 182 | 183 | To recap how you created this, you added references to the Mapzen JS and CSS files, a map `
` with a declared width, and assigned the `map` value to `L.Mapzen.map`. 184 | 185 | ![Leaflet canvas map with controls and attribution](images/basic-webmap.png) 186 | 187 | ## Add the Search box 188 | 189 | So far, you have referenced the necessary files, initialized Leaflet with a map container on the page, and added data to the map. Now, you are ready to add the Search box. 190 | 191 | 1. Inside the same ` 217 | [...] 218 | ``` 219 | 220 | ## Search for places on the map 221 | 222 | Now, you will test your search box by finding a few locations. As you type, the text automatically completes to suggest matching results. 223 | 224 | 1. On the map, type `Seattle University` in the Search box. 225 | 2. In the results list, find the entry for `Seattle University` and click it to zoom and add a point to the map at that location. (The point is only on your map, and does not update OpenStreetMap.) 226 | 227 | ![Entering an address to find on the map](images/geocoder-address-search.png) 228 | 229 | 3. Search for other addresses or places to experiment with the search function and get an idea of the results it returns. For example, you might try looking for a point of interest in Seattle, your work address, or a city outside the United States. 230 | 231 | ## Customize the geocoder 232 | 233 | 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. 234 | 235 | 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. 236 | 237 | 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. 238 | 239 | 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. 240 | 241 | 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/). 242 | 243 | 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. 244 | 245 | ```js 246 | var geocoderOptions = { 247 | autocomplete: false 248 | }; 249 | ``` 250 | 251 | You are setting `autocomplete: false` to specify that the Search box should not suggest potential text matches as you type. Autocomplete is enabled by default, so adding this means that you will turn it off. 252 | 253 | 2. Modify the existing geocoder code to pass in the `geocoderOptions` you set. 254 | 255 | ```js 256 | var geocoder = L.Mapzen.geocoder(geocoderOptions); 257 | ``` 258 | 259 | 3. Save your edits and refresh the browser. 260 | 4. Type `901 12th Avenue` in the Search box and press Enter. Notice now that the matching search results are not listed until you press the Enter key. 261 | 262 | The code from this section should look something like this. 263 | 264 | ```js 265 | var geocoderOptions = { 266 | autocomplete: false 267 | }; 268 | 269 | var geocoder = L.Mapzen.geocoder(geocoderOptions); 270 | geocoder.addTo(map); 271 | ``` 272 | 273 | ### Extra credit: View the JSON response 274 | 275 | 1. Open your browser's developer tools console. In Chrome, you can do this by clicking the menu in the corner, pointing to More Tools, and clicking Developer Tools. 276 | 2. Click the Network tab to see the Internet traffic, including the queries to the Mapzen servers. 277 | 3. Click the Headers tab for more information about the request, including the full URL. For example, the URL might look something like `https://search.mapzen.com/v1/search?text=901%2012th%20avenue&focus.point.lat=47.61032944737081&focus.point.lon=-122.31800079345703&api_key=your-mapzen-api-key` 278 | 4. Paste this URL into a new browser tab and use your own API key to see the JSON response, which can be mapped. 279 | 280 | _Tip: 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._ 281 | 282 | ![Search endpoint query in the browser developer console](images/developer-console.png) 283 | 284 | ## Choose which data sources to search 285 | 286 | 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. 287 | 288 | 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. 289 | 290 | 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. 291 | 292 | 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. 293 | 294 | ```js 295 | var geocoderOptions = { 296 | autocomplete: false, 297 | params: { 298 | sources: 'osm' 299 | } 300 | }; 301 | ``` 302 | 303 | 2. Save your edits and refresh the browser. 304 | 3. Search for `901 12th Avenue` again. Try searching city names, such as `Vancouver`, as you continue to experiment with the geocoder. 305 | 306 | ## Prioritize nearby places and filter search results 307 | 308 | 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. 309 | 310 | 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. 311 | 312 | 1. Within the `geocoderOptions` block, add add a `,` at the end of the `sources: 'osm'` line and then a parameter for `'boundary.country': 'USA'` on the next line. 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. 313 | 314 | ```js 315 | var geocoderOptions = { 316 | autocomplete: false, 317 | params: { 318 | sources: 'osm', 319 | 'boundary.country': 'USA' 320 | } 321 | }; 322 | ``` 323 | 324 | 3. Save your edits and refresh the browser. 325 | 4. Search again for city names in the Search box. Notice that you only see results from within the United States. For example, `Vancouver` in Canada is no longer listed, but you can find the city in Washington. 326 | 5. Optionally, trying changing the `boundary.country` to another country code, such as `AUS` for Australia. There is a [specific format](https://en.wikipedia.org/wiki/ISO_3166-1) you need to use for the country code. Change the code back to `USA` when you are done. 327 | 328 | ## Filter the results by type of place 329 | 330 | 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. 331 | 332 | In this section, you will filter the results to search only addresses and venues, which include point of interest, landmarks, and businesses. 333 | 334 | 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. 335 | 336 | 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. 337 | 338 | ```js 339 | var geocoderOptions = { 340 | autocomplete: false, 341 | params: { 342 | sources: 'osm', 343 | 'boundary.country': 'USA', 344 | layers: 'address,venue' 345 | } 346 | }; 347 | ``` 348 | 2. Save your edits and refresh the browser. 349 | 3. Search for `102 Pike Street, Seattle, WA 98101` (the first Starbucks) and press Enter. Some other places you can try include `Starbucks`, `400 Broad Street` (the address of the Space Needle), `Space Needle`, and `University of Washington`. 350 | 351 | ## Tutorial summary 352 | 353 | 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. 354 | 355 | If you want to learn more about Pelias, review the [documentation](https://mapzen.com/documentation/search). 356 | 357 | 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. 358 | 359 | ## Completed HTML for this tutorial 360 | 361 | You can refer to this HTML if you want to review your work or troubleshoot an error. 362 | 363 | ```html 364 | 365 | 366 | 367 | My Geocoding Map 368 | 369 | 370 | 371 | 379 | 380 | 381 |
382 | 408 | 409 | 410 | ``` 411 | -------------------------------------------------------------------------------- /search.md: -------------------------------------------------------------------------------- 1 | # Pelias: Finding places 2 | 3 | Geocoding is the process of matching an address or other text to its corresponding geographic coordinates. 4 | 5 | All Pelias requests share the same format: 6 | 7 | ``` 8 | https://search.mapzen.com/v1/search?text=London 9 | \___/ \_______________/\__/\_____/\_________/ 10 | | | / | | 11 | scheme domain version path query 12 | ``` 13 | 14 | ## Search the world 15 | 16 | ![Searching globally](/images/world_all.png) 17 | 18 | In the simplest search, you can provide only one parameter, the text you want to match in any part of the location details. To do this, build a query where the `text` parameter is set to the item you want to find. 19 | 20 | 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. 21 | 22 | > [/v1/search?__text=YMCA__](http://pelias.github.io/compare/#/v1/search%3Ftext=YMCA) 23 | 24 | Note the parameter values are set as follows: 25 | 26 | | parameter | value | 27 | | :--- | :--- | 28 | | `text` | YMCA | 29 | 30 | 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. 31 | 32 | 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. 33 | 34 | 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: 35 | 36 | * YMCA, Bargoed Community, United Kingdom 37 | * YMCA, Nunspeet, Gelderland 38 | * YMCA, Belleville, IL 39 | * YMCA, Forest City, IA 40 | * YMCA, Fargo, ND 41 | * YMCA, Taipei, Taipei City 42 | * YMCA, Orpington, Greater London 43 | * YMCA, Frisco, TX 44 | * YMCA, Jefferson, OH 45 | * YMCA, Belleville, IL 46 | 47 | 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: 48 | 49 | > [/v1/search?__text=yMcA__](http://pelias.github.io/compare/#/v1/search%3Ftext=yMcA) 50 | 51 | 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. 52 | 53 | ## Set the number of results returned 54 | 55 | By default, Pelias returns up to 10 results. If you want a different number, set the `size` parameter to the desired number. This example shows returning only the first result. 56 | 57 | | parameter | value | 58 | | :--- | :--- | 59 | | `text` | YMCA | 60 | | `size` | 1 | 61 | 62 | > [/v1/search?text=YMCA&__size=1__](https://pelias.github.io/compare/#/v1/search%3Fsize=1&text=ymca) 63 | 64 | If you want 25 results, you can build the query where `size` is 25. 65 | 66 | > [/v1/search?text=YMCA&__size=25__](https://pelias.github.io/compare/#/v1/search%3Fsize=25&text=ymca) 67 | 68 | ## Narrow your search 69 | 70 | 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. 71 | 72 | ### Search within a particular country 73 | 74 | ![Searching in a country](/images/world_country.png) 75 | 76 | Sometimes your work might require that all the search results be from a particular country or a list of countries. To do this, you can set the `boundary.country` parameter value to a comma separated list of alpha-2 or alpha-3 [ISO-3166 country code](https://en.wikipedia.org/wiki/ISO_3166-1). 77 | 78 | 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: 79 | 80 | > [/v1/search?text=YMCA&__boundary.country=GBR__](https://pelias.github.io/compare/#/v1/search%3Fboundary.country=GBR&text=ymca) 81 | 82 | | parameter | value | 83 | | :--- | :--- | 84 | | `text` | YMCA | 85 | | `boundary.country` | GBR | 86 | 87 | Note that all the results are within Great Britain: 88 | 89 | * YMCA, Bargoed Community, United Kingdom 90 | * YMCA, Orpington, Greater London 91 | * YMCA, Erdington, West Midlands 92 | * YMCA, Malvern CP, United Kingdom 93 | * YMCA, Ancoats, Greater Manchester 94 | * YMCA, Carmarthen Community, United Kingdom 95 | * YMCA, Halebank, Cheshire 96 | * YMCA, Brightlingsea CP, United Kingdom 97 | * YMCA, Lenton Abbey, Nottinghamshire 98 | * YMCA, Old Clee, Lincolnshire 99 | 100 | If you try the same search request with different country codes, the results change to show YMCA locations within this region. 101 | 102 | > [/v1/search?text=YMCA&__boundary.country=USA__](https://pelias.github.io/compare/#/v1/search%3Fboundary.country=USA&text=ymca) 103 | 104 | Results in the United States: 105 | 106 | * YMCA, Belleville, IL 107 | * YMCA, Forest City, IA 108 | * YMCA, Fargo, ND 109 | * YMCA, Frisco, TX 110 | * YMCA, Jefferson, OH 111 | * YMCA, Belleville, IL 112 | * YMCA, Chapel Hill, NC 113 | * YMCA, West Lampeter, PA 114 | * YMCA, Bremerton, WA 115 | * YMCA, Westerly, RI 116 | 117 | ### Search within a rectangular region 118 | 119 | ![Searching in a bounding box](/images/world_rect.png) 120 | 121 | To specify the boundary using a rectangle, you need latitude, longitude coordinates for two diagonals of the bounding box (the minimum and the maximum latitude, longitude). 122 | 123 | For example, to find a YMCA within the state of Texas, you can set the `boundary.rect.*` parameter to values representing the bounding box around Texas: min_lon=-106.65 min_lat=25.84 max_lon=-93.51 max_lat=36.5 124 | 125 | Tip: You can look up a bounding box for a known region with this [web tool](http://boundingbox.klokantech.com/). 126 | 127 | > [/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://pelias.github.io/compare/#/v1/search%3Fboundary.rect.min_lat=25.84&boundary.rect.min_lon=-106.65&boundary.rect.max_lat=36.5&boundary.rect.max_lon=-93.51&text=ymca) 128 | 129 | | parameter | value | 130 | | :--- | :--- | 131 | | `text` | YMCA | 132 | | `boundary.rect.min_lat` | 25.84 | 133 | | `boundary.rect.min_lon` | -106.65 | 134 | | `boundary.rect.max_lat` | 36.5 | 135 | | `boundary.rect.max_lon` | -93.51 | 136 | 137 | * YMCA, Austin, TX 138 | * YMCA, Frisco, TX 139 | * Y.M.C.A, Fort Worth, TX 140 | * YMCA, Rockwall, TX 141 | * YMCA, Missouri City, TX 142 | * YMCA, Northshore, TX 143 | * YMCA, Austin, TX 144 | * YMCA, Tulsa, OK 145 | * YMCA, Los Alamos, NM 146 | * YMCA, Tulsa, OK 147 | 148 | ### Search within a circular region 149 | 150 | ![Searching within a circle](/images/world_circle.png) 151 | 152 | Sometimes you don't have a rectangle to work with, but rather you have a point on earth—for example, your location coordinates—and a maximum distance within which acceptable results can be located. 153 | 154 | 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. 155 | 156 | > [/v1/search?text=YMCA&__boundary.circle.lon=-79.186484&boundary.circle.lat=43.818156&boundary.circle.radius=35__](https://pelias.github.io/compare/#/v1/search%3Fboundary.circle.lon=-79.186484&boundary.circle.lat=43.818156&boundary.circle.radius=35&text=ymca) 157 | 158 | | parameter | value | 159 | | :--- | :--- | 160 | | `text` | YMCA | 161 | | `boundary.circle.lat` | 43.818156 | 162 | | `boundary.circle.lon` | -79.186484 | 163 | | `boundary.circle.radius` | 35 | 164 | 165 | You can see the results have fewer than the standard 10 items because there are not that many YMCA locations in the specified radius: 166 | 167 | * YMCA, Toronto, Ontario 168 | * YMCA, Markham, Ontario 169 | * YMCA, Toronto, Ontario 170 | * Metro Central YMCA, Toronto, Ontario 171 | * Pinnacle Jr YMCA, Toronto, Ontario 172 | * Cooper Koo Family Cherry Street YMCA Centre, Toronto, Ontario 173 | 174 | ### Search within a parent administrative area 175 | 176 | Pelias has a powerful understanding of relationships between places. In particular, it has a concept called the administrative hierarchy: each record in Pelias is listed as belonging to a parent neighbourhood, city, region, country, and other regions. This has many uses, including filtering. The Pelias global id (`gid`) of any record can be used with the `boundary.gid` filter to return only records with a given parent. 177 | 178 | For example, finding YMCAs in [Oklahoma](https://en.wikipedia.org/wiki/Oklahoma) with only a bounding box would be challenging: the bounding box would include much of nearby Texas, possibly leading to incorrect results. 179 | 180 | With `boundary.gid`, this query can return accurate results. 181 | 182 | > [/v1/search?text=YMCA&__boundary.gid=whosonfirst:region:85688585__](http://pelias.github.io/compare/#/v1/search%3Fboundary.gid=whosonfirst:region:85688585&text=ymca) 183 | 184 | * YMCA, Stillwater, OK, USA 185 | * YMCA, Edmond, OK, USA 186 | * YMCA, Guymon, OK, USA 187 | * YMCA, Grove, OK, USA 188 | * YMCA, Midwest City, OK, USA 189 | * YMCA, Shawnee, OK, USA 190 | * YMCA, Owasso, OK, USA 191 | * YMCA, Tulsa, OK, USA 192 | * YMCA, The Village, OK, USA 193 | * YMCA, Broken Arrow, OK, USA 194 | 195 | In the query above, `whosonfirst:region:85688585`, is the Pelias `gid` for Oklahoma, USA. Currently, all parent records come from the [Who's on First](https://whosonfirst.org/) project. `gid`s for records can be found using either the [Who's on First Spelunker](http://spelunker.whosonfirst.org/), a tool for searching Who's on First data, or from the responses of other Pelias queries. In this case a [search for Oklahoma](http://pelias.github.io/compare/#/v1/search%3Ftext=oklahoma) will return the proper `gid`. 196 | 197 | ### Specify multiple boundaries 198 | 199 | ![Searching within multiple regions](/images/overlapping_boundaries.gif) 200 | 201 | 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. 202 | 203 | ## Prioritize results by proximity 204 | 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. 205 | 206 | ### Prioritize around a point 207 | 208 | ![Searching around a point](/images/focus_point.png) 209 | 210 | By specifying a `focus.point`, results will be sorted in part by their proximity to the given coordinate. All else being equal, results closest to the point will show up higher. However, unlike a `boundary.circle` query, important results far from the given coordinate may still be returned. This allows, for example, [a query for places called Paris with a `focus.point` value in Texas to return both Paris, TX and Paris, France](http://pelias.github.io/compare/#/v1/autocomplete%3Ffocus.point.lat=33.7568&focus.point.lon=-95.5362&layers=locality&sources=wof&text=paris). 211 | 212 | To find YMCAs again, but this time near a specific coordinate location (representing the Sydney Opera House) in Sydney, Australia, use `focus.point`. 213 | 214 | > [/v1/search?text=YMCA&__focus.point.lat=-33.856680&focus.point.lon=151.215281__](https://pelias.github.io/compare/#/v1/search%3Ffocus.point.lat=-33.856680&focus.point.lon=151.215281&text=ymca) 215 | 216 | | parameter | value | 217 | | :--- | :--- | 218 | | `text` | YMCA | 219 | | `focus.point.lat` | -33.856680 | 220 | | `focus.point.lon` | 151.215281 | 221 | 222 | 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. 223 | 224 | * YMCA, Redfern, New South Wales [distance: 3.836] 225 | * YMCA, St Ives (NSW), New South Wales [distance: 14.844] 226 | * YMCA, Epping (NSW), New South Wales [distance: 16.583] 227 | * YMCA, Revesby, New South Wales [distance: 21.335] 228 | * YMCA, Kochâang, South Gyeongsang [distance: 8071.436] 229 | * YMCA, Center, IN [distance: 14882.675] 230 | * YMCA, Lake Villa, IL [distance: 14847.667] 231 | * YMCA, Onondaga, NY [distance: 15818.08] 232 | * YMCA, 's-Gravenhage, Zuid-Holland [distance: 16688.292] 233 | * YMCA, Loughborough, United Kingdom [distance: 16978.367] 234 | 235 | ## Combine boundary search and prioritization 236 | 237 | Now that you have seen how to use boundary and focus to narrow and sort your results, you can examine a few scenarios where they work well together. 238 | 239 | ### Prioritize within a country 240 | 241 | 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. 242 | 243 | > [/v1/search?text=YMCA&__focus.point.lat=-33.856680&focus.point.lon=151.215281__](https://pelias.github.io/compare/#/v1/search%3Ffocus.point.lat=-33.856680&focus.point.lon=151.215281&text=ymca) 244 | 245 | | parameter | value | 246 | | :--- | :--- | 247 | | `text` | YMCA | 248 | | `focus.point.lat` | -33.856680 | 249 | | `focus.point.lon` | 151.215281 | 250 | | `boundary.country` | AUS | 251 | 252 | The results below look different from the ones you saw before with only a focus point specified. These results are all from within Australia. You'll note the closest results show up at the top of the list, which is helped by the focus parameter. 253 | 254 | * YMCA, Redfern, New South Wales [distance: 3.836] 255 | * YMCA, St Ives (NSW), New South Wales [distance: 14.844] 256 | * YMCA, Epping (NSW), New South Wales [distance: 16.583] 257 | * YMCA, Revesby, New South Wales [distance: 21.335] 258 | * YMCA, Larrakeyah, Northern Territory [distance: 3144.296] 259 | * YMCA, Kepnock, Queensland [distance: 1001.657] 260 | * YMCA, Kings Meadows, Tasmania [distance: 917.144] 261 | * YMCA, Katherine East, Northern Territory [distance: 2873.376] 262 | * YMCA, Sadadeen, Northern Territory [distance: 2026.731] 263 | * YMCA, Ararat, Victoria [distance: 841.022] 264 | 265 | ### Prioritize within a circular region 266 | 267 | 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. 268 | 269 | > [/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://pelias.github.io/compare/#/v1/search%3Ffocus.point.lat=-33.856680&focus.point.lon=151.215281&boundary.circle.lat=-33.856680&boundary.circle.lon=151.215281&boundary.circle.radius=50&text=ymca) 270 | 271 | | parameter | value | 272 | | :--- | :--- | 273 | | `text` | YMCA | 274 | | `focus.point.lat` | -33.856680 | 275 | | `focus.point.lon` | 151.215281 | 276 | | `boundary.circle.lat` | -33.856680 | 277 | | `boundary.circle.lon` | 151.215281 | 278 | | `boundary.circle.radius` | 50 | 279 | 280 | Looking at these results, they are all less than 50 kilometers away from the focus point: 281 | 282 | * YMCA, Redfern, New South Wales [distance: 3.836] 283 | * YMCA, St Ives (NSW), New South Wales [distance: 14.844] 284 | * YMCA, Epping (NSW), New South Wales [distance: 16.583] 285 | * YMCA, Revesby, New South Wales [distance: 21.335] 286 | * Caringbah YMCA, Caringbah, New South Wales [distance: 22.543] 287 | * YMCA building, Loftus, New South Wales [distance: 25.756] 288 | 289 | ## Filter your search 290 | 291 | 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. 292 | 293 | With Pelias, you can filter by: 294 | 295 | * `sources`: the originating source of the data 296 | * `layers`: the kind of place you want to find 297 | 298 | ### Filter by data source 299 | 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: 300 | 301 | | source | name | short name | 302 | |---|---|---| 303 | | [OpenStreetMap](http://www.openstreetmap.org/) | `openstreetmap` | `osm` | 304 | | [OpenAddresses](http://openaddresses.io/) | `openaddresses` | `oa` | 305 | | [Who's on First](https://whosonfirst.org) | `whosonfirst` | `wof` | 306 | | [GeoNames](http://www.geonames.org/) | `geonames` | `gn` | 307 | 308 | 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. 309 | 310 | > [/v1/search?text=YMCA&__sources=oa__](https://pelias.github.io/compare/#/v1/search%3Fsources=oa&text=ymca) 311 | 312 | | parameter | value | 313 | | :--- | :--- | 314 | | `text` | YMCA | 315 | | `sources` | oa | 316 | 317 | Because OpenAddresses is, as the name suggests, only address data, here's what you can expect to find: 318 | 319 | * 20 Ymca Drive, Niagara, ON, Canada 320 | * 341 Ymca Rd, New Hope, AL, USA 321 | * 318 Ymca Rd, New Hope, AL, USA 322 | * 138 Ymca Rd, New Hope, AL, USA 323 | * 304 Ymca Rd, New Hope, AL, USA 324 | * 1919 Ymca Lane, Minnetonka, MN, USA 325 | * 101 Ymca Dr, Kannapolis, NC, USA 326 | * 2121 Ymca Camp Road, Stokes County, NC, USA 327 | * 1110 Ymca Camp Road, Stokes County, NC, USA 328 | * 1581 Ymca Camp Road, Stokes County, NC, USA 329 | 330 | 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. 331 | 332 | > [/v1/search?text=YMCA&__sources=osm,gn__](https://pelias.github.io/compare/#/v1/search%3Fsources=osm,gn&text=ymca) 333 | 334 | | parameter | value | 335 | | :--- | :--- | 336 | | `text` | YMCA | 337 | | `sources` | osm,gn | 338 | 339 | Each of the data sources supported by Pelias can have different properties, licenses, and strengths. You can learn more on the [data sources for Pelias](data-sources.md) page. 340 | 341 | ### Filter by data type 342 | In Pelias, different types of results are given different `layer` values. This helps us differentiate, for example, an address from a point of interest from a country. 343 | 344 | 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 you filter for just the types of results you want. 345 | 346 | Here's a list of the types of places you could find in the results, sorted by granularity: 347 | 348 | |layer|description| 349 | |----|----| 350 | |`venue`|points of interest, businesses, things with walls| 351 | |`address`|places with a street address| 352 | |`street`|streets,roads,highways| 353 | |`neighbourhood`|social communities, neighbourhoods| 354 | |`borough`|a local administrative boundary, currently only used for New York City| 355 | |`localadmin`|local administrative boundaries| 356 | |`locality`|towns, hamlets, cities| 357 | |`county`|official governmental area; usually bigger than a locality, almost always smaller than a region| 358 | |`macrocounty`|a related group of counties. Mostly in Europe.| 359 | |`region`|states and provinces| 360 | |`macroregion`|a related group of regions. Mostly in Europe| 361 | |`country`|places that issue passports, nations, nation-states| 362 | |`coarse`|alias for simultaneously using all administrative layers (everything except `venue` and `address`)| 363 | |`postalcode`|postal code used by mail services| 364 | 365 | > [/v1/search?text=YMCA&__layers=venue,address__](https://pelias.github.io/compare/#/v1/search%3Flayers=venue,address&text=ymca) 366 | 367 | | parameter | value | 368 | | :--- | :--- | 369 | | `text` | YMCA | 370 | | `layers` | venue,address | 371 | 372 | ## Available search parameters 373 | 374 | | Parameter | Type | Required | Default | Example | 375 | | --- | --- | --- | --- | --- | 376 | | `text` | string | yes | none | `Union Square` | 377 | | `focus.point.lat` | floating point number | no | none | `48.581755` | 378 | | `focus.point.lon` | floating point number | no | none | `7.745843` | 379 | | `boundary.rect.min_lon` | floating point number | no | none | `139.2794` | 380 | | `boundary.rect.max_lon` | floating point number | no | none | `140.1471` | 381 | | `boundary.rect.min_lat` | floating point number | no | none | `35.53308` | 382 | | `boundary.rect.max_lat` | floating point number | no | none | `35.81346` | 383 | | `boundary.circle.lat` | floating point number | no | none | `43.818156` | 384 | | `boundary.circle.lon` | floating point number | no | none | `-79.186484` | 385 | | `boundary.circle.radius` | floating point number | no | 50 | `35` | 386 | | `boundary.gid` | Pelias `gid` | no | none | `whosonfirst:locality:101748355` | 387 | | `sources` | string | no | all sources: osm,oa,gn,wof | openstreetmap,wof | 388 | | `layers` | string | no | all layers: address,venue,neighbourhood,locality,borough,localadmin,county,macrocounty,region,macroregion,country,coarse,postalcode | address,venue | 389 | | `boundary.country` | string | no | none | `GBR,FRA` | 390 | | `size` | integer | no | 10 | 20 | 391 | -------------------------------------------------------------------------------- /release-notes.md: -------------------------------------------------------------------------------- 1 | # Pelias Release Notes 2 | 3 | Pelias as a whole operates on a rolling-release process where we generally recommend the latest version of each individual component. 4 | 5 | In general, it's safe to mix and match newer and older versions of different components, or upgrade one component at a time. 6 | 7 | We try to avoid it, but when there is a breaking change in one component, we 8 | publish a new _major version_ of that component. 9 | 10 | Each component has its own release notes published on GitHub. 11 | 12 | For example, you can view the release notes for the Pelias API at https://github.com/pelias/api/releases. 13 | 14 | Here are some of the major Pelias repositories and their release notes: 15 | 16 | - [API](https://github.com/pelias/api/releases) 17 | - [Elasticsearch schema](https://github.com/pelias/schema/releases) 18 | - [OpenStreetMap importer](https://github.com/pelias/openstreetmap/releases) 19 | - [OpenAddresses importer](https://github.com/pelias/openaddresses/releases) 20 | - [Who's on First importer](https://github.com/pelias/whosonfirst/releases) 21 | - [CSV importer](https://github.com/pelias/csv-importer/releases) 22 | 23 | # Historical release notes 24 | 25 | ## 26 October 2017 26 | 27 | ### Bug fixes 28 | 29 | * The `/place` endpoint would sometimes return records from a [different layer than the one you asked for](https://github.com/pelias/api/pull/1036), but no longer! 30 | * Asking the `/reverse` endpoint to return venues from Geonames used to return a error message. However, it should work, and now [it does](https://github.com/pelias/api/pull/1045)! 31 | 32 | ## 29 September 2017 33 | 34 | ### New features 35 | 36 | This release marks a major update of our [Placeholder](https://github.com/pelias/placeholder) service that is in charge of managing administrative area names. All sorts of queries that need to understand the name of a country, city, county, neighbourhood, or any other administrative area are improved! Especially improved should be queries that use non-English languages. The full details of the code changes are [in the Placeholder pull request](https://github.com/pelias/placeholder/pull/49). 37 | 38 | ### Bug fixes 39 | 40 | Over the last few days we have fixed [several](https://github.com/pelias/api/pull/1006) [regressions](https://github.com/pelias/api/pull/1003) that could cause bad responses from, and sometimes even crash, our API server. 41 | 42 | ## 19 September 2017 43 | 44 | ### Bug fixes 45 | * Thanks to [@rabidllama](https://github.com/rabidllama)'s [excellent PR](https://github.com/pelias/api/pull/974), we now support queries with postalcode and region/country combinations. 46 | 47 | ## 14 September 2017 48 | 49 | ### New features 50 | * We've beefed up downloaders for OpenAddresses, OpenStreetMap, and Who's On First to download subsets of data. 51 | * 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). 52 | 53 | ### Bug fixes 54 | * 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. 55 | 56 | ## 22 August 2017 57 | ### New features 58 | * We now support the ability to specify the admin hierarchy part of an address query in any language 59 | (as long as a name in that language can be found in WOF), for example searching for 60 | [30 w 26th st, Нью Йорк, 미국](http://pelias.github.io/compare/#/v1/search%3Ftext=30%20w%2026th%20st,%20%D0%9D%D1%8C%D1%8E%20%D0%99%D0%BE%D1%80%D0%BA,%20%EB%AF%B8%EA%B5%AD) works like magic! 61 | * 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. 62 | 63 | ### Bug fixes 64 | * 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. 65 | * We fixed our production configuration to fully enable language headers (they were only partially available previously). Ooops! 66 | 67 | ## 6 July 2017 68 | ## Milestones 69 | Today's release has no new code, but it's a big milestone nonetheless. For the first time, we are indexing over 500 million (that's _half a billion_) records, all from open data! We're grateful to all the work from contributors of OpenStreetMap, OpenAddresses, Who's on First, and Geonames that have made this possible and are looking forward to reaching the big _one billion_ mark soon! 70 | 71 | 72 | ## 30 June 2017 73 | ### Bug fixes 74 | Our new Placeholder service queries were working great, except they weren't returning confidence scores. Now they [have confidence scores](https://github.com/pelias/api/pull/918) just like all our other queries. 75 | 76 | ## 27 June 2017 77 | ### New features 78 | * After several months of work we have finally released massively improved admin queries! These use our new service, [Placeholder](https://github.com/pelias/placeholder). Placeholder knows all about cities, countries, and every other type of administrative area, and knows the relationships between them, so it can be used to return much better results. 79 | 80 | ### Bug fixes 81 | * We discovered that we were importing every [jetway](https://en.wikipedia.org/wiki/Jetway) from OpenStreetMap, which isn't really something anyone wants to geocode, so we've improved our [whitelists](https://github.com/pelias/openstreetmap/pull/280) for what's allowed. Results from OSM should be a little cleaner now. 82 | * Autocomplete now works correctly on [very long names](https://github.com/pelias/schema/pull/224). 83 | 84 | 85 | ## 30 May 2017 86 | ### New features 87 | * Deduper will now [prefer results with postalcodes](https://github.com/pelias/api/pull/895/commits/512cec994565e9df298e82b7e3f9137d00ecc055), which comes to us courtesy of our friend @kevincennis. 88 | * WOF Macrohoods have been added to the list of supported hierarchies. 89 | 90 | ## 21 April 2017 91 | 92 | ### New features 93 | * Our first big ticket item is technically a new feature, a code level change, and a bug fix all in one! We've created a standalone microservice whose job it is to handle point-in-polygon requests. So with this release, all reverse queries specifying admin layers will be directed to this new service, instead of going to Elasticsearch like it used to. As a user, you won't see any difference in the interface to these types of requests and you don't have to take any action to use the new functionality. However, faster and better results will be apparent! 94 | * Our second big ticket item (we know, 2 in one release is awesome sauce!) is the long awaited upgrade to `libpostal 1.0`. This is again a code level change that doesn't have any user interface implications but yield significant improvements in results. We can tell just by the number of [old issues we were able to resolve](https://github.com/pelias/pelias/milestone/49?closed=1) as a result of this upgrade that this is a big moment for the Pelias engine. High-fives all around! 95 | * You know how we started supporting search queries with only postalcodes in them, like `/v1/search?text=90210`? Well get excited, because we've added the ability to handle postalcode only queries in `structured` search as well! So queries like `/v1/search/structures?postalcode=90210` will now work. More info [here](structured-geocoding.md#postalcode). 96 | * We fixed a few minor bugs related to address interpolation. There were cases where the results had a mix of street centroids and addresses and the correct address was not showing up first. More details [here](https://github.com/pelias/pelias/issues/528). 97 | * There was an [issue with geonames admin records](https://github.com/pelias/pelias/issues/539) having incorrect ids in their admin hierarchy properties. They were basically masquerading as Who's on First ids leading to invalid results and general chaos. Well no more. We fixed it. 98 | 99 | ## 13 March 2017 100 | 101 | * We've added postalcodes to the Who's on First import process and enabled the postalcode-only query type, so users can now find postalcodes directly! [90210](https://mapzen.com/products/search/?query=90210%2C%20Los%20Angeles%2C%20CA%2C%20USA&endpoint=place&gid=whosonfirst%3Apostalcode%3A554783991&selectedLat=34.10052&selectedLng=-118.41463&lng=-119.73999&lat=34.10271&zoom=7) anyone? 102 | * Dependencies, like [San Jose, PRI](https://mapzen.com/products/search/?query=San%20Jos%C3%A9%2C%20PRI&endpoint=place&gid=whosonfirst%3Alocality%3A101919071&selectedLat=18.40259&selectedLng=-66.25065&lng=-66.91223&lat=18.40275&zoom=8), should now have the proper alpha3 ISO codes of their own in the country abbreviation (`country_a`) properties, instead of alpha2 of the parent country as it did previously. 103 | * Washington DC wasn't getting a region abbreviation at all for a while, but that's water under the [Arlington Memorial Bridge](https://mapzen.com/products/search/?query=Arlington%20Memorial%20Bridge%2C%20Washington%2C%20DC%2C%20USA&endpoint=place&gid=openstreetmap%3Astreet%3Apolyline%3A22398323&selectedLat=38.88844&selectedLng=-77.05266&lng=-77.21809&lat=38.88863&zoom=10) now! 104 | 105 | ***Warning:*** _We are having some technical difficulties with the polylines data generated from the OSM 106 | road network. This data is used to populate our street index and interpolation service. Both features will continue working as before, but data will be stale until a fix is implemented. 107 | We will be using the last known good version, which was built on February 27th, 2017. 108 | We will definitely keep everyone posted as soon as an updated working version is available. Sorry for any 109 | inconvenience this may have caused._ 110 | 111 | ## 6 February 2017 112 | 113 | We bring you another data update this week, but don't worry, we're busy working on cool new features and improvements. If you're curious what those might be, come read all about them [here](http://pelias.io/quarterly_goals/q1-2017.html)! 114 | 115 | ## 1 February 2017 116 | 117 | 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! 118 | 119 | ## 27 January 2017 120 | 121 | Thanks to some wild activity in the [openaddresses](http://openaddresses.io) project, this is the first Pelias build with over 400 million documents! 122 | 123 | We are excited to see open data continue to grow and improve and looking forward to the big half billion milestone. :) 124 | 125 | ### New features 126 | * Big news! 🐯 we have soft-launched our new [street interpolation](https://github.com/pelias/api/pull/769) service, which includes [TIGER](https://en.wikipedia.org/wiki/Topologically_Integrated_Geographic_Encoding_and_Referencing) data. This allows us to return more address results than before. For more info, see https://github.com/pelias/interpolation 127 | 128 | ## Bug fixes 129 | * We've [fixed a bug](https://github.com/pelias/api/pull/780) where structured queries would always return 'fallback' as the 'match_type'. 130 | 131 | ## 17 January 2017 132 | 133 | For our second release of the year we bring the first new batch of street data for our [polylines](https://github.com/pelias/polylines) dataset (derived from OSM) that we introduced late last year. We'll now be updating that data weekly like everything else! 134 | 135 | ### New features 136 | * The `/v1/structured` endpoint [now supports](https://github.com/pelias/api/pull/763) the `venue` parameter, which allows for searching for venues with a particular name. 137 | * We've [improved result balance](https://github.com/pelias/api/pull/729) when using `focus.point` in the autocomplete endpoint. In particular, searching for cities far away from the focus point should work much better. More improvements to `focus.point` are planned for the near future. 138 | 139 | ## 5 January 2017 140 | 141 | Our first release of 2017 is here! Due to some build issues, this is the first update of data since mid-November. We're happy to be back and have improved our build validation along the way. 142 | 143 | ## 28 December 2016 144 | 145 | ### New features 146 | 147 | * Searches for `St Louis, MO` and `Saint Louis, MO` now return the same thing (the same goes for towns starting with `Mount`/`Mt` and `Fort`/`Ft`) 148 | * [Structured geocoding](https://mapzen.com/blog/structured-geocoding/) no longer fails horribly when the `address` parameter consists of only a house number 149 | 150 | ## 05 December 2016 151 | 152 | This week includes only code changes, no data updates. Our production build failed do to an [error reading whosonfirst data](https://github.com/pelias/pelias/issues/477). We'll either kick off a new build for release later this week, or resume data updates with our usual cadence next week. 153 | 154 | ### New features 155 | 156 | * We've released what was previously referred to as component geocoding in the new structured geocoding endpoint! It lives at `/v1/search/structured` 157 | * We fixed a bug where [specifying the same parameter twice](https://github.com/pelias/api/issues/744) (eg `/v1/search?text=paris&sources=geonames&sources=gn`) would cause a 500 error. It now returns a helpful 400 error message that includes which parameter is duplicated, so that the request can be fixed. 158 | * Other errors that should have been 500 errors were [being returned with status code 400](https://github.com/pelias/api/pull/742). Fixing this will allow us to more quickly catch any 500 errors that happen in the future. 159 | 160 | ## 18 November 2016 161 | 162 | * 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. 163 | * 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. 164 | * 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. 165 | * Whether your input contains a 2- or 3-character ISO country code (`FRA` vs `FR`), we'll find it! 166 | 167 | ## 24 October 2016 168 | 169 | * The `/v1/autocomplete` endpoint now supports [boundary.rect](search.md#search-within-a-rectangular-region) just like `/v1/search` 170 | * Labels for administrative areas should be [improved in a few cases](https://github.com/pelias/whosonfirst/pull/139) 171 | 172 | ## 10 October 2016 173 | 174 | * [libpostal](https://github.com/openvenues/libpostal), the super-sophisticated address parser, has been integrated for more accurate analysis of inputs at `/v1/search`. 175 | * Street names containing post-directionals (e.g. - `186 Tuskegee St SE Atlanta GA` -> `186 Tuskegee St SouthEast Atlanta GA`) are now treated the same as their pre-directional brethren. 176 | * 10/10, would release again - geocoding fallback rules that favor traditional geocoding behavior instead of search engine behavior 177 | 178 | ## 19 September 2016 179 | 180 | Another data-only release. Stay tuned for next week! 181 | 182 | ## 12 September 2016 183 | 184 | * 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. 👏 185 | 186 | ## 7 September 2016 187 | 188 | * Crikey! We noticed we weren't handling Australian province abbreviations, so we [added support for them in our labels](https://github.com/pelias/api/pull/638). 189 | * Geonames ADM3 records now are [correctly listed as localadmins](https://github.com/pelias/geonames/pull/120), not venues. 190 | * Our wonderful, now departed intern made sure [Germanic street names are consistently handled](https://github.com/pelias/openaddresses/pull/68) (previously, some would end in -strasse while others ended in the abbreviation -str). 191 | * Records with a Who's on First [dependency](https://github.com/whosonfirst/whosonfirst-placetypes#dependency) now [have that dependency listed in API responses](https://github.com/pelias/api/pull/643). 192 | 193 | ## 22 August 2016 194 | 195 | No changes in functionality at all, just the freshest data! We did clean up some tests and do other work only visible to developers and those who run their own Pelias instance, but nothing major. 196 | 197 | Stay tuned for next week's release where we already have some nice changes queued up. 198 | 199 | ## 18 August 2016 200 | 201 | * After much feedback we've added the [`boundary.country` parameter for autocomplete](https://github.com/pelias/api/pull/634)! It works just like the one on the search endpoint. 202 | * To help make Leaflet maps display results better, we now use [use the `lbl:bbox` property on Who's on First records](https://github.com/pelias/whosonfirst/pull/122). This is useful for places like [San Francisco](https://en.wikipedia.org/wiki/Farallon_Islands) where the mathematical bounding box is bigger than people expect. 203 | * The API was [incorrectly warning](https://github.com/pelias/api/pull/617) against using the `boundary.circle` parameter. Now it doesn't complain! 204 | * We've added a new `/v1/nearby` endpoint that is currently in _early alpha_! There's no documentation, probably some bugs, and any part of the interface is still subject to change. 205 | * Finally, we're now running Node.js 4 in production, rather than Node.js 0.12. For those running their own Pelias instance, be aware that we'll be dropping support for Node.js 0.12 in September. At first, things may work on Node.js 0.12, but we're very excited to finally start using ES2016, so that won't last too long. 206 | 207 | ## 8 August 2016 208 | 209 | Incremental release resolving the final outstanding tasks in the Elasticsearch 2 upgrade. 210 | 211 | We have registered a new website [http://pelias.io](http://pelias.io) which has information about the milstones we have planned for the current quarter. 212 | 213 | * Elasticsearch 2+ does not support co-ordinate wrapping as it did prior to the 2 release. Some front-ends allow users to 'wrap' around the globe. Floats outside of the normal -90/+90 -180/+180 geographic coordinate ranges cause Elasticsearch to error. We added a function to the API which [unwraps these coordinates](https://github.com/pelias/api/pull/608); providing better compatibility with these tools. 214 | - We added `borough` as a [possible layer for Geonames](https://github.com/pelias/api/pull/612) 215 | - Since the beginning of the project the Elasticsearch `_index` name has always been hard-coded as 'pelias', the [index names configurable PRs](https://github.com/pelias/config/pull/30) allow this behaviour to be adjusted in your individual pelias config files. 216 | - We [removed the focus.viewport API](https://github.com/pelias/api/pull/620) which was undocumented and never used outside of test suites. 217 | 218 | ## 2 August 2016 219 | 220 | Another bigger than usual release, we had some ops related challenges to resolve after the update to Elasticsearch 2, as well as some data issues, but we also have some great improvements in store! 221 | 222 | * We use more of the population data in Who's on First, which really helps more [relevant cities come up in searches](https://github.com/pelias/whosonfirst/pull/116). 223 | * Searching for [only records in certain layers in Geonames](https://github.com/pelias/api/pull/573) now works! We keep adding better handling of Geonames data but sometimes our API code doesn't keep up with those changes. 224 | * Labels now [include county names](https://github.com/pelias/api/pull/576) if there's no city (locality) info present. This helps with [addresses that are outside the bounds of any city](https://github.com/pelias/api/issues/575) 225 | * Capitalization across all OpenAddresess records is now more consistent. We've tried to [properly capitalize all records that were either in all caps or all lowercase](https://github.com/pelias/openaddresses/pull/131). This is better in general, although there are certainly exceptions, and we welcome bug reports for those cases. 226 | * Geonames records for New York City boroughs like Manhattan and Brooklyn are [now in the `borough`, rather than `locality` layer](https://github.com/pelias/geonames/pull/100). This makes them consistent with the records from Who's on First, which have been boroughs for some time. 227 | * Addresses in the [Czech Republic](https://github.com/pelias/api/pull/594) now show the street name before the house number, in keeping with local customs 228 | * When using the `/v1/place` endpoint, the source name can either be the full name or the [abbreviation](https://github.com/pelias/api/pull/574) (like the `sources` parameter to the search and autocomplete endpoints). We love saving people some typing :) 229 | * We've made lots of internal changes like [reducing the size of our documents](https://github.com/pelias/model/pull/37), using a cleaner method to construct [layer filter queries](https://github.com/pelias/api/pull/580), removing dependencies on [packages we've deprecated](https://github.com/pelias/schema/pull/151), and allowing the Elasticsearch index name to be configured for both the [API](https://github.com/pelias/api/pull/595) and [schema](https://github.com/pelias/schema/pull/155) packages. 230 | * In related internal changes news, we've also worked to make sure that all our code works with Node.js version 6, which was recently released! Support for Node.js 0.10, which is quite old and near end-of-life, is also starting to be removed. 231 | 232 | We also have two **known issues** in this build: 233 | * Some OpenAddresses records for the statewide data in Massachusetts, USA are incorrect. This is because of an issue [when changing data sources](https://github.com/openaddresses/openaddresses/pull/1892) that will be resolved in the next OpenAddresses build 234 | * Geonames `localadmin` records, like the [City of New York](http://pelias.github.io/compare/#/v1/search%3Fsources=gn&layers=localadmin&text=city%20of%20new%20york) will have extra components in the label (in this case, "Brooklyn, New York"). The [fix for this](https://github.com/pelias/wof-admin-lookup/pull/53) is merged but was accidentally omitted from this build. Look forward to it next week! 235 | 236 | ## 07 July 2016 237 | 238 | * **Big news:** We've finally [upgraded to Elasticsearch 2.3](https://github.com/pelias/pelias/issues/325)! This brings improved performance and more importantly sets us up for lots of improvements from the new features of Elasticsearch 2. Elasticsearch 1.7 is no longer supported. 239 | * As part of the Elasticsearch 2 upgrade we've also improved a few edge cases for searching for numeric values, and with single character tokens. You can [read more](https://github.com/pelias/pelias/issues/325#issuecomment-230724630) in the Github issue for the upgrade. 240 | * We've also fixed some lingering issues where a few places in Denmark were listed as [being part of Sweden](https://github.com/pelias/pelias/issues/368). This was due to the same data bug as mentioned in our recent [blog post](https://mapzen.com/blog/assult-on-copenhagen/). 241 | * The OpenAddresses importer now has better [whitespace cleanup](https://github.com/pelias/openaddresses/pull/130), so there won't be any extra spaces in street names. 242 | * We recently added data to new [layers](search.md#filter-by-data-type) in Geonames, but the API didn't know about it, and prevented you from searching for them. We [fixed it](https://github.com/pelias/api/pull/573). 243 | 244 | ## 13 June 2016 245 | 246 | * Who's on First importer: records now use the label centroid if it's present. The previous behavior was to always use the center of the record's bounding box. In cases like [San Francisco](https://github.com/pelias/pelias/issues/356), this caused the record to not show up where people expect! 247 | * Openstreetmap importer: A bug in config parameter handling that caused admin lookup to be disabled when it shouldn't was fixed. Thanks to [@dylanFrese](https://github.com/DylanFrese) for helping us catch this tricky one. 248 | 249 | ## 26 May 2016 250 | 251 | * We did it... we removed an Elasticsearch analyzer that was presumptuously assuming all queries were in English! The `k-stemming` analysis would do strange things like turn Daly into Dale, so finding "Daly City" was a challange. Well, no more! Word of warning, in `/search` we are now less forgiving when someone uses a plural version of a word where the real name is singular. 252 | 253 | ## 23 May 2016 254 | 255 | * All the extra 0's have been eradicated in addresses coming from OpenAddresses. You should not see any house numbers that reduce to 0 or any leading 0's in house numbers. 256 | * Added the mysteriously missing `source_id` property to response features. This property represents the original id at the source, if one existed, like in OSM and WOF. Where it didn't we made one up to help uniquely identify each record. 257 | 258 | ## 09 May 2016 259 | 260 | * Cleaned up some invalid address data from our OpenAddresses import by removing anything with words like `NULL`, `UNDEFINED`, and `UNAVAILABLE`. 261 | * Improved error reporting in the API so users can decipher what went wrong much easier. More specifically, there are errors that Elasticsearch reports and we propogate up to the API response. 262 | 263 | ## 29 April 2016 264 | 265 | * A big improvements to autocomplete results coming from numerous bug fixes and improvements! More details can be found in the pull requests: [pelias/schema#127](https://github.com/pelias/schema/pull/127) and [pelias/api#526](https://github.com/pelias/api/pull/526). Some highlights include: 266 | - Single digit housenumbers like `8 Main St` can be found more easily 267 | - Support for searching for the street name before the house number, as is common in many European countries, is improved. 268 | - Searches that end in common words no longer return no results. These were being treated as stopwords internally in Elasticsearch. Now queries such as `Moscone West` will work better 269 | * [Remove OpenAddresses records with 0 housenumbers in US/CA](https://github.com/pelias/openaddresses/pull/92) 270 | 271 | ## 18 April 2016 272 | 273 | * Address parsing now works without spaces after commas. This was our bad. Feel free to leave those spaces out as long as you provide commas to delimit admin parts. 274 | * Further streamlining of labels. You can expect the labels to a have more consistent and minimal feel. If the results are coming from New York, expect boroughs such as Manhattan, Brooklyn, Queens, etc. to be part of the label. You're welcome New Yorkers! :heart: 275 | * Fixed a bug where specifying `layers=macrocounty` would fail due to a typo in the API code. You can see how easy it is to mistype `macrocounty` and not notice that `macrocountry` is incorrect. #onlyhuman 276 | 277 | 278 | ## 08 April 2016 279 | 280 | 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. 281 | 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](autocomplete.md#available-autocomplete-parameters). 282 | See the detailed list of changes below for more specifics. 283 | 284 | * Switched from `Quattroshapes` to `WhosOnFirst` as the canonical source for administrative hierarchies and corresponding geometries. 285 | * No longer importing `Quattroshapes` data since `WhosOnFirst` contains all those records and more. Going forward, any use of `quattroshapes` or `qs` in queries will resolve to `whosonfirst` or `wof` automatically. 286 | * New `bbox` property has been added to individual results, for which geometry was available in the original source. This does not affect POI and address data. 287 | * Drastic improvements have been made to the label generation logic. 288 | * `id` and `gid` format has changed to make the ids more unique. 289 | * New id format resolves previously outstanding bugs related to `geonames` ids being invalid for lookup via the `/place` endpoint. 290 | * Additional place-types have been introduced, such as `macroregion`, `macrocounty`, and `borough`. 291 | * `gid` values have been added for each parent in the admin hierarchies of results. 292 | * `/autocomplete` now allows filtering by `sources` and `layers`. 293 | * Fixed a bug that allowed `/autocomplete` to accept the `size` parameter. The default and only size of `/autocomplete` results is now `10`, as originally intended. 294 | --------------------------------------------------------------------------------