A Python tool for scraping, storing, and visualizing Indian election results from the Election Commission of India website.
Scrapes constituency-wise election results โ candidate names, party affiliations, vote counts โ and stores them in a normalized SQLite or PostgreSQL database. Includes a FastAPI + Chart.js dashboard for live visualization on counting day.
- Multi-threaded scraping โ 5 concurrent workers (CLI), 3 (live client)
- Dual database backend โ SQLite (local) or PostgreSQL via
DATABASE_URL - Normalized schema โ states, parties, rounds_ac, constituency_status (schema docs)
- Live dashboard โ FastAPI + Chart.js with seat tally, striped bars (leading) vs solid (declared), auto-refresh
- By-election support โ round_no is the time axis; new elections are just new rounds
- CSV/JSON export โ optional file output alongside database writes
git clone https://github.com/thecont1/india-votes-data.git
cd india-votes-data
uv syncRequires Python 3.14+, Chrome (for Selenium).
Scrapes final results from an ECI party-wise URL. Always writes to DB; optional CSV/JSON.
# DB only (round_no=999)
uv run cli.py --url "https://results.eci.gov.in/ResultAcGenMay2026/partywiseresult-S22.htm"
# DB + CSV
uv run cli.py --url "..." --csv
# DB + CSV + JSON
uv run cli.py --url "..." --csv --json
# Respectful mode (single-threaded, 1s pause every 10 URLs)
uv run cli.py --url "..." --respect
# Limit constituencies
uv run cli.py --url "..." 50Monitors counting day results round-by-round. Connects to the API server.
# Continuous monitoring (every 5 minutes)
uv run eci-ResultsDayLiveClient.py --url "https://results.eci.gov.in/ResultAcGenMay2026/partywiseresult-S11.htm" --live
# Single pass (all rounds)
uv run eci-ResultsDayLiveClient.py --url "..."
# Start from specific round
uv run eci-ResultsDayLiveClient.py --url "..." --start-round 3
# Sequential mode (resource-constrained systems)
uv run eci-ResultsDayLiveClient.py --url "..." --sequential
# Multi-state: start server separately, then run clients with --no-server
uv run server.py --api
uv run eci-ResultsDayLiveClient.py --url "...S11.htm" --no-server
uv run eci-ResultsDayLiveClient.py --url "...S22.htm" --no-serverFastAPI server for programmatic scraping.
uv run server.py --api
# or
uv run uvicorn server:app --reloadEndpoints:
GET /healthโ Health checkPOST /scrapeโ Scrape constituency results from party-wise URLPOST /scrape/ac-roundsโ Scrape all rounds for a single ACPOST /scrape/all-roundsโ Scrape all rounds for all ACs
DATABASE_URL=data/india-votes-data.db uvicorn server:app --reload
# Open http://localhost:8000Dual-backend via DATABASE_URL:
# SQLite (default)
DATABASE_URL="data/india-votes-data.db" uvicorn server:app --reload
# PostgreSQL
DATABASE_URL="postgresql://localhost:5432/election_results" uvicorn server:app --reloadindia-votes-data/
โโโ cli.py # CLI scraper (final results โ DB)
โโโ server.py # FastAPI API server
โโโ eci-ResultsDayLiveClient.py # Live client (round-by-round)
โโโ eci-live-scraper.py # Alternative scraper (requests+BS4)
โโโ config.py # Election config (tracked states, URL template)
โโโ election.conf # Party-wise URLs for current cycle
โโโ static/index.html # Live dashboard (Chart.js)
โโโ db_utils.py # Database layer (SQLite + PostgreSQL)
โโโ core/
โ โโโ scraper.py # Selenium-based ECI extraction
โ โโโ browser.py # Chrome WebDriver setup
โ โโโ output.py # CSV/JSON writing (shared)
โ โโโ models.py # Pydantic data models
โโโ tools/ # Utilities and verification pipeline
โ โโโ ocr_engine.py # Vision LLM + Tesseract OCR engine
โ โโโ normalize_parties.py # Normalize party names in DB
โ โโโ fetch_symbols.py # Fetch party symbols from ECI
โ โโโ fetch_party_data.py # Fetch party metadata
โโโ eci-verify-form20.py # Form 20 batch verification CLI
โโโ data/
โ โโโ states.csv # 36 states/UTs reference
โ โโโ parties.csv # 30 major parties metadata
โ โโโ csv/ # CLI CSV output
โ โโโ json/ # CLI JSON output
โ โโโ india-votes-data.db # SQLite database (gitignored)
โโโ docs/
โ โโโ SCHEMA.md # Database schema docs
โโโ notebooks/
โ โโโ analyse-this.ipynb # Analysis notebook
โโโ archive/ # Historical files
โโโ pyproject.toml # uv project config
โโโ README.md # This file
See docs/SCHEMA.md for full schema documentation.
Quick reference โ 4 tables:
| Table | Rows | Purpose |
|---|---|---|
states |
36 | Reference data (ECI codes as PK) |
parties |
196 | Party metadata + aliases |
rounds_ac |
209K | Vote counts per candidate per round |
constituency_status |
4K | AC lifecycle tracking |
- Primary:
curlsubprocess + BeautifulSoup โ bypasses ECI's Akamai TLS fingerprint blocking - Fallback: Selenium headless Chrome โ for pages requiring JavaScript rendering
- Rate limiting: 0.2-0.8s jitter between requests per thread
Form 20 is the official election result document published by the Chief Electoral Officer of each state under Section 64 of the Representation of the People Act, 1951. It contains the complete, booth-wise breakdown of votes polled for every candidate in a constituency โ the most granular official record of an election. This is the source document that returning officers sign before declaring results.
Our scraper captures aggregate vote totals from ECI's party-wise summary pages. Form 20 lets us verify those numbers against the original signed document.
The verification pipeline (eci-verify-form20.py + tools/ocr_engine.py) downloads each constituency's Form 20 PDF, converts pages to images, and sends them to a Vision LLM (currently MiMo 2.5). The model reads candidate names and vote counts directly from the scanned document, then cross-checks them against our database.
Tesseract OCR runs as a fallback when no Vision API is configured. When Vision is available, Tesseract is skipped entirely โ it takes 23 seconds per AC and the Vision LLM is more accurate on these tabular documents.
Page selection: the summary page (typically the last page) plus 20% random booth pages are sent to the Vision model. This balances thoroughness against API cost.
| Status | Meaning | Action |
|---|---|---|
| Verified | All candidates confirmed, vote counts match | None โ data is trustworthy |
| Mismatch | Vision LLM read different vote counts than our DB | Investigate โ could be our data or LLM error |
| Error | Pipeline couldn't read the PDF (corrupt download, API failure) | Re-run โ usually recovers on retry |
| Unavailable | No Form 20 URL set for this AC | Source the PDF from the CEO website |
# Verify all ACs in a state (skips already-verified, retries errors)
uv run eci-verify-form20.py S03
# Re-run everything from scratch
uv run eci-verify-form20.py S03 --force
# Single AC
uv run eci-verify-form20.py S25 110
# Tesseract only (no Vision API)
uv run eci-verify-form20.py S03 --skip-visionThe terminal shows a Braille grid โ one block per AC, 20 per line. Pre-existing verified ACs appear as filled blocks from the start. Each new result appends to the grid in real time.
Automation catches gross errors (wrong totals, missing candidates) but cannot judge everything. Mismatched ACs need a human to decide: did the LLM misread a smudged scan, or does our scraped data have the wrong number? The dashboard sorts ACs by verification priority (Mismatch โ Error โ Unavailable โ Verified) so the most suspicious constituencies surface first.
The goal is not zero mismatches โ it's knowing exactly which constituencies to trust and which to double-check. That's what makes this data publishable.
CLI generates CSV/JSON in data/csv/ and data/json/:
YYYY<Type>-<state>.csv (e.g., 2026Assembly-WB.csv)
YYYY<Type>-<state>.json (e.g., 2026Assembly-WB.json)
Also available at Kaggle.
analyse-this.ipynb โ Jupyter notebook for analyzing election results from CSVs. Includes:
- Party-wise vote shares and seat counts
- Victory margins and deposit losses
- Assembly composition treemaps
- Multi-state comparison across all available CSVs
Reads CSVs from data/csv/.
Historical files in archive/:
eci-karnataka.htmlโ Karnataka election results page2024 Parliamentary Elections India.csvโ 2024 Lok Sabha results
MIT โ see LICENSE.