Introduction:

The Cook Political Report API is a simple RESTful API that provides CPR Race Ratings for US House, US Senate, Governor and Presidential elections. The House ratings API also includes the Cook PVI. The API requires HTTP basic authentication with an email and password to access the data. The data is returned in JSON format with a consistent structure for each endpoint.

The CPR Race Ratings are never updated more than one time a day, and, depending on the time within the election cycle, changes may be infrequent. Please limit API calls to once a day. Contact us for more guidance.

Learn more about how to request access to the CPR API.

Authentication:

The API uses basic authentication, and requires that an authentication header be passed to access the API endpoints.  The format of the authentication header is:

Authorization: Basic $AUTHENTICATION_STRING

where $AUTHENTICATION_STRING is a user’s email address and password for their user account, that has been base64 encoded.  The user’s email address and password are concatenated into a single credentials string, with a colon (:) as the separator.

The format of the unencoded credentials string is [email protected]:mypassword.

Follows is a link to a website that can provide base64encoding for the credentials string:  https://www.base64encode.org/

Simply paste an unencoded credentials string into the top text area, and click the “Encode” button, and the bottom text area will return the encoded string.

Accessing an endpoint with properly encoded credentials can be accomplished as follows:

cURL request:

curl https://www.cookpolitical.com/api/race/house -H "Authorization: Basic $AUTHENTICATION_STRING" -H "Accept: application/json"

PHP Code Example:


// User credentials
$credentials = "[email protected]:mypassword";
// API endpoint
$endpoint = "https://www.cookpolitical.com/api/race/house";
// Encoded user credentials 
$auth = base64_encode($credentials);
// Initialize a curl session 
$request = curl_init();
// Set the request URL
curl_setopt($request, CURLOPT_URL, $endpoint);
// Create and set the authorization header and response type as application/json
$headers = ['Authorization: Basic ' . $auth, 'Accept: application/json'];
curl_setopt($request, CURLOPT_HTTPHEADER, $headers);
// Send the request and store the data as output
$output = curl_exec($request);
// Close the curl session
curl_close($request);
// Print the data to the screen
print $output;

Python Code Example:

import requests
# User credentials
credentials = "[email protected]:mypassword"
# API endpoint 
endpoint = "https://www.cookpolitical.com/api/race/house"
# Encoded user credentials 
auth = base64.b64encode(credentials.encode()).decode('utf-8')
# Set up the headers 
headers = { 'Authorization': 'Basic ' + auth, 'Accept': 'application/json', 'Cache-Control': 'no-store' }
# Send the request and capture the response
response = requests.get(endpoint, headers=headers)
# Print the response 
content print(response.text)

Note: The python code above uses the requests library installed in your Python environment to make the HTTP request.  The library can be installed using: pip install requests.

Endpoints:

The API provides three endpoints to retrieve the current CPR Race Ratings for House (+ Cook PVI), Senate, and Governor elections. The endpoints are:

US House Endpoint:

The House endpoint provides the current CPR Race Ratings for US House elections. The response is returned in JSON format, with 50 items, and the following structure:

{

  "Title": "ME-01 2024",
  "State": "Maine",
  "District": "ME-01",
  "Incumbent": "Chellie Pingree (D)",
  "Cook_PVI": "D+9",
  "Rating": "Solid D",
  "Cycle": "2024",
  "Rating_date": "2023-02-02T00:14:22"
}

US Senate Endpoint:

The Senate endpoint provides the current CPR Race Ratings for Senate elections. The response is returned in JSON format with the following structure:

{

  "Title": "AZ Senate 2024",
  "State": "Arizona",
  "Incumbent": "Kyrsten Sinema (I)",
  "Rating": "Toss Up"
}
 

Governor Endpoint:

The Governor endpoint provides the current CPR Race Ratings for Governor elections. The response is returned in JSON format with the following structure:

{

  "Title": "KY Governor 2023",
  "State": "Kentucky",
  "Incumbent": "Andy Beshear (D)",
  "Rating": "Lean D"
}

Presidential Endpoint:

The Presidential endpoint provides the current CPR Race Ratings for Presidential elections. The response is returned in JSON format with the following structure:

{

  "Title": "EC Alabama (5)",
  "State": "Alabama",
  "Electoral_votes": "5",
  "Rating": "Solid R"
  "Cycle": "2024",
  "Rating_date": "2023-03-16T17:12:44",
}
 

The meaning of each field is as follows:

  • Title: the title of the election.
  • State: the state in which the election is held.
  • District: the district number in which the election is held.
  • Incumbent: the name and party affiliation of the incumbent.
  • Cook_PVI: the Cook Partisan Voting Index score for the district.
  • Rating: the current CPR Race Rating for the election.

Pager:

The page's number is an integer. It is used to gain more information or to page through the results. Must be larger than 0; 0 is the default.

Example:

  • Start the results at a specified point. As there are more than 1000 sources, they can't be returned in one query. This returns the next sources in sequence (and would normally also be used with the page parameter.

    GET:

    https://www.cookpolitical.com/api/race/house?page=2