Changelog

Source: NEWS.md

cfbfastR v2.0.0

CRAN release: 2025-09-09

Breaking Changes to Loading Functions

• All load_cfb_*() functions now use sportsdataverse-data releases or the CollegeFootballData.com API as their underlying data source to remain in compliance with CFBD API terms and conditions (See Note below).
• Updated load_cfb_pbp() dataset to include various team- and game-level ID’s and flags that were not being included, like home_team_id, away_team_id, season_type, venue_id, some drive_* columns, a half-dozen player stat columns, etc. Essentially, all the leg-work users have undoubtedly had to do while using these datasets is mostly just included now. The downside: this means end users need to check their pipelines which build off these datasets to ensure behavior is as expected and all your joins are doing what is intended.

Now upgraded to the CFBD v2 API

Special thanks are in order for our newest contributor, Brad Hill (@bradisbrad) for providing most of the v2 upgrade via his first PR to cfbfastR!! 🙌🏽 👑 🥇 Your contributions are most appreciated by the community.

Note: The free-tier API key for the CFBD v2 API has a strict 1k calls/month limit, so plan your workflows accordingly! If you receive errors mentioning r Request failed [429], you have most likely run out of API calls for the month in your membership tier.

• Added all new cfbd_*() functions accommodated by the new College Football Data API v2. This includes the following functions:

  • Added cfbd_metrics_fg_ep() function to access the new field goal expected points added metric from the API.
  • Added cfbd_metrics_wepa_team_season() function to access the new opponent adjusted team season predicted points added metric from the API.
  • Added cfbd_metrics_wepa_players_passing() function to access the new opponent adjusted players passing predicted points added metric from the API.
  • Added cfbd_metrics_wepa_players_rushing() function to access the new opponent adjusted players rushing predicted points added metric from the API.
  • Added cfbd_metrics_wepa_players_kicking() function to access the new Points Added Above Replacement (PAAR) ratings for kickers from the API.
  • Added cfbd_ratings_fpi() function to access the new FPI ratings from the API.
  • Added cfbd_live_scoreboard() function to access live scoreboard data from the API.
  • Added cfbd_live_plays() function to access live play-by-play data from the API.
  • Added cfbd_api_key_info() function to get information about your API key, including your Patreon level and usage limits.

• Minor changes to the existing cfbd_*() functions under the hood to accommodate the new API v2 structure. Please see below for a list of all updated functions:

  • Updated cfbd_betting_lines() function
  • Updated cfbd_coaches() function
  • Updated cfbd_conferences() function
  • Updated cfbd_drives() function
  • Updated cfbd_calendar() function
  • Updated cfbd_game_box_advanced() function
  • Updated cfbd_game_info() function
  • Updated cfbd_game_media() function
  • Updated cfbd_game_player_stats() function
  • Updated cfbd_game_records() function
  • Updated cfbd_game_team_stats() function
  • Updated cfbd_metrics_ppa_games() function
  • Updated cfbd_metrics_ppa_players_games() function
  • Updated cfbd_metrics_ppa_players_season() function
  • Updated cfbd_metrics_ppa_predicted() function
  • Updated cfbd_metrics_ppa_teams() function
  • Updated cfbd_metrics_wp() function
  • Updated cfbd_metrics_wp_pregame() function
  • Updated cfbd_pbp_data() function
  • Updated cfbd_play_stats_player() function
  • Updated cfbd_play_stats_types() function
  • Updated cfbd_play_types() function
  • Updated cfbd_plays() function
  • Updated cfbd_player_info() function
  • Updated cfbd_player_returning() function
  • Updated cfbd_player_usage() function
  • Updated cfbd_rankings() function
  • Updated cfbd_ratings_sp() function
  • Updated cfbd_ratings_sp_conference() function
  • Updated cfbd_ratings_srs() function
  • Updated cfbd_recruiting_player() function
  • Updated cfbd_recruiting_position() function
  • Updated cfbd_recruiting_team() function
  • Updated cfbd_stats_categories() function
  • Updated cfbd_stats_game_advanced() function
  • Updated cfbd_stats_season_advanced() function
  • Updated cfbd_stats_season_player() function
  • Updated cfbd_stats_season_team() function
  • Updated cfbd_team_info() function
  • Updated cfbd_team_matchup() function
  • Updated cfbd_team_matchup_records() function
  • Updated cfbd_team_roster() function
  • Updated cfbd_team_talent() function
  • Updated cfbd_venues() function

