Build the planet

"Planet 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." for a geocoder is two claims, and they come apart. One is that every place on Earth resolves to a coordinate; that one is answered globally by a single 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.. The other is that a house number resolves to a building; that one is answered 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. by 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., and today it is answered for two countries. By the end of this page you'll have built streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels.-level 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. for one regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. of France twice — once from the French government's address 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., once 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. — geocoded the same address against both, and seen which answers it. About twenty minutes of work plus a 1.65 GB download.

You will also know which countries you could repeat it for and which have no path at all. The status page answers that question in terms of parser localeslocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for.; this page answers it in terms of data.

Prerequisites

This page forks partway through, and it is a packaging fork rather than a preference. Steps 1 and 2 run entirely from npm. Step 3 does not: @mailwoman/osm is not published to npm, so that section needs a repository checkout. Each requirement below says which half it belongs to.

• About 2 GB of free disk for the path below: 1.65 GB of 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. and under 100 MB of everything else. Adding France's whole national 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. instead of three départements is 6.95 GB; adding the US is 41.3 GB. Check the number for the 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. you want before you start it.

• Steps 1–2, from npm. The CLI, plus the French 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.'s builder:

  npm install mailwoman @mailwoman/neural @mailwoman/neural-weights-en-us
  npm install @mailwoman/resolver @mailwoman/resolver-wof-sqlite @mailwoman/ban

• Step 3, from a checkout. @mailwoman/osm has no npm package, so npm install @mailwoman/osm answers E404. Step 3 restates this where you hit it, along with the clone and build it needs.

• GDAL on your PATH, for step 3 only — ogr2ogr --version should answer. Steps 1 and 2 do not touch it.

• A data root, and the willingness to keep it:

  export MAILWOMAN_DATA_ROOT=/tmp/mw-planet
  mkdir -p "$MAILWOMAN_DATA_ROOT"

Building the US tier is a different shape from everything below, because the US is the one 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. with both 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. 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. and a national streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels.-segmentsegmentA punctuation-bounded chunk of the normalized input — the comma-separated parts of 'Portland, OR' — used to give downstream stages structural context. file. It has its own page: Build the US address dataset.

What "the planet" is here

One 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 global and the rest are per 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., which is the split that makes "planet" two claims instead of one.

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.	Scope	Published today
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.	244 countries, one database	candidate.db, 1.65 GB
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. address pointssitus dataA dataset of exact address-point coordinates (rooftop-level). Mailwoman's geocoder uses a national situs layer (124.9M US points built from state address-point sources) as the highest-precision tier of the geocode cascade.	Per 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.	US (30.3 GB, 52 shardsshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row.) and France (6.95 GB, 1 shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row.)
StreetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. 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.	Per 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.	US only (11.0 GB, 51 shardsshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row.)
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.	Per 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.	US, Canada, Mexico, France in one 3.89 GB 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.

That is the complete published set — mailwoman data pull offers four bundlesevidence 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 no others. Everything else on this page you build yourself.

The 244 comes from the three source lists 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. build unions, and you can read them off the defaults it ships with: 12 countries served from 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. repositories, 85 from Overture divisions, 161 from GeoNamesGeoNamesA free global gazetteer combining administrative, postal, and POI data across 200+ countries. Supplements Who's On First for postcode centroids and places where WOF has gaps., and 244 distinct countries between them. 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. at that 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. means the 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., regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. and localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighborhood in the hierarchy. resolve — not that a streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. does.

1. Get the global gazetteer

npx mailwoman data pull candidate

▸ pull https://public.sister.software/mailwoman/gazetteer/2026-07-07a/candidate.db (~1652.9 MB) → /tmp/mw-planet/wof/candidate.db

export MAILWOMAN_CANDIDATE_DB=/tmp/mw-planet/wof/candidate.db
✓ candidate: gazetteer/2026-07-07a/candidate.db: content-length verified (1652.9 MB) → /tmp/mw-planet/wof/candidate.db
PASS (1/1 checks)

Four minutes for 1.65 GB here. The export line is a leftover the pull still prints; the file landed at <data root>/wof/candidate.db and is found there without it. Take the download unless you have a reason not to, because the build behind it is the heaviest thing in this repository, and this page does not run it. What it involves, so you can price it:

# 1. Clone the Who's On First data repositories. 823 non-archived repos in the org
#    on 2026-08-03; `--repos` narrows it to the countries you need.
npx mailwoman gazetteer inspect sync "$MAILWOMAN_DATA_ROOT/wof/repos" \
  --repos whosonfirst-data-admin-fr,whosonfirst-data-postalcode-fr

