ken_all.csv: el archivo de Japan Post que rompe tu parser

El CSV de Japan Post, o por qué los datos abiertos no siempre son limpios

Un único archivo público, ken_all.csv distribuido por Japan Post, concentra todo el direccionamiento postal de Japón. Cualquier startup o equipo de producto que quiera autocompletar direcciones japonesas acaba tarde o temprano descargándolo, y descubriendo el mismo problema: el archivo está deliberadamente roto para consumo programático. La desarrolladora detrás de posuto (un paquete Python que lo limpia y lo entrega en JSON listo para usar) documentó las trampas en detalle, y son una clase magistral de “datos abiertos que en realidad no lo son”.

El caso es relevante porque ilustra algo que cualquier founder que trabaje con datos de terceros va a reconocer: la calidad del dataset no se evalúa al firmar el contrato, sino el día que intentas parsearlo.

¿Qué tiene de malo ken_all.csv?

El archivo, publicado por Japan Post y actualizado periódicamente, codifica cada código postal (formato 〒XXX-YYYY) con sus barrios y sub-barrios asociados. Sobre el papel, un CSV. En la práctica, varias trampas:

• Líneas partidas sin razón. Cuando el nombre del barrio supera 38 caracteres — o el campo de katakana media anchura supera 76 — el README oficial indica que la línea se divide en varias. La continuación repite todos los demás campos y solo añade el fragmento siguiente del nombre. El punto exacto de corte, según la autora, parece aleatorio: ni cae en el límite, ni respeta fronteras de palabra. El resultado son filas que solo tienen sentido al reconstruirse manualmente.
• Notas parentéticas intercaladas. Muchas filas traen aclaraciones entre paréntesis que describen el orden de las filas siguientes (por ejemplo “excepto los siguientes edificios”). Esas notas son legibles para un humano leyendo el CSV, pero inútiles — y problemáticas — para cualquier consumidor fila a fila.
• Códigos postales “catch-all”. Algunos agrupan barrios completos con la coletilla “excepto los siguientes”, y la única manera fiable de filtrarlos es buscar esa cadena exacta. Hay variantes, y es difícil estar seguro de haberlas cubierto todas.
• Comentarios trampolín como 一円. En japonés significa normalmente “un yen”, pero también “el área circundante”, y aparece como nota a eliminar del nombre del barrio. Excepto en un barrio de Shiga (〒522-0317), donde realmente es el nombre oficial. Es el tipo de excepción que rompe cualquier heurística ingenua.
• Direccionamiento por intersecciones en Kioto. Ciertas zonas de Kioto no usan nombre de calle y número, sino referencias a intersecciones (“al norte desde tal calle, al sur desde tal otra”). El código 〒602-8368 o 〒602-8374 genera líneas continuadas de ocho filas — el récord del archivo.
• El código postal con más filas no es el de Tokio: es 〒452-0961, región Haruhi, ciudad Kiyosu, prefectura de Aichi, con 66 líneas. El motivo: cada sub-barrio tiene fila propia. Haruhi fue el municipio más pequeño de Japón por superficie entre 2006 y 2009, antes de ser incorporado a Kiyosu.

La autora resume el sentir de la comunidad con una cita recurrente en redes: hay un rincón del infierno reservado para quienes creen que los computers deben obedecer a los humanos, y consiste en parsear ken_all.csv por la eternidad.

¿Qué hace posuto y por qué importa?

posuto es un paquete Python publicado por el mismo estudio (dampfkraft) que toma el CSV crudo de Japan Post, aplica todas las correcciones necesarias — reconstrucción de líneas partidas, limpieza de notas parentéticas, filtrado de catch-alls — y expone los datos ya utilizables. Tiene dos modos de uso:

• Como librería Python importable desde cualquier proyecto.
• Como JSON pre-procesado descargable, para equipos que no trabajan en Python o que quieren servir los datos estáticamente.

Es, en esencia, un ejemplo de capa de limpieza sobre un dataset público legacy: lo que toda startup acaba escribiendo internamente cuando se enfrenta a una fuente de datos oficial “gratuita” pero mal mantenida.

El problema del archivo de romaji

Japan Post ofrece también un archivo paralelo con las lecturas en alfabeto latino. La autora lo desaconseja por dos motivos:

• Se actualiza con menor frecuencia que el CSV principal y suele estar desincronizado.
• La conversión es de muy baja calidad. Por ejemplo, 大手町 JAビル (literalmente “Edificio JA de Otemachi”) aparece transliterado como OTEMACHI JIEIEIBIRU: convierte el “JA” ya latino a su lectura fonética japonesa ジェイエイ, y convierte el ジェ (que se escribe “ji grande + e pequeña” pero se pronuncia “je”) tratándolo como si fuera un carácter grande, produciendo jie. Es decir: convierte texto que ya estaba en alfabeto latino en algo que no lo es.

La alternativa mencionada en el artículo es cutlet, otra librería Python de transliteración japonés-romaji, que convierte JAビル en JA building sin romperse. Casos similares convierten “Roppongi Hills” en Roppongihiruzu o “Sweden Hills” en Suedenhiruzu en el archivo oficial.

Qué significa esto para tu startup

Si tu producto hace autocompletado de direcciones, verificación de envíos, logística para Japón, KYC con dirección local o cualquier flujo que dependa de un dataset público de un país, la lección de ken_all.csv es universal: asume que vas a tener que limpiarlo. Tres recomendaciones concretas:

• Presupuesta siempre una capa de normalización propia, incluso cuando uses fuentes “oficiales”. Lo que节省 en licencias lo gastarás en ingeniería de datos. Trata cada dataset externo como input sucio y diseña la tubería en consecuencia.
• Versiona y congela el dataset, no lo re-proceses en cada release. Los CSV gubernamentales cambian sin aviso y, cuando cambian, rompen en producción. Un snapshot inmutable con hash conocido vale más que un “último versión” siempre fresco.
• Cuando un dataset te parece insalvable, mira si ya hay un envoltorio comunitario. posuto, cutlet y proyectos similares existen porque alguien se hartó primero. Antes de pelearte dos semanas con una codificación exótica, busca paquetes que resuelvan exactamente ese dataset.

Fuentes

• Parsing the Infamous Japanese Postal CSV (fuente original)