• Fixed the following functions and/or documentation:

  • Documentation cfbd_team_info() addressing #97
  • Ensuring cfbd_stats_game_advanced() returns an empty data frame when there are no results
  • Documentation cfbd_game_team_stats() updated to reflect all parameter requirement scenarios.
  • Fixed athlete_id parameter cfbd_player_usage() so that it works as users would expect. There was an API query-parameter mismatch
  • Fixed athlete_id parameter for cfbd_play_stats_player() function and added more thorough documentation.
  • Fixed returned position to correct value (instead of NA) from cfbd_stats_season_player()
  • Added more thorough season_type parameter documentation across many functions
  • Changed behavior of cfbd_pbp_data() to substitute 3 timeouts per half when the data is missing from the API.

cfbfastR v1.9.5

• fixed breaking bug related to stringi v1.8 update in cfbd_play_pbp_data() EPA and WPA processing
• Minor documentation and test updates

cfbfastR v1.9.4

• Improve date parsing for espn_cfb_scoreboard() and espn_cfb_schedule() functions while adding lubridate dependency
• Made a minor tweak to the returns of the espn_ratings_fpi() function

cfbfastR v1.9.3

• Add division parameter to the following functions:
  • cfbd_game_info()
  • cfbd_plays()
  • cfbd_drives()
  • cfbd_game_media()
  • cfbd_game_team_stats()

cfbfastR v1.9.2

• espn_cfb_player_stats() function added.

cfbfastR v1.9.1

• Improved drive_pts logic in play-by-play data.
• Fixed an issue that occasionally made the cfbd_game_team_stats() function return data in a long format
• Minor documentation and test updates

cfbfastR v1.9.0

CRAN release: 2022-06-13

Added functions to access ESPN API:

• espn_cfb_calendar()
• espn_cfb_schedule()
• Added EPA and WPA processing to espn_cfb_pbp()
• espn_cfb_team_stats()

Added functions to pull data from the data repo:

• load_cfb_rosters()

• load_cfb_schedules()

• load_cfb_teams()

• Removes furrr, future dependencies, adds Rcpp, RcppParallel, and purrr dependencies

cfbfastR v1.8.0

• All functions now default to return tibbles.
• Added S3 method to print outputs with data info and retrieval timestamps. Thank you to Tan Ho (@tanho36) for the idea.

cfbfastR v1.7.1

• Added espn_ratings_fpi() to exports.

cfbfastR v1.7.0

• Added cfbd_recruiting_transfer_portal().

cfbfastR v1.6.7

• Fixed bug in cfbd_game_team_stats() with _allowed columns duplicating team stats instead of showing opponent stats.
• Updated tests and documentation for cfbd_game_team_stats().

cfbfastR v1.6.6

• Updated function cfbd_pbp_data() to account for additional timeout cases (namely, kickoffs/extra point attempts).

cfbfastR v1.6.5

• Updated tests and documentation for cfbd_betting_lines()
• API call in espn_ratings_fpi() now requires headers in httr request

cfbfastR v1.6.4

CRAN release: 2021-10-27

• Changed options to revert to old options on exit of function.
• Removed check_github functions.

cfbfastR v1.6.3

• Switched package urls in DESCRIPTION again.

cfbfastR v1.6.2

• Switched package urls in README and DESCRIPTION files to https://

cfbfastR v1.6.1

• Removed source urls from many package documentation entries.
• Updated a test to skip on CRAN

cfbfastR v1.6.0

