How close is close enough?
A geocoder turns an address into a point, and the obvious thing to ask is whether the point is right. That question has no answer, because "right" assumes a single tolerance and there isn't one. A point that is right enough to tell you which county regulates this facility can be uselessly wrong for routing a truck to its loading dock. The question that does have an answer is the one the operator keeps coming back to, and the one this page is about: close enough for what?
In short: Mailwoman never hands you a bare point. It hands you a point, a 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., and a calibrated radius — and "close enough" is a comparison between that radius and your task's tolerance, made by the consumer, not asserted by us.
There is no single tolerance
Three real consumers of the same resolved address want three different things:
| consumer | the question | tolerance that's "close enough" |
|---|---|---|
| jurisdiction / 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. | which citylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. / county / HPSAHPSA (Health Professional Shortage Area). A US federal designation identifying areas short of health providers relative to population and need, scored 0–25. An example downstream use of geocoded address data. is this in? | the admin centroid — a few km is fine; the centroid is inside the right polygon |
| record co-location (the matcher) | are these two records the same building? | the 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. — tens of metres; 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. fuses every facility in town |
| routing / dispatch | where is the door? | 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., and you care about the tail, not the median |
A single accuracy number ("p50 3 km") answers none of these on its own. It's only meaningful against a stated tolerance. The jurisdiction consumer is delighted by 3 km; the matcher is sunk by it.
The three tiers, and what each is actually worth
Mailwoman resolves to the finest tier it has data for, and 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. which one it used (measured on 1172 real TX facility addresses, 2026-06-17-geocoder-vs-provided-coords):
| 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. | what it is | coord p50 | when it fires |
|---|---|---|---|
admin | localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. / regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. centroid | 3.4 km | always (fallback) |
interpolated | house-number estimate along the streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. segmentsegmentA punctuation-bounded chunk of the normalized input — the comma-separated parts of 'Portland, OR' — used to give downstream stages structural context. | 0.1 km | a 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. matches |
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. centroid | 0.7 km | 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. has the point |
When a finer 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. fires, the geocoder is streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels.-to-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. accurate — 98.8% within 100 m on the non-circular Travis-County E-911 holdout. 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. means "right citylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy.," nothing finer.
So the first half of "close enough" is which 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. did we reach, because 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. is the grain. A matcher that needs buildings should treat an 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. result as a building it hasn't actually located, even though the centroid happens to sit a mere 3 km away.
Trust the radius, not the point
A 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. labelcomponent 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. is coarse. The per-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. answer to "how close is this one?" is the calibrated uncertainty radius the geocoder reports alongside the coordinate. One rule governs that number, and it's the reason you can trust it (2026-06-14-interp-radius-calibration):
A radius is only meaningful if it's calibrated. If we say ±87 m it must contain the truth ~90% of the time — not 72%. Otherwise the number is decoration.
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. 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. radius covered only ~72% of true errors; a split-conformalconformal calibrationA calibration method that adjusts per-prediction uncertainty so a target coverage (e.g. 90%) is guaranteed on held-out data, without retraining the model. calibration (Q̂ ≈ 1.70, per-regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality.) makes it a real 90% bound. That turns "±87 m" from a guess into a promise: the true point is within this radius ~90% of the time. The consumer can then make the call: "my tolerance is 50 m, your 90% radius is 87 m, so this one isn't close enough, abstain." That beats trusting a bare point that is secretly 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 is the same move the parser makes with confidence calibration: a number you can act on, not a vibe.
Coverage is the frontier, not precision
Where the finer tierstierInternal 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. fire, accuracy is solved (0.1–0.7 km, calibrated). The open problem is 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. — on the TX facility set, the 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. 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. fired on 47% and 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. on a further 12.5%, so ~40% fell back to the 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.. "Close enough" for a building-grain task therefore depends mostly on did we have a shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. for this place, not on 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. math. Widening 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. 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. is the lever that moves the most addresses into "close enough," and it's a data problem, 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.' one.
So: how do we know how close is close enough?
We don't decide it — we report enough that the consumer can. Every resolved address carries:
- a 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. (the grain we actually reached), and
- a calibrated radius (the calibrated 90% bound), so that
- the consumer compares the radius to their tolerance and either uses the point or abstains — the same calibrated-radius downgrade 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. already makes when its candidates scatter.
"Close enough" is not a property of the geocoder. It's a comparison, and our job is to make that comparison truthful: never a bare point, always a point with a 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. and a radius that means what it says.
What's still owed: per-use-case sufficiency thresholds (the matcher's "building-grain" cutoff, a routing cutoff) measured against the calibrated radius, and the 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. push to move the ~40% 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. fallbacks onto a shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row.. Both are tracked under the geocoder-quality work.