Switching from Pelias

Pelias is the modular, self-hosted geocoder — importers for OSMOpenStreetMap (OSM). A community-curated global map database (ODbL-licensed) with addr:* tagged features and place hierarchies. A secondary corpus source and a source of street names., OpenAddressesOpenAddresses (OA). A global open aggregation of address points collected from many official sources. A primary source of component-supervised training data outside proprietary registries., Who's On FirstWOF (Who's On First). An open-source gazetteer of places maintained by Mapzen/whosonfirst. Mailwoman builds a custom SQLite database from WOF GeoJSON repos, extended with postcode data, importance scores, and coincident-role relations., and more, feeding an Elasticsearch cluster. It's capable and it's a lot to operate: the cluster, the importers, the gigabytes, the analysis chain you tune by hand.

Mailwoman keeps the parts you wanted from PeliasPeliasAn open-source geocoder, Mailwoman's spiritual predecessor. — self-hosted, open data, hierarchy-aware — and drops the cluster. The hierarchy lives in SQLite (a Who's On FirstWOF (Who's On First). An open-source gazetteer of places maintained by Mapzen/whosonfirst. Mailwoman builds a custom SQLite database from WOF GeoJSON repos, extended with postcode data, importance scores, and coincident-role relations. ancestors table), and a calibrated neural modelneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.' does the work the analysis chain did with rules.

Mapping the move

PeliasPeliasAn open-source geocoder, Mailwoman's spiritual predecessor. has its own /v1 response envelope, and Mailwoman does not ship a /v1-compatible package today. The migration is by capability rather than by drop-in:

PeliasPeliasAn open-source geocoder, Mailwoman's spiritual predecessor.	Mailwoman
/v1/search	@mailwoman/nominatim /search (structured)
/v1/reverse	@mailwoman/nominatim /reverse
/v1/autocomplete	@mailwoman/photon /api
structured parsingaddress parsingThe process of decomposing a free-text postal address string into structured components — house number, street name, locality, region, postcode, and country — so a geocoder can resolve them to coordinates.	@mailwoman/libpostal /parse

npx @mailwoman/nominatim serve   # structured search + reverse, with annotations
npx @mailwoman/photon serve      # autocomplete (GeoJSON)

What's different

• No Elasticsearch, no import pipelinestaged pipelineMailwoman's runtime architecture: a sequence of pure-function stages (normalize → query-shape → locale-gate → kind-classifier → phrase-grouper → classifier → decoder) connected by typed handoffs. Each stage is published as its own npm package.. One SQLite gazetteergazetteerA geographical index that maps place names and postcodes to real-world coordinates. Mailwoman uses a custom-built Who's On First (WOF) SQLite database as its gazetteer — the 'atlas' half of the grammar/atlas architecture. instead of a cluster you feed.
• A modelneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.', not an analysis chain. Parsingaddress parsingThe process of decomposing a free-text postal address string into structured components — house number, street name, locality, region, postcode, and country — so a geocoder can resolve them to coordinates. is a calibrated neural tagger, so you get a confidence you can route on — and an OpenCage-style annotations block PeliasPeliasAn open-source geocoder, Mailwoman's spiritual predecessor. doesn't produce.

What's missing

• No /v1 envelope yet. If your client is hard-wired to PeliasPeliasAn open-source geocoder, Mailwoman's spiritual predecessor.'s exact response, you'll adapt it to the Nominatim / Photon shapes (or a /v1 adapter is a reasonable contribution).
• CoveragecoverageThe fraction of a population or region for which a data source has real, non-placeholder entries — e.g. 47% rooftop coverage on Texas addresses. Distinct from accuracy on the rows that are present. and ranking are their own long roads; PeliasPeliasAn open-source geocoder, Mailwoman's spiritual predecessor.'s mature importer set still wins in places.

See how Mailwoman compares for the capability matrix.