k-vote-cli: una CLI para obtener datos públicos de elecciones de Corea con un solo comando y sin clave de API

Los resultados del escrutinio, las encuestas de opinión y la participación electoral son públicos por ley, pero al intentar obtenerlos directamente, la accesibilidad no es buena.

El Sistema de Estadísticas Electorales (info.nec.go.kr) bloquea por completo el acceso automatizado mediante robots.txt; los archivos están codificados en EUC-KR y cada elección tiene formatos de Excel distintos; para las encuestas de opinión solo hay PDFs en foros, sin una API oficial; y la OpenAPI requiere solicitud de uso y emisión de clave de autenticación para cada conjunto de datos.

Lo creé con la intención de mejorar la accesibilidad incluso de datos que ya existen. Solo usa canales oficiales de distribución de la Comisión Nacional Electoral (datos de archivos en data.go.kr) y no elude sitios bloqueados por robots.

Funciones principales:

• kvote nec corpus --normalize — descarga simultáneamente los principales resultados históricos de escrutinio (elecciones presidenciales 16.ª, 17.ª y 21.ª; elecciones legislativas y representación proporcional; elecciones locales 5.ª a 8.ª) y los normaliza a JSONL por unidad de centro de votación. Incluye decodificación EUC-KR, manejo de duplicados en centros de votación con el mismo nombre y separación entre voto del día de la elección y voto anticipado
• kvote nesdc sync / bulk — recopilación completa de encuestas de opinión, serie temporal de más de 1,400 registros acumulados de apoyo a partidos (desde 2023.10) y tablas cruzadas de composición muestral (sexo·edad·región × completados/ponderados)
• kvote nec turnout-analysis — normalización de la participación electoral por sexo y grupo etario (ejes demográficos que no están en los resultados del escrutinio)
• kvote db / kvote mcp — carga en SQLite local + consultas SQL de solo lectura; incluye un servidor MCP integrado para que agentes como Claude Code puedan realizar directamente exploración→recopilación→SQL
• Las OpenAPI que requieren clave de autenticación automatizan la solicitud de uso con kvote api login/apply

El principio de diseño es uno solo: conservar los datos originales tal cual y agregar únicamente valores calculados estándar con definiciones explícitas (participación electoral, porcentaje de votos, votos válidos). No incorpora ninguna interpretación ni juicio. Si se ejecuta el mismo comando, cualquiera obtiene los mismos datos.

Binario único en Go (sin cgo), licencia MIT, macOS/Linux/Windows. Se puede instalar con Homebrew y go install. Algunas funciones (recopilación de encuestas de opinión y rutas de búsqueda de datasets) dependen de la estructura HTML del portal; las roturas se revisan con kvote doctor.