Downloading bulk data via API

Ballotpedia’s bulk data clients can access their data on-demand with our client portal at https://clients.ballotpedia.org/. The data is refreshed every 24 hours. You may access your data through two methods, as described below:

1. Login with provided password and click to download latest file (for non-technical users)

2. Access latest data file via API (for technical users, see next page)

API instructions

Contact Ballotpedia’s data sales staff to request such a key.

The API can be called directly by interacting with two endpoints. Please note that these endpoints can only be accessed from a non-CORS context.

GET https://api.ballotpedia.org/getQueryList

This endpoint will return an array of objects, each object represents a data set and contains the ID, Title and Description.

The endpoint requires your API Key passed in as a header:

x-api-key: [your api key]

Examples

Example call using Postman

Example response with a single file:

{"success":true,"data":[{"id":"1098","title":"Endorsements Sample for Data Clients","description":"List endorsements for 2020 candidates"}],"message":null}

This endpoint will return a URL to the requested file:

POST https://api.ballotpedia.org/getQueryResults

The endpoint requires your API Key passed in the header as described above, the content type of application/json, and the ID (obtained from the getQueryList endpoint) of the data set and the format passed via the body in the POST request.

Headers

x-api-key: [your api key]
Content-Type: application/json

Body

{
  "id": "1098",
  "format": "json"
}

To get the data to return in csv format, make the same call as for json data but change the format parameter from json to csv.

{
  "id": "1098",
  "format": "csv"
}

Example call using Postman

Example Response:

{"success":true,"data":{"url":"https://ballotpedia-data-clients.s3.amazonaws.com/metabase_query_results_1253.json?AWSAccessKeyId=XXXXXXXXXXXXXXX&Expires=XXXXXXX&Signature=XXXXXXXX"},"message":"Success"}

The URL for the downloadable file expires after 5 minutes. The URL returned should change with each call to getQueryResults. Files are re-generated daily, and the URL will always return only the last generated file.