Mailwoman
 | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Authors: | Teffen Ellis, Sister Software (sister-software/mailwoman/graphs/contributors GitHub) | |||||||||||||||||||
| License: | AGPL-3.0-only or commercial (free of charge) | |||||||||||||||||||
| Platform: | Cross-platform | |||||||||||||||||||
| Status: | Active | |||||||||||||||||||
| Version: | 10.8.0 releases (2026-11-04) | |||||||||||||||||||
| Language: | multiple languages
| |||||||||||||||||||
| Website: | mailwoman.post / demo: mailwoman.post/demo | |||||||||||||||||||
| Source code: | sister-software/mailwoman GitHub | |||||||||||||||||||
| Programming languages: | TypeScript and Rust | |||||||||||||||||||
|
Address parser and geocoder that runs in Node.js and the browser | ||||||||||||||||||||
| ||||||||||||||||||||
Mailwoman is an open source address parser and geocoder. It splits a free-text postal address into components (house number, street, locality, region, postcode, country, …) and resolves them to coordinates. It runs in Node.js and in the browser, and stores its gazetteer in SQLite files instead of a PostgreSQL or Elasticsearch cluster.
Mailwoman began as a fork of the Pelias Parser. It is developed by Teffen Ellis of Sister Software.
How it works
Mailwoman has two parts:
- Parser. A small transformer encoder (about 30 MB) scores each token of the input, and a Viterbi decoder picks the most likely consistent sequence of labels (street, locality, postcode and so on). It is a token classifier, not a generative language model. Gazetteer matches are passed to the model as extra input features, and the output includes a confidence value for each component.
- Resolver. The parsed components are matched against a Who's On First gazetteer to find administrative places and postcodes, then against address-point layers for street or rooftop coordinates where one is installed.
Worldwide model, per-country address systems
One model is trained on addresses from around the world instead of one model per country. Its training corpus holds rows from about 200 countries and territories, and the gazetteer covers 248 of the 250 jurisdictions the project tracks. Chinese, Japanese and Korean addresses use a separate character-level model.
Before the model runs, Mailwoman looks at the structure of the input (script, segmentation, postcode patterns and other known formats) to detect which country's address system it probably follows. Per-country reference data for 197 countries, derived largely from Google's libaddressinput, records each system's postcode syntax and component order, and for some countries the official street-type abbreviations. A postcode's form narrows the candidate countries, and the same data formats parsed addresses back into each country's postal layout.
Coverage and accuracy differ by country. The project publishes a per-jurisdiction coverage table listing training rows, gazetteer places and evaluation results for each one.
Data sources
Mailwoman keeps the software separate from the data it loads, and the operator chooses which sources to install. Each database records its source, license and build date, and each result names the source its coordinate came from.
- Administrative places and postcodes come from Who's On First and Overture Maps divisions.
- Street and rooftop coordinates come from address-point layers. These can be built from official address registers, such as France's Base Adresse Nationale, Australia's G-NAF and New Zealand's LINZ data, from OpenAddresses, or from OpenStreetMap.
OpenStreetMap
OSM is a supported source for address points. The @mailwoman/osm package reads a Geofabrik .osm.pbf extract and builds a per-country database of addr:housenumber points (nodes and building centroids). Optionally, points with no addr:street can take the name of a named highway within a short radius (30 m by default). The user builds this database locally; the project publishes no prebuilt OSM address database. The result is a derivative database under the Open Database License. Operators who cannot accept share-alike terms can configure Mailwoman to refuse to start while an OSM database is installed.
The parser's training corpus also includes addresses extracted from OSM. Those extracts are published under the ODbL.
When a result's coordinate comes from an OSM layer, the HTTP servers include "© OpenStreetMap contributors" and a link to the copyright page in that result, so a client can show the attribution. Operators of a public service built on an OSM layer must follow the ODbL and the OSMF Geocoding Guideline.
HTTP servers
Mailwoman includes servers that accept the same requests as other geocoders, so existing clients can switch by changing the base URL:
| Package | Compatible with | Endpoints |
|---|---|---|
@mailwoman/nominatim |
Nominatim | /search, /reverse, /status
|
@mailwoman/photon |
Photon | /api, /reverse (GeoJSON)
|
@mailwoman/libpostal |
libpostal REST | /parse, /expand
|
@mailwoman/api |
Mailwoman's own API | /v1/parse, /v1/geocode, /v1/batch, /v1/resolve
|
Each server publishes an OpenAPI 3.1 description. The Photon-compatible server accepts the osm_tag and layer filters, and the Nominatim-compatible server accepts countrycodes and structured queries. A hosted Photon-compatible endpoint for evaluation runs at https://photon.mailwoman.post, with conservative rate limits.
Usage
Parse an address from the command line:
npx mailwoman parse "1600 Amphitheatre Parkway, Mountain View, CA 94043"
Run a local Nominatim-compatible server after downloading the gazetteer:
npx mailwoman data pull candidate
npx @mailwoman/nominatim serve
Mailwoman requires Node.js 24.18 or later. Installation and library use are documented at mailwoman.post.
Mailwoman also ships an MCP server, @mailwoman/mcp, that exposes parsing, geocoding and point-of-interest search to AI agents, and can render a point-of-interest query as an Overpass query.
License
The code is available under the AGPL-3.0-only license or under a separate commercial license. Data that Mailwoman loads keeps its own license; see Data sources.