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.
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")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.
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.
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-HERESave 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")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
-
Jared Lee
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.
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}
}