Pelias: Modular Open-Source Geocoder Built on Elasticsearch

What Pelias Does: Forward and Reverse Geocoding

Geocoding is the process of taking a text input, such as a street address or a place name, and returning a latitude and longitude. Reverse geocoding does the opposite: given a latitude and longitude, it returns the places and addresses at or near that point. Pelias supports both directions.

The README describes Pelias as a search engine for places worldwide, powered entirely by open data. It supports multiple result types including addresses, venues, cities, countries, and other administrative areas. Autocomplete is a supported use case: the system is designed for fast, accurate autocomplete queries suitable for user-facing geocoding inputs, not just batch processing. Multiple languages are supported for both input queries and result display.

Pelias was originally built at Mapzen and has been maintained by the same core team since 2013. It is now maintained and developed by Geocode Earth, which also operates a cloud-hosted version of the service at geocode.earth. The project is fully MIT licensed and the code is publicly available. The README reflects a clear position: open data, open source, and open strategy are preferred over proprietary solutions at every layer of the stack.

Architecture: Three Main Components

The README describes the Pelias architecture in three layers. Each layer contains multiple independent services, and this modularity is both a strength and a deployment challenge.

The first layer is data importers. Importers filter, normalise, and ingest geographic datasets into the Elasticsearch database. There are six officially supported importers: OpenStreetMap (nodes, ways, and relations), OpenAddresses (hundreds of millions of global addresses collected from government sources), Who's on First (administrative areas and venues), Geonames (admin records and venues), Polylines (road data from OpenStreetMap in Google Polyline format), and CSV (any custom or proprietary data in comma-separated format). Custom importers can be written to load proprietary datasets into a private Pelias instance.

The second layer is the database. Pelias uses Elasticsearch as its primary datastore. Elasticsearch handles the full-text search and geographic queries that power geocoding results. The README notes that versions 7 and 8 are currently supported. The `pelias-schema` tool sets up the Elasticsearch indices with the correct mappings for Pelias.

The third layer is frontend services. These handle the actual geocoding requests from users and include: the API service (the main HTTP endpoint), Placeholder (a service for administrative area relationships, since Elasticsearch does not handle relational data well), the PIP service (point-in-polygon calculations for reverse geocoding), the Libpostal service (address parsing using machine learning, based on the `libpostal` library), and the Interpolation service (for estimating addresses that are not in the database but can be inferred from nearby known addresses).

Data Sources and Their Coverage

The data coverage of a Pelias instance depends entirely on which importers you run and which datasets you load. This is fundamentally different from using Google Maps or Mapbox Geocoding APIs, where the data is managed by the provider.

OpenStreetMap is the most comprehensive source for venue and point-of-interest data globally, with contributions from millions of volunteers. OpenAddresses aggregates address data from authoritative government sources in many countries, providing precise address-level coverage where available. Who's on First is a dataset of administrative areas maintained by Geocode Earth, covering countries, regions, cities, and neighbourhoods with well-defined hierarchical relationships. Geonames is a database of geographic names that complements the other sources for places not covered elsewhere.

The CSV importer is particularly useful for organisations that have proprietary address or venue data they want to search alongside the open datasets. A team could run the CSV importer to load their own business locations into the same Elasticsearch index that holds OpenStreetMap data, giving users a unified search experience across both sources.

Pelias's open data model means your geocoding results are only as good as the underlying datasets you import. Areas with sparse OpenStreetMap coverage or no OpenAddresses data will return fewer and less precise results than areas with dense coverage.

Deploying Pelias: Docker and Complexity

The recommended installation path is through the `pelias/docker` repository, which the README links to for local installation. The Dockerfile in the main repository is for running the Pelias website documentation, not for running Pelias itself. The actual deployment instructions are in the separate Docker repository.

A complete Pelias deployment requires running Elasticsearch, importing at least one dataset through one of the six official importers, and starting the frontend services. The number of moving parts is significant: each importer runs as a separate process, each frontend service runs as a separate process, and Elasticsearch requires its own cluster configuration. The README frames this as a feature rather than a limitation, pointing out that the modular design means you do not need to import all datasets or run all services. A minimal deployment might use only the OpenStreetMap importer and the API and Placeholder services.

For teams who want Pelias capabilities without operating the infrastructure, Geocode Earth provides a managed API service running the full Pelias stack. This is the same organisation that maintains the Pelias open-source project.

Special-Purpose Services: Libpostal and Interpolation

Two of Pelias's frontend services address specific limitations of naive geocoding approaches.

The Libpostal service handles address parsing using machine learning. Addresses in different countries follow different conventions; in some countries the house number comes before the street name, in others it follows. Some addresses include floor numbers, building names, or administrative subdivisions that standard string splitting cannot handle correctly. Libpostal, the underlying library, was trained on hundreds of millions of addresses from around the world and is widely used in geocoding projects. Pelias wraps it in a Go HTTP service, built by the Who's on First team, to make it available to the rest of the system.

The Interpolation service addresses the gap between known addresses and the full address space. Address datasets are never complete. A street may have every even house number recorded but no odd numbers, or vice versa. The Interpolation service stores knowledge about streets and addresses and uses it to generate reasonably accurate estimated locations for addresses that are not directly in Elasticsearch. This allows Pelias to return a useful result for an address that no importer has explicitly recorded, as long as adjacent addresses are known.

Neither of these services is required for a basic Pelias deployment, but both improve result quality for address-heavy use cases.

Pelias Compared to Nominatim

Nominatim is the geocoder that powers OpenStreetMap's own search at nominatim.openstreetmap.org. It is also open source and self-hostable. The primary difference in approach is the underlying database: Nominatim uses PostgreSQL with the PostGIS extension, while Pelias uses Elasticsearch.

This has practical implications. Elasticsearch is better suited to fuzzy full-text search and autocomplete queries at scale. PostgreSQL with PostGIS handles complex spatial queries and relational data more naturally. Nominatim is limited to OpenStreetMap data only; Pelias can combine OpenStreetMap, OpenAddresses, Geonames, Who's on First, and custom CSV data in the same search index. For a deployment that needs to search across multiple data sources simultaneously, Pelias has a structural advantage. For a deployment that needs only OpenStreetMap data and already runs PostgreSQL, Nominatim may be simpler to operate.

Pelias requires Elasticsearch as an external dependency, which adds infrastructure cost and operational complexity. Nominatim requires PostgreSQL with PostGIS, which is a more common infrastructure component in many organisations. Both projects support multilingual queries, reverse geocoding, and self-hosting.

Editorial conclusion

Teams building applications that require self-hosted geocoding with full control over the underlying data should evaluate Pelias. It covers addresses, venues, cities, and administrative areas from OpenStreetMap, OpenAddresses, Geonames, and Who's on First. The deployment complexity is high: six official data importers, five frontend services, and an Elasticsearch cluster must all run together. Teams who need a managed service can use Geocode Earth, which runs the same Pelias stack. Verify Elasticsearch version compatibility before deployment; the README states that versions 7 and 8 are currently supported.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. pelias/pelias on GitHub
4. Project website
5. README