The database fallacy

There is a persistent belief in geocodinggeocodingThe process of converting an address into geographic coordinates (latitude and longitude). Mailwoman geocodes in a multi-tier cascade: exact address-point match → street interpolation → locality centroid. Each tier is progressively coarser but more widely available.: "If we just had a database of all addresses, this problem would be trivial." The belief is wrong in three independent ways. Together, they make the database approach structurally inadequate.

Fallacy 1 — There is no master list

Every attempt to build a comprehensive address database has produced a partial, outdated, purpose-specific snapshot.

The USPS AMS

The US Postal Service maintains the Address Management SystemAddress Management System (AMS). The USPS's authoritative database of every deliverable US address (~165 million points). Licensed to commercial mailers under strict terms, not openly available — part of why an open parser can't just look every address up. (AMS), the closest thing to a master list for US addresses. It contains every delivery point the USPS recognizes — about 165 million addresses. It is not public. It is licensed to commercial mailers under strict terms. It does not include addresses that USPS does not deliver to (many rural areas, some apartment buildings that use cluster boxes with non-standard numbering). It does not include the names people use for places — only the USPS-preferred form.

National address gazetteers

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.	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.	Currency
France	BANBAN (Base Adresse Nationale). France's authoritative open national address register — the highest-quality training source for French addresses, with full component structure. (Base Adresse Nationale)	~25M addresses	Updated monthly, ~95% commune 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.
UK	AddressBase Plus (Ordnance Survey)	~40M addresses	Updated every 6 weeks, licensed
Canada	National Address Database (NADNAD (National Address Database). A US Department of Transportation dataset of structured address points, added to the training corpus as a major source of real US addresses.)	~14M addresses	Incomplete — assembled from volunteer provincial contributions
Japan	MLIT address data	~30M addresses	Comprehensive but in Japanese only
India	None	0	No national address database exists

Each is built for a different purpose: postal delivery (USPS), land registration (AddressBase), census enumeration (MLIT), or navigation (OpenStreetMapOpenStreetMap (OSM). A community-curated global map database (ODbL-licensed) with addr:* tagged features and place hierarchies. A secondary corpus source and a source of street names.). They disagree on what counts as an address. A French commune may have a BANBAN (Base Adresse Nationale). France's authoritative open national address register — the highest-quality training source for French addresses, with full component structure. entry for every building but the postal service delivers to a subset. A UK address in AddressBase may have a UPRN (Unique Property Reference Number) that no other system uses. There is no universal key.

OpenStreetMap

OSMOpenStreetMap (OSM). A community-curated global map database (ODbL-licensed) with addr:* tagged features and place hierarchies. A secondary corpus source and a source of street names.'s addr:* tags are volunteer-contributed, uneven in 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., and structurally different from government gazetteersgazetteerA 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.. OSMOpenStreetMap (OSM). A community-curated global map database (ODbL-licensed) with addr:* tagged features and place hierarchies. A secondary corpus source and a source of street names. tags individual buildings (addr:housenumber=12, addr:street=République) rather than mailing addresses. An apartment building with 50 unitsunitA subdivision of a building — apartment, suite, floor — that refines a street address. Mailwoman's unit component; a designator plus identifier forms a subpremise. is one OSMOpenStreetMap (OSM). A community-curated global map database (ODbL-licensed) with addr:* tagged features and place hierarchies. A secondary corpus source and a source of street names. node with one housenumber. The mailing addresses for those 50 unitsunitA subdivision of a building — apartment, suite, floor — that refines a street address. Mailwoman's unit component; a designator plus identifier forms a subpremise. (Apt 1A through Apt 5J) are not in OSMOpenStreetMap (OSM). A community-curated global map database (ODbL-licensed) with addr:* tagged features and place hierarchies. A secondary corpus source and a source of street names..

OSMOpenStreetMap (OSM). A community-curated global map database (ODbL-licensed) with addr:* tagged features and place hierarchies. A secondary corpus source and a source of street names. is a collaborative map of the physical world, not an address database — it was never designed to be one.

The union of all sources

