Locales and tiers
Scope
A localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. is claimed when a coordinate-graded evaluationevalRunning the model against a held-out golden dataset and computing per-component F1, exact-match, calibration, and resolved-coordinate error. exists for it. Trained exposure is not a claim, and neither is a published package. This page states what each tier means, lists the localeslocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. in each, and separately lists what ships per localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for..
Read the two lists as answering different questions. The tier table answers "how well is this
measured". The shipping table answers "what will npm install and mailwoman data pull give me".
They do not line up, and the mismatch is the point.
Tiers are maintained in the scope declaration at
SCOPE.mdx and
reproduced here. The table below is the declaration of 2026-07-02; several packages listed under
What ships postdate it.
Tiers
| Tier | LocaleslocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. | What the tier means |
|---|---|---|
| 1 | US, FR | Per-tag floors gated in the release process, plus real-world evaluationevalRunning the model against a held-out golden dataset and computing per-component F1, exact-match, calibration, and resolved-coordinate error. slices |
| 2 | IT, PT, PL, AT, CZ, DE, AU, BE, ES, NL, CH, HR, DK, FI | Trained, with a per-localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. coordinate panel behind the claim |
| 3 | NO, SE | Trained exposure, thinly measured. Claims beyond the panel are unverified |
| 4 | CZ, PL, SK, SI | Covered by the diacriticdiacriticAn accent mark that modifies a letter (é, ñ, ç). Address normalization must fold diacritics for matching without discarding the information a user typed. tokenizertokenizerThe component that converts a raw address string into a sequence of numeric token IDs the model can process. Mailwoman's tokenizer is a SentencePiece unigram model trained specifically on postal addresses. splice shipped in release 5.1.0 |
| 5 | JP | ResolverresolverThe component that converts parsed address components (locality, region, postcode) into coordinates by looking them up in the gazetteer. The resolver ranks candidates by name match, population, and proximity, and returns the best-matching place with its centroid or polygon. route only: postcodepostcodeThe country-specific postal code (US ZIP, French code postal, etc.). Mailwoman handles postcode parsing entirely by rule classifier — a regex problem, not an ML one. resolution, with no parser trainingtrainingThe process of adjusting a model's parameters so its predictions match labeled examples, by repeatedly measuring error and nudging the weights to reduce it. Distinct from inference, when the trained model is run on new input. claim |
A localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. appearing in two tiers is not an error. Tier 4 records a tokenizertokenizerThe component that converts a raw address string into a sequence of numeric token IDs the model can process. Mailwoman's tokenizer is a SentencePiece unigram model trained specifically on postal addresses. capability rather than an evaluationevalRunning the model against a held-out golden dataset and computing per-component F1, exact-match, calibration, and resolved-coordinate error., so CZ and PL hold both a coordinate panel and a splice.
Tier 1 is the only tier whose numbers gate a release. A regression on US or FR blocks a ship; a regression on a tier-2 localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. is recorded and argued about.
Queued
Queued behind an external constraint rather than an engineering one: GB, IE, SE, HU and RO corpora via 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., which is gated on the share-alike review; and KR, which has no adopted open data path. The constraint on Korean is data licensing. There is no engineering estimate to give, because there is nothing to estimate until a corpuscorpusThe BIO-labeled training data used to train Mailwoman's neural classifier. Assembled from real sources (OpenAddresses, National Address Database) and synthetic shards (boundary stress, order variants, negative space). Managed by @mailwoman/corpus. is available.
What ships
Two things ship per localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for., and they are independent. A 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. package makes the parser localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for.-aware. A data 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. gives the resolverresolverThe component that converts parsed address components (locality, region, postcode) into coordinates by looking them up in the gazetteer. The resolver ranks candidates by name match, population, and proximity, and returns the best-matching place with its centroid or polygon. coordinates to answer with.
Weights packages
Every overlay layerslayerOne transformer block — attention plus a feed-forward network, with normalization and residual connections — applied to every position. Stacking layers lets the model build up richer representations; Mailwoman's encoder has 6. on the en-us encoderencoderThe part of a transformer that turns input tokens into contextualized vector representations. Mailwoman's classifier is a small encoder-only transformer (~30M parameters). rather than replacing it, so a second localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. downloads
localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. data rather than a second 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.'.
| Package | LocalelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. | Postcode anchorsanchor inferenceA technique where structured knowledge (postcode locations, gazetteer place names) is injected into the model as soft input features — not as deterministic overrides. The model still decides the final labels, but the anchor signal biases it toward correct admin tags. | Pair index | LocalelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. 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. index |
|---|---|---|---|---|
@mailwoman/neural-weights-en-us | United States | Yes | Yes | Yes |
@mailwoman/neural-weights-fr-fr | France | Yes | Yes | Yes |
@mailwoman/neural-weights-en-gb | Great Britain | Yes | Yes | Yes |
@mailwoman/neural-weights-en-nz | New Zealand | No | Yes | No |
@mailwoman/neural-weights-de-de | Germany | No | Yes | No |
@mailwoman/neural-weights-es-es | Spain | No | Yes | No |
@mailwoman/neural-weights-it-it | Italy | No | Yes | No |
@mailwoman/neural-weights-en-in | India | No | Yes | No |
en-us is the base and carries 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.', the tokenizertokenizerThe component that converts a raw address string into a sequence of numeric token IDs the model can process. Mailwoman's tokenizer is a SentencePiece unigram model trained specifically on postal addresses., and the calibration tables. The rest carry
localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. data only, so @mailwoman/neural-weights-en-us is installed alongside any of them.
The New Zealand overlay ships no postcode anchoranchor inferenceA technique where structured knowledge (postcode locations, gazetteer place names) is injected into the model as soft input features — not as deterministic overrides. The model still decides the final labels, but the anchor signal biases it toward correct admin tags. table. The encoderencoderThe part of a transformer that turns input tokens into contextualized vector representations. Mailwoman's classifier is a small encoder-only transformer (~30M parameters). is anchor-trained, so New Zealand 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. run with the anchor channel off. That is a declared gap, recorded in the package's model cardmodel cardA JSON metadata file (model-card.json) shipped with each weights bundle. It declares the model version, lineage, label set, required inference channels (anchor, gazetteer), calibration data, and training provenance., not a silent one.
Data bundles
mailwoman data pull <bundle> downloads these. Sizes are the registered artifact totals at headattention headOne of several parallel attention computations in a layer, each free to focus on a different kind of relationship between tokens. Their outputs are concatenated — 'multi-head attention'. Mailwoman uses 4 heads..
| 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. | Covers | Artifacts | Size | Tiers it unlocks |
|---|---|---|---|---|
candidate | 244 countries | 1 | 1.65 GB | admin everywhere |
us | 50 states, DC, and VI | 103 | 41.3 GB | address_point and interpolated |
fr | France | 1 | 6.95 GB | address_point only |
poi | US, CA, MX, FR | 1 | 3.89 GB | POIpoint of interest (POI). A named place that is not strictly an address — landmark, transit stop, venue, amenity, or franchise. Mailwoman tags these as venue and resolves them through the gazetteer. search, not address resolution |
candidate is the one every install needs. It answers on the admin tier globally, which is a
localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighborhood in the hierarchy. or regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. centroid rather than a 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. coordinate.
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 per state: mailwoman data pull us --only nh fetches New Hampshire alone rather
than the full 41.3 GB. The French 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. ships 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. points with no interpolationinterpolationA geocoding technique that estimates a coordinate along a street segment based on the house number range. Used as the middle tier of Mailwoman's geocode cascade when exact address-point data is unavailable. tier, so a French
address whose exact point is absent falls straight through to admin rather than to a house-number
estimate along the streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels..
The US Virgin Islands ship a 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. shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. and no interpolationinterpolationA geocoding technique that estimates a coordinate along a street segment based on the house number range. Used as the middle tier of Mailwoman's geocode cascade when exact address-point data is unavailable. shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row.. That is a data gap, not an omission from this table.
The combination
| LocalelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. | 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. overlay | StreetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. data 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. | Best tier available from published artifacts |
|---|---|---|---|
| United States | Yes | us | address_point |
| France | Yes | fr | address_point |
| Great Britain | Yes | None | admin |
| New Zealand | Yes | None | admin |
| Germany | Yes | None | admin |
| Spain | Yes | None | admin |
| Italy | Yes | None | admin |
| India | Yes | None | admin |
| Everywhere else | None | candidate only | admin |
Two localeslocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. reach a 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. coordinate from published downloads: the United States and France. Every other localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. resolves to an administrative centroid unless you build streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. data yourself — Build the US dataset and Full planet build are those builds.
Canada, Mexico and France have POIpoint of interest (POI). A named place that is not strictly an address — landmark, transit stop, venue, amenity, or franchise. Mailwoman tags these as venue and resolves them through the gazetteer. 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. without a localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. 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. overlay, because the POIpoint of interest (POI). A named place that is not strictly an address — landmark, transit stop, venue, amenity, or franchise. Mailwoman tags these as venue and resolves them through the gazetteer. layerlayerOne transformer block — attention plus a feed-forward network, with normalization and residual connections — applied to every position. Stacking layers lets the model build up richer representations; Mailwoman's encoder has 6. is built from a source that spansspanA 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. countries rather than from per-localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. trainingtrainingThe process of adjusting a model's parameters so its predictions match labeled examples, by repeatedly measuring error and nudging the weights to reduce it. Distinct from inference, when the trained model is run on new input..
Errors
| Condition | Meaning | Next step |
|---|---|---|
Could not resolve @mailwoman/neural-weights-<locale> | No overlay is published for that localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. | Use en-US. The base modelgolden masterThe from-scratch base model every capability comes from in ONE recipe with one provenance and zero named watches at ship — the starting line every fine-tune engagement inherits, with its Fisher artifact beside it. 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. non-tier-1 input at lower accuracy |
Every result comes back on the admin tier | No streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. 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 installed for that 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. | Check the combination table. Only US and FR have published streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. data |
| A Japanese address 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. poorly | There is no Japanese parser claim. The resolverresolverThe component that converts parsed address components (locality, region, postcode) into coordinates by looking them up in the gazetteer. The resolver ranks candidates by name match, population, and proximity, and returns the best-matching place with its centroid or polygon. route is postcodepostcodeThe country-specific postal code (US ZIP, French code postal, etc.). Mailwoman handles postcode parsing entirely by rule classifier — a regex problem, not an ML one.-only | Resolve by postcodepostcodeThe country-specific postal code (US ZIP, French code postal, etc.). Mailwoman handles postcode parsing entirely by rule classifier — a regex problem, not an ML one. |
| A Korean address 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. poorly | No open Korean data path has been adopted | None today. The constraint is licensing, not engineering |
| A tier-2 localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. is worse than the panel suggests | Panels are 1000 rows per localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for., and a slice can be unrepresentative | Report it with the input strings |
Rationale
A tier is a measurement, not a promise, and the levels exist so that "we support this localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for." cannot be said without saying how well it was checked. The alternative — one flat list of supported localeslocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. — makes a localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. with a 1000-row coordinate panel indistinguishable from one that appeared in a trainingtrainingThe process of adjusting a model's parameters so its predictions match labeled examples, by repeatedly measuring error and nudging the weights to reduce it. Distinct from inference, when the trained model is run on new input. mix, and those are not the same product.
Publishing an overlay before its tier moves is deliberate. A pair index is useful to somebody 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. German addresses today whether or not a coordinate panel exists for German, and holding the package back until the evaluationevalRunning the model against a held-out golden dataset and computing per-component F1, exact-match, calibration, and resolved-coordinate error. lands would help nobody. It does mean the two tables on this page disagree, which is why they are two tables.
The queued localeslocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. are queued on licensing rather than on effort. Share-alike terms on a corpuscorpusThe BIO-labeled training data used to train Mailwoman's neural classifier. Assembled from real sources (OpenAddresses, National Address Database) and synthetic shards (boundary stress, order variants, negative space). Managed by @mailwoman/corpus. decide whether a trained 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.' can ship under this project's license, and that question is answered by counsel rather than by a trainingtrainingThe process of adjusting a model's parameters so its predictions match labeled examples, by repeatedly measuring error and nudging the weights to reduce it. Distinct from inference, when the trained model is run on new input. run.
See also
- Packages — installing a localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. overlay.
- Footprints — what each of these downloads costs.
- What ships today — the release these tables describe.
- Keep data fresh — when a 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 superseded.
SCOPE.mdx— where the tiers are maintained.