Contest result
The vote count of one contest, with its source. Each choice’s own votes are on the choice.
- Returned by
GET /v1/contests,GET /v1/contests/{id},GET /v1/candidates,GET /v1/candidates/{id},GET /v1/elections/{slug}/export- Found in
- Contest (
result), Candidate (contests[].result) - Shapes
- The full record is in a contest’s result. The shorter forms in a candidate’s contests leave some fields out; a field that isn’t in every form says where it is.
How it connects
- A contest has at most one result. Each choice’s
votes,vote_pctandwinnerare in its ownresult(see Choice).
Good to know
statusisunofficialwhile counts are still changing andcertifiedonce the canvass is certified.- A party result (
source_kindparty) names awinnerwithout counts:votesandtotal_votesarenullandparty_reportedistrue. It is replaced as soon as an official result appears. - Past elections’ results are mostly compiled from certified precinct returns (
source_kindcompiled), withofficial_urllinking the state’s own results where we have them. - The blank, over and under vote counts and precincts are only where the source reports them.
Fields
| Field | Type | Meaning | Example |
|---|---|---|---|
status | string | unofficial (election-night and canvass counts, still changing) or certified (the canvass is certified).unofficial, certified meanings | unofficial |
source_kind | string | Where the result comes from: official (a state, county, city or federal election office), compiled (certified official returns compiled by a research group, such as the MIT Election Data and Science Lab’s precinct returns, summed to the contest) or party (a state or national party’s own announcement of the winner, with no vote counts; replaced as soon as an official result appears).official, compiled, party meanings | official |
party_reported | boolean | true when the result is a party’s announcement (source_kind party), not an official count. | false |
total_votes | integeror null | Votes cast in the contest: the printed choices plus write-ins. null on a party-reported result. | 180571 |
precincts_reporting | integeror null | Precincts counted so far, where the source says.Only in a contest’s result. | 179 |
precincts_total | integeror null | Precincts in the contest, where the source says.Only in a contest’s result. | 179 |
source | object | The source of the result.Only in a contest’s result. | — |
source.name | string | Who published the result.Only in a contest’s result. | California Secretary of State |
source.url | stringURL | Where it was published: the contest’s own results page where the source has one. Every result has one.Only in a contest’s result. | https://api.sos.ca.gov/returns/us-rep/district/44 |
source.contest_name | stringor null | The contest’s name in the source, which may differ from the printed title.Only in a contest’s result. | U.S. House of Representatives District 44 |
source.updated_at | stringor nullISO 8601 date and time with time zone | When the source last updated it, if it says.Only in a contest’s result. | 2026-11-12T18:50:00+00:00 |
official_url | stringor nullURL | For a compiled result, the state’s own certified results, where we have them.Only in a contest’s result. | — |
more_sources | array of object | Further announcements of the same result (party-reported results that more than one party published).Only in a contest’s result. | — |
more_sources[].name | stringor null | Who published it.Only in a contest’s result. | — |
more_sources[].url | stringURL | Where it was published.Only in a contest’s result. | — |
write_in_votes | integeror null | Votes for write-in candidates, where the source counts them.Only in a contest’s result. | — |
blank_votes | integeror null | Blank votes, where the source counts them.Only in a contest’s result. | — |
over_votes | integeror null | Overvotes, where the source counts them.Only in a contest’s result. | — |
under_votes | integeror null | Undervotes, where the source counts them.Only in a contest’s result. | — |
other_choices | array of object | Lines the source reports that aren’t on the printed ballot, such as named write-ins.Only in a contest’s result. | — |
other_choices[].label | stringor null | As the source reports it: a write-in’s name, “Write-in”, or another line not on the printed ballot.Only in a contest’s result. | — |
other_choices[].votes | integeror null | Votes for it.Only in a contest’s result. | — |
other_choices[].write_in | boolean | A write-in candidate.Only in a contest’s result. | — |
rcv_rounds | array of objector null | Ranked choice: the rounds of the official tabulation, as the source reports them; null for other contests or where we don’t have them.Only in a contest’s result. | — |
notes | stringor null | Anything else about the result, such as how a ranked-choice winner was decided.Only in a contest’s result. | — |
fetched_at | stringISO 8601 date and time with time zone | When we last read it from the source.Only in a contest’s result. | 2026-11-13T03:28:26.570963+00:00 |
source_url | stringURL | Where the result was published.Only in a candidate’s contests. | https://api.sos.ca.gov/returns/governor |