Skip to main content

How close is close enough?

The question​

A geocoder hands you 39.797779, -89.645386 and the obvious thing to ask is whether it is right. That question has no answer. Not because geocoders are unknowable, but because "right" assumes one tolerance and there isn't one: the same coordinate can be completely adequate for deciding which county regulates a facility and completely useless for sending a van to its loading dock.

The question with an answer is a different one. Close enough for what?

The analog​

Think about how you'd give directions to two different people. To someone flying in from abroad you say "it's in Springfield, Illinois" and that is a complete answer — they need to book a flight, and the town is the unitunitA subdivision of a building — apartment, suite, floor — that refines a street address. Mailwoman's unit component; a designator plus identifier forms a subpremise. of the decision. To the courier standing outside you say "it's the brown house, third from the corner, blue door", and "Springfield, Illinois" would be a joke. Neither answer is more accurate than the other. They are answers at different grains, and each is wrong at the other's job.

A geocoder cannot know which of those two people is asking. What it can do is tell you which answer it gave.

Three consumers, three tolerances​

Take one resolved address and hand it to three systemsexpectation-maximizationAn iterative algorithm that estimates model parameters when some variables are unobserved. In Mailwoman's matcher, EM learns the Fellegi-Sunter m and u parameters from unlabeled data — no training labels needed..

A jurisdiction check wants to know which citylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighborhood in the hierarchy., county or regulatory area this facility falls in. It needs the point to land inside the correct polygon, and a couple of kilometers of slop inside a polygon that spansspanA contiguous range of characters or tokens in the input string, tagged with an address component type (street, locality, postcode, etc.). Parsed addresses are represented as collections of spans, possibly nested in a tree. tens of kilometers changes nothing. A town centroid is a complete answer.

A record matcher wants to know whether two records describe the same building. Its tolerance is tens of meters, because a town centroid fuses every facility in town into one entity. A coordinate that satisfied the jurisdiction check destroys this one.

A dispatcher wants the door. Its tolerance is meters, and it cares about the tail rather than the median — a routing system that is excellent on average and catastrophic once a week is a routing system with a weekly incident.

A single number — "median error 3 km" — answers none of the three on its own. It is a fact about a distribution, and each consumer needs a fact about this result.

The tier is the grain​

The first half of a per-result answer is which method produced the coordinate. A geocoder does not have one way of placing a point; it has a ladder, and the rung it reached is the grain of the answer.

Mailwoman reports the rung in resolution_tier, with four values. A registered address point, an estimate interpolated along 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. segmentsegmentA punctuation-bounded chunk of the normalized input — the comma-separated parts of 'Portland, OR' — used to give downstream stages structural context., 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. centroid, and an administrative centroid — the last of which always exists, because it is what 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. knows. Improve geocode precision walks all four with real output and shows a result moving from the bottom rung to the top one after a per-state download.

The practical rule is that a consumer with a building-grain tolerance should treat an administrative-tier result as a building it has not located — even when the centroid happens to be three kilometers away and looks close on a map. The tier tells you what kind of thing you were given, and no distance can substitute for that.

The radius is a promise, not an error bar​

The second half is a number, and it is the one that gets misread.

uncertainty_m is a radius, and the claim attached to it is 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. claim: the true location falls inside that radius about 90% of the time. It is not "the answer is off by this much". It is "draw this circle and the answer is inside it, nine times in ten".

That distinction matters because a radius is only worth anything if it has been calibrated against measured error. An uncalibrated radius — half the length of the matched 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., say — sounds principled and is decoration if the truth falls outside it three times in ten. Mailwoman's 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 is calibrated per regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. for exactly that reason, and the tutorial above shows the resulting numbers alongside the results they describe.

Once the radius means what it says, "close enough" becomes arithmetic you can run:

My tolerance is 50 m. This result reports a 90% radius of 141 m. That is not close enough — abstain, or escalate this one.

Which is a far better position than trusting a bare coordinate that is secretly a citylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighborhood in the hierarchy. center.

The two ways a number can be absent​

Two absences look alike in a result and mean opposite things.

At the top tier, Mailwoman reports uncertainty_m: 1 — a floor rather than a measurement. A registered address point is a surveyed position; the 1 is there to say "this is as good as this system's unitsunitA subdivision of a building — apartment, suite, floor — that refines a street address. Mailwoman's unit component; a designator plus identifier forms a subpremise. get", not to claim millimetre knowledge.

At the administrative tier it reports uncertainty_m: null, and that is not zero uncertainty. It is the absence of an estimate: no finer method fired, so there is nothing to price. A consumer that reads a missing radius as a small radius has inverted the meaning of the field. Branch on the tier, then read the radius — not the other way round.

Precision is not the frontier; coverage is​

Where a fine tier fires, the accuracy is a property of the underlying 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. rather than of any 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.', and it is good. The interesting question is how much of your data a fine tier fires on at all, and that is decided by whether a shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. covers the place — a data question, answered by downloads and by what open data exists 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..

This has a consequence for how you read a disappointing result. An administrative-tier answer in 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 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. 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 worth investigating, because something upstream probably went wrong. The same answer in 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 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. is the system working correctly and saying so. Locales and tiers is where the per-localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. picture lives.

The false confidence of decimals​

One habit worth breaking. A coordinate printed to eight decimal places looks authoritative — eight decimals of latitude is about a millimetre of ground — and consumers treat it accordingly. But decimal places are a property of the number's formatting, and they survive every rounding of the truth beneath them. A 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. printed to eight decimals is a 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..

The tier and the radius are the fields that carry the 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. claim. The coordinate never did.

What it costs​

Reporting a grain and a radius instead of one score pushes a decision onto the consumer, and that is a real cost: you have to decide your own tolerance, in meters, and write the comparison. Systemsexpectation-maximizationAn iterative algorithm that estimates model parameters when some variables are unobserved. In Mailwoman's matcher, EM learns the Fellegi-Sunter m and u parameters from unlabeled data — no training labels needed. that return a single confidence score are easier to consume and are answering a question they were never given the inputs for, because "close enough" is a comparison against a tolerance the geocoder was never told.

  • What geocoding is — where 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. tiers come from.
  • Improve geocode precision — the four tiers with real output.
  • Tune confidence thresholds — the parser's separate confidence number and how to act on it.
  • Locales and tiers — which localeslocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. carry which 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..
  • Gazetteers — why the administrative tier exists everywhere.