Address-point tier — VT prototype measurement (2026-06-10, night-10)
The #476 prototype: exact (street, number) → exact 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. point, in front of admin-centroid
resolution. ShardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. from Overture release 2026-05-20.0 (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. lineage), keyed by THE shared
normalizer (resolver-wof-sqlite/street-normalize.ts) on both build and lookup sides.
VT holdout (1,428 honest rows, v4.2.0 int8, tier on vs off)
| 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. | 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 | coord p50 | coord p90 | coord p99 | hit rate |
|---|---|---|---|---|---|---|
| admin-centroid (today's default) | 93.8% | 99.9% | 3.4 km | 7.4 km | 277.4 km | — |
| + address-point | 93.8% | 99.9% | 0.0 km | 0.0 km | 6.2 km | 93.1% (1330/1428) |
The 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. changes where, never which place — admin flags are identical by construction (the hook decorates 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. node's metadata after the admin walk; it cannot alter attribution). On a hit, the resolved coordinate is the actual building: gold OA points and Overture 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. points agree to meters. The 6.9% miss population is exactly what 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. (#483) exists for — and this shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. is its gold standard.
Rollout decision note
- ShardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. shape: per-stateregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality.. VT = 333,610 points → 56 MB (~168 B/point); full US
extrapolates to ~21 GB — fine on the playpen as per-stateregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. files, a non-starter as one
artifact. Build is
scripts/build-address-point-shard.ts --state XX(~1 min/small stateregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality.), idempotent, release-pinned. - 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. scope first, localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. fallback. 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. is the selective key and dodges the
municipal-legal-name trap: 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. localities are charter names (
Barre City,Saint Albans City) while 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. say "Barre" — and VT's Barre CitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. ≠ Barre Town, so the localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. key stays EXACT (no suffix stripping; conflating those two would be a real wrong-answer class). Rows lacking a 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. in the query lean on localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. and will miss more — measured, accepted for the prototype. - No fuzz. Exact-after-normalization got 93.1% on real holdout traffic; fuzzy streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. matching is a separate, later decision with its own evalevalRunning the model against a held-out golden dataset and computing per-component F1, exact-match, calibration, and resolved-coordinate error..
- 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. policy: opt-in
ResolveOpts.addressPoints(an injectedAddressPointLookup), default absent = byte-stable. Server-side (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. B) data; pocket-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. delivery is out of scope (#378's two-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. split).
Next: DE/FR shardsshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. need the analogous Overture pulls (streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels./number fill ≈100% in both); US rollout = build the stateregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. list + a shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row.-routing wrapper (stateregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. → db path) behind the same interface.