The shipped US coordinate is meter-grade — the eval was grading the admin centroid (2026-06-18)

TL;DR

oa-resolver-eval reported US coord p50 3.3 km / p90 10 km and we read that as the assembled-coordinate ceiling — the number behind "the US bottleneck is rural 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. 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.." It is the admin-centroid tiertierInternal versioning of which label classes the model emits. Tier 1 is the coarse components (country, region, locality, postcode); Tier 2 adds venue, street, house_number; Tier 3 (future) would add attention, po_box, and POI venue subtyping. Historically called 'Stage 1/2/3' before the runtime-pipeline naming made that ambiguous.. Production doesn't stop there: mailwoman/geocode-core.ts's geocodeAddress runs a per-stateregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. situssitusThe physical site address of a property, as opposed to the owner's mailing address. Parcel records often carry both; the divergence is a real-world data-quality challenge. + 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. cascade over the #567 address-point 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. (124.9M US points) that the evalevalRunning the model against a held-out golden dataset and computing per-component F1, exact-match, calibration, and resolved-coordinate error. never wired. Graded against what actually ships, the same 10,000 US rows resolve to p50 0.0 km, p90 1.0 km, 85.9% within 100 m, 90% within 1 km — and only 12% fall back to the admin centroid at all. The "coordinate bottleneck" was a measurement gap, not a data gap and not a 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.' gap. Fixed: oa-resolver-eval --cascade (dd3628da) now grades the production coordinate.

What happened

