Skip to contents

Get college football play-by-play data.

Source: R/cfbd_play.R
cfbd_plays.Rd

Get college football play-by-play data.

Usage

cfbd_plays(
  year = 2020,
  season_type = "regular",
  week = 1,
  team = NULL,
  offense = NULL,
  defense = NULL,
  conference = NULL,
  offense_conference = NULL,
  defense_conference = NULL,
  play_type = NULL,
  division = "fbs"
)

Arguments

year

Select year, (example: 2018)

season_type

(String default regular): Season type - regular, postseason, both, allstar, spring_regular, spring_postseason

week

Select week, this is optional (also numeric)

team

Select team name (example: Texas, Texas A&M, Clemson)

offense

Select offense name (example: Texas, Texas A&M, Clemson)

defense

Select defense name (example: Texas, Texas A&M, Clemson)

conference

Select conference name (example: ACC, B1G, B12, SEC, PAC, MAC, MWC, CUSA, Ind, SBC, AAC, Western, MVIAA, SWC, PCC, Big 6, etc.)

offense_conference

Select conference name (example: ACC, B1G, B12, SEC, PAC, MAC, MWC, CUSA, Ind, SBC, AAC, Western, MVIAA, SWC, PCC, Big 6, etc.)

defense_conference

Select conference name (example: ACC, B1G, B12, SEC, PAC, MAC, MWC, CUSA, Ind, SBC, AAC, Western, MVIAA, SWC, PCC, Big 6, etc.)

play_type

Select play type (example: see the cfbd_play_type_df)

division

(String optional): Division abbreviation - Select a valid division: fbs/fcs/ii/iii

Value

cfbd_plays() - A data frame with 27 columns:

col_nametypesdescription
play_idcharacterCFBD play identifier (unique within a game when combined with game_id).
offensecharacterFull name of the offense (team in possession) on the play.
offense_conferencecharacterConference name of the offense (e.g. "SEC", "ACC").
defensecharacterFull name of the defense on the play.
defense_conferencecharacterConference name of the defense (e.g. "SEC", "ACC").
homecharacterFull home team name for the game.
awaycharacterFull away team name for the game.
offense_scoreintegerOffense's score after the play (points).
defense_scoreintegerDefense's score after the play (points).
game_idintegerCFBD game identifier the play belongs to.
drive_idcharacterCFBD drive identifier the play belongs to.
drive_numberintegerSequential drive number within the game (1-indexed).
play_numberintegerSequential play number within the game (1-indexed).
periodintegerGame period / quarter (1-4 regulation, 5+ overtime).
offense_timeoutsintegerTimeouts remaining for the offense at the end of the play.
defense_timeoutsintegerTimeouts remaining for the defense at the end of the play.
yard_lineintegerField-position yard line at the start of the play (0-50 scale from the offense's side).
yards_to_goalintegerDistance in yards from the offense's spot to the opponent's goal line (0-100).
downintegerDown of the play (1-4).
distanceintegerYards to gain for a first down (or to the goal line in goal-to-go situations).
scoringlogicalTRUE when the play results in a score (TD, FG, safety, two-point conversion).
yards_gainedintegerNet yards gained by the offense on the play.
play_typecharacterCFBD categorical label for the play type (see cfbd_play_types()).
play_textcharacterFree-form text description of the play from the CFBD feed.
ppacharacterPredicted Points Added (CFBD's CFB-EPA analogue) for the play.
clock_minutesintegerMinutes remaining on the game clock at the start of the play.
clock_secondsintegerSeconds remaining on the game clock at the start of the play.

See also

Other CFBD PBP: cfbd_live_plays(), cfbd_pbp_data(), cfbd_pbp_data_v2(), cfbd_play_stats_player(), cfbd_play_stats_types(), cfbd_play_types()

Examples

# \donttest{
  try(cfbd_plays(year = 2021, week = 1))
#> ── Play-by-play data from CollegeFootballData.com ──────────── cfbfastR 2.3.0 ──
#> ℹ Data updated: 2026-06-13 04:19:54 UTC
#> # A tibble: 15,066 × 28
#>     game_id drive_id play_id drive_number play_number offense offense_conference
#>       <int> <chr>    <chr>          <int>       <int> <chr>   <chr>             
#>  1   4.01e8 4012827… 401282…            1           1 Illino… Big Ten           
#>  2   4.01e8 4012827… 401282…            1           7 Nebras… Big Ten           
#>  3   4.01e8 4012827… 401282…            1           6 Nebras… Big Ten           
#>  4   4.01e8 4012827… 401282…            1           5 Nebras… Big Ten           
#>  5   4.01e8 4012827… 401282…            1           4 Nebras… Big Ten           
#>  6   4.01e8 4012827… 401282…            1           3 Nebras… Big Ten           
#>  7   4.01e8 4012827… 401282…            1           2 Nebras… Big Ten           
#>  8   4.01e8 4012827… 401282…            2           5 Illino… Big Ten           
#>  9   4.01e8 4012827… 401282…            2           4 Illino… Big Ten           
#> 10   4.01e8 4012827… 401282…            2           3 Illino… Big Ten           
#> # ℹ 15,056 more rows
#> # ℹ 21 more variables: offense_score <int>, defense <chr>,
#> #   defense_conference <chr>, defense_score <int>, home <chr>, away <chr>,
#> #   period <int>, offense_timeouts <int>, defense_timeouts <int>,
#> #   yardline <int>, yards_to_goal <int>, down <int>, distance <int>,
#> #   yards_gained <int>, scoring <lgl>, play_type <chr>, play_text <chr>,
#> #   ppa <dbl>, wallclock <chr>, clock_minutes <int>, clock_seconds <int>
# }