How Mailwoman resolves a place

The parsing page ends with a handoff: a tree of labeled 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. (this text is a localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy., this one 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.) and no coordinates anywhere. Resolution is the second half of the job. If you've run PeliasPeliasAn open-source geocoder, Mailwoman's spiritual predecessor. or Nominatim, you already know its raw materials: 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., an admin hierarchy, population-weighted ranking. Mailwoman keeps all three. The part worth a page is what happens around them: the parse treeparse treeThe hierarchical address structure produced by decoding BIO labels into spans and nesting them per the schema's containment rules (house_number → street → locality → region → country). is checked against the map, the map is allowed to talk back, and the coordinate you get names its own 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..

As before, one address through the whole thing, captured verbatim:

mailwoman geocode "413 S 8th St, Springfield, IL 62701" --format text

input:            413 S 8th St, Springfield, IL 62701
resolution_tier:  address_point
coordinate:       39.797779, -89.645386
uncertainty_m:    1
locality:         Springfield
region:           IL
postcode:         62701
hierarchy:
  locality             Springfield [wof:85940429] (39.7710, -89.6539)
  region               IL [wof:85688697] (40.1242, -89.1486)

That's Abraham Lincoln's house. The rest of this page accounts for those lines: which of America's many Springfields, why the coordinate is a 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. rather than a city centroidlocality centroidThe representative centre point of a city or locality, used as a coarse coordinate when no exact address point is available — the coarsest tier of the geocode cascade., and what uncertainty_m: 1 is promising.

What resolution adds

The 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. asserted that "Springfield" is used as a localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy.. Resolution asks the question the 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. deliberately avoided: which Springfield, of the ones that exist? Three things come back. Identity: each resolved node is stamped with the winning place's stable WhosOnFirst ID, so the result plugs into anything else that speaks 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.. A coordinate, from the finest data available (here a 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., elsewhere perhaps only a town centroid). And objections: when the map contradicts the 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 conflict is surfaced rather than averaged away.

You can watch the decoration land on the same tree the 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. page ended with (mailwoman parse --resolve, XML projection):

<address raw="413 S 8th St, Springfield, IL 62701">
	<region start="27" end="29" conf="0.92" src="resolver:region:85688697" lat="40.124199" lon="-89.148632" place="wof:85688697">IL
		<locality start="14" end="25" conf="0.95" src="resolver:locality:85940429" lat="39.770987" lon="-89.653852" place="wof:85940429">Springfield
			<street start="6" end="9" conf="0.94">8th
				<house_number start="0" end="3" conf="0.89">413</house_number>
				<street_prefix start="4" end="5" conf="0.96">S</street_prefix>
				<street_suffix start="10" end="12" conf="0.90">St</street_suffix>
			</street>
			<postcode start="30" end="35" conf="0.90">62701</postcode>
		</locality>
	</region>
</address>

The 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., offsets, and confidences are the parser's, untouched. What's new is place=, the coordinates, and the src= attribution flipping to resolver, with the classifier's original claim preserved in metadata. 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. and resolving stay separate jobs on purpose: the 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.' owns the grammar, the 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. owns the atlas, and either side can be upgraded without retraining the other. What Mailwoman is makes that argument in full.

The atlas on disk

