API documentation

Base URL https://api.ballotdata.net. Everything is JSON over HTTPS. Machine-readable: /openapi.json (OpenAPI 3.1).

Getting started

1. Create an account. We approve new accounts by hand and email you when yours is ready.
2. Once it’s approved, create a key in the console. You see it only once.
3. Send it on every request:

curl -H "Authorization: Bearer ebk_…" "https://api.ballotdata.net/v1/elections?upcoming=true"

Lists come back as { "data": [...], "next_cursor": "…" }; see paging. Then the races in an election, and what labor unions recommend in California’s upcoming ones:

curl -H "Authorization: Bearer ebk_…" "https://api.ballotdata.net/v1/contests?elections=ca-2026-11-03-general"
curl -H "Authorization: Bearer ebk_…" "https://api.ballotdata.net/v1/recommendations?state=CA&categories=labor"

Address and geography lookups (the ballot at an address, district boundaries, representatives by location) have been retired. Choose races by state, election or contest; see what changed.

What’s here

• Keys, limits and errors

  Sending your key, rate limits, error codes and paging.

• Elections, contests and endorsements

  Elections, contests, endorsers and endorsements, and what chosen endorsers recommend in each race.

• Contests and officeholders

  The district each contest is in, and who holds each seat now.

• The endorsement stream

  Every endorsement change, live, over Server-Sent Events or polling.

• Bulk data

  File formats, identifiers and columns of the datasets sold in bulk.