한국 선거 공개 데이터, CLI 한 줄로 끝내기 — k-vote-cli 완전 가이드

한국 선거 공개 데이터, CLI 한 줄로 끝내기 — k-vote-cli 완전 가이드

한국 정치 데이터를 다뤄본 개발자라면 한 번쯤은 좌절한 적이 있을 겁니다. 개표 결과, 여론조사, 투표율 — 전부 법적으로 공개되어 있지만 막상 받아보려고 하면 문이 잠겨 있습니다. robots.txt로 자동 접근을 전면 차단하고, EUC-KR 인코딩, 선거마다 달라지는 엑셀 양식, 공식 API 부재, 게시판 PDF뿐인 여론조사… CLI 한 방으로 해결하는 도구가 바로 k-vote-cli입니다.

왜 CLI가 필요한가

선거 데이터는 크롤링 봇을 꺼리는 경향이 강합니다. OpenAPI도 토큰과 범위 제한이 까다롭습니다. 연구자, 기자, 시민 개발자 모두 같은 벽에 부딪히죠. k-vote-cli는 API 키 없이 표준 입력 한 줄로 데이터를 받아볼 수 있게 설계됐습니다.

선거통계시스템(info.nec.go.kr)은 robots.txt로 자동 접근을 전면 차단합니다. 파일은 EUC-KR 인코딩에 선거마다 엥셀 양식이 제각각이고, 여론조사는 공식 API 없이 게시판 PDF뿐입니다. OpenAPI는 데이터마다 활성화 시점이 다르고 신청 절차도 복잡합니다. 이런 환경에서 CLI는 가장 현실적인 우회로 작동합니다.

핵심 기능

k-vote-cli는 다음과 같은 데이터를 한 명령으로 받아옵니다.

• 개표 결과 — ElectionsInfo(중앙선거관리위원회) 제공, 선거구별 득표수·당선 여부·득표율 포함
• 여론조사 — 주요 조사기관 공개 PDF 자동 파싱, 정당·후보·성별·연령별 교차표 지원
• 투표율 — 선거구별 실시간 집계, 시간대별 추이 그래프 출력 가능
• 후보자 정보 — 공약, 학력, 경력, 재산, 세금 체납 내역 등 공직선거 데이터베이스 연동

실제 사용 예시

# 최신 개표 결과
k-vote results --election 2024-assembly

# 특정 정당 지지율 추이
k-vote poll --party demo --range 30d

# 투표율 시간대별 추이
k-vote turnout --election 2024-assembly --by-hour

# 후보자 상세 정보
k-vote candidate --id 2024-12345

데이터 정규화

원본 데이터의 가장 큰 문제는 양식 불일치입니다. 지방선거와 국회의원 선거의 컬럼 순서가 다르고, 코드 값도 매번 바뀝니다. k-vote-cli는 내부적으로 모든 출력을 스키마 하나로 정규화해서 JSON/CSV로 내보냅니다.

{
  "election_id": "2024-assembly",
  "district": "서울 강남구",
  "candidates": [
    {"name": "홍길동", "party": "A당", "votes": 45231, "rate": 0.523},
    {"name": "김영희", "party": "B당", "votes": 41209, "rate": 0.476}
  ],
  "turnout": 0.781,
  "updated_at": "2024-04-10T22:30:00+09:00"
}

설치와 의존성

설치는 pip으로 간단합니다. Python 3.9+ 환경에서 pandas, requests, beautifulsoup4가 자동으로 설치됩니다.

pip install k-vote-cli

PDF 파싱을 위해선 pdftotext(poppler-utils) 시스템 패키지가 필요합니다. macOS의 경우 brew install poppler, Ubuntu의 경우 sudo apt install poppler-utils로 설치할 수 있습니다.

캐싱과 증분 업데이트

k-vote-cli는 로컬 SQLite 캐시를 내장하고 있어, 한 번 받아본 데이터는 즉시 재사용됩니다. 증분 업데이트는 --since 옵션으로 받아올 수 있어 대량 데이터 분석 시 네트워크 비용을 크게 절약할 수 있습니다.

한계와 주의사항

이 도구가 모든 문제를 해결해주진 않습니다. 중앙선거관리위원회가 페이지 구조를 바꾸면 파서가 일시적으로 실패할 수 있고, 여론조사 PDF는 OCR 품질에 따라 인식률이 들쭉날쭉합니다. 결과 데이터는 참고용이며, 공식 발표 수치와 다를 수 있으니 중요한 분석에는 반드시 원본 출처를 대조해야 합니다.

마무리

선거 데이터는 민주주의의 공공재입니다. 도구가 막혀 시민의 접근권이 깎이는 상황은 안타깝습니다. k-vote-cli 같은 오픈소스 CLI가 그 벽을 조금이라도 낮춰주길 바랍니다. 다음 선거 때쯤이면 더 풍부한 데이터로 한 단계 진화한 모습이 기대됩니다. 기여는 GitHub 저장소에서 환영합니다.