Skip to main content

Addressing around the world

The question​

Write a parser against US addresses and it will do well on US addresses. Point it at a German one and the 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. has moved to the end of 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. line; point it at a Japanese one and there is 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. at all. Is there a universal address grammar underneath, with local spellings on top? Or is the US shape one option among several, with no privileged status?

The analog​

Every postal system is answering the same question — how do you narrow the world to one delivery point? — and each one picked a different thing to divide by.

Divide by 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 you get the shape most English-language software assumes: 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. identifies a line, a number identifies a position along it. Divide by block and 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. becomes irrelevant: an area contains numbered blocks, a block contains numbered buildings, and the road between them is unnamed. Divide by landmark and the address becomes a route description that only works if you already know the neighborhood.

None of these is a corruption of the others. They are three answers to the same problem, adopted by 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 grew at different times under different constraints.

The tour​

Number then streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels.. 350 5th Ave — the US, the UK, Canada, Australia. The type word (Ave, Street, Road) sits at the end, which is where suffix-matching parsers learned to look for it.

StreetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. then number. Hauptstraße 5 in Germany, Kornetintie 6 in Finland. Same components, order reversed. And the type word does not have to be a suffix at all: French, Spanish and Italian put it in front (rue de Rivoli, Calle Mayor, Via Roma), while German fuses it onto the name (Hauptstraße). A rule that strips a trailing type word finds nothing to strip in three of these and mutilates the fourth.

Coarse to fine. Written in Japanese, an address starts with the prefecture and works inward, which is the reverse of the English-language convention of starting with 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. and working outward (Japan Post).

Blocks instead of streetsstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels.. Japanese addresses identify a district, then a chōmechōmeIn Japanese addressing, a district-level subdivision in the block-based chōme / banchi / gō numbering scheme, which uses area-and-block numbers instead of street names., then a block, then a building within that block — 1-1-1 is three levels of nesting, and none of the three 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. in the Western sense. There is 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. name because 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. is not 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 division. Mannheim runs a grid of lettered and numbered blocks on the same principle, and writes R 5, 6-13 where a German address elsewhere would carry 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..

No 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.. Hong Kong's domestic mail carries none. Ireland had none until Eircode launched in 2015. Where a 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. does exist, its grain varies by two orders of magnitude: an Eircode identifies one delivery point, a French five-digit code covers a commune. The Universal Postal Union publishes a per-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. description of these 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., which is the reference to reach for before assuming a shape (UPU addressing solutions).

Landmarks and directions. In parts of Central America an address is a route: a known building, then a distance and a direction. It resolves for a local carrier and for nobody else. Michael Tandy's catalogue of address falsehoods collects the examples that make this concrete, and they are the ones that break form validators first.

Collection instead of delivery. In places where door-to-door delivery is thin, the box at the post office is the address rather than a fallback from one, which makes PO boxes and other non-street addresses a primary case rather than an edge case.

The takeaway​

There is no universal address grammar, so a parser cannot hold one. What exists instead is a set of per-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. conventions, each with its own component order, its own type-word position, its own 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. shape, and its own set of components that do not appear anywhere else.

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.' can learn those conventions from data, one localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. at a time, which turns "does this parser work?" into a question that only has per-localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. answers. Which localeslocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. carry a measured claim, what that claim covers, and where the gaps are is on Locales and tiers.

What it costs​

Per-localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. learning is per-localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. work. A convention that no trainingtrainingThe process of adjusting a model's parameters so its predictions match labeled examples, by repeatedly measuring error and nudging the weights to reduce it. Distinct from inference, when the trained model is run on new input. data covers is a convention the 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.' has not seen, and its output on that input is a structural guess from position and punctuation rather than a read. That produces plausible components rather than visibly broken ones, which is the harder failure to notice.

The second cost is data, not modelling. Parsingaddress 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. a Japanese address and finding coordinates for it are separate capabilities, and open 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. 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 uneven in a way that does not track the parser's 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. at all. What ships today keeps the two lists apart on purpose.