Table of Contents

Contests

Contest objects contain information about specific ballot measures or races. This is where you want to look for the actual list of candidates and text of ballot measures. To search contests (e.g. search for a particular candidate), use the /contests endpoint.

Things that you should know:

Contest and candidate lists change can change unexpectedly (e.g. when a candidate is added or dropped last minute), so if you are caching objects on your end, be able to handle situations where Contest attributes don't match what you had previously and where candidates lists have had candidates added/removed/modified.
For the same elected position (e.g. mayor) we still assign a new Contest id for that race every election, because these positions can change from election-to-election (e.g. the city's boundary changes). To see the same position's contests over multiple elections, filter by ocd_id, which corresponds to the position, not the contest.

API Endpoints

GET /contests - List contests (can be searched and filtered).
GET /contests/{id} - Get a specific contest.

Attributes

Attribute	Format	Description	Example
`type`	ObjectType	This object's data type. Will always be "contest".	`"contest"`
`id`	String	This is the unique id we assign to the Contest. NOTE: The same elected position (e.g. mayor) is assigned a new id every election (read more).	`"a74635..."`
`ocd_id`	OCD-ID or `null`	This is the Open Civic Data Identifier (OCD-ID) for the elected position in this contest. If there is no OCD-ID (often the case for ballot measures), this value will be `null`.	`"ocd-jurisdiction/country:us/..."`
`election_id`	String	This is the Election.id to which this Contest belongs.	`"95hrhf3..."`
`election`	Election	(only if included) This is the full object for the Contest's Election. This is useful if you are querying contests across multiple elections and want to get information each election.	`{"type": "election", ...}`
`contest_type`	ContestType	This is the type of contest (e.g. ballot measure, elected position, etc.). See ContestType for a full list of possible values.	`"ballot_measure"`
`contest_level`	ContestLevel	This is jurisdictional level of contest (e.g. federal, state, etc.). See ContestLevel for a full list of possible values.	`"federal"`
`voting_method`	VotingMethod	This is the specific method of voting (e.g. choose one, ranked choice, approval, etc.). See VotingMethod for a full list of possible values.	`"choose_one"`
`voting_instructions`	String	These are the human-readable instructions for a particular voting method. This may also contain special instructions or restrictions on who can vote in this contest.	`"Select only one candidate."`
`title`	String	This is the title of the ballot measure or race.	`"U.S. Senate"`
`question`	String or `null`	For ballot measures, this is the question being asked for approval or disapproval. For elected positions, this value will be `null`.	`"Do you approve of allocating..."`
`choices`	List(ChoiceObject)	This is a list of choices for the Contest. For ballot measures, the list is usally approve or disapprove. For elected positions, this is a list of candidates.	`[{"type": "candidate", ...}, ...]`
`precincts`	Response	(only if included) These are the Precincts that are part of this Contest. NOTE: This response list can be paginated, so be sure to know how to handle paginated responses.	`{"type": "response", "data": [...], ...}`
`...`		We may add more Contest attributes in the future, so be able to handle unknown attributes.

Examples

A ballot measure example:

{
    "type": "contest",
    "id": "234-5",
    "ocd_id": null,
    "election_id": "123-4",
    "contest_type": "ballot_measure",
    "contest_level": "state",
    "voting_method": "choose_one",
    "voting_instructions": "Choose Approve or Disapprove.",
    "title": "Measure B: Tax Incentive Plan",
    "question": "Shall the Deleware constitution be updated to...",
    "choices": [
        {
            "type": "choice",
            "id": "39u31",
            "ocd_id": null,
            "title": "Approve",
            "party": null,
            "info": null,
        },
        {
            "type": "choice",
            "id": "303-21",
            "ocd_id": null,
            "title": "Disapprove",
            "party": null,
            "info": null,
        }
    ]
}

An elected position example:

{
    "type": "contest",
    "id": "234-5",
    "ocd_id": null,
    "election_id": "123-4",
    "contest_type": "elected_position",
    "contest_level": "city",
    "voting_method": "ranked_choice",
    "voting_instructions": "Number candidates in the order...",
    "title": "Mayor of Springfield",
    "question": null,
    "choices": [
        {
            "type": "candidate",
            "id": "49547yd",
            "ocd_id": "ocd-person/11111-22222-33333-4444-5555555",
            "title": "Jane Smith",
            "party": null,
            "info": "Teacher/Mother",
        },
        {
            "type": "candidate",
            "id": "60id3j9",
            "ocd_id": "ocd-person/11111-22222-33333-4444-5555556",
            "title": "John Smith",
            "party": null,
            "info": "Current Mayor",
        },
        {
            "type": "candidate",
            "id": "0i3okee",
            "ocd_id": null,
            "title": "Montgomery Burns",
            "party": null,
            "info": "Tycoon/Chairman",
        }
    ]
}

Contest Types

These are our general categories of contest types.

Contest Type	Description
`ballot_measure`	A proposed piece of legislation or question to be voted on directly by voters.
`elected_position`	A contest to elect one or more candidates to a specific political seat.
`...`	We may add more contest types in the future, so be able to handle unknown attributes.

Contest Levels

These are our general government level of the contest.

Contest Level	Description
`federal`	National contests (e.g. U.S. Senate).
`state`	State-level contests (e.g. California State Assembly District 15).
`regional`	Covers a widespread area across multiple counties or cities (e.g. Bay Area Transit Region).
`county`	County-level contests (e.g. Tax Assessor-Collector).
`city`	City-level contests (e.g. City Council Seat 4).
`sublocality`	Covers a local area/neighborhood/ward (e.g. school district).
`...`	We may add more contest levels in the future, so be able to handle unknown attributes.

Voting Methods

These are our general categories of voting methods.

Voting Method	Description
`choose_one`	Vote for one choice. This is the NOTE: Special win conditions, such as when the winner has a plurality but not over 50% of the vote, are not usually listed on the ballot, so they will still appear as a choose_one voting method.
`choose_multiple`	Vote for multiple choices. A specific number of choices with the most votes win the election. See the `voting_instructions` attribute for the maximum number of choices the voter is allowed to choose (e.g. "Choose up to five candidates. The top two candidates will win the two open seats.").
`ranked_choice`	Rank choices from most approved to least approved. See the `voting_instructions` attribute for specifics on how voters should number their votes (e.g. "Assign numbers 1 through 10 to each of the candidates, 10 being the most approved, 1 being the least approved. Do not assign the same number to multiple candidates. You can also choose to not assign a candidate any number.").
`instant_runoff`	Choose a first and second choice. See the `voting_instructions` attribute for specifics on how voters should mark their votes (e.g. "Assign 1 to the candidate that you most prefer. Assign 2 to the second candidate preferred after your first choice.").
`approval`	Choose any number of candidates of which you approve. This is basically the most extreme version of `choose_multiple` where you can choose any number of candidates (i.e. you could choose all candidates if you wanted). As with choose_multiple, see the `voting_instructions` attribute for any specific instructions or additional info on candidates.
`...`	We may add more voting methods in the future, so be able to handle unknown attributes.

Choice Object

These are the objects in the choices list in Contest objects. They contain information about specific contest choices (e.g. candidates and ballot measure choices). See examples of Contest objects.

Attribute	Format	Description	Example
`type`	ChoiceType	This choice's type. See ChoiceType for a full list of possible values.	`"candidate"`
`id`	String	This is the unique id we assign to the Choice. NOTE: Even though the same person may run for multiple races, we will assign them a unique id for every contest. If you want to track the same person across multiple contests, use ocd_id.	`"ch_94yehd..."`
`ocd_id`	OCD-ID or `null`	This is the Open Civic Data Identifier (OCD-ID) for the specific person or ballot measure. If there is no OCD-ID (often the case for ballot measures), this value will be `null`.	`"ocd-person/..."`
`title`	String	This name of the choice. For ballot measures, this is usually "Approve" or "Disapprove". For elected positions, this is usually the name of the candidate.	`"Barbra Lee"`
`party`	String or `null`	Any party affiliation associated with the choice. For ballot measures and contests that are non-partisan (e.g. school board races), this value will be `null`.	`"Democrat"`
`info`	String or `null`	Text with any additional information about the choice. For elected positions, this is usually the official short description of the candidate. For ballot measures, this is usually `null`.	`"Teacher/mother"`
`...`		We may add more Choice attributes in the future, so be able to handle unknown attributes.

Choice Types

These are our general types of choices.

Choice Type	Description
`choice`	This is a ballot measure choice (Approve/Disapprove).
`candidate`	This is specific candidate in an elected position contest.
`write_in`	This is a choice to write in a candidate in an elected position contest.
`...`	We may add more Choice types in the future, so be able to handle unknown attributes.

Choice Object Examples

These are some examples of Choice Objects.

A ballot measure choice example:

{
    "type": "choice",
    "id": "ch0-349u3",
    "ocd_id": null,
    "title": "Approve",
    "party": null,
    "info": null,
}

A candidate example:

{
    "type": "candidate",
    "id": "ch10450-3",
    "ocd_id": "ocd-person/11111-22222-33333-4444-5555556",
    "title": "Barbra Lee",
    "party": "Democrat",
    "info": "Politician/activist",
}

A write-in example:

{
    "type": "write_in",
    "id": "5i5441",
    "ocd_id": null,
    "title": "Write-in Candidate",
    "party": null,
    "info": null,
}

Under Development

Documentation

API Endpoints

Contests

API Endpoints

Attributes

Examples

A ballot measure example:

An elected position example:

Contest Types

Contest Levels

Voting Methods

Choice Object

Choice Types

Choice Object Examples

A ballot measure choice example:

A candidate example:

A write-in example: