Elections, contests and endorsements
Everything on the ballot and who endorses what. For districts, officeholders and representatives see Districts 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/ballot | The ballot at a location (or lat+lng): its districts and every upcoming contest with endorsements. elections, categories, endorsers, endorser_states |
GET /v1/recommendations | What chosen endorsers recommend on the ballot at a location (or lat+lng): each contest’s choices, most-backed first, with their backers, and the choices to mark. Endorsers by categories, endorsers, endorser_states or a saved subscription (default: all). Contests by elections, levels, contest_kinds. 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.
Locations
location is a street address (1480 Laurel Ave, San Francisco, CA), a ZIP code (94114), a city (Oakland, CA), a county (Alameda County, CA) or a state (CA). An address or lat+lng gives one voter’s ballot (location.exact is true). A ZIP code, city, county or state gives every contest anyone there could see, since one ZIP code can span several districts (exact is false). Locations are looked up with the U.S. Census geocoder and TIGERweb. We don’t store or log addresses.
Recommendations
Each contest in /v1/recommendations 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.