If you combine USPS AMSAddress Management System (AMS). The USPS's authoritative database of every deliverable US address (~165 million points). Licensed to commercial mailers under strict terms, not openly available — part of why an open parser can't just look every address up. + OSMOpenStreetMap (OSM). A community-curated global map database (ODbL-licensed) with addr:* tagged features and place hierarchies. A secondary corpus source and a source of street names. + BANBAN (Base Adresse Nationale). France's authoritative open national address register — the highest-quality training source for French addresses, with full component structure. + NADNAD (National Address Database). A US Department of Transportation dataset of structured address points, added to the training corpus as a major source of real US addresses. + WOFWOF (Who's On First). An open-source gazetteer of places maintained by Mapzen/whosonfirst. Mailwoman builds a custom SQLite database from WOF GeoJSON repos, extended with postcode data, importance scores, and coincident-role relations. + OpenAddressesOpenAddresses (OA). A global open aggregation of address points collected from many official sources. A primary source of component-supervised training data outside proprietary registries. + TIGERTIGERThe US Census Topologically Integrated Geographic Encoding and Referencing database. Used as a corpus source for street-segment data. + every stateregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality.-level 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. dataset, you get a superset that still has gaps. Rural routes, informal settlements, new construction, addresses in administrative transition — these are systematically underrepresented in every source because they are hard to collect. The union is larger than any single source but the missingness is correlated across sources, not independent. Combining them doesn't fill the gaps — it makes the known-unknowns more visible.

Fallacy 2 — Addresses are not coordinates

An address is a social protocol for directing a human courier, not a geographic coordinate. Multiple protocols coexist on the same building:

System	Address for 350 Fifth Avenue, New York
USPS mailing	350 5th Ave, New York, NY 10118
911 emergency	350 5th Ave, Manhattan, NY 10001
Utility billing (ConEd)	350 5th Ave, New York, NY 10001-0001
Building management	Empire State Building, 350 Fifth Avenue
What a tourist types	Empire State Building, NYC

All five refer to the same physical building. A database that stores only the USPS form will not match a tourist query. A database that stores only the mailing address will misroute a 911 call. A database that tries to store all five forms needs a data 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 treats them as equivalent — and that equivalence is a human judgment, not a database join.

The ZIP code problem

ZIP codes are carrier routescarrier routeThe delivery path one postal carrier covers on a shift. A ZIP code is fundamentally a set of carrier routes, not a geographic polygon, which is why ZIP boundaries are fuzzy and shift over time., not areas. USPS draws them for delivery efficiency, not for geographic coherencecoherenceThe property of a parse whose resolved places form a consistent geographic hierarchy — the resolved locality really does sit inside the resolved region.:

• ZIP codes change when carriers retire and routes get redrawn.
• ZIP codes can overlap (different carriers serve different sides of the same streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels.).
• ZIP codes can have holes (a building served by a different post office than the surrounding area).
• A single ZIP code can spanspanA 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. multiple municipalities and multiple counties.

