Skip to main content

Regex-anchored fields

Most applications don't need a full address 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.. They need three or four fields: 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., the stateregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality., the street 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., maybe 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. Extract those with regexes. Ignore everything else. The unparsed 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. are "the rest" — available for display, labelcomponent 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. printing, and downstream processing, but not part of the 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. decision.

The approach​

  1. Identify the fields you care about. For a US e-commerce checkout: 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 tax calculation), stateregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. (for shipping zone), street 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. (for delivery point barcode), 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 (for address validation). You don't need to identify the localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. — 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. implies it. You don't need to identify the 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. — it's always the US.
  2. Write a regex for each field. 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.: \d{5}(-\d{4})? near the end of the address. StateregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality.: a dictionary of 50 stateregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. names and abbreviations, matched against 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. after 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. or before the end. Street 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.: \d+[A-Za-z]? at or near the start. 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: everything between the street 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. and the stateregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality./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..
  3. Anchor the regexes to position. A US address has a predictable order: [number] [street] [city] [state] [zip]. Don't just search for the pattern anywhere — use the expected position to disambiguate. A 5-digit number at the end of the address is 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 5-digit number at the beginning is probably a street 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. (but could be 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. in French formatting).
  4. Extract and move on. The extracted fields go to the downstream system. The unparsed 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. — the apartment number, the "Attn:" line, the company name — are preserved as raw text but not classified.

This is not address parsingaddress 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. in the Mailwoman sense. It is field extraction with positional anchors. It works because US addresses have a highly regular structure that a few well-placed regexes can exploit.

When it works​

  • You work with structured, predictable address formats. US addresses. USPS-standardized addresses from a database. Addresses from a form with separate fields that got concatenated. The format is predictable enough that positional regexes work.
  • You need a small number of fields. 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 stateregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. cover regional analysis. Street 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. 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. name cover address validation. You don't need 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. implies it. You don't need the venuevenueA named, non-address place — a business, building, park, or stadium. Mailwoman's free-text point-of-interest component, added as a Tier 2 fine label. because your addresses don't have venuesvenueA named, non-address place — a business, building, park, or stadium. Mailwoman's free-text point-of-interest component, added as a Tier 2 fine label..
  • You're in a single 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.. Positional regexes are 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.. A US regex expects [number] [street] [city] [state] [zip]. A French regex expects [number] [street type] [street name] [postcode] [city]. A Japanese regex expects [postcode] [prefecture] [city] [ward] [district] [block] [lot]. The regex set is small and per-localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for., not learned.
  • You can tolerate regex maintenance. When a new stateregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. joins (unlikely), add one dictionary entry. 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. format changes (very unlikely in the US — it's been \d{5} since 1963), update one regex. The maintenance surface is small and well-defined.
  • You need to ship today. A few regexes, a stateregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. dictionary, a positional heuristic. A few hundred lines of code. Ship in an afternoon.

What you lose​

  • The unparsed 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.. Everything between 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 and the stateregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality./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 rest." If the localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. matters for your use case, you didn't extract it. If the apartment number matters, you didn't extract it. The system can display the raw text but cannot act on it structurally.
  • Non-standard ordering. 75008 Paris, 12 rue de la République — 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 at the beginning, the street 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. is 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. type, the citylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. is after 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.. Every positional assumption is wrong. The regexes extract nothing or extract the wrong thing.
  • Multi-word streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. names. Martin Luther King Jr Blvd, 123 — is "Jr" 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 or a suffix marker? Is "Blvd" 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. type? The regex for "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 greedy — it grabs everything from the street 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. to the stateregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality./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.. If the input has extra 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. in that 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. (a building name, a dependent streetdependent streetA secondary street name required for delivery in some postal systems (notably Royal Mail), as in '6 Elm Avenue, Runcorn Road, Birmingham' where Runcorn Road is the dependent street.), the regex includes them in 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.
  • VenuevenueA named, non-address place — a business, building, park, or stadium. Mailwoman's free-text point-of-interest component, added as a Tier 2 fine label.-vs-address confusion. NY-NY Steakhouse, 123 Main St, Springfield, IL — the regex sees "123" as the street 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. and extracts "Main St" as 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. The venuevenueA named, non-address place — a business, building, park, or stadium. Mailwoman's free-text point-of-interest component, added as a Tier 2 fine label. name at the beginning is unparsed — the regex doesn't know it's there. This is correct for this input but wrong for 123 Main St, NY-NY Steakhouse where the venuevenueA named, non-address place — a business, building, park, or stadium. Mailwoman's free-text point-of-interest component, added as a Tier 2 fine label. follows the address.
  • No confidence signal. The regex matched or it didn't. There is no "I'm 60% sure this 5-digit number near the end is 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." — there is only "the pattern matched at position 45" or "it didn't match at all." When the pattern matches in an unexpected position (a 5-digit number mid-input that looks like 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. but isn't), the system has no way to flag the ambiguity.

Where Mailwoman fits​

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. (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). 2) and kind classifierkind classifierStage 2.5 of the runtime pipeline: categorizes the input into one of seven query kinds (structured_address, postcode_only, locality_only, intersection, po_box, landmark, vague) so the coordinator can route to the right parsing strategy. (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). 2.5) serve the same function as the positional anchor: "this is a US address in standard ordering." The difference is that Mailwoman learns the ordering from data rather than hardcoding it 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..

A system that starts with regex-anchored field extraction can add Mailwoman as a second pass for the extracted fields. The regex extracts 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; Mailwoman 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. it into street_prefix=W, street=Somerville, street_suffix=Ave. The regex 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.; 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. uses it as a search-space constraint on top of that.

See also​