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, and 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. after that is a function call with no network in it.
Reading an address and placing it are two passes, and they become available at different times. 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: it takes a string and returns tagged components with a confidence score on each. Placing those components on the map is a second pass over 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 you download once and keep. There is no account, no API key and no meter, because there is nothing on our side of the call to meter.
What it does
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 matchingrecord matchingThe process of determining whether two database records refer to the same real-world entity. Mailwoman's matcher uses a geocode-first approach (match the resolved place, not the address string) with Fellegi-Sunter probabilistic scoring. and annotations run from the same install. Each one has a page that runs it end to end.
What it costs to carry
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 523 MB of that is 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. rather than anything of ours. 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. Geocoding adds a 1.65 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, which is why it is a second decision rather than part of the first. Every figure is stated with the command that produced it, and so is every accuracy number on Benchmarks.
Where it runs
A Node library, a container, a serverless instance, a browser tab, or an MCP server 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 per component.
What it is not
It is not a hosted service, and it is not 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 hand it and matches what it can against open data, so it will tell you that a string looks like an address in Manhattan and where that is — it will not tell you that mail arrives there. What Mailwoman is has the full shape of that boundary.