Documentation
API Endpoints
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.
HTTP Request
GET /v1/elections
Examples
- Get a list of all Elections:
- https://api.ballotapi.org/v1/elections
- Get a list of all upcoming Elections:
- https://api.ballotapi.org/v1/elections?dates=now,future
- Get a list of upcoming Elections for a specific location:
- https://api.ballotapi.org/v1/elections?coords=37.7942635,-122.3955861&dates=now,future
- Include Contests for each Election:
- https://api.ballotapi.org/v1/elections?include=contests
Query Parameters
Parameter | Format | Description | Example |
---|---|---|---|
ids
|
String | A comma separated list of specific Election ids to include in the response. |
ids=a12345,a23456
|
ocd_ids
|
OCD-ID | Filter by a comma separated list of specific Open Civic Data Identifers for elections. |
ocd_ids=ocd-division%2F...
|
coords
|
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
|
dates
|
DateTimeRange | Filter to elections occurring only within a certain datetime range. You can include shorthand names in addition to normal datetimes. |
dates=now,future |
include
|
String |
A comma separated list of resources to include
for each Election object response. Options are:
"contests"
and
"precincts" .
|
include=contests |
Response
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/..." }
HTTP Response Codes
Code | Response Format | Description |
---|---|---|
200
|
Response | Successful request. |
400
|
Error Response | The query parameters you included were invalid. The Error Response will include a message describing exactly was invalid. |
429
|
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.
|
500
|
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. |
503
|
N/A | We are down for maintenance. Please try your request again in a few minutes. |
504
|
N/A | Your request timed out. Please try your request again in a few minutes. |