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 pak 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.

CollegeFootballData API coverage

The cfbd_*() wrappers cover all 84 endpoints in the current CFBD specification (v5.27.1). The most recent additions are the passing and rushing families, which carry charting detail the older cfbd_stats_*() and cfbd_metrics_*() functions do not:

# season passing production, split across seven pass locations
cfbd_passing_players_season(year = 2025, team = "Texas")

# every pass with air yards, YAC, target id and location
cfbd_passing_plays(year = 2025, week = 5, outcome = "interception")

# rushing production split across four run directions, offense and defense
cfbd_rushing_teams_season(year = 2025, team = "Texas")

These endpoints begin in 2025; earlier seasons return an empty data frame rather than an error. See ?cfbd_passing and ?cfbd_rushing — the frames are wide (up to 375 columns) because one production block repeats per location or direction, so the family topics document the block and the naming scheme once instead of listing every column.

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

Cheat sheet

A printable one-page reference for cfbfastR — the function families, the loaders, and what each one returns.

📄 Download the cfbfastR cheat sheet (PDF)

Free to download, print and hand out; light and dark, US Letter landscape. Every SportsDataverse package has one — browse them all at sportsdataverse.org/cheatsheets.

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 = {2026}
}