1. Documentation
2. API
3. Contests
4. List

Listing Contests

Get a list of Contests, reverse ordered by election date, then government level (e.g. federal, state, city, etc.). By default, we return a paginated list all contests, which problaby isn't very useful to you, so you probably want to include some query parameters to filter the list for the elections you actually want.

HTTP Request

GET /v1/contests

Examples

Get all the contests for a specific election:

https://api.ballotapi.org/v1/contests?elections=a12345

Get the ballot measures for a specific precinct:

https://api.ballotapi.org/v1/contests?precincts=z34536482&contest_types=ballot_measure

Search for upcoming contests for a specific term:

https://api.ballotapi.com/v1/contests?q=soda%20tax&dates=now,future

Get the district maps for two contests:

https://api.ballotapi.org/v1/contests?ids=958hd92,9584h3b1&extra=contest_geos

Query Parameters

Search Strings

Contests are where you can find the names of specific races and candidates, so we let you search those fields using our generalized search query parameter (q=...). Here's a general rundown of search features:

• Searches look for mentions of your search terms in these fields: Contest Title, Contest Question, Choice Title, Choice Party, and Choice Info.
• All searches are case insensitive, so you don't need to worry about whether something is capitalized.
• You can surround a phrase with quotes (e.g. "soda tax") and we will search for that specific phrase.
• You can combine the search string with other query parameters to limit the search results (e.g. combine q=... with dates=... to limit the search to elections happening only within a specific date range).
• You can search for a ballot measure name or candidate name by prefixing with "title:" (e.g. title:"Measure FF" or title:"Barbra Lee"). This indicates that we should only look for that term in the Contest Title for ballot measures and the Choice Title for elected positions.

Contest Geometries

If you include the extra=contest_geos query parameter in your request, we will merge all of the areas of the precincts for each contest in the results and return those merged geometries as a key-value object of Contest id to GeoJSON object in the extra results parameter. This is useful for generating district maps for races and ballot measures.

Example contest geometries in response:

{
    "type": "response",
    "data": [
        {"type": "contest", "id": "c239842", ...},
        {"type": "contest", "id": "494y185", ...},
        ...
    ],
    "next": "...",
    "extra": {
        "contest_geos": {
            "c239842": {"type": "MultiPolygon", ...},
            "494y185": {"type": "MultiPolygon", ...},
            ...
        },
    },
    "timestamp": "...",
    "url": "..."
}

NOTE: We merge all the precincts of only the Contests in the current page of results. So, if the response is paginated, you will need to go to each page to get all the contest merged precinct geometries.

NOTE: If you want to also get the ids of the Precincts for each of the contest geometries, use the include=precincts parameter to include the Precints for each contest in the results.

Response

We will return the results of your request as a Response object with the data attribute as the list of Contests.

Responses can be paginated! Be sure to check the next attribute for the next page of data.

Example response:

{
    "type": "response",
    "data": [
        {
            "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": [...]
        },
        ...
    ],
    "next": "https://api.ballotapi.org/...",
    "extra": {},
    "timestamp": "2018-01-01T00:00:00+00:00",
    "url": "https://api.ballotapi.org/..."
}

HTTP Response Codes