• Added cfbd_ratings_elo() function
• Fixed a bug in update_cfb_db() where the function failed when trying to load recent games from the data repo. (#35)
• Added the option cfbfastR.dbdirectory that allows to set the database directory in update_cfb_db() globally.

cfbfastR v1.5.2

• Remove verbose parameter

cfbfastR v1.5.1

Minor release

• Removed calculated columns from cfbd_stats_season_team() that were not behaving correctly
• Fixed bug where only_fbs input in cfbd_team_info() was ignored. It is now possible to get the team info for all the colleges in the API instead of only FBS schools.
• Removed default year from cfbd_metrics_ppa_teams. cfbd_metrics_ppa_teams and cfbd_metrics_ppa_players_season now require one of team or year to be specified

cfbfastR v1.5.0

Added espn_cfb_scoreboard()

Added espn_cfb_pbp()

cfbfastR v1.4.0

Added cfbd_game_weather()

cfbfastR v1.3.3

Hotfix cfbd_game_player_stats()

cfbfastR v1.3.2

Added ID linking to cfbd_recruiting_players()

cfbfastR v1.3.0-1

Added three NFL draft functions:

• cfbd_draft_teams() - Get list of NFL teams
• cfbd_draft_positions() - Get list of NFL positions for mapping to collegiate
• cfbd_draft_picks() - Get list of NFL Draft picks

cfbfastR v1.2.1

Minor release

• Added headshot_url to outputs of cfbd_team_roster()

• Renamed returns in cfbd_game_box_advanced():

  • rushing_line_yd_avg to plural rushing_line_yds_avg
  • rushing_second_lvl_yd_avg to plural rushing_second_lvl_yds_avg
  • rushing_open_field_yd_avg to plural rushing_open_field_yds_avg

• Completed documentation for all returns except cfbd_pbp_data()

• Continued work on intro vignette

cfbfastR v1.2.0-1

Add significant documentation to the package

• Added mini-vignettes pertaining to CFB Data functionality:
  • cfbd_betting,
  • cfbd_games,
  • cfbd_plays,
  • cfbd_recruiting,
  • cfbd_stats,
  • cfbd_teams
• Introductory vignette stub added

ESPN/CFBD metrics function variable return standardization

• Change id variable to team_id in espn_ratings_fpi()
• Changed espn_game_id variable to game_id in espn_metrics_wp(), corrected the away_win_percentage calculation and added tie_percentage to the returns.
• Change id variable to athlete_id in cfbd_metrics_ppa_players_season()

cfbfastR v1.1.0

Add loading from Data Repository functionality

• Added load_cfb_pbp() and update_cfb_db() functions. Pretty much cherry-picking the nflfastR methodology of loading data from the cfbfastR-data repository.

Add support for parallel processing and progress updates

• Added furrr, future, and progressr dependencies to the package to allow for parallel processing of the play-by-play data with progress updates if desired.

cfbfastR v1.0.0

Function Naming Convention Change

• All functions sourced from the College Football Data API will start with cfbd_ as opposed to cfb_ (as in cfbscrapR). One additional cfbd_ function has been added that corresponds to the result when cfbd_pbp_data() has the parameter epa_wpa=FALSE. It has now been separated into its own function for clarity cfbd_plays(). The parameter and functionality still exists in cfbd_pbp_data() but we expect this function will still exist but made obsolete in favor of a function more closely matching nflfastR’s naming conventions.

• Similarly, data and metrics sourced from ESPN will begin with espn_ as opposed to cfb_. In particular, the two functions are now espn_ratings_fpi() and espn_metrics_wp()

• Data generated from any of the cfbfastR methods will use cfb_

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=XXXX-YOUR-API-KEY-HERE-XXXXX 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 = XXXX-YOUR-API-KEY-HERE-XXXXX

Save the script and restart your RStudio session, by clicking Session (in between Plots and Build) and click Restart R (n.b. 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.

{r} Sys.setenv(CFBD_API_KEY = "XXXX-YOUR-API-KEY-HERE-XXXXX")

• Added API Key methods. If you forget to set your environment variable, functions will give you a warning and ask for one.