Elections, contests and endorsements
Everything about the races on the ballot and who endorses what. For the district a contest is in and who holds each seat now, see Contests and officeholders.
Endpoints
| Endpoint | What |
|---|---|
GET /v1/states | States, with FIPS codes |
GET /v1/elections | Elections, with their voting rules in details. states, types, from, to (YYYY-MM-DD), upcoming=true |
GET /v1/endorser-categories | Kinds of endorser: labor, newspaper, party, advocacy… |
GET /v1/endorsers | Endorsers. categories, states (home state, or national), elections, q |
GET /v1/endorsers/{slug} | One endorser and the elections they’ve endorsed in |
GET /v1/contests | Contests with their choices. elections, states, levels, contest_kinds, districts (OCD ids), upcoming |
GET /v1/contests/{id} | One contest with every endorser’s position. categories, endorsers |
GET /v1/endorsements | Endorsements, flat. categories, endorsers, endorser_states, elections, states, contest_kinds, levels, contest, upcoming |
GET /v1/recommendations | What chosen endorsers recommend in each contest, grouped by election: each contest’s choices, most-backed first, with their backers, and the choices to mark. Contests by state (required unless election or contest is given), election, contest (ids), levels, contest_kinds. Endorsers by categories, endorsers, endorser_states or a saved subscription (default: all). only_endorsed |
GET /v1/coverage | Per state: elections, contests, measures, endorsers, endorsements, and when they last changed. upcoming=false counts past elections too |
List parameters take comma-separated values: categories=labor,newspaper.
Ballot details
Contests carry details where they apply: uncontested, nonpartisan, term, short_term, vote_required and majority_required for measures, amount for bonds, runoff_date, elected_at_large, none_of_these and more, plus the official source_url. Elections carry voting rules: all_mail, ranked_choice, fusion_voting, runoff_date. A choice has party_label where the ballot prints one (Washington’s “Prefers Democratic Party”), and option: "none_of_these" for Nevada’s “None of these candidates”. Add lang=es to any data endpoint for Spanish ballot text where the state publishes it.
How positions are shaped
A contest has a vote_method: plurality (vote for one), multi_seat (vote for up to votes_allowed), ranked_choice (rank up to ranks_allowed), approval or yes_no (measures and judicial retention). Each endorser’s position is a list of picks: one choice for vote-for-one; up to N for multi-seat; ranked choices with rank 1, 2, 3… for ranked choice; and the Yes or No choice (measure_answer) for a measure. An endorser with no entry has taken no position.
Address and geography lookups retired
The API no longer looks up places. GET /v1/ballot (the ballot at an address), GET /v1/districts and /v1/districts/{id} (districts and their boundaries) and GET /v1/representatives (who represents a place) have been removed, and the location, address, zip, city, county, lat and lng parameters are refused with 400 invalid_parameter. Choose contests by state, election or contest id instead. Every contest still names its district (id, ocd_id, name, level, type, state), which is all you need to tell races apart.
Recommendations
Give a state for its upcoming contests, or name an election or contest ids (past or upcoming). The response has the scope you asked for, the endorsers counted ("all", or the filter or subscription) and elections, each with its contests: federal, then state, then local, in ballot order.
curl -H "Authorization: Bearer ebk_…" \ "https://api.ballotdata.net/v1/recommendations?state=CA&categories=labor&only_endorsed=true"
Each contest has a recommendation: choice_ids to mark (the measure answer, the candidate or candidates for vote-for-N, or the ranking for ranked choice), the endorser_count who took a position, and their agreement: unanimous, majority, plurality, split (a tie; tied choices are left out, except in a ranking) or none. Each choice lists endorsed_by with every backer’s rank, statement and source, and endorsement_count (plus first_choice_count for ranked choice). Withdrawn candidates are never recommended.