Overview
Mailwoman is an address parser and geocoder that runs inside your own process. npm install puts a
39.4 MB 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.' file on your disk. After that, a parseaddress 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 function call that makes no network request.
Mailwoman reads an address and places it in two separate passes. Each pass becomes available at a different time. 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.' reads a string and returns tagged components, each with a confidence score. A second pass places those components on the map using a 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. database that you download once and keep. Mailwoman requires no account and no API key, and it does not meter usage, because no call reaches a server of ours.
What it does
The same install supports 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., forward and 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., autocomplete, validation, record matching and annotations. Each featurefeatureAn input signal a model conditions on. Beyond the raw tokens, Mailwoman feeds soft features — gazetteer-membership channels and the postcode anchor — that inform predictions without overriding them. has a page that runs it end to end.
What it costs to install
A full install of the entry package plus the English weightsparameterA 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. is 707 MB, and the ONNX runtimeONNX (Open Neural Network Exchange). An open format for machine learning models that enables interoperability between training frameworks and inference runtimes. Mailwoman ships its trained model as an ONNX file so it can run in Node.js and the browser via onnxruntime. accounts for 523 MB of that. 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.' inside it is 39.4 MB. The geocoder adds a 2.88 GB 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, so you decide on it separately. Each figure is published with the command that produced it, as is each accuracy number on Benchmarks.
Where it runs
Mailwoman runs as a Node library, in a container, on a serverless instance, in a browser tab, or as an MCP server that an agent talks to over stdio. The shapes differ in what has to be resident and what each one gives up.
What it can stand in for
Three servers answer on the request and response shapes Nominatim, Photon and libpostallibpostalAn open-source C address parser used by Pelias. Mailwoman's rule-based v0 and neural classifier supersede it. clients already send, so an existing client moves with a base-URL change.
One parse, start to finish
With the packages installed, this is the whole round trip:
npx mailwoman parse "350 5th Ave, New York, NY 10118"
{
"region": "NY",
"locality": "New York",
"street": "5th",
"house_number": "350",
"street_suffix": "Ave",
"postcode": "10118"
}
That command opened no socket. The same call from the library returns the tree behind this flattened view, with a spanspanA contiguous range of characters or tokens in the input string, tagged with an address component type (street, locality, postcode, etc.). Parsed addresses are represented as collections of spans, possibly nested in a tree. and a confidence score for each component.
What it is not
Mailwoman is not a hosted service or an authoritative registerinput modeThe Decision-A register switch: 'fragmented' (human-typed fragments — feeds the evidence channels) vs 'formatted' (complete records — runs the trained absence identity). Explicit on CLI/API; per-endpoint defaults (batch→formatted, autocomplete→fragmented); kind-derived otherwise. of delivery points. It reads the string you give it and matches what it can against open data. It can tell you that a string looks like an address in Manhattan and where that address is. It cannot tell you that mail arrives there. What Mailwoman is has the full shape of that boundary.