Results API

Get a key

Email [email protected] with who you are and how you will use the results. Each key is for one organisation. Keep it secret and send it only in the Authorization header—never put it in a link. The tester below can make a one-off browser request without storing the key.

Test or download a request

Your key stays in this page's memory and is sent only to Poliwave. Reloading clears it.

A 403 scope response means the key does not include that endpoint. Ask Poliwave for a historical key before using an archive preset.

Make a request

Send the key in the Authorization header.

curl -H "Authorization: Bearer pwk_..." https://www.poliwave.com/api/v1/live
curl -H "Authorization: Bearer pwk_..." https://www.poliwave.com/api/v1/live/ca/election-2026
curl -H "Authorization: Bearer pwk_..." "https://www.poliwave.com/api/v1/historical/pe/gen/2021?office=president"

GET /api/v1/live

Every election the API serves, with its results URL.

GET /api/v1/live/{country}/{slug}

One election now: counts, winners and calls, as its live page shows them.

GET /api/v1/historical/{country}/{district}/{year}

Licensed historical results by unit. This endpoint needs a key with the historical scope.

?unit=CODE

One riding, state or region; on a municipal night, one municipality (Toronto is amo-15614).

?office=president

Select presidential results when legislative results share the year.

?stage=VALUE

Rehearsals only: that point of the night (listed in stages).

?units=1

US midterms only: add county results.

What you get back

available

false until the first count of this election is published.

fetchedAt, sourceTime

When we read the count, and the time the source put on it.

units

Ridings, states or regions. Each has status (awaiting, tied, leading, won), winner, leader, counted (% of polls reported) and candidates in vote order.

contests, places

Municipal nights and referendums: every race or question, with seats, status (awaiting, counting, final, acclaimed) and who is elected.

national, seats

Totals and seats won and led, counted the way the page counts them.

calls

Every race called. basis is final (count complete), projected (a Poliwave call) or source (declared by the source or our desk).

candidates, projected_percentages_round1

Historical runoff elections retain every first-round candidate and vote count. projected_percentages is the runoff; projected_percentages_round1 is round one.

attribution

A ready credit line naming Poliwave and the official source.

The numbers are the ones on the live page, from the same snapshot. Forecasts, model estimates and candidate photos are not included.

Limits and testing

Each key allows 120 requests a minute unless we agree a different limit. Counts change about every 20 to 30 seconds, so polling every 15 to 30 seconds is plenty. A refused request answers 401 (key), 403 (scope) or 429 (limit) with a JSON error.

Elections marked rehearsal: true serve made-up or replayed counts, so you can build and test before the night.

Credit

Credit Poliwave when you publish these results, with a link to the election's page (the page field). Official counts stay credited to their source, named in sources. Use of the API falls under our terms, and a key can be withdrawn.