Submitting CFBD predictions with HTTP requests

John Edwards -

A week ago on the College Football Data Discord, some folks were discussing the difficulties of updating their predictions for the CFBD Model Pick'em Contest:

I see this complaint a fair amount–it is difficult to track all of the games that are available to pick, not to mention significant changes to the outlook of different games (a team's starting QB being scratched with injury, for instance). That's why one of my top tips for doing well in the CFBD Model Pick'em is to automate everything! This does not just mean how you make your predictions, but how you submit your predictions as well.

Thanks to some new features implemented by Bill, I have since moved beyond the Selenium-based pipeline I implemented a few years ago, and now my entire CFBD Model Pick'em pipeline relies on a series of simple HTTP calls. In this post, I will demonstrate how to format and execute these calls using cURL. cURL is an open-source library for uploading and downloading data from websites.

It is extremely unlikely that you will write these pipelines exclusively in cURL–rather, you will likely use a cURL wrapper library in your language of choice. Fortunately, the fantastic free website curlconverter.com will allow you to copy and paste valid cURL commands and convert them to the language of your choice (R, Python, etc.)

Obtaining your token

To begin, we will need to obtain a token for submitting to the game. We will first need to sign up for the predictions game if we have not done so already, then log in with our account. Visit predictions.collegefootballdata.com and sign in with one of the available options.

Once logged in, go to predictions.collegefootballdata.com/api/auth/token. You will see a long string of characters–this is your prediction token. This is a unique identifier that the CFBD Model Pick'em API will use to check that it is genuinely you submitting your picks, and not someone else.

Two very important notes:

  1. This token is different from your basic CFBD API key and these cannot be used interchangeably! So do not swap them around–you cannot use your car key to open your house and vice versa!
  2. Do not share this token with anyone! If you give this token to someone else, they can log into your account and access your predictions and information.

This token will work for one month. You can simply set a reminder for yourself once a month to update the prediction token when convenient.

Getting games to pick

Now that we have our token, we can begin to make HTTP requests to the site using cURL.

The most basic HTTP request is a GET request–when we make a GET request, we are asking the url we are querying to get us data and return it to us in some format. We first need to specify the web url we are trying to query, which is the picks endpoint of the CFBD Model Pick'em API. This API contains the list of games for which we can submit picks in a given week.

curl 'https://predictionsapi.collegefootballdata.com/api/picks'
{"error":"Unauthorized"}

Bummer! We cannot see the games to pick unless we can prove we have a CFBD Model Pick'em account. No matter, we will just need to give it our token. To do this, we will need to pass in our token as a header, which is specified with an -H tag. Note the backslashes (\) in our request–they allow us to put parts of our command on different lines, which allow us to make our requests more readable.

Much like querying the CFBD API, we simply pass the header 'authorization: Bearer {your token here--no brackets!} into our request as a header to our basic request. 

curl 'https://predictionsapi.collegefootballdata.com/api/picks' \
  -H 'authorization: Bearer {your token here!}'
[{"id":401754531,"season":2025,"seasonType":"regular","week":3,"homeId":154,"homeTeam":"Wake Forest","awayId":152,"awayTeam":"NC State","spread":7.5,"pickId":120172,"pick":[REDACTED]},
...
{"id":401752921,"season":2025,"seasonType":"regular","week":14,"homeId":130,"homeTeam":"Michigan","awayId":194,"awayTeam":"Ohio State","spread":5.5,"pickId":104248,"pick":[REDACTED]}]

With this request, we have raw JSON data representing all of the games we have to pick! The id for each game returned by your request is identical to the id for games returned by requests to the CFBD API, so you can easily determine which games you need to predict for the contest.

Submitting predictions

Suppose we have our prediction for the Michigan/Ohio State game for the end of the season–we predict Michigan will win by 3.5 points (Bill will not let me publish this blog post if I do not have Michigan winning). We want to submit our prediction to the site. How can we? We have three options:

  1. We can manually submit our prediction on the website.
  2. We can use the CSV import button on the website to submit our prediction for the game and any other games we want to make predictions for.
  3. We can use cURL to make another HTTP request and submit our predictions algorithmically!

The third option is going to integrate most seamlessly into any prediction pipeline we build. To do this, we can craft another cURL, this time making a POST request.

A POST request is kind of like sending a letter–you put what you want to send in your envelope, address it, and then POST it in the mail.

Just like before, we will need to include authorization for our request. Then, as a second header, we will need to tell cURL what format the data we are sending it is in–in this case, we are sending it some JSON. Finally, we send it some formatted JSON to reflect the pick we are submitting:

curl 'https://predictionsapi.collegefootballdata.com/api/picks' \
  -H 'authorization: Bearer {your token here!}' \
  -H 'content-type: application/json' \
  --data-raw '{"gameId":401752921,"pick":-3.5}'

We don't get any output to our console with this request, but if we check the website, we can see that our submission went through to the predictions page!

Our final prediction

Wrapping it up

Keep in mind to use HTTP requests responsibly–you do not want to spam a website with HTTP requests, as this can cause an unintentional denial of service or "DoS" attack or cause your IP to be limited (or even banned!) if you are not careful. Make sure you put adequate time in between HTTP requests to allow the website enough time to process your requests.

This should arm you with the tools to quickly pull in, predict, and submit your forecasts to the CFBD Model Pick'em! If you have data structured with a prediction for each CFBD game ID, submitting your predictions becomes a cinch. And because of how many languages allow you to submit HTTP requests, it should take very little work to submit predictions automatically using whatever language you use to generate predictions! Enjoy and best of luck in the prediction contest!