Getting started with geographic APIs

Ballotpedia’s Geographic APIs allow anyone with an active API key to query the API endpoints.

Required parameters: These parameters are required to successfully hit the endpoint.

Optional parameters: These parameters are optional and accept one or more from the given comma separated list described under each endpoint.

Data points: Not all data points may be returned as shown in the examples depending on your API package.

Changes: We avoid making breaking changes to API endpoints or the structure of returned data without notice. New endpoints and data elements may be added at any time, but we alert our API customers via email 1 month in advance of small changes (like a field being renamed or its format changed) and 3 months in advance of larger changes (like data structure changes or endpoints being retired, etc.). We also avoid making such changes close to large elections to avoid disruptions. If you have questions about this policy, please contact [e-mail].

All of the endpoints accept HTTP GET requests only. The following two HTTP headers must be included:

x-api-key: your_api_key
Content-Type: application/json

Data will be JSON-formatted text, and successful queries will receive an HTTP 200 response. Unsuccessful queries will respond with an appropriate HTTP response code in the 4xx or 5xx type.

Please note that in order to hit the following endpoints from an application on the internet, you must contact the Ballotpedia team to whitelist the domains from which those requests will originate. Requests from non-whitelisted origin domains will receive a preflight CORS permissions error. You are free to run test requests locally or in a non-cors context such as cURL, Postman, etc.

Examples

Via cURL:

curl "https://api4.ballotpedia.org/data/the-endpoint-name-and-options" -X GET -H 'x-api-key: your-api-key' -H 'Content-Type: application/json' 

Via PHP:

    $curl = curl_init();
    curl_setopt_array($curl, array(
      CURLOPT_URL => 'https://api4.ballotpedia.org/data/the-endpoint-name-and-options',
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_ENCODING => '',
      CURLOPT_MAXREDIRS => 10,
      CURLOPT_TIMEOUT => 0,
      CURLOPT_FOLLOWLOCATION => true,
      CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
      CURLOPT_CUSTOMREQUEST => 'GET',
      CURLOPT_HTTPHEADER => array(
        'Content-Type: application/json',
        'x-api-key: your-api-key'
      ),
    ));
    
    $response = curl_exec($curl);
    
    curl_close($curl);
    echo $response;

Via JavaScript:

var myHeaders = new Headers();
myHeaders.append("Content-Type", "application/json");
myHeaders.append("x-api-key", "your-api-key");

var requestOptions = {
    method: 'GET',
    headers: myHeaders
};

fetch("https://api4.ballotpedia.org/data/the-endpoint-name-and-options", requestOptions)
    .then(response => response.text())
    .then(result => console.log(result))
    .catch(error => console.log('error', error));

Samples

Download sample data sets:

• https://external-api-guide.s3.amazonaws.com/external-api-sample-set.zip
• https://external-api-guide.s3.amazonaws.com/external-api-sample-set-2.zip