The US Census Bureau publishes ZIP Code Tabulation Areas (ZCTAsZCTA (ZIP Code Tabulation Area). The US Census Bureau's polygon approximation of a ZIP code, generalized from census blocks rather than USPS delivery routes. Explicitly not USPS ground truth and often wrong in rural areas.) as a statistical approximation — generalized polygons that roughly correspond to ZIP code delivery areas. ZCTAsZCTA (ZIP Code Tabulation Area). The US Census Bureau's polygon approximation of a ZIP code, generalized from census blocks rather than USPS delivery routes. Explicitly not USPS ground truth and often wrong in rural areas. are not USPS ground truthground truthThe correct answer for an example, used as the standard a prediction is graded against. Mailwoman's ground truth is the hand-labeled golden set; its quality caps achievable accuracy.. USPS explicitly does not publish ZIP code boundaries as polygons. Any geocoder that treats a ZIP code as an area is using an approximation of an approximation.

The postcode problem (international)

Non-US postal codes are even less polygon-like:

• UK 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. (e.g., SW1A 1AA) cover about 15 addresses on average — small enough to be effectively points, but not routing areas.
• Canadian postal codes (e.g., K1A 0B1) cover one side of one block faceblock faceOne side of a street between two intersections. Several postal systems specify delivery to block-face granularity — e.g. the USPS ZIP+4 extension. in urban areas, or an entire rural route.
• Irish 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. (Eircode) are unique per delivery point — each address gets 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.. 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. IS the address.
• French 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. (e.g., 75008) correspond to commune boundaries — they are effectively municipal codes that happen to use 5 digits.

A geocoder that treats 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. as polygons will produce different error characteristics in every 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..

Fallacy 3 — Administrative boundaries drift

Municipalities annex, de-annex, incorporate, dissolve, and rename themselves. 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. get split. StreetsstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. get renamed. The half-life of an address is about 5 years in any urban area — after 5 years, roughly half of the addresses in a fast-growing citylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. have changed in some administratively meaningful way.

What changes	How often	Example
MunicipalitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. annexation	Annual	Austin, TX annexed ~50 sq mi between 2010-2020
StreetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. renaming	Ongoing	"Malcolm X Boulevard" replaces "Reid Avenue" in Brooklyn
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. split	As needed	90210 split into 90210 and 90211 when volume exceeded capacity
New construction	Continuous	~1.4M new US housing unitsunitA subdivision of a building — apartment, suite, floor — that refines a street address. Mailwoman's unit component; a designator plus identifier forms a subpremise. per year
Building renumbering	Rare but impactful	Entire blocks renumbered when addressing standards change

A database snapshot taken in 2024 is wrong in 2026 for some fraction of its entries. The error is not random — it concentrates in the places that are changing the most: growing cities, developing economies, regionsregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. with active administrative reform. These are exactly the places where geocodinggeocodingThe process of converting an address into geographic coordinates (latitude and longitude). Mailwoman geocodes in a multi-tier cascade: exact address-point match → street interpolation → locality centroid. Each tier is progressively coarser but more widely available. accuracy matters most.

The maintenance cost

Keeping a national address database current requires continuous field data collection, integration from municipal building-permit 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., USPS change-of-address feeds, and manual correction of user-reported errors. The USPS spends about $1 billion per year on address management. The UK's Ordnance Survey spends about £150 million. France's BANBAN (Base Adresse Nationale). France's authoritative open national address register — the highest-quality training source for French addresses, with full component structure. is maintained by a consortium of government agencies and La Poste.

For a geocoder that consumes these databases, the maintenance burden is lower — you pull updates from upstream sources. But you are still dependent on those upstream sources staying current, staying funded, and staying in a format you can consume. When the UK's AddressBase licensing terms changed in 2020, several open-source geocoders had to drop UK 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. entirely.

What this means for a parser

The parser should not try to be a database — it should not store every address, or attempt to resolve "Springfield" to a coordinate without context.

The parser's job is to extract structured components from a string — to say "this tokentokenOne word or subword in the tokenized input. For the neural classifier, tokens come from SentencePiece (subword units); for the rule classifiers, tokens are whitespace- and punctuation-separated words. is a localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy., this tokentokenOne word or subword in the tokenized input. For the neural classifier, tokens come from SentencePiece (subword units); for the rule classifiers, tokens are whitespace- and punctuation-separated words. is a regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality., and their relationship to each other is administrative containment." 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.'s job is to look up those components in 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. and return candidates with confidence scores. 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. can be updated independently of the parser when gazetteersgazetteerA 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. change.

A parser that tries to memorize addresses will be wrong on every address that changed since 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. data was collected. A parser that learns the structure of addresses — what tokenstokenOne word or subword in the tokenized input. For the neural classifier, tokens come from SentencePiece (subword units); for the rule classifiers, tokens are whitespace- and punctuation-separated words. look like, how they group, what ordering patterns are statistically likely — will generalize to new addresses in new construction in renamed municipalities. The database fallacy is the belief that the first kind of parser can be made complete. It can't, and there's no reason to build one that tries.

See also

• How mail delivery actually works — the system that doesn't need a perfect database either
• The 90% trap — why 90% database 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 deceptively expensive
• The tokenization tautology — why traditional parsers fall into a related completeness trap
• What is an address? — the data 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.' these databases attempt to capture
• Falsehoods about addresses — the falsehoods catalogue, organized by category