Everything 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. consults is a read-only SQLite artifact, built ahead of time and sealed with provenance and a release date. The base layerlayerOne transformer block — attention plus a feed-forward network, with normalization and residual connections — applied to every position. Stacking layers lets the model build up richer representations; Mailwoman's encoder has 6. is WhosOnFirst — the same open 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. PeliasPeliasAn open-source geocoder, Mailwoman's spiritual predecessor. uses, chosen for stable IDs and a containment hierarchy. The reference build's admin layerlayerOne transformer block — attention plus a feed-forward network, with normalization and residual connections — applied to every position. Stacking layers lets the model build up richer representations; Mailwoman's encoder has 6. carries about 4.1 million places across 244 countries, each with alternate names, population, bounding box, and ancestor chainparent chainThe sequence of administrative parents above a place — Springfield → Sangamon County → Illinois → United States. Used to check the geographic coherence of a parse.. Beside it sit 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. shardsshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. (US 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. centroids, Dutch PC6 codes at streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels.-block grain, a GeoNamesGeoNamesA free global gazetteer combining administrative, postal, and POI data across 200+ countries. Supplements Who's On First for postcode centroids and places where WOF has gaps.-derived international tail) and the 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. layerslayerOne transformer block — attention plus a feed-forward network, with normalization and residual connections — applied to every position. Stacking layers lets the model build up richer representations; Mailwoman's encoder has 6.: about 125 million US address pointssitus dataA dataset of exact address-point coordinates (rooftop-level). Mailwoman's geocoder uses a national situs layer (124.9M US points built from state address-point sources) as the highest-precision tier of the geocode cascade. from the National Address Database and 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., sharded per stateregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality., and 26 million French points from BANBAN (Base Adresse Nationale). France's authoritative open national address register — the highest-quality training source for French addresses, with full component structure., the national address register. These artifacts are built or downloaded separately from the packages; the browser demo reads a hosted copy of the same 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. over byte-range requests, so demo and server agree.

From a span to candidates

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. walks the tree top-down. At each node whose tag names a place (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., regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality., localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy., 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.) it asks the backend one question: what places carry this name, of this type, under these constraints? Lookups are budgeted (ten per tree, five candidates each, by default), and tags with no place semantics (house_number, unit) are never queried.

Retrieval is an exact probe on normalized name keys, with a trigram index as the fuzzy netneural networkA model made of layers of simple numeric units whose connection strengths (weights) are learned from data. The transformer encoder at Mailwoman's core is a neural network. beneath it. Ranking is a strict hierarchy:

1. Exact name matches outrank partial matches. A place named exactly "Springfield" beats every "Springfield Gardens" the index also returns.
2. Within a tiertierInternal versioning of which label classes the model emits. Tier 1 is the coarse components (country, region, locality, postcode); Tier 2 adds venue, street, house_number; Tier 3 (future) would add attention, po_box, and POI venue subtyping. Historically called 'Stage 1/2/3' before the runtime-pipeline naming made that ambiguous., prominence decides — capped log-population, plus a proximity term when the caller supplies a map viewport or user location. This is the importance ranking a PeliasPeliasAn open-source geocoder, Mailwoman's spiritual predecessor. reader expects, confined to breaking ties within match quality: applied across tierstierInternal versioning of which label classes the model emits. Tier 1 is the coarse components (country, region, locality, postcode); Tier 2 adds venue, street, house_number; Tier 3 (future) would add attention, po_box, and POI venue subtyping. Historically called 'Stage 1/2/3' before the runtime-pipeline naming made that ambiguous., population pulls "ME" to Missouri (a populous partial match) over Maine (the exact one).
3. The raw text-match score is the last tiebreak. Full-text scores penalize a famous citylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy.'s long, alias-heavy index entry (measured at roughly 15 BM25 points against a tiny namesake's clean one), so the text score admits candidates to the pool but doesn't get to order them.

Under that ranking, a bare Springfield with no other evidence resolves to Springfield, Missouri — the most populous holder of the name. That's the right answer to a question with no context.

The tree must agree with the map

Our query isn't a bare Springfield: the 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. nested it under a regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality.. The walk is top-down, so IL resolves first, to Illinois, and the localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. lookup below it is scoped to descendants of Illinois in the 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.'s containment graph. The Missouri Springfield never enters the pool. This is the namesake problem — which Berlin, which Warsaw — settled by the same containment logic the tree builder used to nest the 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., now enforced against the map instead of the string.

Scoping is a bet that the parent resolved correctly, so it's hedged, and the hedges carry most of the namesake work:

