Falsehoods programmers believe about addresses
This article series is inspired by and cites Michael Tandy's original catalogue of address falsehoods, maintained since 2013. Tandy's article is a taxonomy of assumptions that break parsers, validators, and databases. This series expands on that taxonomy, adding historical context on how geocoders have handled (or failed to handle) each category, and what Mailwoman's neural approach changes.
The falsehoods are the central cases
Tandy's falsehoods are not edge cases. They are the central cases that rule-based geocoders fail on. Each falsehood is a place where a human can see what's happening ("that's a building number, even though it's a fraction") but a regex cannot. The thesis of Mailwoman's neural approach is that 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.' trained on diverse address data can learn to handle these cases without explicit rules, including combinations of falsehoods that no rule set could enumerate.
Mailwoman is not the first project to notice this. Deepparse (2020) showed that a BiLSTM could match libpostallibpostalAn open-source C address parser used by Pelias. Mailwoman's rule-based v0 and neural classifier supersede it. on structured addresses. The academic literature since has confirmed that transformersneural 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.' beat CRFsCRF (Conditional Random Field). A statistical modeling method that predicts structured outputs by modeling dependencies between adjacent labels. Mailwoman uses a linear-chain CRF as the Viterbi decoder at inference time to enforce BIO label consistency — a B-street must be followed by I-street or O, never I-locality. on noisy and multilingual address data. What Mailwoman adds is a staged pipeline that separates concerns: a phrase grouperphrase grouperStage 2.7 of the runtime pipeline: proposes coherent input units (street phrase, locality phrase, postcode, etc.) with structural kind hypotheses. Decouples boundary discovery from type classification so the classifier answers 'what type?' not 'where?' proposes boundaries, a neural classifierneural 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.' types 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., a CRFCRF (Conditional Random Field). A statistical modeling method that predicts structured outputs by modeling dependencies between adjacent labels. Mailwoman uses a linear-chain CRF as the Viterbi decoder at inference time to enforce BIO label consistency — a B-street must be followed by I-street or O, never I-locality. enforces sequence validity, and a reconciler checks joint coherencecoherenceThe property of a parse whose resolved places form a consistent geographic hierarchy — the resolved locality really does sit inside the resolved region. against a 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.. Each stagestageOne of the dataflow stages in the runtime pipeline (normalize, locale gate, kind classify, phrase group, token classify, sequence correct, reconcile, resolve). Distinct from tier (model vocabulary) and phase (plan milestone). handles a different class of falsehood without the others needing to know about it.
Categories
Each article in this series takes one category of falsehood, explains what traditional geocoders assumed, what counterexamples broke those assumptions, and how Mailwoman's architecture addresses the class of problem rather than the individual counterexample.
| Category | Article | What it covers |
|---|---|---|
| Numbers | Falsehoods about numbers in addresses | Zero, negative, fractions, duplicates, ranges, names that 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. | Falsehoods about street names | Missing suffixes, numbered streetsstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels., recurring names, addresses with no streetsstreetThe 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 |
| 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. | Falsehoods about postcodes | Leading zeros, multi-citylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. 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., per-building 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., missing 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. |
| Hierarchy | Falsehoods about administrative hierarchy | No statesregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality., no counties, duplicate citylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. names, city-statesdual-role placeA place that is two placetypes at once — Berlin as both a city and a state, Washington DC as city and district. Resolved using the coincident-roles relation plus hierarchy completion. |
| Format | Falsehoods about address format | Punctuation, non-ASCII, variable ordering, mixed character sets, changing addresses |
| Shapes | Falsehoods about address shapes and dimensions | Not a point, not a polygon, not a building, not at ground level, not unique per coordinate |
| PrecisionprecisionOf the spans the model labeled as a given tag, the fraction it got right. High precision means few false positives. Paired with recall to compute F1. | Falsehoods about geocoded precision and frontages | Not one correct coordinate, not always "close enough," not the front door |
Original
If you haven't read Michael Tandy's original article, start there: Falsehoods programmers believe about addresses. It is the reference this series builds on. Every falsehood in these articles originates in Tandy's catalogue or in the operator's own production-geocoder experience. Attribution is in each article's introduction.
See also
- How mail delivery actually works — the system these falsehoods enter
- How humans break addresses — the failure taxonomy organized by root cause
- The tokenization tautology — why rule-based parsers can't handle combinations of falsehoods