Contest
One race or question on the ballot: an office to fill, a measure to pass, or a judge to keep.
- Returned by
GET /v1/contests,GET /v1/contests/{id},GET /v1/elections/{slug}/export- Found in
- Endorsement (
contest), Election export (JSON) (contests) - Shapes
- The full record is in GET /v1/contests/{id}. The shorter forms in GET /v1/contests, an endorsement’s contest and the export leave some fields out; a field that isn’t in every form says where it is.
How it connects
- A contest belongs to one election and is voted in one district.
- Its choices are the lines a voter can mark, in ballot order; each endorser’s position points at those choices by
choice_id. - Every endorsement (
GET /v1/endorsements) names its contest byid.
Good to know
- Every contest is on the printed ballot, worded as printed. Where a state leaves unopposed races off the ballot, so do we.
office,race_typeandpartisanarenullfor a measure;topicsis empty for a candidate contest.ballot_textis the measure’s printed wording and isnullwhere we don’t have it yet;descriptionmay be a summary.resultisnulluntil a source publishes one. Results are read again every day until they arecertified.endorsements(GET /v1/contests/{id}only) lists only endorsers who took a position; an endorser with no entry took none.
Fields
| Field | Type | Meaning | Example |
|---|---|---|---|
id | integer | Contest id. | 92 |
title | string | Title as printed on the ballot. | Member of City Council, District 1, City of Berkeley |
short_title | stringor null | Shorter title. | Berkeley Council, D1 |
kind | string | candidate (an office), measure (a proposition) or retention (keep a judge?).candidate, measure, retention meanings | candidate |
vote_method | string | How votes are cast: plurality (vote for one), multi_seat (vote for up to votes_allowed), ranked_choice (rank up to ranks_allowed), approval, or yes_no.plurality, multi_seat, ranked_choice, approval, yes_no meanings | ranked_choice |
votes_allowed | integeror null | How many choices a voter may mark (vote for N). | 1 |
ranks_allowed | integeror null | Ranked choice: how many choices a voter may rank. | 5 |
measure_code | stringor null | The measure’s letter or number: “K”, “Prop 1”. | 5 |
description | stringor null | A short description or question. For a measure with ballot_text, often a summary. | Changes Recall Election Process for Statewide Officers |
ballot_text | stringor null | A measure’s wording exactly as printed on the ballot; null where we don’t have it yet. | CHANGES RECALL ELECTION PROCESS FOR STATEWIDE OFFICERS. LEGISLATIVE CONSTITUTIONAL AMENDM… |
full_text_url | stringor nullURL | The official full text of a measure. | https://vig.cdn.sos.ca.gov/2026/general/pdf/prop5-text-proposed-laws.pdf |
unopposed | boolean | A candidate contest with no more candidates still running than seats (the same rule endorsedby.org uses). Always false for measures. | true |
ballot_order | integeror null | Position on the printed ballot. | 151 |
party | Partyor null | For a party primary, the party. | — |
details | object | Facts about the contest. Only keys that apply are present. | — |
details.uncontested | booleanoptional | Only one candidate is running. | — |
details.nonpartisan | booleanoptional | Candidates appear without a party. | — |
details.measure_type | stringoptional | What kind of measure, as the election office classes it.105 values so far: meanings | legislative constitutional amendment |
details.vote_required | stringoptional | Share of the vote needed to pass, e.g. "2/3" or "55%". | — |
details.majority_required | booleanoptional | A candidate needs a majority to win outright (else a runoff). | — |
details.amount | numberoptional | Dollar amount of a bond or tax measure. | — |
details.term | stringoptional | Length of the term, e.g. "4 years". | — |
details.short_term | booleanoptional | The seat is for the remainder of an unexpired term. | — |
details.justice | stringoptional | The judge or justice a retention question is about. | Kelli M. Evans |
details.runoff_date | stringoptionalYYYY-MM-DD | Date of a runoff, if one is needed. | — |
details.stage | stringoptional | Which round of a multi-round contest this is.open_primary, runoff, general, … meanings | — |
details.elected_at_large | booleanoptional | Elected by the whole jurisdiction, not by district. | — |
details.none_of_these | booleanoptional | The ballot offers “None of these candidates” (Nevada). | — |
details.primary_nominating | booleanoptional | The primary nominates a party’s candidate. | — |
details.winners | integeroptional | Number of winners, where it differs from votes_allowed. | — |
details.ref_type | stringoptional | Kind of referendum.nonrecurring, debt, operating, other, … meanings | — |
details.party_lines_unverified | booleanoptional | The candidates are known, but their party lines haven’t been checked against a printed ballot yet. | — |
details.question_wording | stringoptional | How description relates to the printed question.notice, … meanings | — |
source_url | stringor nullURL | The official source the contest was loaded from. | — |
office | objector null | The office a candidate or retention contest fills; null for a measure. | — |
office.type | string | The office, normalized across states: us_representative, governor, state_senator, mayor, school_board, trial_court, sheriff, …51 values: meanings | city_council |
office.level | string | Level of government the office belongs to (state courts are state, whatever district they sit in).federal, state, local meanings | local |
office.branch | string | Branch of government.executive, legislative, judicial meanings | legislative |
race_type | stringor null | regular (a full term), special (the rest of an unexpired term, or a special election), recall, or retention (keep a judge?); null for a measure.regular, special, recall, retention meanings | regular |
partisan | booleanor null | Candidates run with a party label on the ballot; null for a measure or retention question. | true |
topics | array of string | A measure’s topics (GET /v1/measure-topics), assigned by rule from its title, summary and wording; empty for candidate contests.36 values: meanings | ["housing","elections","government"] |
district | District | The district a contest is voted in. | — |
result | Contest resultor null | The election result, once a source has one; null before then. | — |
election | Election | The election the contest is in.Not in the export. | — |
choices | array of Choice | Every choice, in ballot order.Only in GET /v1/contests/{id} and GET /v1/contests. | — |
endorsements | array of Position | Every (matching) endorser’s position, by endorser name.Only in GET /v1/contests/{id}. | — |