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

Listing Elections

Get a list of Elections, reverse ordered by election date. By default, we return a paginated list all elections, 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. 

GET /v1/elections
https://api.ballotapi.org/v1/elections
https://api.ballotapi.org/v1/elections?dates=now,future
https://api.ballotapi.org/v1/elections?coords=37.7942635,-122.3955861&dates=now,future
https://api.ballotapi.org/v1/elections?include=contests
Parameter Format Description Example
String A comma separated list of specific Election ids to include in the response. ids=a12345,a23456
OCD-ID Filter by a comma separated list of specific Open Civic Data Identifers for elections. ocd_ids=ocd-division%2F...
Coordinates Filter by a specific location point or area. For areas, if any part of an Election's precincts overlap the query area, that Election is included. coords=37.7942635,-122.3955861
DateTimeRange Filter to elections occurring only within a certain datetime range. You can include shorthand names in addition to normal datetimes. dates=now,future
String A comma separated list of resources to include for each Election object response. Options are: "contests" and "precincts". include=contests

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

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

Example response: 

{
    "type": "response",
    "data": [
        {
            "type": "election",
            "id": "123-4",
            "ocd_id": null,
            "election_type": "general",
            "election_name": "Midterm Election",
            "date": "2018-11-05",
            "short_info": "This is a major national election that..."
        },
        ...
    ],
    "next": "https://api.ballotapi.org/...",
    "extra": {},
    "timestamp": "2018-01-01T00:00:00+00:00",
    "url": "https://api.ballotapi.org/..."
}
Code Response Format Description
Response Successful request.
Error Response The query parameters you included were invalid. The Error Response will include a message describing exactly was invalid.
N/A You are making too many requests to the API. Check the Retry-After header for how many seconds to wait until trying the request again. See our docs on Rate Limiting.
N/A An internal server error occurred. We log these errors and try to fix them quickly, so if you keep getting 500 errors for a few days, please email us.
N/A We are down for maintenance. Please try your request again in a few minutes.
N/A Your request timed out. Please try your request again in a few minutes.