The map runs out before the country does

For about a month our resolver used one method. It takes a postcode, finds the city polygon that contains the postcode's centroid, and reads off the city. The method got the Netherlands to 95% and Germany to 93%. Then we ran it on Japan, and Japan's gazetteer data has no city polygons.

This post covers two countries where the gazetteer data is sparse, what a geocoder can still do there, and where it stops. We resolved Japan to 94% by replacing the polygon lookup with a postal-authority lookup. Korea had the opposite problem. We could place the coordinate correctly for every postcode, but we could not confirm the name of the place most of the time.

The work raised three questions:

• What do you do when the gazetteer gives you points where you expected shapes?
• Does the method that worked for Japan generalize, or did it work only once?
• What happens when the map is missing data for the part of a country you most need?

Japan has no city polygons

A few weeks ago we extracted Japan's address hierarchy from Who's On First and learned that Japanese addresses run from largest to smallest unit and have no street names. This post covers resolving them.

The European method is point-in-polygon, the simplest form of geocoding. A postcode comes with a centroid. Who's On First provides administrative polygons. You find the locality polygon that contains the centroid, and that locality is the city. The method is fast, and it worked for four European locales.

It gets Japan to 25%. It took us a long time to see why, because the failure looked like a tuning problem. We went through WOF's Japanese geometry one placetype at a time, and the same pattern held for each. The prefectures have polygons. The wards and sub-prefectures have polygons. The municipality (the 市区町村 level a postcode resolves to) is almost entirely points: a latitude and a longitude with no area.

Point-in-polygon cannot work without polygons, and tuning the containment test does not change that. Korea and Taiwan have the same gap. In all three countries, the municipality layer is points where Europe has polygons, so the European method does not transfer.

You stop asking the polygon and start asking Japan Post

Without polygons, the resolver can ask the postal authority which municipality a postcode belongs to and then look up that municipality in WOF by name. Japan Post publishes that mapping in a file called KEN_ALL. It also publishes a romanized edition whose municipality column reads SAPPORO SHI CHUO KU, in the same alphabet WOF uses for its romanized place names. That gives two romanized strings to compare.

The file took effort to retrieve. Every KEN_ALL download URL we had on record returned a 404. The replacement URLs required JavaScript and a fetch from inside Japan, so a plain script received an error page instead of data. The file itself is CP932 (Shift-JIS) encoded, even in 2025. It provides the municipality. WOF's own postcode hierarchy lacks that level. WOF stops at the prefecture, about a hundred kilometers too coarse.

The matching had one complication. Japanese municipalities are spread across several WOF placetypes. A regular city is in locality, a ward in county or localadmin, and a Tokyo special ward in borough. One placetype matched around 55% of postcodes. The full set matched 94.3% of postcodes to a real municipality, and end-to-end resolution lands between 94 and 98% depending on the gold set. That clears our 85% bar. The European locales come out of the change byte-for-byte identical, because the new path runs only for the countries that need it.

The same strategy, a build shaped to the country

This part decides whether the approach scales. The Japanese build feeds the exact same resolver strategy the European one does. We wrote only a Japan build: a different way of filling in the table the resolver already reads. The resolver code did not change. A Japanese postcode goes through the same code path as an Amsterdam postcode and comes out as a locality.

The "rule engine" design depends on this: one strategy, plus a per-country table that each country populates however its data allows. Japan populates it with names from its postal authority. We had not yet tested whether a different country, with different data, could populate the same table without a set of special cases. Korea was that test, and the results were mixed.

Korea, the same trick inverted

Korea's data is the reverse of Japan's, so its build works in the reverse order.

For Japan we had to fetch the names from a postal authority. For Korea, the GeoNames postal file already contains the postcode, the place name, the province, and a latitude and longitude in one place, without an encoding problem. The difficulty is that the names are in Hangul (추자면), while WOF's romanized spr.name for Korea uses a transliteration that may not match. A Hangul name cannot match its romanized form. That mismatch is why Korea was on our "blocked" list for a while.

That assessment stopped one step early. WOF keeps more than the romanized name. Its names table also contains Hangul: 13,120 native entries plus several thousand more filed under "undetermined language" that are also Hangul. A Hangul-to-Hangul join is therefore possible. Every Korean postcode also arrives with a coordinate, so the build can start from the coordinate and use the Hangul name as confirmation. Korea's build is point-primary. It takes the postcode's coordinate, finds the nearest WOF locality, and confirms it by name where a name exists. The first step differs from Japan's, but the output is the same table, and the resolver needed no new code. That was the property we were testing.

The coordinate and province results are strong. WOF's Korean locality layer is dense, with 21,139 localities, roughly one per village. The nearest locality to a postcode is a median of 0.96 km away. The province is exact: GeoNames' province name matches WOF's Korean region name 17 times out of 17. For 100% of Korean postcodes, we place the address in the right province and within about a kilometer of the right location. That is a reliable coarse result.

Where the map runs out

The administrative name is much weaker. The name confirms on 26% of Korean postcodes, compared with 94% for Japan. The method and the care were the same, and the difference comes from what the gazetteer contains.

Two problems cause the misses. The first is a granularity mismatch. GeoNames labels a postcode with a place at the eup/myeon/dong level, such as 추자면, Chuja-myeon. WOF's locality layer is one level finer, at the hamlet. The nearest WOF point to that postcode is a village called "Mung" inside Chuja-myeon. The coordinate is correct, but the name belongs to a smaller place. Both sources are accurate about different levels of the hierarchy, and the levels do not align.

The second problem is more serious. The largest group of misses is 구 (gu), the urban districts, such as Gangnam-gu and Haeundae-gu. For most of Seoul and Busan, the gu is the main administrative unit of the address. WOF Korea does not list gu as localities with names, so there is no locality name to confirm against. The gazetteer has the least coverage in the most address-dense part of the country. The method works, but the map lacks names where most people live, and that limits Korea today. No change to the method can match a name that is absent from the dataset.

A bug the verifier caught, and you should want it to

The first version of the Korean build reported 56% name confirmation. When we checked distances, the "confirmed" matches averaged 71 kilometers from the postcode, and a few were more than 500 kilometers away.

Korean place names recur across dozens of villages. The matcher had been accepting a name match anywhere in Korea and then taking the nearest copy. That copy could still be a province away. The fix is the same proximity limit Japan's build already used: a name counts as confirmation only if the matched place falls within that limit. That lowered the rate to the correct 26% and brought the average distance back under five kilometers. Two signals that are not independent are worse than one signal. The inflated 56% would have overstated Korea's coverage by a factor of two. Check that two signals agree independently before counting them as two.

What we keep, and what the map still owes us

The architecture worked as intended. A point-primary build and a name-primary build, for two countries whose data has almost no overlap, both feed the same resolver strategy without new resolver code. That shows the approach generalizes beyond one locale. It cannot supply place names that are missing from Who's On First.

Korea ships with its actual coverage: reliable province and coordinate, a documented 26% name tier, marked experimental and kept out of the default bundle until the name coverage improves. The source for better coverage is known. Korea's road-name database, Juso, has the gu and dong names natively. It requires a government API key, so obtaining it is a deliberate acquisition, and it is next on the list. Taiwan is further behind. GeoNames has no postal file for Taiwan (the URL returns a 404), so there is no coordinate to start from until we find another source.

The lesson from both countries is that a geocoder is limited by its reference data, and missing entries are one source of that limit. Japan's data was missing shapes, and we found another way to the answer. Korea's data is missing names in the cities, and no alternative route exists yet. Before tuning a model or a matcher, check what your reference data contains in the area you care about most. Data coverage sets the ceiling for the result.