• An empty scope triggers one retry without the parent (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. constraint stays). 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. whose ancestor chainparent chainThe sequence of administrative parents above a place — Springfield → Sangamon County → Illinois → United States. Used to check the geographic coherence of a parse. is missing a link shouldn't turn a resolvable town into a null.
• A resolved regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. whose child localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. failed means the greedy order probably picked the wrong regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality.: a bare "ME" reads as Maine, but also as Messina, Italy. A post-walk pass re-asks the question jointly: which same-named regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. candidate has a localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. of this name under it? Both nodes are re-picked as a pair, and the swap is recorded on the node.
• An explicit 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. 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. gets the same joint treatment. For "Vienna, Austria" 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. re-picks the localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. to the same-named placevenueA 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. inside 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. the address itself names; the resolved output is the Austrian capital (48.2085, 16.3721), not a populous namesake abroad.
• A resolved 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 an anchor. 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. are unambiguous within 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. in a way town names are not. A localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. that resolves more than 50 km from its sibling 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. gets re-picked to the same-named candidate nearest that 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 none reconciles, the coordinate falls back 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 area and the node is flagged postcode_city_mismatch — the case where your input, not the map, is likely wrong. This pass exists because of a measured failure class: "06260 Saint-Pierre", one of many French Saint-Pierres, once resolved 617 km from 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..
• When nothing resolved at all, a last-resort pass re-reads the raw text against the 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. — the 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.' occasionally fragments an accented name ("Grudziądz") into piecesECE (Expected Calibration Error). A metric that measures how well a model's confidence scores align with its actual accuracy. Lower is better. Mailwoman's held-out ECE drops from 0.067 (raw) to 0.0035 (calibrated). no lookup can match — and injects the recovered localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy., marked as recovered rather than asserted.

Every pass stamps what it did into node metadata (admin_coherence_repicked, postcode_city_mismatch, span_rescore, …), and each fires only on failure, so a tree that resolved cleanly passes through byte-identical. Nothing is settled silently; you can always see which side won.

The precision ladder

Admin resolution ends at centroids. "Springfield" is a point near the middle of town: for our query, about 3 km from Lincoln's door. The ladder is what runs after the admin walk, each rung consulted only when the rung above found nothing:

1. 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. (address_point) — an exact (streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels., house 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.) match in an address-point shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row., scoped by 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 localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy.. Our example lands here: the matching row carries its own provenance (source: "overture:NAD", release: "2026-05-20.0") into the node's metadata, and uncertainty_m reports the 1 m floor — a registered address point, which no estimate is ever allowed to overwrite.
2. InterpolationinterpolationA geocoding technique that estimates a coordinate along a street segment based on the house number range. Used as the middle tier of Mailwoman's geocode cascade when exact address-point data is unavailable. (interpolated) — no exact point, but the house 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. falls within a known range along a streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. segmentsegmentA punctuation-bounded chunk of the normalized input — the comma-separated parts of 'Portland, OR' — used to give downstream stages structural context. (US TIGERTIGERThe US Census Topologically Integrated Geographic Encoding and Referencing database. Used as a corpus source for street-segment data. data). The estimate carries a priced radius: half the segmentsegmentA punctuation-bounded chunk of the normalized input — the comma-separated parts of 'Portland, OR' — used to give downstream stages structural context. length, times a per-regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. conformal calibrationconformal calibrationA calibration method that adjusts per-prediction uncertainty so a target coverage (e.g. 90%) is guaranteed on held-out data, without retraining the model. factor (1.44 in dense DC up to 3.12 in Arizona sprawl, 1.95 where unmeasured), sized so the stated radius contains the true point about 90% of the time; the raw radius covered only ~72%, a number that looked precise and wasn't.
3. StreetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. centroid (street) — for queries with no house 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. at all ("Place Bellecour, Lyon"): the center 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. itself, radius half 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.'s extent. Backed by the BANBAN (Base Adresse Nationale). France's authoritative open national address register — the highest-quality training source for French addresses, with full component structure. register today, so French 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. in practice.
4. Admin centroid (admin) — the floor that exists wherever the 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. has the place: a localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy., 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 regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. centroid, with uncertainty_m: null because no finer estimate exists to price.

The tiertierInternal versioning of which label classes the model emits. Tier 1 is the coarse components (country, region, locality, postcode); Tier 2 adds venue, street, house_number; Tier 3 (future) would add attention, po_box, and POI venue subtyping. Historically called 'Stage 1/2/3' before the runtime-pipeline naming made that ambiguous. leads the output for a reason: resolution_tier names the rung, uncertainty_m prices it, and whether that's close enough depends on your task — routing a truck needs the 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.; assigning a sales territory doesn't. How close is close enough? is the full version of that argument, with measured accuracy per rung.

