diff --git a/services.md b/services.md new file mode 100644 index 0000000..febc839 --- /dev/null +++ b/services.md @@ -0,0 +1,62 @@ +# Pelias services + +A running Pelias installation is composed of several different services. Each service is well suited +to a particular task. + +## Service Use Cases + +Here's a list of which services provide which features in Pelias. If you don't need everything Pelias +does, you may be able to get by without installing and running all the Pelias services + +| Service | /v1/search | /v1/autocomplete | /v1/reverse | /v1/reverse (coarse) | Multiple language support (any endpoint) | +| ------ | ----- | ----- | --------- | ------- | ----- | +| API | **required** | **required** | **required** | **required** | **required** | +| Placeholder | **required** | | | | **required** | +| Libpostal | **required** | | | | | +| PIP | | | recommended | **required** | | +| Interpolation | optional | | | | | + +## Descriptions + +### [API](https://github.com/pelias/api) + +This is the core of Pelias. It talks to all other services (if available), Elasticsearch, and +provides the interface for all queries to Pelias. + +### [Placeholder](https://github.com/pelias/placeholder) + +Placeholder is used specifically to handle the relational component of geocoding. Placeholder +understands, for example, that Paris is a city in a country called France, but that there is another +city called Paris in the state of Texas, USA. + +Placeholder also stores the translations of administrative areas in multiple languages. Therefore it +is required if any support for multiple languages is desired. + +Currently, Placeholder is used only for forward geocoding on the `/v1/search` endpoint. In the +future, it will also be used for autocomplete. + +### Libpostal + +Libpostal is a library that provides an address parser using a statistical natural language processing +model trained on OpenStreetMap, OpenAddresses, and other open data. It is quite good at parsing +fully specified input, but cannot handle autocomplete very well. + +The data required for Libpostal to run is around 3GB, and has to be loaded into memory, so this +service is fairly expensive to run, even for small installations. + +Unlike the other Pelias services, we didn't actually write a Pelias Libpostal service. We recommend +using the [go-whosonfirst-libpostal](https://github.com/whosonfirst/go-whosonfirst-libpostal) +service created by the [Who's on First](https://whosonfirst.org) team. + +## [Point-in-Polygon (PIP)](https://github.com/pelias/pip-service) + +The PIP service loads polygon data representing the boundaries of cities, states, regions, countries +etc into memory, and can perform calculations on that geometric data. Its used to determine if a +given point lies in a particular polygon. Thus, it's highly recommended for reverse geocoding. + +## [Interpolation](https://github.com/pelias/interpolation) + +The interpolation service combines street geometries with known addresses and address ranges, to +allow estimating the position of addresses that might exist, but aren't in existing open +data sources. It is only used by the `/v1/search` endpoint, but [autocomplete support may be added in +the future](https://github.com/pelias/interpolation/issues/131).