Add services documentation

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).