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

Full News on Releases

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-HERE to your .Renviron file (easily accessed via usethis::edit_r_environ()). Run usethis::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

Our Contributors (they’re awesome)

Authors Emeritus - `cfbscrapR`[archived]

Special Thanks

Nick Tice

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}
}