API Overview

The CompughterRatings API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side web application (though you should never expose your secret API key in any public website's client-side code). JSON is returned by all API responses, including errors.


Organization

The API delivers five key features for college and professional sports: Team Rankings, Conference/Divisional Rankings, Team Report Cards, Game Predictions, and Game Simulations. All ratings, rankings, predictions, and simulations are produced by a proprietary mathematical algorithm and published exclusively through the CompughterRatings API.

Team Rankings Teams are assigned an ordinal ranking for overall performance, power, offense, defense, current strength of schedule, future strength of schedule, and prestige.
Conference/Divisional Rankings For college sports, conference rankings are assigned based on performance ratings of the teams in each conference (ACC, SEC, Pac-12, etc). Similarly, divisional rankings are assigned for professional sports. These rankings depict the overall strength of the conferences or divisions in each sport relative to each other.
Team Report Cards Team performance over the current season is depicted with alphabetic ratings, records, rankings, superlatives, and other interesting statistics.
Game Predictions Final score predictions for every single regular and post season game are computed using the award winning prediction algorithm.
Game Simulations The final score between any two teams can be simulated along with a side-by-side comparative analysis of each team's ratings, rankings, records, superlatives, and other statistics.

Authentication

Authenticate your account when using the API by including your application ID and secret API key in the request. Your API keys carry many privileges, so be sure to keep them secret! Do not share your secret API keys in publicly accessible areas such GitHub, client-side code, and so forth.

To use your API key, you need to pass it along with your application ID in the header of the API call. All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Warning: Do not call the API from client side code such as Javascript or Jquery, as your credentials will be in plain view inside the browser. Usage of your credentials by a 3rd party will count against your rate limit. It is up to you to keep them safe.


Code Examples

The following code snippets demonstrate how to call the API using several popular technologies. Each example depicts the usage of your uniquely assigned application ID and secret API keys.


import requests

url = "https://www.compughterratings.com/api/v1/teamsummary/cbb/Kansas"

headers = {
    'app-id': "[Your App ID]",
    'api-key': "[Your API Key]",
    'cache-control': "no-cache"
    }

response = requests.request("GET", url, headers=headers)

print(response.text)


$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://www.compughterratings.com/api/v1/teamsummary/cbb/Kansas",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
	"api-key: [Your API Key]",
	"app-id: [Your App ID]",
	"cache-control: no-cache"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}


import Foundation

let headers = [
  "app-id": "[Your App ID]",
  "api-key": "[Your API Key]",
  "cache-control": "no-cache"
]

var request = NSMutableURLRequest(URL: NSURL(string: "https://www.compughterratings.com/api/v1/teamsummary/cbb/Kansas")!,
                                        cachePolicy: .UseProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.HTTPMethod = "GET"
request.allHTTPHeaderFields = headers

let session = NSURLSession.sharedSession()
let dataTask = session.dataTaskWithRequest(request, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    println(error)
  } else {
    let httpResponse = response as? NSHTTPURLResponse
    println(httpResponse)
  }
})

dataTask.resume()


Errors

The CompughterRatings API uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted.), and codes in the 5xx range indicate an error with CompughterRatings' servers (these are rare).


Request API Key

30-day free trials are available for developers interested in integrating the CompughterRatings API with their own website or mobile app. To request a free trial, just send us a message.