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.

Data status

The release-backed load_*() functions read assets on sportsdataverse-data (load_cfb_schedules(), load_cfb_rosters() and load_cfb_teams() call the CFBD API instead). The badges below are rebuilt nightly from each producer’s latest workflow run and newest release files; idle means the sport is out of season. Full detail: sportsdataverse.org/status.

Dataset	Data updated	Through	Pipeline	Update workflows
College football (ESPN)
College football play-by-play (CollegeFootballData)
College football (stats.ncaa.org)
Conference, division and ballpark reference				—

Installation

You can install the CRAN version of cfbfastR with:

install.packages("cfbfastR")

You can install the latest build from R-universe with:

install.packages("cfbfastR", repos = c("https://sportsdataverse.r-universe.dev", getOption("repos")))

You can install the development version of cfbfastR from GitHub with:

if (!requireNamespace("pak", quietly = TRUE)) install.packages("pak")
pak::pak("sportsdataverse/cfbfastR")
# or, with remotes:
# if (!requireNamespace("remotes", quietly = TRUE)) install.packages("remotes")
# remotes::install_github("sportsdataverse/cfbfastR")

Quick start

The release loaders need no API key; the cfbd_*() functions need a CFBD_API_KEY (see College Football Data API Keys below).

library(cfbfastR)

# play-by-play with EPA/WPA for a season, from the data releases
pbp <- load_cfb_pbp(seasons = 2024)

# today's games from the ESPN scoreboard
espn_cfb_scoreboard()

# week 1 game info from the CollegeFootballData API
cfbd_game_info(year = 2024, week = 1)

Every loader family is listed under Full Season Data Loaders, and the intro vignette walks through a first analysis.

Full Season Data Loaders

cfbfastR ships five 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()`	The original cfbfastR EPA/WPA play-by-play	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, ESPN↔︎Fox↔︎Yahoo 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+
Conference & division membership	`load_cfb_groups()`, `load_cfb_group_seasons()`, `load_cfb_group_aliases()`, `load_cfb_team_group_seasons()`	Subdivision, conference and division lineages, each group’s name, parent and member count by season, ESPN/CFBD id aliases, and every team’s groups per season	1869+

Which play-by-play do I want?

load_cfb_pbp() — the classic cfbfastR pbp with the full EPA/WPA model columns; 2014+, FBS games plus FCS games from 2022 (filter on home_team_division / away_team_division). Existing code keeps working unchanged.
load_espn_cfb_pbp() — the ESPN-derived pbp (about 500 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.

These release 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.

load_cfb_schedules(), load_cfb_rosters() and load_cfb_teams() are not release loaders: they call the CollegeFootballData API (through cfbd_game_info(), cfbd_team_roster() and cfbd_team_info()), so they need a CFBD_API_KEY and take no dbConnection or tablename. load_cfb_teams() takes fbs_only instead of seasons.

CollegeFootballData API coverage

The cfbd_*() wrappers cover 93 of the 93 endpoints in the current CFBD specification (v5.33.2). The most recent additions are the punting, 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")

# every punt with gross, net and return yards and where the kick ended
cfbd_punting_plays(year = 2025, week = 1, team = "Texas")

The passing and rushing endpoints begin in 2025 and the punting endpoints in 2015; earlier seasons return an empty data frame rather than an error. See ?cfbd_passing, ?cfbd_rushing and ?cfbd_punting — the frames are wide (up to 385 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.

Proxy support

If you run cfbfastR from behind a corporate proxy, set it once per session and every cfbd_*() call routes through it (the espn_cfb_*() functions don’t read this option):

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 for full detail.

Model cache

The EPA, win probability and other models behind calculate_*(), cfbd_pbp_data(epa_wpa = TRUE) and espn_cfb_pbp(epa_wpa = TRUE) are downloaded from GitHub the first time they are needed. They are cached in file.path(tools::R_user_dir("cfbfastR", "cache"), "models") and refreshed once a day (change it in seconds, e.g. options(cfbfastR.cache_duration = 7 * 86400) for a week). A model is kept in memory for the rest of the R session once it is loaded, so the daily refresh does not reach a session that already uses it: restarting R drops the loaded models but not the cache, so a new session still reads the cached copy until it expires. An expired copy only triggers a download attempt: if the download fails, the expired copy is used and stays loaded for the session. To pick up a new model at once, run cfb_clear_model_cache(), which deletes the cache and the loaded models; do that with a working connection, since it also removes the offline fallback.

Documentation

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")

Companion packages

Other SportsDataverse packages work directly on cfbfastR data:

cfbseedR — simulate college football seasons: conference standings with each conference’s tiebreakers and the 12-team College Football Playoff. CRAN: install.packages("cfbseedR").
cfb4th — fourth-down decision tables (go, field goal or punt) on cfbfastR play-by-play. r-universe only.
sdvplotR — team logos, colors, headshots and gt tables for every SportsDataverse league, league = "cfb" included. r-universe only.
sportyR — regulation playing surfaces for ggplot2, including the college football field (geom_football("ncaa")). CRAN: install.packages("sportyR").
cfbplotR — college football logos and colors for ggplot2 and gt. r-universe only.

The r-universe packages install with:

install.packages(
  c("cfb4th", "sdvplotR", "cfbplotR"),
  repos = c("https://sportsdataverse.r-universe.dev", getOption("repos"))
)

The SportsDataverse

cfbfastR is part of the SportsDataverse, a set of open-source packages for sports data.

Package	Sport / Scope
cfbfastR	College football
hoopR	Men’s basketball (NBA and NCAA)
wehoop	Women’s basketball (WNBA and NCAA)
fastRhockey	Hockey (NHL and PWHL)
baseballr	Baseball (MLB, MiLB, NCAA)
softballR	College softball
oddsapiR	Sports betting odds
recruitR	College football recruiting
usfootballR	US soccer
cfbseedR · cfb4th	CFB playoff simulation · fourth-down decisions
cfbplotR · sdvplotR · sportyR	Logos, colors, tables · playing surfaces
sportsdataverse-R	Umbrella R metapackage
sportsdataverse-py · sportsdataverse.js	Python and Node.js

See the full ecosystem at sportsdataverse.org.

Follow cfbfastR and the SportsDataverse on X and star this repo

Our Authors

Our Contributors (they’re awesome)

Authors Emeritus - `cfbscrapR`[archived]

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.

Code of Conduct

Please note that the cfbfastR project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.

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

License

cfbfastR is released under the MIT License.