Data products
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.' travels with the npm package. The reference data does not, because the smallest useful 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. is 2.9 GB and a registry tarball that size would be paid for by every consumer who wanted only the parser. So the data is a separate download, pulled once and kept.
mailwoman data pull fetches it. The table below is the whole published set, read from the command's
own registry when this page is built, and the command exits with an error and lists the same names if
you name anything else.
What you can pull today
| Bundle | Size | Files | What it covers |
|---|---|---|---|
candidate | 2.9 GB | 1 | Global admin candidate gazetteer — population-first place resolution + postcode coverage across 244 countries. |
poi | 3.9 GB | 1 | Overture-places POI layer, covering the United States, Canada, Mexico and France. |
fr | 7 GB | 1 | French national rooftop address-point database (BAN), with situs points only and no interpolation tier. |
us | 41.3 GB | 103 | US national street tier — per-state rooftop address-point (situs) and TIGER interpolation databases. Use --only <slug> to pull a single state. |
The us bundleevidence bundleThe pair of retrieval-augmented input channels (street-type + locality-surface) that feed lexicon membership as soft per-token evidence alongside the text. Shipped in 6.7.0; trained natively from step 0 in the from-scratch base line. is 103 files, so pull the states you serve rather than the
tier: mailwoman data pull us --only nh. Every size above is summed from the registered artifacts,
and mailwoman data pull <bundle> --dry-run prints the same figures without touching the network.
As served
The registry states what the command expects. The table below lists what the bucket served on the date it was measured, from a committed snapshot that a repository check compares against the registry, so the two cannot drift apart without a build failing.
| Bundle | Served | Tier | Database license | Artifact's own expression |
|---|---|---|---|---|
candidate | 2.9 GB | unmeasured for 1 of 1 files | unmeasured | unmeasured for 1 of 1 files |
poi | 3.9 GB | unmeasured for 1 of 1 files | unmeasured | unmeasured for 1 of 1 files |
fr | 7 GB | unmeasured for 1 of 1 files | unmeasured | unmeasured for 1 of 1 files |
us | 41.3 GB | unmeasured for 103 of 103 files | unmeasured | unmeasured for 103 of 103 files |
Measured against https://public.mailwoman.ai/mailwoman/. Served is the content-length the bucket reported. Tier and expression are read from each artifact's own layer_manifest on a host holding the published file, and unmeasured means no such host ran the snapshot. The database license is the license on the database as a whole, which ODbL grants separately from rights in the contents, and it is unmeasured until an artifact records one.
What you build yourself
Everything else on the shelf is a local build, and three cases are listed here because people ask for them by name.
The 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 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. needs. Not a published bundleevidence bundleThe pair of retrieval-augmented input channels (street-type + locality-surface) that feed lexicon membership as soft per-token evidence alongside the text. Shipped in 6.7.0; trained natively from step 0 in the from-scratch base line., and not the
candidate 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. above — a separate build carrying the place_bbox R*TreeR*TreeSQLite's spatial index of bounding boxes, enabling fast geographic range and nearest-neighbor queries in the resolver.. It is hours of work
and tens of gigabytes of source data.
Timezone, NUTS and UN/LOCODE lookups. @mailwoman/timezone-lookup, @mailwoman/nuts-lookup and
@mailwoman/un-locode-lookup publish code to npm and build their own databases locally. No bundleevidence bundleThe pair of retrieval-augmented input channels (street-type + locality-surface) that feed lexicon membership as soft per-token evidence alongside the text. Shipped in 6.7.0; trained natively from step 0 in the from-scratch base line. in
the bucket serves them.
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. rooftoprooftopGeocoding precision at the building or parcel level — coordinates within a few meters — the highest tier of the geocode cascade. Sourced from address-point and situs data. databases. Built, and deliberately unpublished — ODbL is share-alike on a derived database, and no file goes to npm or the bucket until counsel has reviewed how that applies to serving a coordinate from one. Build one and the obligation is yours.
Where the data came from
Every source is recorded with its license at the point it enters the pipelinestaged pipelineMailwoman's runtime architecture: a sequence of pure-function stages (normalize → query-shape → locale-hint → kind-classifier → phrase-grouper → classifier → decoder) connected by typed handoffs. Each stage is published as its own npm package., and each built
artifact includes an ATTRIBUTION.json naming the source, release and license behind it. Two items
matter to a review and are stated in full on the compliance page. The 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. rooftoprooftopGeocoding precision at the building or parcel level — coordinates within a few meters — the highest tier of the geocode cascade. Sourced from address-point and situs data.
extractsextractA partial output file of the corpus build, written in Parquet format. The training pipeline streams extracts row by row. in @mailwoman/osm reach no published artifact. The served candidate 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. does contain
a Northern Ireland postcodepostcodeThe country-specific postcode (US ZIP, French code postal, etc.). Mailwoman handles postcode parsing entirely by rule classifier — a regex problem, not an ML one. fold derived from 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. under ODbL, 4,757 places measured
2026-09-27, and what ODbL asks of that is with counsel. And one source's license is recorded
inconsistently in our own files, so attribute 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. until that is settled.
Data provenance on the compliance page, and the provenance record that records the measurement.
When it changes
No cadence is committed. Artifacts are rebuilt when 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. changes or an ingest bug is fixed, rather than on a schedule, and this is the one to plan against: do not build a pipelinestaged pipelineMailwoman's runtime architecture: a sequence of pure-function stages (normalize → query-shape → locale-hint → kind-classifier → phrase-grouper → classifier → decoder) connected by typed handoffs. Each stage is published as its own npm package. that assumes a weekly or a monthly artifact.
What you get instead is that each artifact is sealed and dated, and the vintage travels in the remote
path, so you can always tell which build you are running without downloading anything. A new build is
a new path. The new path arrives in a new release of the mailwoman package.