1. Documentation
  2. API
  3. Elections

Elections

See examples of Election objects.

Election objects contain general details about a particular election, such as election type, date, a short description, and any particular overall requirements for the election. Additionally, you can optionally include the particular Contests or Precincts for an Election.

Attribute Format Description Example
ObjectType This object's data type. Will always be "election". "election"
String This is the unique id we assign to the Election. This is the id used in Contest.election_id and Precinct.election_id. NOTE: This is our own unique identifier for the election, which is different from the ocd_id for the election. "a74635..."
OCD-ID or null This is the Open Civic Data Identifier (OCD-ID) for this Election. If there is no OCD-ID, this value will be null. "ocd-election/country:us/..."
ElectionType This is the type of election (e.g. general, primary, etc.). See the full list of Election Types for possible values and what they mean. "general"
String This is a short display name for the election. We try to keep it under 10 words. "2018 Midterm Election"
Date This is the official election date. NOTE: Since polling hours vary by location, we put those specific dates and times (with local timezones) in the Precinct.voting_info attribute. "2018-05-15"
String This is a short description for the election. We try to keep it to a single sentence under 25 words. "This is a major national election that happens every two years to elect many federal, state, and local positions."
Response (only if included) These are the Contests that are part of this Election. NOTE: This response list can be paginated, so be sure to know how to handle paginated responses. {"type": "response", "data": [...], ...}
Response (only if included) These are the Precincts that are part of this Election. NOTE: This response list can be paginated, so be sure to know how to handle paginated responses. {"type": "response", "data": [...], ...}
We may add more Election attributes in the future, so be able to handle unknown attributes. 
{
    "type": "election",
    "id": "123-4",
    "election_type": "general",
    "election_name": "Midterm Election",
    "date": "2018-11-05",
    "short_info": "This is a major national election that happens every two years to elect many federal, state, and local positions."
}

{
    "type": "election",
    "id": "3983-b823",
    "election_type": "primary",
    "election_name": "California Primary Election",
    "date": "2018-06-05",
    "short_info": "This is a major primary election for political parties in California."
}

{
    "type": "election",
    "id": "339-83az",
    "election_type": "special",
    "election_name": "Arizona 8th U.S. Congressional District Special Election",
    "date": "2018-04-24",
    "short_info": "This is a special election to fill the vacant Arizona 8th U.S. Congressional District seat."
}

These are our general categories of election types.

Election Type Description
A regularly-scheduled general election with many contests covering multiple states.
A regularly-scheduled state election covering all or the majority of a single state.
A regularly-scheduled local election covering all or the majority of a local municipality or region.
A regularly-scheduled election for political parties (can be for one or more political party).
A non-regularly-scheduled (e.g. one-time) election for specific contests.
A non-regularly-scheduled (e.g. one-time) primary election for political parties (can be for one or more political party).
We may add more election types in the future, so be able to handle unknown attributes.