What an address is

The question

You have a column of addresses and you want coordinates. It reads like a lookup: each string names a place, each place has a location, so the work is finding the row. Then two strings that describe the same building disagree with each other, a third turns out to contain no streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels., and a fourth resolves to a town four states from where you expected. What is an address, such that this keeps happening?

The analog

An address is an instruction for reaching a delivery point — the smallest unitunitA subdivision of a building — apartment, suite, floor — that refines a street address. Mailwoman's unit component; a designator plus identifier forms a subpremise. a postal service will deliver to. One letterbox. One post office boxPO boxA numbered mailbox at a post office used as a delivery address instead of a physical street location. Mailwoman tags it as the po_box component; structurally the same family as a subpremise.. One loading dock behind a warehouse. The UK's unitunitA subdivision of a building — apartment, suite, floor — that refines a street address. Mailwoman's unit component; a designator plus identifier forms a subpremise. 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. groups about fifteen of them, and never more than a hundred (Office for National Statistics). The US Postal Service added two digits to the ZIP+4 in 1991 so that mail could be sorted "directly to a residence or business" (USPS).

Read an address as an instruction and its shape follows. It has to narrow the world to one delivery point, in words the receiving postal service recognizes, in the order that service reads them. It does not have to describe the building, name who owns it, or place it on a map. PO Box 1234, San Francisco, CA 94119 is a complete address with no geometry in it at all: the courier's work ends at a shelf behind a counter, and the person who rents that shelf may live twenty miles away.

Why one building carries several

Once the address is an instruction rather than a property of the building, one building can be the subject of several instructions at once, each written for a different reader.

The postal service wants the form its own file accepts, which is why an office tower with enough mail volume can hold a ZIP Code of its own, and why a tenant inside it gets a distinct ZIP+4 — the last four digits identify unitsunitA subdivision of a building — apartment, suite, floor — that refines a street address. Mailwoman's unit component; a designator plus identifier forms a subpremise. as fine as "a floor or group of floors in a building, a firm within a building" (USPS Domestic Mail Manual 602). Emergency dispatch wants the entrance a vehicle can reach. A tax assessor wants 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.. A visitor wants the name on the front of the building, which is how Empire State Building works as an address for a tourist and fails as one for a sorting machine.

None of these is the shadow of a truer address underneath. They are four instructions to four organizations, and a building that touches 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., sits on a municipal boundary, or holds two hundred tenants will accumulate more of them.

What that means for software

An address string is evidence about a place rather than an identifier for one. Two strings that disagree can both be usable, and the disagreement is information: it tells you which system the string came out of.

That is the division of labor Mailwoman is built around. A 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. takes the string apart and 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. the 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. — this run of characters is a 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., that one is a localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighborhood in the hierarchy. — without deciding which postal system the writer had in mind; the labelcomponent 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. vocabularyvocabularyThe fixed set of tokens a tokenizer can produce. Mailwoman's SentencePiece vocabulary is tens of thousands of subword pieces, with byte fallback for anything outside it. is on Component tags. Attaching coordinates is a second pass over the labeled result, and it reports which tier of data answered, because 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. point and a citylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighborhood in the hierarchy. centroid are different claims that would otherwise look identical.

What it costs

Two things, and both of them bite in production.

You cannot key a record on an address string. The same delivery point will arrive spelled four ways across four source 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., and none of the four is canonical. Matching records means comparing components after a 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., not comparing text.

And a geocode that returns a coordinate has not told you that the delivery point exists. Mailwoman reads what you hand it and matches what it can against open data; the question of whether mail arrives at that address belongs to a postal authority's address file, which is a licensed 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 real letterboxes. What Mailwoman is draws that line in more detail.

Related

• Postcodes and ZIP Codes — what the routing code encodes, and why it makes a poor locator.
• Two addresses, one building — the multiple-instruction problem worked through.
• How mail gets delivered — the chain the instruction travels down, and why the format is ordered the way it is.
• Component tags — the 25 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. a 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. can assign.