The pelias/pelias repository is a project hub, not a geocoder
Pelias is a modular open-source geocoder using Elasticsearch.
At a glance
- What is it?
- The description calls this a modular open source geocoder, yet the tree holds no service code. The API, the importers and the reverse geocoding pieces each live in sibling repositories, and the one Dockerfile here previews the documentation site.
- Who is it for?
- Treat this repository as a map, not as software. Everything that runs a query lives elsewhere, the documentation stops one word into its dependency list, and no releases mark which builds belong together, so an adopter has to assemble a coherent set from the component repositories and verify the Elasticsearch version against pelias-schema before trusting results.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 121 days ago.
- What is it written in?
- Mainly Twig, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 22, 2026, and from our analysis. They are not legal advice.
Star history
- pelias/pelias3,608 ★ · +16
| Repository | 2026-09-24 | 2026-11-22 |
|---|---|---|
| pelias/pelias | 3.6k | 3.6k |
16 Stars in the last 59 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The Dockerfile in this repo previews the website, not a geocoder
The description on this repository calls it a modular open source geocoder using Elasticsearch. The tree does not match that description, and matching it is the first thing an evaluator has to do. What sits at the root is a project hub: `.devin/`, `.github/`, `announcements/`, `communication/`, `img/`, `milestones/`, `quarterly_goals/`, `website/`, and a row of Markdown files including `lessons_learned.md`, `fun_facts.md` and `in_code_documentation_guidelines.md`. There is no `src/` directory, no service directory, and no compose file in the listing. The single Dockerfile installs a PHP image, pulls in the Couscous static site generator, and starts a preview server on port 8000. Its own comment redirects anyone looking for a running geocoder:
# This is a Dockerfile to run the Pelias website :)
# For some very awesome Dockerfiles to run Pelias itself,
# see https://github.com/pelias/docker/
FROM composer:latest
RUN composer global require couscous/couscous
RUN ln -s /tmp/vendor/bin/couscous /usr/local/bin
WORKDIR /home/
COPY . .
ENTRYPOINT [ "/usr/local/bin/couscous" ]
CMD [ "preview", "0.0.0.0:8000" ]`_config.yml` and `couscous.yml` at the root are that site generator's configuration, and Twig is the primary language GitHub reports for the repository, which fits a documentation site rather than the search services the overview goes on to describe. Someone who clones pelias/pelias expecting something to query gets a website preview, and the README's Local Installation link points at github.com/pelias/docker for everything else.
Six official importers, two of them fed by the same upstream
There are six officially supported importers, and the six are not six independent upstreams. Two of them read the same source: the OpenStreetMap importer takes nodes, ways and relations, while the Polylines importer takes any data in the Google Polyline format and is described as mainly used for importing roads from OpenStreetMap. Two more overlap on the same record types, since Who's on First supplies admin areas and venues while Geonames supplies admin records and venues. Counted by upstream, the list is OpenStreetMap, OpenAddresses, Who's on First and Geonames, plus a format shim and a generic CSV path. OpenAddresses is the largest of them by volume, described as the hundreds of millions of global addresses collected from various authoritative government sources. The CSV importer is the escape hatch for private data, taking any data in CSV format, which is also the documented route for proprietary records. Support for further datasets is still an open discussion on issue 254 in this repository, and operators are invited to write their own importers for data the official six do not cover rather than waiting for one.
Elasticsearch 7 and 8 only, and a separate tool owns the indices
Elasticsearch does the query heavy lifting, and the supported range fits in one sentence: versions 7 and 8. That range is a real constraint for anyone standing an instance up, because the two major versions differ in cluster and index behaviour, so the choice is a decision rather than a default that the project can make for you. Setting up indices is not left to the operator either. A separate tool, pelias-schema, exists for the job of setting up Elasticsearch indices properly for Pelias, which means the index layout is owned by another repository and versioned apart from the services that read it. The architecture gives a second reason indices cannot hold everything. The API service is described as talking to Elasticsearch or other services as needed, and one of those other services exists because Elasticsearch does not handle relational data very well. Placeholder was built for the relationship between administrative areas, the catch all term the README uses for a city, state, country and anything of that kind. The hierarchy that every result leans on is therefore not in the search index at all.
Reverse geocoding mixes estimated addresses with known ones
Given a coordinate, Pelias returns a list of places near it, and that list comes from more than one mechanism. The PIP service handles the point in polygon work, determining which admin area polygons a given point lies in, which is how a coordinate becomes a country, a region and a city. Those boundaries are real data, and a match means the point genuinely falls inside the shape. The Interpolation service handles everything below that. It knows about addresses and streets, supplements the known addresses that are stored directly in Elasticsearch, and returns what the README calls fairly accurate estimated address results for many more queries than would otherwise be possible. Estimate is the operative word. A house number produced this way was computed between known points instead of read out of a dataset, and nothing in the description of the service marks those answers as a different kind of value from the ones that came out of Elasticsearch. A consumer that stores every reverse geocode result as a verified address is treating two different things as one.
Address parsing runs on a machine learning service from another team
The features list promises easy installation with minimal external dependencies, and the architecture section counts against that promise. A single query can need Elasticsearch, the PIP service for polygons, the Placeholder service for the admin hierarchy, the Interpolation service for estimated addresses, the API service in front, and an address parser. That last piece deserves a second look, because it is not a Pelias component. Pelias uses the libpostal project for parsing addresses using machine learning, and reaches it through a Go service built by the Who's on First team rather than by the people who maintain the geocoder. The parser is the place where a change in an upstream machine learning model changes what Pelias returns, and it sits in the dependency position the features list calls minimal. It is also the only part of the stack whose weight is a model rather than a service, which is part of why the overview gives dependencies a section of their own at the very end.
Release notes in the tree, no releases on the repository
This repository has no GitHub releases. In their place the tree carries a process library: `release-notes.md`, `milestone_template.md`, `milestones/`, `quarterly_goals/`, `lessons_learned.md`, `announcements/`, `communication/`, `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md` and `in_code_documentation_guidelines.md`. That is a deliberate way to run a project, and it has a consequence for anyone assembling the system. Since every service and importer lives in its own repository, a working instance is a set of builds chosen across many repositories, and nothing visible here records which combination belongs together. The counters make this the busiest part of the hub rather than the quietest: 3592 stars, 240 forks and 234 open issues, with the last commit on the default branch `master` dated 2026-07-24. `INSTALL.md` sits at the root, and every install path named in the overview leaves this repository, pointing at github.com/pelias/docker for local runs, a documentation repository, and the hosted webservice at geocode.earth.
The dependency list stops one word into its first sentence
The README ends on the question an operator most wants answered. Its last heading is Dependencies, and underneath the text opens with `These are software projects tha` and stops there. No list follows, so the number of external dependencies that would confirm or contradict the minimal claim in the features list is not written down in the overview. The same gap shows up elsewhere: no API endpoints, no query parameters, no index names and no configuration file paths appear anywhere in it. What the document does give is a component map with every piece linked to its own repository, which explains a distributed system well and substitutes poorly for operating one. A smaller sign of the same looseness sits in the middle of the architecture, where the PIP service is is very good at quickly determining which admin area polygons a given point lies in, with the word is written twice. Licensing is handled more carefully. The code is MIT, and the tree keeps `data_licenses.md` as a separate file, which is the right split for a geocoder whose answers come from imported datasets carrying terms of their own.
Editorial conclusion
Treat this repository as a map, not as software. Everything that runs a query lives elsewhere, the documentation stops one word into its dependency list, and no releases mark which builds belong together, so an adopter has to assemble a coherent set from the component repositories and verify the Elasticsearch version against pelias-schema before trusting results. The estimated addresses from Interpolation are usable as suggestions and should not be stored as verified ones.
Frequently asked questions
Does the pelias/pelias repository contain the Pelias geocoder source code?
No. The tree holds no service directories. The API, Placeholder, PIP, Libpostal and Interpolation services and the six data importers each live in their own repository, and the one Dockerfile here builds the documentation site.
How do you install Pelias from the pelias/pelias repository?
You do not, not from this repository. Its README points Local Installation at github.com/pelias/docker, and the comment in the Dockerfile in this tree says the Dockerfiles that run Pelias itself live there.
Which Elasticsearch versions does Pelias support?
Versions 7 and 8. A separate tool called pelias-schema sets up the Elasticsearch indices that Pelias queries, and it is versioned in its own repository.
Which datasets can Pelias import?
Six officially supported importers: OpenStreetMap nodes, ways and relations; OpenAddresses; Who's on First; Geonames; any data in the Google Polyline format, mainly for OpenStreetMap roads; and arbitrary CSV for custom or proprietary data.
Are reverse geocoding results from Pelias always exact addresses?
Not all of them. The PIP service returns the admin area polygons a point falls inside, while Interpolation returns estimated address results for the many queries that go beyond the known addresses stored directly in Elasticsearch.
Does the pelias/pelias repository publish releases?
No. It has no GitHub releases. The tree carries release-notes.md, milestones/, quarterly_goals/ and milestone_template.md instead, and the last commit on the default branch master is dated 2026-07-24.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/pelias-pelias)Star history chart for your README
[](https://hysenlabs.com/projects/pelias-pelias)Was this useful?