Documentation

JSON API

Every page on this site is backed by an endpoint, and every endpoint is public. No key, no rate limit, no registration, CORS open to any origin.

The envelope

Every response has the same shape, so an empty result is never confused with a failure. Payload is always under data; anything else at the top level is metadata.

{
  "ok": true,
  "source": "Janadesh",
  "count": 16,
  "data": [ … ]
}

Errors keep the envelope and set an HTTP status — 400 for a bad request, 404 for a slug that does not exist, 503 when the database is unreachable.

{
  "ok": false,
  "error": "Election \"lok-sabha-1999x\" not found",
  "data": null
}

Endpoints

GET /api/elections

Elections, newest first, with the largest party and headline totals. The only endpoint that will return both houses at once.

house — lok-sabha (default), assembly, or all
state — state slug — assembly elections in one state, e.g. kerala

Try it: /api/elections?house=assembly&state=kerala →

GET /api/elections/{slug}

One election: its summary, its party table, and — for a general election — its state-by-state breakdown.

Try it: /api/elections/kerala-2021 →

GET /api/elections/{slug}/parties

Party performance in one election — seats, contested, votes, share, deposits lost.

limit — default 60, max 500

Try it: /api/elections/lok-sabha-2019/parties?limit=500 →

GET /api/elections/{slug}/seats

Seat results for one election, with winner and runner-up. The slug fixes the house, so there is no house parameter here.

limit — default 100, max 1000
offset — default 0
state — state slug, e.g. kerala
order — name (default) or margin

Try it: /api/elections/lok-sabha-2024/seats?state=kerala&order=margin →

GET /api/states

Every state and union territory that has voted, with its Lok Sabha and assembly seat counts.

Try it: /api/states →

GET /api/states/{slug}

One state: its party trend across elections, and all its seats in the chosen house.

house — lok-sabha (default) or assembly

Try it: /api/states/tamil-nadu?house=assembly →

GET /api/parties

Parties ranked by seats won all time in the chosen house.

house — lok-sabha (default) or assembly
minSeats — default 1 — pass 0 for parties that never won

Try it: /api/parties?house=assembly&minSeats=0 →

GET /api/parties/{slug}

One party: its timeline in the chosen house, its state strongholds, and — under assembly — its record in every state assembly it has contested.

house — lok-sabha (default) or assembly
year — restrict the state breakdown to one election year

Try it: /api/parties/dmk?year=2024 →

GET /api/constituencies/{state}/{slug}

One seat: every election held in it, and counterpart, the seat of the same name in the other house if there is one.

house — lok-sabha (default) or assembly
year — expand that year’s contest to its full candidate list
month — with year, picks between two polls in one year — Bihar, 2005

Try it: /api/constituencies/kerala/thrissur?house=assembly →

GET /api/search

One query across constituencies, candidates, parties, states and elections.

q — required, at least 2 characters
limit — default 40, max 100

Try it: /api/search?q=vajpayee →

GET /api/health

Liveness plus a real database round-trip. Returns 503 if the database is unreachable.

Try it: /api/health →

Conventions

Rule	Detail
Election slugs	`lok-sabha-{year}` for a general election — `lok-sabha-1962` through `lok-sabha-2024`. For an assembly election, `{state}-{year}`, as `kerala-2021`, with the month appended where a state voted twice in one year: `bihar-2005-february` and `bihar-2005-november`.
Houses	Every row carries a `house` of `lok_sabha` or `vidhan_sabha`. The query parameter takes the friendlier `lok-sabha` and `assembly`, and defaults to the Lok Sabha everywhere.
Other slugs	Lowercase, hyphenated names: `tamil-nadu`, `bjp`, `amethi`.
Big integers	Vote counts are returned as strings, not numbers, so nothing is lost to float precision.
Percentages	Returned as strings in the range 0–100, not fractions.
Caching	`public, max-age=300, s-maxage=3600, stale-while-revalidate=86400`. The data changes once every five years; cache freely.
Limits	Clamped server-side. An out-of-range `limit` is capped, not rejected.

Fetching it

const res  = await fetch('https://janadeshonline.in/api/elections/lok-sabha-2024/parties?limit=10')
const body = await res.json()

for (const p of body.data) {
  console.log(p.abbr, p.seatsWon, p.voteShare)
}

No key and no rate limit is a promise about access, not an invitation to hammer the server. Cache what you fetch; the responses are built for it. If you need the whole dataset, take a database dump rather than crawling — it is faster for you and cheaper for everyone.

Field names, sources, and the gaps in the data are documented in methodology & gaps. In particular: 2024 has no turnout figures, the first two general elections of 1951 and 1957 are not in the archive, and assembly results end with the June 2023 source release, so the rounds held since are absent.