# 2. Build the admin database. Reads the repos above, streams Overture divisions
#    from S3, folds GeoNames dumps you have already downloaded.
npx mailwoman gazetteer build admin

# 3. Derive the query-time gazetteer from it.
npx mailwoman gazetteer build candidate

Step 2 runs nine stagesstageOne of the dataflow stages in the runtime pipeline (normalize, locale gate, kind classify, phrase group, token classify, sequence correct, reconcile, resolve). Distinct from tier (model vocabulary) and phase (plan milestone). in order — ingest-wof, fold-overture, fold-geonames, freeze, enrich, VACUUM INTO, fts, verify, seal — and a failed verify throws and leaves the artifact unsealed instead of shipping it. Step 3 folds the GeoNamesGeoNamesA free global gazetteer combining administrative, postal, and POI data across 200+ countries. Supplements Who's On First for postcode centroids and places where WOF has gaps. alias tail in and compresses the result into the byte-range-friendly candidate table.

Budget disk for two databases, not one, because step 3 reads what step 2 wrote. The sizes are from the maintainer build host, not from a run on this page: the admin database there, built 2026-08-02, measures 5,275,287,552 bytes; the published candidate database is 1,652,916,224 bytes, which is a little under a third of it.

Two things about the sync command before you run it. It shells out to gh repo list, so the GitHub CLI has to be installed and authenticated. And its own source comment estimates "~100 whosonfirst-data repos … ~2.9 GB of git" — the organization holds 823 non-archived repositories today, so pass --repos and size against what you asked for.

2. Add a country with a national register

France publishes the Base Adresse Nationale — 26 million addresses under the Licence Ouverte 2.0, which asks for attribution and imposes no share-alike. That makes it the same licensing shape as the permissive core, and it is why France is the one non-US 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. with a published shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row..

Take three départements, not the whole 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., so the step finishes while you watchnamed watchA known below-target reading recorded at ship with an owner and a retirement condition — never a silent waiver. Example: fr.cedex shipped at 83.3 under the waived floor, named, and retired when the from-scratch base read 90.5.:

mkdir -p "$MAILWOMAN_DATA_ROOT/ban/sources"
for d in 48 2A 05; do
  curl -sL -o "$MAILWOMAN_DATA_ROOT/ban/sources/adresses-$d.csv.gz" \
    "https://adresse.data.gouv.fr/data/ban/adresses/latest/csv/adresses-$d.csv.gz"
done

7.3 MB of gzipped CSV. Then build:

node node_modules/@mailwoman/ban/out/scripts/build-address-point-shard.js \
  --csv-dir "$MAILWOMAN_DATA_ROOT/ban/sources" --depts 48,2A,05 \
  --release 2026-08-03 --out "$MAILWOMAN_DATA_ROOT/ban/address-points-fr-sample.db"

[ban] building fr rooftop shard from 3 départements in /tmp/mw-planet/ban/sources
[ban]   dept 05: 81,258 cumulative
[ban]   dept 2A: 138,573 cumulative
[ban]   dept 48: 200,406 cumulative
[ban] indexing…
[ban] DONE /tmp/mw-planet/ban/address-points-fr-sample.db
      départements                     : 3
      total source rows                : 200,406
      written points                   : 200,406
      skipped (no street/number)       : 0
      bytes                            : 53,411,840
      md5                              : 765cacaaaf1cc224530117a6d1d1a991
      source                           : ban:fr  release=2026-08-03  license=Licence Ouverte / Open Licence 2.0 (Etalab)

6.84 s, 200,406 points, and zero rows skipped: every row in these three départements carries both a streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. and a number, which is what a government 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. buys you and what step 3 does not have. The build streams the CSV instead of loading it, so the national set is the same command with a longer file list — 26 million rows, and 6.95 GB in the published shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row..

Two things about that invocation. It is a script inside the installed package, not a mailwoman subcommand — there is no mailwoman ban group, the fetch is a curl against a documented URL pattern, and the build is the script above. And the path is a node_modules path because @mailwoman/ban is on npm; if you are working from a checkout instead, the same file is at ban/out/scripts/build-address-point-shard.js after yarn compile.

3. Build the same ground from OpenStreetMap

For a 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. with no open 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., 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. is the fallback. Two constraints come before the command, because both of them stop the step rather than complicate it.

