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

• Saiem Gilani

• Akshay Easwaran

• Jared Lee
  

• Eric Hess
  

Our Contributors (they’re awesome)

• Nate Manzo

• Michael Egle

• Jason DeLoach

• Tej Seth

• Conor McQuiston

• Tan Ho

• Keegan Abdoo

• Matt Spencer

• Sebastian Carl

• John Edwards
  

• Brad Hill
  

Authors Emeritus - cfbscrapR[archived]

• Meyappan Subbiah

• Parker Fleming

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