Skip to main content

Falsehoods about addresses

The question​

Every address validator starts as a short list of reasonable rules. House numbershouse 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. are numbers. StreetsstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. end in Street or Road. Every address has a town and 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.. The list is reasonable because it describes the addresses the person writing it has seen. Which assumptions on that list are wrong, and how wrong?

Where this comes from​

Michael Tandy has maintained a catalogue of address falsehoods since 2013, and the UK and Dutch counterexamples below are drawn from it. The framing worth keeping is his: these are the cases a rule set fails on first, and they arrive in production data at a rate that makes them ordinary rather than exotic.

Each line is one assumption and one address that breaks it.

Format​

  • Addresses are ASCII. 東京都千代田区丸の内1-1-1 is a Tokyo address. A validator built on [a-zA-Z] for names and \d for numbers cannot see it at all.
  • Punctuation can be stripped. The Hague's Dutch name is 's-Gravenhage. Strip the leading apostrophe and you have a different word. A Devon village is spelled Westward Ho!, exclamation mark included.
  • Components come in a fixed order. Germany writes 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. after 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. name. Japanese addresses start at the prefecture and work inward. The order is a local convention, not a property of addresses.
  • An address fits in five lines. A UK government office address carrying a department, a division, a building name, an industrial estate, a town and 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. runs to eight.
  • Place namestoponymA proper name for a geographic place. contain no rude words. Scunthorpe and Penistone are real English towns, and profanity filters reject both.

Streets​

  • 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. name ends in a type word. Piccadilly, Broadway, Strand. Three of the best-known streetsstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. in the English-speaking world carry no suffix.
  • There is exactly one type word, and it comes last. rue de Rivoli puts it first. Avenue Road in Toronto is built from two of them, so a suffix-stripping pass leaves nothing behind.
  • 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. name contains no digits. Plein 1944 in Nijmegen is named after a year, and it takes house numbershouse 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. after that year.
  • 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. name is unique within a citylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighborhood in the hierarchy.. London has sixteen streetsstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. whose name is some form of High Street — plain in several postcodespostcodeThe 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., with a place folded in elsewhere, like Islington High Street and Camden High Street — so High Street, London alone never picks out a single one.
  • Every address has 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.. Japanese addresses number blocks rather than streetsstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels.. Mannheim writes R 5, 6-13, where R 5 is a block in a lettered grid.

Numbers​

  • Building numbers are positive integers. 0 Egmont Road, Middlesbrough exists. So do hyphenated ranges such as 4-5 Bonhill Street, London, and half-numbers, which appear as 43 1/2, 43.5 or 43½ depending on which database you are reading.
  • A number at the front of the address is the building number. Minusone Priory Road, Newbury has no building number. The word is part 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. name.
  • 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. and a number identify one place. There are two 50 Ammanford Road addresses about four miles apart, in different towns, under different postcodespostcodeThe 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..
  • A spelled-out number equals its digits. Ten Post Office Square and 10 Post Office Square in Boston are different buildings. Normalizing one to the other merges two locations.
  • Leading zeros can be dropped. Apartment 001 and apartment 1 have been different apartments on different floors of the same building.

Postcodes​

  • PostcodespostcodeThe 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. are numeric. SW1A 1AA in the UK, K1A 0B1 in Canada, D02 X285 in Ireland.
  • PostcodespostcodeThe 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. do not start with zero. 02109 is Boston. In France 06130 is Grasse and 6130 routes to a different département, so an integer column silently relocates the address.
  • 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. names one town. The US Postal Service publishes preferred and acceptable citylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighborhood in the hierarchy. names for a ZIP Code, so one code carrying several town names is the design rather than a data defect.
  • 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. covers a group of buildings. A ZIP+4 can identify "a firm within a building" (USPS), and a building with enough mail volume holds a ZIP Code of its own. In the other direction, one Irish Eircode is one delivery point.
  • Every address has 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., and postcodespostcodeThe 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. hold still. Ireland had none before Eircode launched in 2015 and Hong Kong uses none domestically, while UK 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. boundaries change continuously as addresses are built and mail volumes shift (ONS).

Hierarchy​

  • Every address has a state. No UK, French or Japanese address carries a level that corresponds to one.
  • Every address has a county. UK addresses have not formally required one since 1996, when automated 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. sorting made it redundant (Post & Parcel, 2010).
  • A town name is unique within 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.. Count the primary citylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighborhood in the hierarchy.-rank names in the candidate 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. build this shelf was measured against (candidate-global-1026.db) and the US holds 92 distinct places called Springfield: 86 of them across 33 states, and six with no state recorded against them at all — an absence in 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. rather than a fact about those six places. Springfield on its own is a 92-way question.
  • The postal town is the municipalitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighborhood in the hierarchy.. 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; the municipalitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighborhood in the hierarchy. is New York. Both are correct, for different readers.
  • Administrative boundaries hold still. The county of Gwent was abolished. Annexation moves a building into a new municipalitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighborhood in the hierarchy. without moving the building, and the postal town can lag the legal one by years.

What they have in common​

Every line above is a place where a person reading the address sees what is going on and a pattern cannot. That is the argument for learning the distribution rather than enumerating the rules: a rule set has to name each case, and the cases combine — a Cyrillic 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, in a non-English order, with an apostrophe in it, in a town that was renamed last year.

Learning has its own version of the same limit, and it is worth stating plainly. 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.' that has seen no fractional house numbershouse 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. will not invent the category; it will assign the piecesECE (Expected Calibration Error). A metric that measures how well a model's confidence scores align with its actual accuracy. Lower is better. Mailwoman's held-out ECE drops from 0.067 (raw) to 0.0035 (calibrated). to whatever 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. its 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. distribution makes likely. The counterexamples above are useful to 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.' only insofar as the 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. corpuscorpusThe BIO-labeled training data used to train Mailwoman's neural classifier. Assembled from real sources (OpenAddresses, National Address Database) and synthetic shards (boundary stress, order variants, negative space). Managed by @mailwoman/corpus. contains their shapes, which is why localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. claims here are made per localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. and measured rather than asserted for the world (Locales and tiers).

  • Addressing around the world — the conventions these assumptions come from.
  • Postcodes and ZIP Codes — the 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. section, at length.
  • Two addresses, one building — the hierarchy section, at length.
  • Handle messy input — what the 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. repairs today, and what it leaves alone.