k-vote-cli: CLI para obter dados públicos de eleições coreanas com um único comando, sem chave de API

Resultados de apuração, pesquisas de opinião e taxas de comparecimento são públicos por lei, mas, na prática, acessá-los diretamente não é fácil.

O Sistema de Estatísticas Eleitorais (info.nec.go.kr) bloqueia totalmente o acesso automatizado via robots.txt; os arquivos usam codificação EUC-KR e cada eleição tem um formato de Excel diferente; as pesquisas de opinião estão apenas em PDFs de fórum, sem API oficial; e o OpenAPI exige solicitação de uso e emissão de chave de autenticação para cada conjunto de dados.

Criei isto com o objetivo de melhorar a acessibilidade de dados que já existem. Ele usa apenas canais oficiais de distribuição da Comissão Eleitoral Nacional (dados em arquivos do data.go.kr) e não contorna locais bloqueados por robots.

Principais recursos:

• kvote nec corpus --normalize — baixa simultaneamente os principais resultados históricos de apuração (eleições presidenciais 16ª, 17ª e 21ª; eleições gerais e proporcionais; eleições locais da 5ª à 8ª) e normaliza em JSONL no nível da seção eleitoral. Inclui decodificação EUC-KR, tratamento de duplicatas em seções eleitorais com o mesmo nome e separação entre votação no dia e votação antecipada
• kvote nesdc sync / bulk — coleta completa de pesquisas de opinião, série temporal com mais de 1.400 registros acumulados de intenção de voto por partido (desde 2023.10) e tabelas cruzadas de composição da amostra (sexo, idade e região × concluído/ponderado)
• kvote nec turnout-analysis — normalização da taxa de comparecimento por sexo e faixa etária (eixos demográficos ausentes nos resultados de apuração)
• kvote db / kvote mcp — carga em SQLite local + consultas SQL somente leitura; servidor MCP integrado, permitindo que agentes como Claude Code executem diretamente exploração → coleta → SQL
• OpenAPIs que exigem chave de autenticação têm a solicitação de uso automatizada por kvote api login/apply

O princípio de design é um só: preservar os dados brutos como estão e acrescentar apenas valores calculados padronizados com definição explícita (taxa de comparecimento, percentual de votos, votos válidos). Nenhuma interpretação ou julgamento foi incluído. Ao executar o mesmo comando, qualquer pessoa obtém os mesmos dados.

Binário único em Go (sem cgo), licença MIT, macOS/Linux/Windows. Pode ser instalado via Homebrew e go install. Alguns recursos (coleta de pesquisas de opinião, caminhos de busca de datasets) dependem da estrutura HTML dos portais, e quebras podem ser verificadas com kvote doctor.