Drop-in replacements
A drop-in is a server that speaks a request and response shape your client already sends, running on your hardware against your data. Moving a client is a base-URL change rather than a rewrite, and each server keeps its original's error shape rather than substituting ours, because a client written against the original parsesaddress 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. that shape.
Three shapes ship today.
Nominatim
/search, /reverse and /status, with /lookup routed but answering 501. Results carry an
OpenCage-style annotations block the original does not have.
npx @mailwoman/nominatim serve
Photon
/api and /reverse, answering GeoJSON FeatureCollections. Failures come back as an empty
collection carrying a message, so a client iterating features needs no new branch.
npx @mailwoman/photon serve
libpostal
/parse and /expand, over GET or POST. This is the one that needs no 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. at all — the
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.' arrives as a package dependency, so it starts on a machine that has downloaded nothing.
npx @mailwoman/libpostal serve
What each one honors
Compatibility is not the same as equivalence, and the difference is worth reading before you cut over. Every request parameterparameterA single learned number inside a model — one weight or bias. Mailwoman's encoder has roughly 30 million of them; training is the search for good values. on all three surfaces carries one of three verdicts — honored, accepted with no effect, or not read — and the tables that assign them are on the swap tutorial, one per surface. They are read off the route handlers and then checked against a running server.
The shape of what they say: free-text and structured field queries are honored, and countrycountryThe top-level address component (an ISO country). Closed-vocabulary, so it is best handled by a deterministic matcher feeding a proposal rather than a retrained model head.
restriction is a hard filter. Language and category parametersparameterA single learned number inside a model — one weight or bias. Mailwoman's encoder has roughly 30 million of them; training is the search for good values. are accepted and change nothing, so a
client sending them gets a valid unfiltered answer rather than an error. Bounding-box parametersparameterA single learned number inside a model — one weight or bias. Mailwoman's encoder has roughly 30 million of them; training is the search for good values. are
not read at all. And nothing here is keyed to an OpenStreetMapOpenStreetMap (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. object, so osm_id and osm_type are
never set.
Two things to settle before you cut over
Forward geocodinggeocodingThe process of converting an address into geographic coordinates (latitude and longitude). Mailwoman geocodes in a multi-tier cascade: exact address-point match → street interpolation → locality centroid. Each tier is progressively coarser but more widely available. works from the 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. download; reverse geocodinggeocodingThe process of converting an address into geographic coordinates (latitude and longitude). Mailwoman geocodes in a multi-tier cascade: exact address-point match → street interpolation → locality centroid. Each tier is progressively coarser but more widely available. does not. /reverse on
the Nominatim and Photon shapes runs point-in-polygon over a full WOFWOF (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. distribution that
mailwoman data pull does not ship, so it answers an empty result until you build one and put it
there.
There is no authentication in front of any of them, and each binds 0.0.0.0 by default. Bind
127.0.0.1 or put the server behind your own ingress before it reaches anything shared.
Ports and packages
| Shape | Package | Command | Default port |
|---|---|---|---|
| Nominatim | @mailwoman/nominatim | nominatim serve | 8080 |
| Photon | @mailwoman/photon | photon serve | 2322 |
| libpostallibpostalAn open-source C address parser used by Pelias. Mailwoman's rule-based v0 and neural classifier supersede it. | @mailwoman/libpostal | libpostal serve | 8081 |
Each server also serves its own OpenAPI document at /openapi.json. The endpoint tables, query
parametersparameterA single learned number inside a model — one weight or bias. Mailwoman's encoder has roughly 30 million of them; training is the search for good values. and error bodies are on HTTP APIs.