Skip to main content

Postcode-only geocoding

The fastest geocoder extracts 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., looks it up in 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.-to-coordinate table, and returns the centroid. It doesn't parseaddress 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. 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., the building number, or the localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy., because 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 most machine-readable part of any address, and for many applications, 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.-level accuracy is sufficient.

The approach​

  1. Extract 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.. For US addresses, \d{5}(-\d{4})? near the end of the string. For UK, [A-Z]{1,2}\d[A-Z\d]? \d[A-Z]{2}. For France, \d{5} in a specific position. One regex 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., or a small 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. patterns.
  2. Look up 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.. A table mapping 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. → (lat, lon, citylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy., stateregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality.). For the US, the Census Bureau's ZIP Code Tabulation Area (ZCTAZCTA (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.) file. For the UK, the ONS Postcode Directory. For France, the La Poste code postal database.
  3. Return the centroid. 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.'s representative coordinate. For a ZIP code covering 50 square miles, this is off by up to several miles. For a 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. covering ~15 addresses, this is off by ~50 meters. 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. varies by 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..

That's it. Three steps, each deterministic, each trivially updateable when a new 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 assigned. The rest of the address — 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., the building number, the apartment — is for the delivery driver, not the geocoder.

When it works​

  • You need rough geographic distribution. A marketing campaign targeting "customers in 90210." A delivery zone analysis. A regional sales territory assignment. 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.-level accuracy is sufficient for statistical aggregation and regional routing.
  • You're in 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. with precise 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.. 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. cover ~15 addresses on average. Irish Eircodes are unique per delivery point. Canadian postal codes 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 these countries, 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.-only 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. is nearly building-level.
  • You're in the US and your use case is regional. ZIP-level 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. in Manhattan is off by a few blocks. ZIP-level 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. in rural Montana is off by 10-15 miles. If your application needs "which stateregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality./county is this in?" not "which building is this at?", ZIP centroids work.
  • You have the rest of the address for non-geographic use. 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. and building number are for printing shipping labelscomponent tagOne of the 33 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., not for 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.. The geocoder only needs to answer "which delivery zone?" and 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. answers that.
  • You need speed. A regex extraction + hash table lookup is microseconds per address. You can geocode millions of addresses on a laptop.

What you lose​

  • Everything finer than 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.'s resolution. In rural US, this is miles. In dense urban areas, a ZIP code can cover multiple distinct neighborhoods with different demographic profiles. Aggregating by ZIP centroid loses the fine-grained signal.
  • Addresses without 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.. Ireland before 2015 (Eircode launch). Hong Kong. Rural routes in developing countries. Military addresses (APO/FPOAPO/FPO (Army Post Office / Fleet Post Office). US military postal addresses for personnel stationed overseas or aboard ship. They route through military postal hubs rather than geographic locations, so they break geographic parsing assumptions.). The regex extracts nothing, the lookup returns nothing, the geocoder fails.
  • 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.. ZIP code 33334 covers Oakland Park, Wilton Manors, and Fort Lauderdale. The centroid is in one of them. The other two are wrong. The geocoder returns one citylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. for 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. that serves three.
  • 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. that change. USPS changes ~5,000 ZIP codes per year. 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.-to-coordinate table built in 2024 has stale entries in 2026. The table must be updated continuously to stay current.
  • No validation of the rest of the address. The geocoder returns a coordinate for 90210 regardless of whether 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. exists in Beverly Hills. 123 Fake St, Beverly Hills, CA 90210 geocodes to the 90210 centroid, silently accepting a nonexistent streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels..
  • The user's expectation. A user who types their full address and gets a coordinate expects sub-building accuracy. A ZIP centroid feels like a wrong answer even when it's the best the system can do. The geocoder has no way to signal "this is ZIP-level accuracy, not address-level."

Where Mailwoman fits​

Mailwoman's 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. treats 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. as supplementary evidence, not a primary locator. When 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 present, 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. limits 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. lookups to 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.'s rough administrative area — the same information 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.-only approach uses. But Mailwoman also uses the parsed localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy., regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality., and streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. to narrow the candidate set further. 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. + localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. + regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. match is more precise than 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. alone.

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.-only approach and Mailwoman are not competitors. A system that starts with 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.-only 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. and later needs finer resolution can add Mailwoman as a second pass: 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.-only for the 90% of addresses where ZIP-level accuracy is sufficient, Mailwoman for the 10% where a specific building matters. 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. extracted by the regex feeds directly into Mailwoman's locale gatelocale gateStage 2 of the runtime pipeline: rule-based locale detection from the query shape's script and known-format signals. Returns a LocaleHint with the top candidate and alternatives, surfacing disagreement with an explicit --locale flag. and 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. constraints.

See also​