The license. OSMOpenStreetMap (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. is ODbL, which is share-alike on a derived database, and a shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. built here is a derived database. Mailwoman publishes no OSMOpenStreetMap (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. shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. to npm, R2 or the demo, and will not until counsel has reviewed how share-alike applies to serving a coordinate from one. If you build one, the obligation is yours and it rides on the file.

The package. The same review keeps the builder off npm too, so this step cannot run from an install the way step 2 did:

npm install @mailwoman/osm

npm error code E404
npm error 404 Not Found - GET https://registry.npmjs.org/@mailwoman%2fosm - Not found
npm error 404
npm error 404  The requested resource '@mailwoman/osm@*' could not be found or you do not have permission to access it.

That is the state today, with no date attached to it — the package is absent from the registry while the license review is open, and this page will not guess when that changes. Until it does, the builder comes from a checkout:

git clone https://github.com/sister-software/mailwoman.git
cd mailwoman && yarn install && yarn compile

The two node osm/out/scripts/... commands in this section run from that checkout's root. Step 4 goes back to the npm CLI and does not care where the shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. was built.

Three countries have a registered streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels.-normalization localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. for this path — fr, de and nl. Adding a fourth means registering the 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. and writing its branch in 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. normalizer in the same commit, which is why the list grows one considered 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. at a time.

Pull an extract and build. The Corsica extract is 34 MB, small enough to finish in seconds:

mkdir -p "$MAILWOMAN_DATA_ROOT/osm/geofabrik"
curl -sL -o "$MAILWOMAN_DATA_ROOT/osm/geofabrik/corse-260803.osm.pbf" \
  "https://download.geofabrik.de/europe/france/corse-latest.osm.pbf"

node osm/out/scripts/build-rooftop-shard.js \
  --country fr --slug corse --release 260803 \
  --pbf "$MAILWOMAN_DATA_ROOT/osm/geofabrik/corse-260803.osm.pbf"

[osm] building fr/corse rooftop shard from /tmp/mw-planet/osm/geofabrik/corse-260803.osm.pbf
[osm] indexing…
[osm] DONE /tmp/mw-planet/osm/address-points-fr-corse.db
      total addr:housenumber features : 15,774
      written total                    : 8,674  (of which recovered: 0)
      skipped (no addr:street)         : 7,100  (45.0% raw association gap)
      skipped (bad coord)              : 0
      source                           : openstreetmap:fr  release=260803  recover=false

2.41 s, and the skipped line is the one to read. 7,100 of 15,774 house-number featuresfeatureAn 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. carry no addr:street, so 45.0% of the data is unqueryable as an address. The build counts them instead of inventing a streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels., and that count is the input to the fix: rerun with --recover and the builder attaches each orphan to the nearest named highway within 30 m.

node osm/out/scripts/build-rooftop-shard.js \
  --country fr --slug corse --release 260803 --recover \
  --pbf "$MAILWOMAN_DATA_ROOT/osm/geofabrik/corse-260803.osm.pbf"

[osm] recovery index: 369,423 highway vertices (radius 30m)
[osm] building fr/corse rooftop shard from /tmp/mw-planet/osm/geofabrik/corse-260803.osm.pbf
[osm] indexing…
[osm] DONE /tmp/mw-planet/osm/address-points-fr-corse.db
      total addr:housenumber features : 15,774
      written total                    : 14,714  (of which recovered: 6,040)
      skipped (no addr:street)         : 1,060  (6.7% raw association gap)
      skipped (bad coord)              : 0
      source                           : openstreetmap:fr  release=260803  recover=true

3.32 s, 6,040 points recovered, and the gap falls from 45.0% to 6.7%. The recovered rows carry openstreetmap:fr#recovered in their source column rather than openstreetmap:fr, so a consumer that does not trust a geometric guess can filter them out with one predicate.

4. See which one answers

You now hold two shardsshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. over overlapping ground. Ask both for the same address — --address-points-db points the geocoder at an explicit shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. instead of the per-state US convention:

npx mailwoman geocode "12 Cours Napoléon, 20000 Ajaccio" --default-country FR \
  --address-points-db "$MAILWOMAN_DATA_ROOT/ban/address-points-fr-sample.db" --format text

input:            12 Cours Napoléon, 20000 Ajaccio
resolution_tier:  address_point
coordinate:       41.919826, 8.737100
uncertainty_m:    1
locality:         Ajaccio
postcode:         20000
hierarchy:
  locality             Ajaccio [wof:404376035] (41.9346, 8.7005)

npx mailwoman geocode "12 Cours Napoléon, 20000 Ajaccio" --default-country FR \
  --address-points-db "$MAILWOMAN_DATA_ROOT/osm/address-points-fr-corse.db" --format text

input:            12 Cours Napoléon, 20000 Ajaccio
resolution_tier:  admin
coordinate:       41.934571, 8.700510
locality:         Ajaccio
postcode:         20000

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. from the 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., city centroidlocality centroidThe representative center point of a city or locality, used as a coarse coordinate when no exact address point is available — the coarsest tier of the geocode cascade. 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., on the same streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. in the same town. The density behind that is the whole story: the 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. holds 57,315 points for Corse-du-Sud alone against 14,714 for all of Corsica in OSMOpenStreetMap (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., after recovery. This is why 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. consults a national 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. ahead of the OSMOpenStreetMap (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. tier when both are present, and why the ordering is not a preference you tune.

It does not run one way every time. Swap the address for 20 Boulevard Tino Rossi, 20000 Ajaccio, in the same town, and the two swap places:

# register:  resolution_tier: admin
# OSM:       resolution_tier: address_point   coordinate: 41.908027, 8.679581

The 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. files that quay as Quai Port Plaisance Tino Rossi, so the query misses it and falls to the citylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighborhood in the hierarchy.. Neither source contains the other. If you carry both, carry them as tiers with the 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. first rather than merging them into one file.

5. What has no path today

Absence is a claim, so here are the ones worth stating outright.

Great Britain has no open address source in this stack. Overture's addresses theme carries no GB rows at all, which you can confirm in about two minutes. Pass a release that is currently in Overture's bucket rather than the CLI's built-in default, which has aged out of it — the release pin section on the US page has the one-line command that lists what is live. 2026-06-17.0 was live on 2026-08-03:

npx mailwoman gazetteer overture-ingest --countries GB --release 2026-06-17.0

[ingest] GB -> /tmp/mw-planet/overture/2026-06-17.0/addresses-gb.parquet (138s)
[probe] GB: no rows found — check the country code or release
✓ overture ingest: /tmp/mw-planet/overture/2026-06-17.0
  release 2026-06-17.0 · GB · 0 probed

The command succeeds and writes a 532-byte parquetParquetThe open columnar file format the corpus is written and streamed in. The training pipeline reads shards row-by-row from Parquet.: a valid file holding the schema and no rows. That is the shape of a real absence, and it is a different fact from a failed download. Royal Mail's Postcode Address File is not open, so the GB streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. tier is a licensing gap rather than a build anyone can run. 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.-level resolution for GB still works, out of 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..

Korea has no adopted open data path, and that is a data-licensing constraint, not an engineering one. Australia's G-NAFG-NAF (Geocoded National Address File). Australia's authoritative open address register (CC-BY-licensed), used as a training source for Australian addresses. is in the repository, but as 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.-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. adapter (mailwoman gnaf assemble emits labeled JSONL), not a shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. builder — there is no address-points-au to build today. New Hampshire is a hole inside the 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. that does have a tier: its published 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. is 20,480 bytes and holds zero rows, because the state appears in neither Overture nor the OpenAddressesOpenAddresses (OA). A global open aggregation of address points collected from many official sources. A primary source of component-supervised training data outside proprietary registries. set the build falls back to.

Two closing notes on the word "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.". A missing row is not a measured zero, and newer mailwoman artifacts make that distinction structural: the spatial-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. contract 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. follows stores per-cell survey completeness beside the data, so a consumer can tell "surveyed and empty" from "never surveyed". The address shardsshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. on this page predate it and carry no such table, which is why the New Hampshire case above has to be stated in prose. And a localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. claim on the status page is a claim about 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., not about streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels.-level coordinates: France and the US are tier 1 for both, and every other claimed localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. 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. against a coordinate panel while resolving at the admin tier.

What you have now

Two 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. shardsshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. over Corsica built from different sources under different licenses, a global 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. under both of them, and a row count for what each source holds instead of an assumption about it. The same two commands, given a 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. code the normalizer knows and an extract or a 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. dump, produce the next one.

Next

• Build the US address dataset — the one 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. with both 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. 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. and a national streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels.-segmentsegmentA punctuation-bounded chunk of the normalized input — the comma-separated parts of 'Portland, OR' — used to give downstream stages structural context. file, and the fifty-state numbers.
• Improve geocode precision — the published French shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row., downloaded rather than built, and what the four resolution tiers mean.