Choice

One line a voter can mark in a contest: a candidate, or a Yes or No answer to a measure or retention question.

Returned by: GET /v1/contests, GET /v1/contests/{id}, GET /v1/endorsements/{id}, GET /v1/elections/{slug}/export
Found in: Contest (choices), Endorsement (choice)

How it connects

A choice belongs to one contest. Endorsements point at it by choice_id.
A candidate choice has a candidate, whose id is the same in every contest they run in (GET /v1/candidates/{id}).

Good to know

label is the name exactly as printed, which can differ from the candidate’s full_name.
incumbent is null where we don’t know yet, and always null for a measure answer.
result is null until the contest has a result. Choices’ votes can add up to less than the contest’s total_votes, because write-ins and other lines are counted separately.
endorsement_count counts endorsers, so a ranked-choice ranking or a slate counts once per endorser.

Fields

Field	Type	Meaning	Example
`id`	integer	Choice id: the choice_id endorsements refer to.	`191`
`label`	string	As printed: the candidate’s ballot name, or Yes / No.	`Daria Wrubel`
`measure_answer`	stringor null	yes or no for a measure or retention question; null for a candidate.`yes`, `no` meanings	`yes`
`option`	stringor null	A special line: none_of_these (Nevada).`none_of_these` meanings	—
`ballot_designation`	stringor null	Occupation line printed under the name, e.g. “Transit Planner”.	`Youth Therapist`
`withdrawn`	boolean	The candidate withdrew but is still printed on the ballot.	`false`
`incumbent`	booleanor null	The candidate holds this seat now: true or false where we know, null where we don’t yet (and for a measure answer).	`true`
`vote_meaning`	stringor null	For a measure answer: what a Yes (or No) vote means, as the election office words it.	`A YES vote on this measure means: The state would create a new homebuying assistance prog…`
`endorsement_count`	integer	Endorsers who endorsed this choice (for a measure: who back this answer).	`6`
`candidate`	Candidateor null	The candidate; null for a measure answer.	—
`party`	Partyor null	The party (or party preference) printed beside the name.	—
`party_label`	stringor null	The party text exactly as printed, where it differs (fusion lines, top-two preferences).	—
`result`	objector null	This choice’s votes, once the contest has a result; null before then.	—
`result.votes`	integeror null	Votes for this choice. null only on a party-reported result, which names a winner without counts.	`33000`
`result.vote_pct`	numberor null	Share of the contest’s votes, 0 to 100, as the source gives it (three decimals).	`18.275`
`result.winner`	booleanor null	true for a winner (for vote-for-N, each of the N), false for a choice that lost; null when not decided yet or not stated, such as a race headed to a runoff.	—

Download every dictionary as CSV or JSON.