The evalevalRunning the model against a held-out golden dataset and computing per-component F1, exact-match, calibration, and resolved-coordinate error. builds a neural parseaddress parsingThe process of decomposing a free-text postal address string into structured components — house number, street name, locality, region, postcode, and country — so a geocoder can resolve them to coordinates., resolves it through the WOFWOF (Who's On First). An open-source gazetteer of places maintained by Mapzen/whosonfirst. Mailwoman builds a custom SQLite database from WOF GeoJSON repos, extended with postcode data, importance scores, and coincident-role relations. admin 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 takes the resolved place's centroid as the coordinate. That centroid is honest as far as it goes — a city centroidlocality centroidThe representative centre 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. is legitimately tens of km from an edge address, which is exactly why we lead with admin-match rate there, not the coordinate. The trouble is we then carried the 3.3 km admin number into the 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.-to-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., the 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., and the docs as if it were the coordinate the product delivers.

It isn't. The geocode CLI and the /api/geocode service both run geocodeAddress, which reads the parsed regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality., picks that stateregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality.'s situssitusThe physical site address of a property, as opposed to the owner's mailing address. Parcel records often carry both; the divergence is a real-world data-quality challenge. + 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., and resolves through a coordinate cascade: an exact address-point (rooftoprooftopGeocoding precision at the building or parcel level — coordinates within a few metres — the highest tier of the geocode cascade. Sourced from address-point and situs data./parcelparcelA property polygon or record carrying a situs (site) address and often a separate owner mailing address. County GIS parcel aggregations are a training source for address-point variety and situs-vs-owner divergence.) when the 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. is on file, a house-number 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. 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. segmentsegmentA punctuation-bounded chunk of the normalized input — the comma-separated parts of 'Portland, OR' — used to give downstream stages structural context. otherwise, and the admin centroid only when neither exists. The evalevalRunning the model against a held-out golden dataset and computing per-component F1, exact-match, calibration, and resolved-coordinate error. simply called resolveTree with no shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. options, so every row landed at the admin tiertierInternal versioning of which label classes the model emits. Tier 1 is the coarse components (country, region, locality, postcode); Tier 2 adds venue, street, house_number; Tier 3 (future) would add attention, po_box, and POI venue subtyping. Historically called 'Stage 1/2/3' before the runtime-pipeline naming made that ambiguous.. copy-weights is skipped on CI and the per-stateregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. shardsshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. are multi-GB, so nobody noticed the evalevalRunning the model against a held-out golden dataset and computing per-component F1, exact-match, calibration, and resolved-coordinate error. was running a different, blunter path than production.

--cascade closes that: it builds a multi-stateregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. ShardProvider (per-row stateregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. selection), routes the neural resolve through the same address_point > interpolated > admin cascade the geocoder ships, and reports it as the neural+cascade arm. The default (no flag) stays byte-identical — the admin-centroid headline is unchanged, so this adds the shipped coordinate beside it rather than rewriting history.

The numbers (self-emitted, --cascade, v1.5.0, anchor-on, 10k US OpenAddresses rows)

parser	localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy.-match	regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality.-match	resolved	coord p50 km	coord p90 km	p99 km
neural (admin centroid)	98.0%	100.0%	100.0%	3.3	10.0	159.4
v0 (PeliasPeliasAn open-source geocoder, Mailwoman's spiritual predecessor.)	95.5%	99.5%	99.7%	3.4	11.0	259.1
neural+addrpt	98.0%	100.0%	100.0%	0.0	2.9	19.9
neural+cascade (SHIPPED coord)	98.0%	100.0%	100.0%	0.0	1.0	18.3

neural+cascade is the production coordinate (geocode-core.ts: address_point > interpolated > admin, per-stateregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. shardsshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row.). TiertierInternal versioning of which label classes the model emits. Tier 1 is the coarse components (country, region, locality, postcode); Tier 2 adds venue, street, house_number; Tier 3 (future) would add attention, po_box, and POI venue subtyping. Historically called 'Stage 1/2/3' before the runtime-pipeline naming made that ambiguous. share: address_point 79.8%, interpolated 8.2%, admin 12.0%. Within 100 m: 85.9% · within 1 km: 90.0% (n=10,000). The entire residual coordinate error lives in the 12% admin tail — rows in places with no situssitusThe physical site address of a property, as opposed to the owner's mailing address. Parcel records often carry both; the divergence is a real-world data-quality challenge./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. point 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., where the centroid is the honest best estimate.

Update (post-fix, 2026-06-19): characterizing that 12% admin tail (#723) found 54% of it recoverable with no new data, and two fixes from this diagnostic's follow-up landed it on the same 10k rows — the directional-quadrant streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels.-key fold (d1b8bcbe: a quadrant 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.' mis-tagged unit, "Taylor StreetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. NE") and the US-gated 5-digit-house-number-as-ZIP relabel (5977ce4d: "24588 Outback Trl" → house_number, with the FR reversed-order #560 shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. left untouched, gate- verified fr.house_number flat). Re-measured: address_point 79.8 → 83.5%, interpolated 8.2 → 9.7%, admin 12.0 → 6.8%; within 100 m 85.9 → 90.0%, within 1 km 90.0 → 94.8%, cascade p99 18.3 → 10.9 km. The admin tail is now under 7%, and the remaining bulk is a situssitusThe physical site address of a property, as opposed to the owner's mailing address. Parcel records often carry both; the divergence is a real-world data-quality challenge. shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. theme-reselect (the SD/IL holes are in Overture's 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. theme, not the sparser 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. theme we ingested), not a 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. gap — #723.

Why this matters

This is the same trap as the #375 localadmin scoring artifact and the #566 reconcile regression: grade the assembled output the product actually ships, not an intermediate. The new twist is the direction — every prior instance had us over-reporting (a metric looking better than the shipped behavior); this one had us under-reporting by three orders of magnitude. A 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 win on labelscomponent tagOne of the 33 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. while the assembled address resolves wrong (the #566 case); it can also resolve streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels.-accurate while the evalevalRunning the model against a held-out golden dataset and computing per-component F1, exact-match, calibration, and resolved-coordinate error. reports a city centroidlocality centroidThe representative centre 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. (this case). Both are fixed by the same discipline: pull the rows, run what ships over them, grade that.

It also retires "the US coordinate bottleneck is rural 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. 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.." The rural statesregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. aren't the laggards once you grade the cascade — SD and VT land their addresses at the address-point tiertierInternal versioning of which label classes the model emits. Tier 1 is the coarse components (country, region, locality, postcode); Tier 2 adds venue, street, house_number; Tier 3 (future) would add attention, po_box, and POI venue subtyping. Historically called 'Stage 1/2/3' before the runtime-pipeline naming made that ambiguous. like everywhere else; their lower localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy.-match (VT 93.8%, IA 95.8%) is a separate, mostly naming-convention residual (civic suffixes like "Barre" vs "Barre Town", ~71% of the 2% miss), not a coordinate problem. The next US coordinate gain is point-data 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 the 12% admin tail, not a retrain and not more 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. breadth.

Caveats

• The cascade needs the data 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.. The bare @mailwoman/neural-weights-* 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. plus the admin 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. give the admin centroid; the meter-grade coordinate requires the per-stateregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. situssitusThe physical site address of a property, as opposed to the owner's mailing address. Parcel records often carry both; the divergence is a real-world data-quality challenge. + 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. wired in (the server's ShardProvider, the CLI's --address-points / --interpolation, or --cascade here). The shardsshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. are not in the npm package — they are the data release the geocoder consumes.
• Ship-config parity is partial. The evalevalRunning the model against a held-out golden dataset and computing per-component F1, exact-match, calibration, and resolved-coordinate error. feeds the 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. anchor (the dominant channel for admin recovery, which reproduces the 98.0% headline) but builds the classifier manually, so it does not yet feed 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./conventions channels. Routing it through the canonical createScorer for full ship-config parity is a tracked follow-up; it does not affect the coordinate result here.
• LocalitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy.-match residual is separate. The ~2% localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. miss is mostly civic-suffix / coincident-municipalitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. naming, not absent places — a metric-fairness item, not a 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. hole.

Raw report: oa-resolver-eval --cascade self-emitted via --out-md. Reproduces the situssitusThe physical site address of a property, as opposed to the owner's mailing address. Parcel records often carry both; the divergence is a real-world data-quality challenge.-cascade diagnostic run independently through geocodeAddress over the same rows (p50 0.0 / p90 1.0 / 85.9% within 100 m).