cfbfastR
Access College Football Play by Play Data
A utility to quickly obtain clean and tidy college football data. Serves as a wrapper around the < https://collegefootballdata.com/> API and provides functions to access live play by play and box score data from ESPN < https://www.espn.com> when available. It provides users the capability to access a plethora of endpoints, and supplement that data with additional information (Expected Points Added/Win Probability added).
cfbfastR 
The goal of cfbfastR is
to provide the community with an R package for working with CFB data. It
is an R API wrapper around https://collegefootballdata.com/. Beyond
data aggregation and tidying ease, one of the multitude of services that
cfbfastR provides is for
benchmarking open-source expected points and win probability metrics.
Installation
You can install the CRAN version of
cfbfastR with:
install.packages("cfbfastR")
You can install the released version of
cfbfastR from
GitHub with:
# You can install using the pacman package using the following code:
if (!requireNamespace('remotes', quietly = TRUE)){
install.packages('remotes', repos = "https://cloud.r-project.org")
}
remotes::install_github("sportsdataverse/cfbfastR")
Full Season Data Loaders
cfbfastR ships four loader families that pull pre-built season
datasets from the sportsdataverse-data
releases
— no API key, no scraping, one function call per dataset:
| Family | Functions | Source / contents | Coverage |
|---|---|---|---|
| Classic | load_cfb_pbp(), load_cfb_schedules(), load_cfb_rosters(), load_cfb_teams() |
The original cfbfastR EPA/WPA play-by-play + companions | pbp 2014+ |
| ESPN | load_espn_cfb_*() (27) |
ESPN-derived datasets: pbp, schedules, team/player box, drives, game rosters, linescores, betting, play participants, FPI power index, percentiles, passing/rushing/receiving EPA splits, team summaries, model pbp, and eleven adv_* advanced-stat datasets |
mostly 2004+ |
| Ratings & recruiting | load_cfb_ratings(), load_cfb_ratings_weekly(), load_cfb_fpi_weekly(), load_cfb_team_summaries_weekly(), load_cfb_team_talent(), load_cfb_recruits(), load_cfb_recruiting_proj(), load_cfb_returning_production(), plus the load_cfb_*_crosswalk() id crosswalks |
Season/weekly power ratings, talent composite, recruiting, CFBD↔ESPN id crosswalks | varies (2002+) |
| NCAA (stats.ncaa.org) | load_ncaa_mfb_*() (10) |
pbp (native + cfbfastR-shaped), drives, linescore, officials, player/team stats, rosters, schedule, teams — includes FCS and lower divisions ESPN misses | 2013+ |
Which play-by-play do I want?
load_cfb_pbp()— the classic cfbfastR pbp with the full EPA/WPA model columns; FBS, 2014+. Existing code keeps working unchanged.load_espn_cfb_pbp()— the ESPN-derived pbp (469 columns incl. EPA/WPA and participant ids) with deeper history, 2004+.load_ncaa_mfb_pbp()— stats.ncaa.org pbp incl. FCS and lower divisions, 2013+;load_ncaa_mfb_pbp_cfbfastr()is the same data reshaped onto cfbfastR pbp column conventions for cross-source binds.
All loaders accept a vector of seasons (or seasons = TRUE for
everything published) and an optional dbConnection + tablename to
write straight into a database instead of returning a tibble.
Breaking Changes
College Football Data API Keys
The CollegeFootballData API now requires an API key, here’s a quick run-down:
-
To get an API key, follow the directions here: College Football Data Key Registration.
-
Using the key: You can save the key for consistent usage by adding
CFBD_API_KEY=YOUR-API-KEY-HEREto your .Renviron file (easily accessed viausethis::edit_r_environ()). Runusethis::edit_r_environ(), a new script will pop open named.Renviron, THEN paste the following in the new script that pops up (without quotations)
CFBD_API_KEY = YOUR-API-KEY-HERE
Save the script and restart your RStudio session, by clicking Session
(in between Plots and Build) and click Restart R (there also
exists the shortcut Ctrl + Shift + F10 to restart your session). If
set correctly, from then on you should be able to use any of the cfbd_
functions without any other changes.
- For less consistent usage: At the beginning of every session or
within an R environment, save your API key as the environment
variable
CFBD_API_KEY(with quotations) using a command like the following.
Sys.setenv(CFBD_API_KEY = "YOUR-API-KEY-HERE")
Proxy support
If you run cfbfastR from behind a corporate proxy, set it once per
session and every cfbd_*() / espn_cfb_*() call routes through it:
options(cfbfastR.proxy = "http://proxy.host.example:8080")
# or, for an authenticated proxy:
options(cfbfastR.proxy = list(
url = "http://proxy.host.example", port = 8080,
username = "me", password = "pw", auth = "basic"
))
The resolution order is: explicit proxy = argument ->
getOption("cfbfastR.proxy") -> http_proxy / https_proxy env vars.
See the intro
vignette and
CLAUDE.md for full detail.
Follow cfbfastR and the SportsDataverse on Twitter and star this repo
Our Authors
-
Jared Lee
Our Contributors (they’re awesome)
Authors Emeritus - cfbscrapR[archived]
Special Thanks
Citations
To cite the cfbfastR R
package in publications, use:
BibTex Citation
@article{gilani_et_al_2021_cfbfastr,
author = {Saiem Gilani and Akshay Easwaran and Jared Lee and Eric Hess},
title = {cfbfastR: Access College Football Play by Play Data},
url = {https://cfbfastR.sportsdataverse.org/},
doi = {10.32614/CRAN.package.cfbfastR},
journal = {CRAN: Contributed Packages},
publisher = {The R Foundation},
year = {2021}
}