Election
One election in one state on one day: a general, a primary, a runoff or a special election.
- Returned by
GET /v1/elections- Found in
- Contest (
election), Election export (JSON) (election) - Shapes
- The full record is in GET /v1/elections. The shorter forms in a contest’s election leave some fields out; a field that isn’t in every form says where it is.
How it connects
- An election has many contests:
GET /v1/contests?elections={slug}, or the whole election at once withGET /v1/elections/{slug}/export. - The slug is stable and readable (
<state>-<date>-<type>); use it in everyelections=filter.
Good to know
- details holds only the voting rules that apply, so most elections have one or two keys and some have none.
- Past elections (November 2020, 2022, 2023, 2024 and 2025) are kept for their results and history and have
details.historicalset totrue.upcoming=trueleaves them out. result_countrises as sources publish results; it is 0 for an upcoming election.
Fields
| Field | Type | Meaning | Example |
|---|---|---|---|
id | integer | Election id. | 1 |
slug | string | Election slug, used in elections= filters: <state>-<date>-<type>. | ca-2026-11-03-general |
name | string | Election name. | California General Election |
short_name | stringor null | Shorter name. | CA General |
date | stringYYYY-MM-DD | Election day. | 2026-11-03 |
state | stringor nullTwo capital letters (USPS code) | State; null for a multi-state election. | CA |
type | string | Kind of election.general, primary, special, special_primary, runoff, consolidated meanings | general |
primary_system | stringor null | How the state runs primaries.none, closed, semi_closed, open, top_two, top_four, nonpartisan meanings | none |
info_url | stringor nullURL | Official election page. | https://www.sf.gov/november-3-2026-consolidated-general-election |
details | object | Voting rules for the election. Only keys that apply are present. | — |
details.all_mail | booleanoptional | Every voter is mailed a ballot. | — |
details.ranked_choice | booleanoptional | Some contests in this election use ranked choice voting. | — |
details.fusion_voting | booleanoptional | Candidates can appear on more than one party’s line (New York, Connecticut). | — |
details.partisan_primary | booleanoptional | A party primary. | — |
details.primary | stringoptional | Which primary, where a state holds several. | — |
details.consolidated_with | string or array of stringoptional | Elections held on the same ballot: a name, or a list of names. | ["San Francisco Consolidated General Election"] |
details.runoff_date | stringoptionalYYYY-MM-DD | Date of a runoff, if one is needed. | — |
details.runoff_election_date | stringoptionalYYYY-MM-DD | Date of the runoff election. | — |
details.top_two_primary_date | stringoptionalYYYY-MM-DD | Date of the top-two primary that chose these candidates. | — |
details.louisiana_open_primary | booleanoptional | Louisiana’s open (jungle) primary. | — |
details.note | stringoptional | Anything else voters should know. | — |
details.historical | booleanoptional | A past election kept for its results and history (the November 5, 2024 general, for example). Never shown to voters on endorsedby.org. | true |
contest_count | integer | Contests on the ballot.Only in GET /v1/elections. | 2477 |
endorsement_count | integer | Endorsements in those contests.Only in GET /v1/elections. | 8156 |
result_count | integer | Contests on the ballot with a result.Only in GET /v1/elections. | 242 |