k-vote-cli: CLI nhận dữ liệu công khai về bầu cử Hàn Quốc chỉ với một lệnh, không cần API key

Kết quả kiểm phiếu, thăm dò dư luận và tỷ lệ cử tri đi bầu đều được công khai theo quy định pháp luật, nhưng khi tự lấy về thì khả năng tiếp cận không hề tốt.

Hệ thống Thống kê Bầu cử (info.nec.go.kr) chặn hoàn toàn truy cập tự động bằng robots.txt, các tệp dùng mã hóa EUC-KR và mẫu Excel lại khác nhau tùy từng kỳ bầu cử; dữ liệu thăm dò dư luận thì chỉ có PDF trên bảng tin chứ không có API chính thức; còn OpenAPI thì mỗi loại dữ liệu đều cần đăng ký sử dụng và cấp khóa xác thực riêng.

Công cụ này được tạo ra với mục tiêu tăng khả năng tiếp cận ngay cả với những dữ liệu vốn đã tồn tại. Chỉ sử dụng kênh phân phối chính thức của Ủy ban Bầu cử (dữ liệu tệp trên data.go.kr) và không lách qua những nơi bị chặn bởi robots.

Các tính năng chính:

• kvote nec corpus --normalize — tải đồng thời các kết quả kiểm phiếu chính qua nhiều kỳ (bầu cử tổng thống khóa 16, 17, 21; tổng tuyển cử và đại diện theo tỷ lệ; bầu cử địa phương lần 5~8) và chuẩn hóa thành JSONL ở cấp điểm bỏ phiếu. Bao gồm giải mã EUC-KR, xử lý trùng lặp điểm bỏ phiếu cùng tên, tách riêng bỏ phiếu ngày chính thức và bỏ phiếu sớm
• kvote nesdc sync / bulk — thu thập toàn bộ dữ liệu thăm dò dư luận, chuỗi thời gian tích lũy hơn 1.400 bản ghi về tỷ lệ ủng hộ đảng phái (từ 10.2023~), bảng chéo cấu phần mẫu (giới tính·độ tuổi·khu vực × hoàn tất/trọng số)
• kvote nec turnout-analysis — chuẩn hóa tỷ lệ cử tri đi bầu theo giới tính và nhóm tuổi (trục nhân khẩu học không có trong dữ liệu kiểm phiếu)
• kvote db / kvote mcp — nạp vào SQLite cục bộ + truy vấn SQL chỉ đọc; tích hợp sẵn máy chủ MCP nên các agent như Claude Code có thể trực tiếp thực hiện từ khám phá → thu thập → SQL
• Với OpenAPI cần khóa xác thực, kvote api login/apply sẽ tự động hóa việc đăng ký sử dụng

Chỉ có một nguyên tắc thiết kế: giữ nguyên dữ liệu gốc, và phần duy nhất được bổ sung là các giá trị tính toán chuẩn có định nghĩa rõ ràng (tỷ lệ đi bầu, tỷ lệ phiếu, phiếu hợp lệ). Không thêm bất kỳ diễn giải hay phán đoán nào. Chạy cùng một lệnh thì ai cũng nhận được cùng một dữ liệu.

Một binary Go duy nhất (không có cgo), giấy phép MIT, hỗ trợ macOS/Linux/Windows. Có thể cài bằng Homebrew và go install. Một số tính năng (thu thập thăm dò dư luận, đường dẫn tìm kiếm bộ dữ liệu) phụ thuộc vào cấu trúc HTML của cổng thông tin, và có thể kiểm tra lỗi bằng kvote doctor.