Skip to main content

Build the US address dataset from public sources

Let's say the hosted shardsshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. are not an option for you — an air-gapped deployment, a license review that wants provenance per row, or a state whose published shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. is stale. By the end of this page you'll have built one state's address data yourself, from Overture's US address slice and Census TIGERTIGERThe US Census Topologically Integrated Geographic Encoding and Referencing database. Used as a corpus source for street-segment data., and geocoded a real streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. address against it at the 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. tier. Vermont takes about half an hour, and 21 minutes of that is one download you make once for all fifty states.

Vermont is the worked example because it is small enough to finish 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. and complete enough to prove the whole ladder. Step 9 gives the numbers for the other 49.

Prerequisites​

Read the first two before you start anything. They are the ones that stop a run partway through.

  • 9 GB of free disk for Vermont. The parts, in decimal GB as your disk vendor counts them: a 6.93 GB national Overture parquetParquetThe open columnar file format the corpus is written and streamed in. The training pipeline reads shards row-by-row from Parquet. you need even for one state (the ingest has no per-state mode), 215 MB of Census TIGERTIGERThe US Census Topologically Integrated Geographic Encoding and Referencing database. Used as a corpus source for street-segment data. archives for Vermont's 14 counties, 140 MB of finished shardsshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row., and 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.. That sums to 8.94 GB, which du -sh will report back to you as 8.4G because du counts in GiB. Step 9 gives the national figures.

  • 8 GB of free RAM. The ingest peaked at 7.62 GB resident (/usr/bin/time -v reports "maximum resident set size 7,445,032 KB", and that field is kibibytes despite the labelcomponent tagOne of the 25 labels in Mailwoman's address schema — street, locality, region, postcode, house_number, unit, po_box, country, venue, intersection, and others. Each parsed span carries exactly one component tag., so the GB figure is 7,445,032 × 1024 ÷ 1e9). Everything after it stays under 500 MB. That leaves under 400 MB of headroom against the 8 GB figure above, tighter than it looks — treat 8 GB as a floor, not a comfortable margin. If you have less, the ingest is the step that fails, and it fails at the end of a 21-minute run.

  • The CLI, and Node 24.18 or newer:

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

  • A data root you have chosen on purpose. Every command below takes $MAILWOMAN_DATA_ROOT from the environment and writes gigabytes under it.

If what you want is the data rather than the build, stop here and read Improve geocode precision instead: mailwoman data pull us --only vt downloads the same two Vermont shardsshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. in a couple of minutes. This page is for when you need to produce them yourself.

The Overture release pin, before it bites you​

The ingest and every command that reads its output carry a built-in --release 2026-05-20.0. That release is no longer in Overture's bucket, so the default fails:

npx mailwoman gazetteer overture-ingest --countries US
✗ Error: IO Error: No files found that match the pattern "s3://overturemaps-us-west-2/release/2026-05-20.0/theme=addresses/type=address/*.parquet"

Overture keeps a rolling window of releases and drops the rest. Ask the bucket what it has, and pass one of the answers to every command on this page:

curl -s "https://overturemaps-us-west-2.s3.us-west-2.amazonaws.com/?list-type=2&delimiter=/&prefix=release/" \
  | tr '<' '\n' | grep -i "Prefix>release/2"
Prefix>release/2026-06-17.0/
Prefix>release/2026-07-22.0/

Two on 2026-08-03. Everything below pins 2026-06-17.0. Pin the same release across the ingest and every shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. built from it — rows churn between monthly releases, and a shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. whose provenance column disagrees with the parquetParquetThe open columnar file format the corpus is written and streamed in. The training pipeline reads shards row-by-row from Parquet. it came from is a shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. you cannot audit.

1. Point everything at one data root​

export MAILWOMAN_DATA_ROOT=/tmp/mw-us-build
mkdir -p "$MAILWOMAN_DATA_ROOT"
npx mailwoman data status
✗ candidate: wof/candidate.db: missing (expected ~1652.9 MB) — mailwoman data pull candidate
✗ poi: poi/poi.db: missing (expected ~3889.2 MB) — mailwoman data pull poi
✗ fr: ban/address-points-fr.db: missing (expected ~6952.5 MB) — mailwoman data pull fr
✗ us: address-points/address-points-us-ak.db: missing (expected ~78.6 MB) — mailwoman data pull us
...

data status reports the four published 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. against your data root, and every one of them is missing, which is the correct starting state. It is also the check you come back to in step 7, so run it now and know what empty looks like.

2. Ingest the US address slice​

npx mailwoman gazetteer overture-ingest --countries US --release 2026-06-17.0
[ingest] US -> /tmp/mw-us-build/overture/2026-06-17.0/addresses-us.parquet (1258s)
[probe] US: 126672517 rows · postcode 93.5% · postal_city 61.8% · OA-lineage 32.5%
[done] report -> /tmp/mw-us-build/overture/2026-06-17.0/fill-rates.{json,md}
✓ overture ingest: /tmp/mw-us-build/overture/2026-06-17.0
  release 2026-06-17.0 · US · 1 probed
  report: fill-rates.json + fill-rates.md
  US: 126,672,517 rows · postcode 93.5% · OA 32.5%

21 minutes and 6.93 GB on the machine this page was verified on, for 126,672,517 rows. Most of the clock is the scan, not the write: Overture's addresses theme is partitioned by type and not 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., so a 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. ingest reads the planet's address parquetParquetThe open columnar file format the corpus is written and streamed in. The training pipeline reads shards row-by-row from Parquet. and filters. Liechtenstein, the smallest 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. in the theme, takes 132 s for 12,950 rows on the same connection — the floor is the scan.

The run writes a fill-rate report beside the parquetParquetThe open columnar file format the corpus is written and streamed in. The training pipeline reads shards row-by-row from Parquet., and it is worth opening before you build anything on top of it:

head -8 "$MAILWOMAN_DATA_ROOT/overture/2026-06-17.0/fill-rates.md"
# Overture addresses fill-rate report — release 2026-06-17.0

Generated by `mailwoman gazetteer overture-ingest` (#471). Gate rule (epic #470): no
downstream issue proceeds on a country whose relevant field fills <80% without a note.

| country | rows | postcode | street | number | unit | postal_city | address_levels | OA-lineage |
| --- | --: | --: | --: | --: | --: | --: | --: | --: |
| US | 126,672,517 | 93.5% | 99.2% | 98.9% | 14.3% | 61.8% | 100% | 32.5% |

StreetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. fills at 99.2% and number at 98.9%, which is what 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. keys on. unit at 14.3% is the number to plan around: apartment and suite detail is present for one row in seven, so a build on this source resolves buildings, not doors. Below the table the report lists every contributing dataset by row count — 120 of them. NAD, the US National Address Database, supplies 85,482,422 rows; the other 119 arrive through 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. one jurisdiction at a time, 57 of them California counties.

If you want that report again later without re-ingesting, --probe-only reruns the probe against the parquetParquetThe open columnar file format the corpus is written and streamed in. The training pipeline reads shards row-by-row from Parquet. already on disk. It took 9.67 s here against the 21 minutes of the full run, and it overwrites the report each time — a second ingest for a different 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. replaces it rather than appending, so keep a copy if you need to compare two countries.

3. Build one state's rooftop shard​

npx mailwoman situs address-points --state VT --release 2026-06-17.0
✓ 333610 points → /tmp/mw-us-build/address-points/address-points-us-vt.db
  333610 VT rows from addresses-us.parquet
  distinct streets: 18466 · postcodes: 264
  provenance (VT, release 2026-06-17.0):
    overture:NAD                 333,610 rows

7.32 s over the 6.93 GB parquetParquetThe open columnar file format the corpus is written and streamed in. The training pipeline reads shards row-by-row from Parquet., and 81.9 MB on disk. That ratio is the reason step 2 is a one-time cost: the parquetParquetThe open columnar file format the corpus is written and streamed in. The training pipeline reads shards row-by-row from Parquet. is scanned once per state and every state after the first is seconds.

The provenance block is per-row, not per-file. Every Vermont point traces to NAD, so this shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. carries one license. A California build prints 57 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. county sources under that heading, and each of them wants credit — which is what step 5 is for.

4. Build the same state's interpolation shard​

The 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. answers a house numberhouse numberThe numeric or alphanumeric identifier of a building on a street. Mailwoman's house_number component; its position relative to the street name flips between locales. it holds. The 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. answers one it does not, by walking the Census TIGERTIGERThe US Census Topologically Integrated Geographic Encoding and Referencing database. Used as a corpus source for street-segment data. 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. its number falls on. That is a separate source and a separate command:

npx mailwoman situs interpolation --states VT
=== National TIGER interpolation shard build ===
states:      VT
edges-dir:   /tmp/mw-us-build/census/tiger2023-edges
out-dir:     /tmp/mw-us-build/interpolation
concurrency: 12
release:     TIGER2023

Step 1: county population ranking
  3144 counties in ranking
  14 counties to process

Step 2: downloading TIGER EDGES ZIPs (concurrency=12)
  downloaded: 14, skipped (already present): 0, failed: 0

Step 3: building per-state shards
  1 states with available SHPs: VT

Building VT…
  [VT] ✓ 137256 segment-sides →
  [VT] /tmp/mw-us-build/interpolation/interpolation-us-vt.db
  [VT]   distinct streets: 17182 · postcodes: 296
  [VT]   parity: odd 68537 · even 68711 · mixed 8
  [VT]   skipped non-numeric ranges: 146
  [VT]   baked radius calibration: ×1.95 (default, split-conformal:2026-06-14)

✓ interpolation: /tmp/mw-us-build/interpolation
  States built:    1 / 1
  Total segments:  137,256
  Wall clock:      6.0s

17 s end to end — 14 county archives downloaded and unpacked to 215 MB, then 6.0 s of build — for a 58.5 MB shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. holding 137,256 segmentsegmentA punctuation-bounded chunk of the normalized input — the comma-separated parts of 'Portland, OR' — used to give downstream stages structural context.-sides. The command downloads its own TIGERTIGERThe US Census Topologically Integrated Geographic Encoding and Referencing database. Used as a corpus source for street-segment data. data, so there is nothing to fetch first.

Three lines in that output are worth knowing. Parity splits the segmentsegmentA punctuation-bounded chunk of the normalized input — the comma-separated parts of 'Portland, OR' — used to give downstream stages structural context.-sides into odd and even runs, which is how the interpolator picks the correct side of 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. for 118 rather than 117; the 8 mixed sides are the ones TIGERTIGERThe US Census Topologically Integrated Geographic Encoding and Referencing database. Used as a corpus source for street-segment data. records as carrying both, and the lookup accepts them for either parity after it fails to find an exact side. 146 skipped non-numeric ranges are segmentssegmentA punctuation-bounded chunk of the normalized input — the comma-separated parts of 'Portland, OR' — used to give downstream stages structural context. whose house numbershouse numberThe numeric or alphanumeric identifier of a building on a street. Mailwoman's house_number component; its position relative to the street name flips between locales. are not numbers at all, so they are dropped rather than guessed. And the baked radius calibration of ×1.95 is what turns the raw half-segmentsegmentA punctuation-bounded chunk of the normalized input — the comma-separated parts of 'Portland, OR' — used to give downstream stages structural context. radius into the uncertainty_m you read at query time; it travels inside the shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row., so the number does not depend on which client opens it.

If you were reaching for mailwoman tiger fetch here, don't — that command loads census blocks, places and address 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. for demographic work, into a different database. The 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 is built by situs interpolation alone.

5. Record where the rows came from​

npx mailwoman situs attribution-manifest --release 2026-06-17.0
vt            333,610 points · 1 sources
✓ attribution: /tmp/mw-us-build/address-points/ATTRIBUTION.json
  1 shards · 333,610 total points
  top sources:
    NAD                                      333,610

This reads every shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. in the directory and aggregates the per-row source column into one ledger. Run it after the last state you build, not after each one: it counts what is on disk, so a partial run undercounts and a rerun fixes it. NADNAD (National Address Database). A US Department of Transportation dataset of structured address points, added to the training corpus as a major source of real US addresses. is US public domain; 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. sources named in ATTRIBUTION.json are the ones you owe credit to when you redistribute a shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row..

6. Add the gazetteer​

The two shardsshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. you built hold streetsstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. and house numbershouse numberThe numeric or alphanumeric identifier of a building on a street. Mailwoman's house_number component; its position relative to the street name flips between locales., and nothing in either resolves the word "Burlington". That comes from 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., which mailwoman publishes as a download rather than asking you to build it — the build needs the 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. data repositories cloned first, and the database it produces is over 5 GB before the query-time one is derived from it. Build the planet covers that path; here, take the download:

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

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

4 minutes and 7 seconds for 1.65 GB here. content-length verified is the check the pull does: it HEADsattention 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. the object and compares the byte count it downloaded against what the server declared. The bucket publishes no checksum sidecar for any artifact, so content-length is the strongest integrity signal available.

7. Check what you have​

npx mailwoman doctor
✓ Model weights (en-us): package:@mailwoman/neural-weights-en-us · model.onnx 39.4 MB, tokenizer.model 1.6 MB
✓ Node runtime: node v26.2.0 (engines: >=24.18.0)
✓ ONNX runtime: onnxruntime-node loadable
✓ Data root: /tmp/mw-us-build ($MAILWOMAN_DATA_ROOT) — exists, writable
✓ Admin gazetteer: candidate.db · /tmp/mw-us-build/wof/candidate.db (convention path)
✗ POI layer: /tmp/mw-us-build/poi/poi.db not found (optional)
    fix: mailwoman gazetteer build poi   (or: mailwoman data pull poi)

PASS — core checks ok (weights + runtime); parse is ready

The POI 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 a separate artifact and 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. does not need it, which is why doctor marks it optional and passes anyway. (convention path) on 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. line means it was found at <data root>/wof/candidate.db with nothing configured — which is why step 6 was one command and no export, and why the export line the pull printed can be ignored.

Now run the other check, and read its verdict carefully:

npx mailwoman data status us 2>&1 | grep -i vt
✗ us: address-points/address-points-us-vt.db: stale — 81.9 MB on disk vs 72.9 MB (recorded) at /tmp/mw-us-build/address-points/address-points-us-vt.db
✗ us: interpolation/interpolation-us-vt.db: stale — 58.5 MB on disk vs 58.5 MB (recorded) at /tmp/mw-us-build/interpolation/interpolation-us-vt.db

Both files are correct and both report stale, so know what that word means before you act on it. data status compares each file's byte count against the size recorded for the 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.; it is a "does your download match ours" check, not a validity check on a shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. you built. A locally-built shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. fails it by construction. The 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. file is 81,903,616 bytes against the bucket's 72,945,664 because you built it from a newer Overture release; the 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. file is 58,511,360 against 58,507,264, one 4 KB SQLite page apart, and both round to 58.5 MB in the message — which is why that second line reads as a contradiction and is not one. After a build, doctor plus a real geocode is the check that means something.

8. Geocode against what you built​

Three addresses, one per tier, against the two shardsshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. and 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. now on your disk.

npx mailwoman geocode "149 Church St, Burlington, VT 05401" --format text
[resolver] candidate-table backend (demo-parity, population-first): /tmp/mw-us-build/wof/candidate.db
input:            149 Church St, Burlington, VT 05401
resolution_tier:  address_point
coordinate:       44.476312, -73.212823
uncertainty_m:    1
locality:         Burlington
region:           VT
postcode:         05401
hierarchy:
  locality             Burlington [wof:101728319] (44.4876, -73.2315)
  region               VT [wof:85688763] (44.0753, -72.6625)

address_point with uncertainty_m: 1 — 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. hit out of the shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. you built in step 3. The hierarchy block underneath comes from 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., and it is the reason to keep both: Burlington's own centroid is 1,942 m from this building, which is the error you would have carried without step 3.

Church Street holds 131 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 between numbers 1 and 272, with gaps. Ask for one of the gaps:

npx mailwoman geocode "27 Church St, Burlington, VT 05401" --format text
input:            27 Church St, Burlington, VT 05401
resolution_tier:  interpolated
coordinate:       44.479487, -73.212731
uncertainty_m:    90
locality:         Burlington
region:           VT
postcode:         05401

interpolated, from the TIGERTIGERThe US Census Topologically Integrated Geographic Encoding and Referencing database. Used as a corpus source for street-segment data. shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. in step 4, with 90 m of reported uncertainty — the half-segmentsegmentA punctuation-bounded chunk of the normalized input — the comma-separated parts of 'Portland, OR' — used to give downstream stages structural context. radius already multiplied by the ×1.95 calibration baked into the shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row..

Then ask for a state you did not build:

npx mailwoman geocode "107 N Main St, Concord, NH 03301" --format text
input:            107 N Main St, Concord, NH 03301
resolution_tier:  admin
coordinate:       43.230549, -71.559526
locality:         Concord
region:           NH
postcode:         03301

admin, and no uncertainty_m at all: the coordinate is Concord's centroid, because no New Hampshire shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. exists in this data root. PrecisionprecisionOf the spans the model labeled as a given tag, the fraction it got right. High precision means few false positives. Paired with recall to compute F1. is bought per state. Branch on resolution_tier and you can tell the three apart in code without guessing from the coordinate.

9. Scale to fifty states​

Nothing above changes shape at national scale — the two build commands take lists instead of one state, and the parquetParquetThe open columnar file format the corpus is written and streamed in. The training pipeline reads shards row-by-row from Parquet. you already have is the input for all of them.

# Every covered state, four at a time, each in its own child process.
npx mailwoman situs build --release 2026-06-17.0 --concurrency 4

# Every state plus DC. The county ranking it walks holds 3,144 rows.
npx mailwoman situs interpolation

Those two are the only commands on this page that were not run to produce it — a national build is days of wall clock, not an afternoon. So the numbers below are the published national tier's, which was built by these same two commands, read off the 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. registry the CLI ships:

ArtifactFilesSize
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. (50 + DC + VI)5230.3 GB
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. shardsshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row.5111.0 GB
Both10341.3 GB

Vermont's 140 MB is a three-hundredth of that, and the spread between states is wide: California's 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 3.47 GB and Alaska's is 78.6 MB. Two things scale and one does not. The parquetParquetThe open columnar file format the corpus is written and streamed in. The training pipeline reads shards row-by-row from Parquet. is a fixed 6.93 GB whatever you build from it. ShardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. build time scales with rows, so plan against the population of the states you want rather than their count. And the TIGERTIGERThe US Census Topologically Integrated Geographic Encoding and Referencing database. Used as a corpus source for street-segment data. working set scales with counties — 215 MB bought Vermont's 14, against the 3,144 in the ranking — so give the 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. step room well beyond the finished 11.0 GB.

Two states do not come out of the Overture path at all, and this is the part to check before you promise 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.:

  • Hawaii is absent from Overture's US addresses theme. The published shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. was built from 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. instead, with situs address-points --state HI --oa-csv <conformed.csv>, and holds 348,377 points.
  • New Hampshire is absent from both, and its published shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. holds zero rows. The file exists — 20,480 bytes, the schema and no data — so a lookup against it opens, succeeds, and returns nothing. An empty shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. and an absent shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. read the same way at the call site and mean different things, so if you serve New Hampshire, treat the 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. tier there as unbuilt. Its 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. is unaffected: 57.6 MB and 156,620 segmentsegmentA punctuation-bounded chunk of the normalized input — the comma-separated parts of 'Portland, OR' — used to give downstream stages structural context.-sides, built from TIGERTIGERThe US Census Topologically Integrated Geographic Encoding and Referencing database. Used as a corpus source for street-segment data. like every other state's.

What you have now​

A data root holding one state's address data that you built rather than downloaded: 333,610 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 per-row provenance back to a named federal dataset, 137,256 TIGERTIGERThe US Census Topologically Integrated Geographic Encoding and Referencing database. Used as a corpus source for street-segment data. segmentsegmentA punctuation-bounded chunk of the normalized input — the comma-separated parts of 'Portland, OR' — used to give downstream stages structural context.-sides behind them, and an ATTRIBUTION.json that says which license each row arrived under. The same commands, given a longer --states list, produce the other 49 against the parquetParquetThe open columnar file format the corpus is written and streamed in. The training pipeline reads shards row-by-row from Parquet. already on your disk.

Next​

  • Build the planet — 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. you downloaded in step 6, built from source, and which countries outside the US have an address tier at all.
  • Improve geocode precision — what the four resolution tiers mean and what uncertainty_m measures in each.