The 90% trap
A geocoder that correctly parsesaddress 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. 90% of addresses sounds good. It sounds especially good when the alternative — building or buying a better one — costs engineering time or API fees. The trap is that the 10% tail is not random. It is concentrated in the populations you most need to serve: rural areas, developing economies, multifamily housing, and anyone whose address doesn't look like a suburban US single-family home.
This article is an economic argument, not a technical one. It explains why 90% 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 — and why owning your parser so you can fix your own failure modes is cheaper long-term than renting someone else's.
The 10% tail is concentrated
Geocoder accuracy varies sharply by location type:
The accuracy figures below are illustrative ranges drawn from industry experience and published geocoder evaluationsevalRunning the model against a held-out golden dataset and computing per-component F1, exact-match, calibration, and resolved-coordinate error.. They vary by provider, 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., and evaluationevalRunning the model against a held-out golden dataset and computing per-component F1, exact-match, calibration, and resolved-coordinate error. methodology. The pattern — accuracy drops sharply for rural, multifamily, and informal-addressing populations — is well-documented; the exact percentages are approximate.
| Location type | Typical geocoder accuracy | Share of US population |
|---|---|---|
| Urban single-family | > 95% | ~25% |
| Suburban single-family | > 92% | ~35% |
| Urban multifamily (apartments) | ~80% | ~15% |
| Rural routes | ~70% | ~15% |
| PO boxesPO 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. / general delivery | ~55% | ~3% |
| Tribal lands / informal addressing | ~40% | ~2% |
| New construction (last 2 years) | ~60% | ~5% |
The 90% headline accuracy comes from the top two rows — urban and suburban single-family homes, which together are about 60% of the population. The other 40% of the population experiences accuracy that ranges from "mostly works" (urban multifamily at 80%) to "effectively broken" (rural routes at 70%, tribal lands at 40%).
The distribution matters because the populations with the worst geocoder accuracy are the populations where accurate addressing matters most:
- Rural areas have the highest per-delivery cost. A misrouted package in Manhattan can be walked to the correct address. A misrouted package in rural Montana requires an hour-long round trip.
- Multifamily housing concentrates in lower-income urban areas. A geocoder that resolves to the building rooftoprooftopGeocoding precision at the building or parcel level — coordinates within a few metres — the highest tier of the geocode cascade. Sourced from address-point and situs data. but not to the apartment means delivery to the wrong 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 failure mode that disproportionately affects renters.
- Tribal lands and informal addressing are systematically excluded from the address databases that geocoders train on. The geocoder has 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 for these address formats and fails silently.
- New construction is concentrated in growth regionsregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. — exactly the places where businesses are adding customers and delivery routes are being established. The geocoder is wrong on the addresses that most need to work.
This is the inverse of the Pareto principle: the last 10% of 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. costs more than the first 90%, and the populations in that 10% are the least able to absorb the cost.
Renting vs. owning
Google's Geocoding API
| Factor | Cost |
|---|---|
| Price | $5 per 1,000 requests |
| Terms | Results cannot be cached beyond 30 days |
| 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. | Global, but variable 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. |
| Latency | ~50-200ms per request |
| Privacy | Your queries are Google's data |
| Customization | None — you get Google's ontology |
At $5/1K requests, 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. 1 million addresses per month costs $5,000. That is not a large line item for a logistics company — $60,000/year. But the dependency is total: you cannot audit the results, you cannot fix failures, you cannot cache your own correctness corrections, and your query logs train Google's 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.', not yours. If Google changes its pricing (it has, multiple times) or its terms (it has), you have no alternative.
geocode.earth / Pelias
| Factor | Cost |
|---|---|
| Price | Pay-as-you-go, ~$0.50/1K requests |
| Terms | Open-source core, hosted service |
| 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. | Global, 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. + 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. + 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. |
| Customization | You can run your own instance |
| Parser | The same rule-based engine Mailwoman forked |
geocode.earth is a better deal: the core is open-source, the licensing is more permissive, and you can run your own instance if the hosted service doesn't meet your needs. But the parser is the same PeliasPeliasAn open-source geocoder, Mailwoman's spiritual predecessor. rule engine that Mailwoman v1 was built on — it has the same tokenization-tautology ceiling. Running your own instance means you own the infrastructure but not the parser's failure modes.
What owning gets you
If you run your own parser + 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.:
- You can fix your own failure modes. When a specific address format repeatedly fails — a customer's regional addressing convention, a data source with idiosyncratic formatting — you can add 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, adjust weightsparameterA single learned number inside a model — one weight or bias. Mailwoman's encoder has roughly 30 million of them; training is the search for good values., or tune the reconciler.
- You can audit correctness. When the parser returns a result, you can trace which 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). produced it and which evidence supported it.
- You can improve over time. Every correction you make to your own data stays yours. You are not paying recurring rent on someone else's 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.'.
- You can choose your 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.. If 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.'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. is weak for your regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality., you can plug in a different 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. without changing the parser.
The cost is engineering time — building the parser, maintaining the 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. 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., 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. modelsneural 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.', integrating with downstream 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.. Mailwoman exists to make that cost lower.
Why not just use what works for the 90% and fall back for the rest?
This is the most common architecture: call Google/geocode.earth for the 90% that parsesaddress 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. cleanly, fall back to manual review for the 10% that doesn't. But the fallback cost dominates the total.
Manual address correction costs between $0.50 and $5.00 per address depending on the complexity (a call center agent, a field visit, a returned package). If the geocoder fails on 10% of 1 million addresses, that is 100,000 manual corrections at $0.50-$5.00 each — $50,000 to $500,000 per month. The API cost for the 90% is $4,500 per month (at Google's rate). The fallback cost is 10-100× the API cost.
Reducing the failure rate from 10% to 5% halves the manual-correction cost. Reducing it from 10% to 2% reduces it by 80%. The payoff is measured in manual reviews avoided. Every percentage point of parser accuracy past 90% shrinks the pile of addresses a human has to touch — which is where the thousands of dollars per month come from.
What Mailwoman's approach means for this problem
Mailwoman does not target 100% accuracy. No parser does. It targets:
- Calibrated confidence. When the parser is uncertain, it says so, instead of returning a confident wrong answer. The downstream system can decide: escalate to manual review, surface the ambiguity to the user, or accept the best guess with a caveat.
- Retrainability. When a specific address class fails, you can add it to the 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. and retrain. The 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. 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. is designed for this — the adapter pattern makes adding a new data source a few hundred lines of TypeScript.
- Component-level improvement. The policy registrypolicy registryThe per-component table that decides which classifier (rule or neural) has authority for each address component. The Ship-of-Theseus dial. lets you improve one component at a time. If the neural 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.' is weak on
regionbut strong onstreet, you can use the neural 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.' forstreetand keep the rule classifier forregion. You don't have to wait for every component to beat the baseline before shipping.
The economic argument for owning your parser is that you can make it better where you need it — the cost of the failures you can't fix at Google is higher than the cost of running your own.
See also
- The database fallacy — why the 90% that works is built on partial data
- How mail delivery actually works — the system that already handles ambiguity through human fallback
- Why a neural parser? — the technical argument for the neural approach
- The case for simple geocoders — the counterargument: when simple is the right choice