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:
Login with provided password and click to download latest file (for non-technical users)
Access latest data file via API (for technical users, see next page)
API instructions
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 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 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.
Last updated