Deciphering the Notorious Japanese Postal CSV

This article is a deep dive into the architectural nightmares found within Japan Post's data distribution. It relates to the development of posuto, a package designed to make this data actually usable.

The Source of the Chaos

Late last year, I launched posuto, a tool that transforms Japanese postal code data into a developer-friendly format. The underlying source is the official data from Japan Post, a dataset that is as ubiquitous as it is frustrating to parse.

While the mascot from Irasutoya is charming, the raw CSV files are anything but.

The "Human-Centric" Design Flaw

I first encountered the absurdity of this data when an address auto-complete form filled in a location as:

"XXX-borough (except the following buildings)"

Confused by the parenthetical, I dug into the CSV and discovered that the file contains editorial notes intended for human readers, often referencing the sequence of rows. In a field-delimited format like CSV, these notes are entirely unnecessary—a dedicated "notes" column would have sufficed.

The frustration is widespread. On Twitter, users frequently vent about this. One particularly vivid description suggests that those who believe computers should simply "obey" humans are punished in the afterlife by being forced to parse ken_all.csv for eternity.

---

The Technical Horrors: Line Splitting

The README for the dataset reveals a truly bizarre rule: if a field exceeds a certain length, the record is split across multiple lines.

The Splitting Logic

The trigger for a line break is defined as:

• Neighborhood Name $> 38$ characters
• Half-width Katakana (ﾊﾝｶｸｶﾅ) pronunciation $> 76$ characters

When this happens, the long field is truncated, and the record continues on the next line. Crucially, all other fields are duplicated on the subsequent lines.

Example of a "Split" Entry

If we imagine a very long neighborhood name, the CSV looks like this:

12345,Tokyo,Minato,This place name is really 12345,Tokyo,Minato,very long it didn't fit in 12345,Tokyo,Minato,a single line so we had to 12345,Tokyo,Minato,split it

The logic behind this is a mystery. Perhaps it was a limitation of a fixed-width buffer from thirty years ago? Regardless, the breaks are seemingly random—they don't occur at character limits or logical word boundaries.

---

Data Anomalies and Edge Cases

Not all issues are technical; some are inherent to the complexity of Japanese geography.

Comparison of Extreme Cases

The Kyoto entries are particularly wild, describing locations relative to "Up Lower Godsroad" or "Down Turtle Street." Note that the actual CSV uses a non-standard comma rather than quotes to handle these fields.

The Cleaning Checklist

To make the data usable, several "catch-all" strings must be scrubbed:

• Remove "except the following" (除外)
• Handle "surrounding area" notes
• Exception: Do NOT remove the string in Shiga (〒522-0317), where the "note" is actually the legal name of the neighborhood.

---

The Romaji Disaster

The provided Romaji (Latin script) data is of abysmal quality. I recommend using cutlet instead.

The "Alphabet Soup" Effect

The system converts text phonetically in a way that destroys existing Latin characters. For example: 大手町 JAビル $\rightarrow$ OTEMACHI JIEIEIBIRU

The logic follows this broken path:

1. JA is read as the Japanese phonetic ジェイエイ (Je-i-e-i).
2. The small ェ (e) is treated as a full-sized character.
3. The result is a phonetic transcription of an English acronym.

Other victims include:

• Roppongi Hills $\rightarrow$ Roppongihiruzu
• Sweden Hills $\rightarrow$ Suedenhiruzu

---

Final Thoughts

Wrestling with this file was a humbling experience in how much complexity can be crammed into a single CSV.

If you need this data, you can use posuto as a Python library or simply download the pre-processed JSON. If you're feeling nostalgic, Japan Post still provides tools at the bottom of their page to copy data onto IBM H floppy disks using Win3.1 or DOS.

$\text{Complexity} \propto \text{Age of Legacy System}$