What an address is

The question

You have a column of addresses and you want coordinates. It looks like a lookup: each string refers to a place, each place has a location, and the work is finding the matching row. Then two strings that describe the same building disagree, a third contains 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 away from where you expected. This page explains what an address is and why these problems keep happening.

The analog

An address is an instruction for reaching a delivery point. A delivery point is 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 delivers 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., or 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 postcode (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).

If you read an address as an instruction, its structure makes sense. It must narrow the world to one delivery point, using words the receiving postal service recognizes, in the order that service reads them. It does not need to describe the building, identify the owner, or place the building on a map. PO Box 1234, San Francisco, CA 94119 is a complete address without any geometry. 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 has several

Because an address is an instruction and not a property of the building, one building can have several addresses at once, each written for a different reader.

The postal service wants the form its own address file accepts. For that reason, an office tower with enough mail volume can have its own ZIP Code, and 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 small 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. That is why Empire State Building works as an address for a tourist and fails as one for a sorting machine.

None of these is a less accurate version of one true address. They are four instructions for four organizations. 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 have even more of them.

What that means for software

An address string is evidence about a place instead of an identifier for one. Two strings that disagree can both be usable, and the disagreement is informative: it shows which system each string came from.

Mailwoman divides the work along those lines. 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. splits the string into 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. 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. them, for example as 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. or 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. Component tags lists 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.. 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. adds coordinates in a second pass over the labeled result. That pass reports which tier of data produced the answer, 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 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. mean different things and would otherwise look identical.

What it costs

This has two consequences in production.

You cannot key a record on an address string. The same delivery point will be spelled four ways across four source systems, and none of the four is canonical. To match records, compare 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. instead of comparing text.

A geocode that returns a coordinate also does not prove that the delivery point exists. Mailwoman reads the string you give it and matches what it can against open data. Only a postal authority's address file can establish whether mail arrives at that address. That file 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 explains this limit 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.