Japan has no city polygons. The postcode resolves it anyway.
Date: 2026-06-05 Scope: the CJK resolution arenaarenaA standardized test set probing one capability: libpostal (clean canonical), perturb (noisy and degraded), postal (edge formats). Each arena answers a different question about where rule vs neural wins. — the point-geometry finding (JP/KR/TW), the pivot from point-in-polygon to authoritative name-match, and Japan landing at 94% built / 94–98% resolved.
We spent the European localeslocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. teaching a 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. to drop 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.'s centroid into a citylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy.'s polygon and read off the citylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy.. Then we pointed it at Japan, and the first thing it told us is that Japan doesn't have the polygons. The second thing it told us is that it doesn't matter.
The wall: there are no municipality polygons in CJK
The European coordinate-first recipe is point-in-polygon: take 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. centroid, find the 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. localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. whose polygon contains it, done. It got Germany to 92.6% and the Netherlands to 94.9%. It gets Japan to 25% — and it took a while to understand why, because the failure is structural, not a tuning gap.
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 administrative geometry for the CJK countries is point-based exactly where 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. resolve. We sampled the per-placetypeplacetypeThe 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. geometry and the pattern is the same across all three:
| 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. placetypeplacetypeThe 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. | maps to | JP | KR | TW |
|---|---|---|---|---|
| regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. | prefecture / provinceregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. | polygons | — | polygons |
| county | sub-prefecture / ward | polygons | 69% | 3% |
| localadmin | municipalitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. (市区町村) | 0% | 0% | 0% |
| localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. | sub-municipalitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. | ~1% | ~0.4% | ~1% |
The level 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. actually resolves to — the municipalitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. — is essentially all points, in Japan, Korea, and Taiwan alike. So point-in-polygon has nothing to contain. This isn't a Japan quirk we can special-case around; it's the shape of the whole CJK arenaarenaA standardized test set probing one capability: libpostal (clean canonical), perturb (noisy and degraded), postal (edge formats). Each arena answers a different question about where rule vs neural wins., and it means the European recipe doesn't generalize east. Confirmed, quantified, written down.
The pivot: resolve by authoritative name, not by polygon
If you can't ask "which polygon contains this point," you ask the postal authority "what's the municipalitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. for this 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 then you find that municipalitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. 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.. Japan's postal authority publishes exactly that — KEN_ALL, from Japan Post, and crucially a romanized edition whose municipalitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. column reads SAPPORO SHI CHUO KU, in the same alphabet as 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 romanized place namestoponymA proper name for a geographic place.. Authoritative, and matchable.
Getting it was its own small saga: every KEN_ALL download URL we knew was a 404, the new ones are gated behind JavaScript and a Japan-only fetch, and the file when it finally arrives is CP932/Shift-JIS from 2025. But it arrives, and it carries the one thing 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 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. hierarchy doesn't — the municipalitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy., not just the prefecture (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 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.→admin chain stops at the prefecture, far too coarse).
The build is then a different shape feeding the same machinery:
postcode → KEN_ALL municipality NAME (romanized, authoritative)
postcode → GeoNames point
name + point → match to a nearby WOF place → WOF id, with is_containing=1
That last step writes the ordinary postcode_locality table, so the existing postcode_area_resolution strategy resolves Japan with zero new 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. code. The European localeslocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. drop a centroid into a polygon; Japan matches an authoritative name to a point. Same table, same strategy, different build — which is exactly the division of labor the Geographic Rule Engine was built to carry.
The detail that moved it from 52% to 94%
The first name-match attempts capped at 52–60%, and the reason is a lesson about 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 CJK modeling: Japanese municipalities are split across 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. 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.. A regular citylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. is a locality. A designated-citylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. ward is a county or localadmin. A Tokyo special ward is a borough. Match against any single placetypeplacetypeThe 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. and you miss half 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. — Osaka's 530-0001 resolves to Kita (the correct ward) but you scored it against locality and found a town named Kita three prefectures away.
Search all the municipalitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy.-ish 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. at once — locality + county + localadmin + borough — and keep the one whose name appears in the authoritative municipalitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. string, nearest first, and it jumps to 94.9%. The granularity inconsistency that capped the single-placetypeplacetypeThe 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. match dissolves when you stop assuming 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. 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.' municipalities in one place.
Results
n = 2,000 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., scored two ways:
| measure | result | gold |
|---|---|---|
| build name-match | 94.9% | KEN_ALL (authoritative) |
| end-to-end 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. (citylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. text + 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.) | 98.5% | KEN_ALL |
| end-to-end 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., independent cross-check | 93.9% | 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. admin2 (sourced separately from KEN_ALL) |
The 93.9% is the one to trust: 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.' municipalitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. field comes from a different lineage than KEN_ALL, so a resolved place agreeing with it isn't the build grading its own homework. Japan resolves its 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. to the right municipalitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. nine times in ten, with an out-of-distribution parser and no citylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. polygons, 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 language-agnostic and the postal authority is right.
Merging Japan into the shared asset left the European localeslocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. byte-identical — Germany, France, Britain, and the Netherlands resolve exactly as before; Japan rides alongside them.
What it doesn't do yet, and what it proved
The honest edges: a bare ward name shared across cities (Chuo alone, no citylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy.) can still let the resolverresolverThe component that converts parsed address components (locality, region, postcode) into coordinates by looking them up in the gazetteer. The resolver ranks candidates by name match, population, and proximity, and returns the best-matching place with its centroid or polygon.'s exact-name tiering pick the wrong regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. over 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 realistic citylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy.-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. flow resolves at 98.5%, so it's an edge, but a proximity-gated exact 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. would close it and help the European localeslocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. too (filed separately). Korea is obtainable but its 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. names are Hangul against 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 romaji, so it wants a coordinate-match to sidestep transliterationtransliterationConverting a name from one writing system to another while preserving pronunciation (Cyrillic → Latin, for instance). Needed for multilingual address handling and corpus synthesis.. Taiwan is the real gap — no 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. postal file at all, and it isn't in the admin DB yet.
But the thing this validated is bigger than Japan. The point-geometry wall is CJK-wide, which means name-based-from-the-postal-authority isn't a Japanese workaround — it's the CJK resolution architecture, and the convention/strategy machinery already holds it: a different build for a different data shape, feeding one unchanged 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.. The European recipe didn't have to bend to fit Asia. We just wrote the second recipe and pointed the same engine at it.