What to trust, and how much

Two kinds of numbers ride on a result, answering different questions. The conf= on each 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. is the parser's ("how sure am I this text is a localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy.?"), and an isotonic-calibrated version is available, so 0.94 can mean right-about-94%-of-the-time rather than a mood. The resolve side does not compress into one score. It reports the tiertierInternal versioning of which label classes the model emits. Tier 1 is the coarse components (country, region, locality, postcode); Tier 2 adds venue, street, house_number; Tier 3 (future) would add attention, po_box, and POI venue subtyping. Historically called 'Stage 1/2/3' before the runtime-pipeline naming made that ambiguous. and radius, plus named flags where evidence conflicted, because its failure modes differ in kind, not degree:

• 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. gaps. No 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. shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. for a regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. means the ladder stops at the admin rung — and says so. The coordinate is still the right town; nothing in the output dresses a centroid up as a 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..
• Namesakes. The coherencecoherenceThe property of a parse whose resolved places form a consistent geographic hierarchy — the resolved locality really does sit inside the resolved region. passes break most of them. Where the 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.'s own hierarchy can't settle one, the runner-up candidates ride along on the node (alternatives), so a consumer can re-rank with context Mailwoman doesn't have.
• Contradictory input. postcode_city_mismatch means the address disagrees with the map — a transposed 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 stale citylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. name. The returned point is the safer of the two readings; the flag is the part worth acting on.
• Stand-in placetypesplacetypeThe Who's On First hierarchical classification of places: planet → continent → country → region → county → locality → neighbourhood. The resolver uses placetype to rank candidates — an exact locality match outranks a county-level match.. When a regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. 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. matched only a broader admin tiertierInternal versioning of which label classes the model emits. Tier 1 is the coarse components (country, region, locality, postcode); Tier 2 adds venue, street, house_number; Tier 3 (future) would add attention, po_box, and POI venue subtyping. Historically called 'Stage 1/2/3' before the runtime-pipeline naming made that ambiguous. (an Italian regione is a macroregion in 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 taxonomy), resolution_quality: "fallback" records that a coarser tiertierInternal versioning of which label classes the model emits. Tier 1 is the coarse components (country, region, locality, postcode); Tier 2 adds venue, street, house_number; Tier 3 (future) would add attention, po_box, and POI venue subtyping. Historically called 'Stage 1/2/3' before the runtime-pipeline naming made that ambiguous. stood in.

Where it's strong, where it's thin

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 claimed per localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. and only where a coordinate-graded evalevalRunning the model against a held-out golden dataset and computing per-component F1, exact-match, calibration, and resolved-coordinate error. exists; the current tiertierInternal versioning of which label classes the model emits. Tier 1 is the coarse components (country, region, locality, postcode); Tier 2 adds venue, street, house_number; Tier 3 (future) would add attention, po_box, and POI venue subtyping. Historically called 'Stage 1/2/3' before the runtime-pipeline naming made that ambiguous. table lives in the scope declaration: US and France first-class and floor-gated, fourteen more localeslocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. trained and coordinate-paneled, Japan 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.-route only. Where the 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. tierstierInternal versioning of which label classes the model emits. Tier 1 is the coarse components (country, region, locality, postcode); Tier 2 adds venue, street, house_number; Tier 3 (future) would add attention, po_box, and POI venue subtyping. Historically called 'Stage 1/2/3' before the runtime-pipeline naming made that ambiguous. have data, accuracy is a property of the data, not the 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.' — so the open frontier is 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 it's kept visible: the demo map carries a 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. overlay that fogs exactly the places 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't yet pin (the build is documented in the coverage-overlay runbook). For the measured record — 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. ladder, interpolationinterpolationA geocoding technique that estimates a coordinate along a street segment based on the house number range. Used as the middle tier of Mailwoman's geocode cascade when exact address-point data is unavailable. calibration, the postcode anchoranchor inferenceA technique where structured knowledge (postcode locations, gazetteer place names) is injected into the model as soft input features — not as deterministic overrides. The model still decides the final labels, but the anchor signal biases it toward correct admin tags., per-localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. coordinate panels — see the resolver & geo eval reports, dated so you can tell what "now" meant when each number was written down.