Skip to main content

Two addresses, one building

The question​

Your database has two records. Same building, same footprint, two addresses that share no components beyond the town. Neither record is a typo and neither system that produced them is wrong. Which one is the address, and what should a geocoder hand back when it is asked about the other?

The analog​

Ask four people for a building's address and you get four answers, because each is answering for a different organization.

The postal service answers with the form its address file accepts, which is the form that gets mail sorted. Emergency dispatch answers with the entrance a vehicle can reach, which is a different door on a different streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. when the building takes a corner. A tax assessor answers with the 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., which may carry a number from before the building existed. A visitor answers with the name on the front — and a name works as an address for a courier who has been there and for nobody's sorting machine.

There is no fifth answer underneath these four that the four are approximating. The address is selected by the asker.

Where the copies come from​

Corner frontages. A building on the corner of two named streetsstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. has two streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. frontages and can be numbered on either. The postal address takes one; the other stays a valid way to describe the same door, and it is the one a caller reports when they walked in from that side.

Names used as addresses. A building with a name is addressed by that name in the 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. of things people say, and by a number in the 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. a postal file accepts. The two coexist for the same structure, and the name-shaped one carries prestige, which is why it survives being useless to a sorting machine.

UnitunitA subdivision of a building — apartment, suite, floor — that refines a street address. Mailwoman's unit component; a designator plus identifier forms a subpremise. numbering. One 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 and two hundred delivery points is the normal condition for an apartment block or an office tower. The building's footprint is one polygon; the addresses are two hundred labelscomponent 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. attached to it, distinguished by a component that has no geometry of its own — a floor, a suite, a letter.

Boundaries under the building. A structure can sit across a municipal line, so its legal municipalitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighborhood in the hierarchy. and its postal town disagree by design. It can be in an annexed area whose postal town still names the town that annexed it. Brooklyn is a postal citypostal cityThe city name the postal service uses for a ZIP, which can differ from the legal municipality a resident lives in — e.g. many suburbs share a larger city's postal name. A source of locality ambiguity. that the Postal Service accepts, and the legal municipalitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighborhood in the hierarchy. is New York; both appear in real records, and a system that treats one as a misspelling of the other loses information.

What a geocoder owes you​

The behavior worth asking for is that the result state what kind of answer it is, rather than flattening four kinds into one coordinate.

A Mailwoman geocode carries that in the result: resolution_tier names the data that answered, uncertainty_m bounds it, and hierarchy gives the administrative chain the components resolved through. With the US address data installed, 350 5th Ave, New York, NY 10118 returns resolution_tier: "interpolated" with uncertainty_m: 64 — a position estimated along the block from 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. network, not a point the building itself contributed. That is a different claim from 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 and it is labeled as one. The four tiers and what each measures are on Improve geocode precision.

A fourth field, candidates, lists 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. places the answer was built from, and it holds more than one when several match the resolved scope: Springfield, IL returns three — the citylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighborhood in the hierarchy., a township of the same name, and a second Springfield about 8 km north. It is not a record of everything 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. looked at, though. A bare Springfield returns one entry, 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. holds 92.

Two consequences follow for code that consumes this. Branch on the tier rather than on the coordinate looking plausible, because 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. is a valid coordinate in the middle of the wrong claim. And when a building's identity matters — the same structure under two addresses — compare resolved components and the hierarchy rather than comparing coordinates, since two entrances on two streetsstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. can sit tens of meters apart and two records for the same door can differ by more than that.

What it costs​

The main cost is that "the" address stops being available. Software that has to pick one is making an administrative choice on the user's behalf, and the useful version of that choice is an explicit one: this pipelinestaged pipelineMailwoman's runtime architecture: a sequence of pure-function stages (normalize → query-shape → locale-gate → kind-classifier → phrase-grouper → classifier → decoder) connected by typed handoffs. Each stage is published as its own npm package. stores the postal form, this map shows the entrance, and the join between them is a place identifier rather than a string.

There is a data-side limit worth stating too. A postal town resolves only if 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. carries it as a place under that name, at a rank 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. treats as a localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighborhood in the hierarchy.; a name filed under a different rank, or under a canonical form that differs from the postal one, can miss even when the place plainly exists. Read hierarchy on the result to see which place answered, instead of assuming the name in your input is the name that matched.

  • What an address is — why an address is an instruction to an organization, not a property of the building.
  • Postcodes and ZIP Codes — why two 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. assign different codes to one structure.
  • PO boxes and other non-street addresses — the case where the address has no building at all.
  • Improve geocode precision — the tier ladder, run end to end.