Package {cfbfastR}

Title: Access College Football Play by Play Data
Version: 3.0.0
Description: A utility to quickly obtain clean and tidy college football data. Serves as a wrapper around the https://collegefootballdata.com/ API and provides functions to access live play by play and box score data from ESPN https://www.espn.com when available. It provides users the capability to access a plethora of endpoints, and supplement that data with additional information (Expected Points Added/Win Probability added).
License: MIT + file LICENSE
URL: https://cfbfastR.sportsdataverse.org/, https://github.com/sportsdataverse/cfbfastR
BugReports: https://github.com/sportsdataverse/cfbfastR/issues
Depends: R (≥ 4.1.0)
Imports: cli (≥ 3.0.0), data.table (≥ 1.15.0), dplyr (≥ 1.1.1), glue (≥ 1.4.0), httr2 (≥ 1.0.0), janitor, jsonlite, mgcv (≥ 1.8-33), nnet, purrr (≥ 0.3.0), Rcpp (≥ 1.0.7), RcppParallel (≥ 5.1.4), rlang (≥ 0.4.10), stringr (≥ 1.4.0), tibble (≥ 3.0), tidyr (≥ 1.2.0)
Suggests: arrow, bit64, cachem, crayon (≥ 1.3.4), curl, DBI, ggplot2, ggrepel, memoise, patrick, progressr (≥ 0.6.0), rmarkdown, RSQLite, stats, stringi, testthat, usethis (≥ 1.6.0), withr, xgboost (≥ 1.1)
Config/roxygen2/version: 8.1.0
Config/testthat/edition: 3
Encoding: UTF-8
LazyData: true
NeedsCompilation: no
Packaged: 2026-08-24 14:37:39 UTC; saiem
Author: Saiem Gilani ORCID iD [cre, aut], Akshay Easwaran [aut], Jared Lee [aut], Eric Hess [aut], Michael Egle [ctb], Nate Manzo [ctb], Jason DeLoach [ctb], Tej Seth [ctb], Conor McQuiston [ctb], Tan Ho [ctb], Keegan Abdoo [ctb], Matt Spencer [ctb], Sebastian Carl [ctb], John Edwards [ctb], Brad Hill [ctb], cfbfastR authors [cph]
Maintainer: Saiem Gilani <saiem.gilani@gmail.com>
Repository: CRAN
Date/Publication: 2026-08-24 16:40:02 UTC

cfbfastR: Access College Football Play by Play Data

Description

logo

A utility to quickly obtain clean and tidy college football data. Serves as a wrapper around the https://collegefootballdata.com/ API and provides functions to access live play by play and box score data from ESPN https://www.espn.com when available. It provides users the capability to access a plethora of endpoints, and supplement that data with additional information (Expected Points Added/Win Probability added).

Author(s)

Maintainer: Saiem Gilani saiem.gilani@gmail.com (ORCID)

Authors:

Other contributors:

See Also

Useful links:

CFBD API Key Endpoint Overview

Description

Details

Get information about your CFBD API key

cfbd_api_key_info()

Register / save your CFBD API key

Sys.setenv(CFBD_API_KEY = "YOUR-API-KEY-HERE")

Retrieve the CFBD API key

cfbd_key()

Check whether a CFBD API key is registered

has_cfbd_key()

CFBD Betting Endpoint Overview

Description

Details

Get betting lines information for games

cfbd_betting_lines(year = 2018, week = 12, team = "Florida State")

Get against-the-spread (ATS) summary records by team

cfbd_betting_ats(year = 2023, team = "Michigan")

CFBD Against-the-Spread (ATS) Records

Description

Get against-the-spread (ATS) summary records by team

Retrieves a season-level against-the-spread summary for each team: how often the team covered, failed to cover, or pushed relative to the closing spread, plus the average margin by which it beat the spread. Complements cfbd_betting_lines(), which returns the per-game lines themselves.

Usage

cfbd_betting_ats(year = NULL, team = NULL, conference = NULL)

Arguments

year

(Integer required): Year, 4 digit format (YYYY).
Minimum value accepted: 2019

team

(String optional): D-I Team

conference

(String optional): Conference abbreviation - Select a valid FBS conference
Conference abbreviations P5: ACC, B12, B1G, SEC, PAC
Conference abbreviations G5 and FBS Independents: CUSA, MAC, MWC, Ind, SBC, AAC

Value

Against-the-spread records with the following 9 columns:

col_name types description
year integer Four-digit season year.
team_id integer Unique CFBD team identifier.
team character D-I team name.
conference character Team conference name.
games integer Number of games included in the ATS summary.
ats_wins integer Games the team covered the spread.
ats_losses integer Games the team failed to cover the spread.
ats_pushes integer Games that pushed against the spread.
avg_cover_margin numeric Average margin by which the team beat the spread.

See Also

Other CFBD Betting Functions: cfbd_betting_lines()

Examples


   try(cfbd_betting_ats(year = 2023, team = "Michigan"))

CFBD Betting Lines Endpoint Overview

Description

Get betting lines information for games

Usage

cfbd_betting_lines(
  game_id = NULL,
  year = NULL,
  week = NULL,
  season_type = "regular",
  team = NULL,
  home_team = NULL,
  away_team = NULL,
  conference = NULL,
  line_provider = NULL
)

Arguments

game_id

(Integer optional): Game ID filter for querying a single game. Required if year not provided
Can be found using the cfbd_game_info() function

year

(Integer optional): Year, 4 digit format(YYYY). Required if game_id not provided
Minimum value accepted: 2013

week

(Integer optional): Week - values from 1-15, 1-14 for seasons pre-playoff (i.e. 2013 or earlier)

season_type

(String default regular): Select Season Type: regular, postseason, both, allstar, spring_regular, spring_postseason

team

(String optional): D-I Team

home_team

(String optional): Home D-I Team

away_team

(String optional): Away D-I Team

conference

(String optional): Conference abbreviation - Select a valid FBS conference
Conference abbreviations P5: ACC, B12, B1G, SEC, PAC
Conference abbreviations G5 and FBS Independents: CUSA, MAC, MWC, Ind, SBC, AAC

line_provider

(String optional): Select Line Provider - Caesars, consensus, numberfire, or teamrankings

Value

Betting information for games with the following 21 columns:

col_name types description
game_id integer Unique CFBD game identifier.
season integer Four-digit season year (e.g. 2024).
season_type character Season type (regular, postseason, both).
week integer Week of the season; 1-15, or 1-14 for seasons pre-playoff (2013 earlier).
start_date character Kickoff timestamp in ISO 8601 format.
home_team character Home D-I team name.
home_conference character Home team D-I conference.
home_classification character Home team conference classification (fbs, fcs, ii, iii).
home_score integer Final score of the home team.
away_team character Away D-I team name.
away_conference character Away team D-I conference.
away_classification character Away team conference classification (fbs, fcs, ii, iii).
away_score integer Final score of the away team.
provider character Sportsbook / line provider name.
spread character Closing point spread for the game.
formatted_spread character Human-readable formatted spread (e.g. "Florida State -7.5").
spread_open character Opening point spread for the game.
over_under character Closing over/under (total) for the game.
over_under_open character Opening over/under (total) for the game.
home_moneyline character Home team moneyline odds.
away_moneyline character Away team moneyline odds.

See Also

Other CFBD Betting Functions: cfbd_betting_ats()

Examples


   try(cfbd_betting_lines(year = 2018, week = 12, team = "Florida State"))

Get calendar of weeks by season.

Description

Get calendar of weeks by season.

Usage

cfbd_calendar(year)

Arguments

year

(Integer required): Year, 4 digit format (YYYY)
Minimum value accepted: 2002

Value

cfbd_calendar() - A data frame with 5 variables:

col_name types description
season character Calendar season.
week integer Calendar game week.
season_type character Season type of calendar week.
first_game_start character First game start time of the calendar week.
last_game_start character Last game start time of the calendar week.

See Also

Other CFBD Games: cfbd_game_box_advanced(), cfbd_game_info(), cfbd_game_media(), cfbd_game_player_stats(), cfbd_game_records(), cfbd_game_team_stats(), cfbd_game_weather(), cfbd_live_scoreboard()

Examples


  try(cfbd_calendar(2019))

CFBD Coaches Endpoint Overview

Description

Coach information search A coach search function which provides coaching records and school history for a given coach

Usage

cfbd_coaches(
  first = NULL,
  last = NULL,
  team = NULL,
  year = NULL,
  min_year = NULL,
  max_year = NULL
)

Arguments

first

(String optional): First name for the coach you are trying to look up

last

(String optional): Last name for the coach you are trying to look up

team

(String optional): Team - Select a valid team, D1 football

year

(Integer optional): Year, 4 digit format (YYYY).
Minimum value accepted: 1886

min_year

(Integer optional): Minimum Year filter (inclusive), 4 digit format (YYYY).

max_year

(Integer optional): Maximum Year filter (inclusive), 4 digit format (YYYY)

Details

Coach information search

cfbd_coaches(first = "Nick", last = "Saban", team = "alabama")

Get a coach profile

cfbd_coaches_profile(coach_id = 1)

Get coaching seasons

cfbd_coaches_seasons(team = "Georgia")

Get coaching tenures

cfbd_coaches_tenures(team = "Georgia")

Value

Returns a tibble with 15 variables:

col_name types description
first_name character First name of coach.
last_name character Last name of coach.
hire_date character Hire date of coach (ISO date string from CFBD).
school character School of coach for the listed season.
year integer Four-digit season year of record.
games integer Games coached during the season.
wins integer Wins for the season.
losses integer Losses for the season.
ties integer Ties for the season.
preseason_rank integer Preseason AP rank for the school of coach (NA if unranked).
postseason_rank integer Postseason AP rank for the school of coach (NA if unranked).
srs character Simple Rating System adjustment for team.
sp_overall character Bill Connelly's SP+ overall rating for team.
sp_offense character Bill Connelly's SP+ offense rating for team.
sp_defense character Bill Connelly's SP+ defense rating for team.

See Also

Other CFBD Coaches Functions: cfbd_coaches_profile(), cfbd_coaches_seasons(), cfbd_coaches_tenures()

Examples


  try(cfbd_coaches(first = "Nick", last = "Saban", team = "alabama"))

Get a coach profile

Description

Get a coach profile Biographical profile for a single coach.

Usage

cfbd_coaches_profile(coach_id, proxy = NULL)

Arguments

coach_id

(Integer required): Coach identifier.

proxy

(List optional): Per-call proxy override passed to get_req(). NULL (default) falls back to getOption("cfbfastR.proxy") and then the ⁠http(s)_proxy⁠ environment variables, so a caller can override the shared setting for one endpoint.

Value

cfbd_coaches_profile() - A tibble with 19 columns:

col_name types description
id integer Record identifier.
first_name character First name.
last_name character Last name.
display_name logical Display name.
current_team logical Current team.
birth_date logical Birth date and time (ISO 8601).
alma_mater logical Alma mater.
graduation_year logical Graduation year.
wikidata_id logical Wikidata identifier.
hall_of_fame_year logical Hall of fame year.
career_seasons integer Seasons coached across the career.
career_teams integer Distinct teams coached.
career_first_year integer First season of the coaching career.
career_last_year integer Most recent season coached.
career_games integer Career games coached.
career_wins integer Career wins.
career_losses integer Career losses.
career_ties integer Career ties.
career_win_percentage numeric Career winning percentage.

See Also

Other CFBD Coaches Functions: cfbd_coaches(), cfbd_coaches_seasons(), cfbd_coaches_tenures()

Examples


  try(cfbd_coaches_profile(coach_id = 1))

Get coaching seasons

Description

Get coaching seasons Season-by-season coaching records.

Usage

cfbd_coaches_seasons(
  coach_id = NULL,
  team = NULL,
  year = NULL,
  min_year = NULL,
  max_year = NULL,
  proxy = NULL
)

Arguments

coach_id

(Integer optional): Coach identifier.

team

(String optional): Team filter.

year

(Integer optional): Season, 4 digits (YYYY).
Minimum value accepted: 1886

min_year

(Integer optional): Earliest season to include.

max_year

(Integer optional): Latest season to include.

proxy

(List optional): Per-call proxy override passed to get_req(). NULL (default) falls back to getOption("cfbfastR.proxy") and then the ⁠http(s)_proxy⁠ environment variables, so a caller can override the shared setting for one endpoint.

Value

cfbd_coaches_seasons() - A tibble with 68 columns:

col_name types description
year integer Four-digit season year.
games integer Games played.
wins integer Wins.
losses integer Losses.
ties integer Ties.
win_percentage numeric Win percentage.
preseason_rank integer Preseason rank.
postseason_rank integer Postseason rank.
srs numeric Srs.
sp_overall numeric Sp overall.
sp_offense numeric Sp offense.
sp_defense numeric Sp defense.
attribution_complete logical Attribution complete.
coach_id integer Coach identifier.
coach_first_name character Coach first name.
coach_last_name character Coach last name.
team_id integer Referencing team id.
team_school character School name of the team.
team_conference character Conference the team belongs to.
team_metrics_sp_special_teams numeric Team metrics sp special teams.
team_metrics_strength_of_schedule numeric Team metrics strength of schedule.
team_metrics_second_order_wins numeric Team metrics second order wins.
team_metrics_fpi numeric Team metrics fpi.
team_metrics_year_over_year_wins integer Team metrics year over year wins.
team_metrics_year_over_year_srs numeric Team metrics year over year srs.
team_metrics_year_over_year_sp_overall numeric Team metrics year over year sp overall.
recruiting_rank integer Recruiting rank.
recruiting_points numeric Recruiting points scored.
recruiting_talent numeric Recruiting talent.
poll_resume_preseason_rank integer Poll resume preseason rank.
poll_resume_postseason_rank integer Poll resume postseason rank.
poll_resume_best_rank integer Poll resume best rank.
poll_resume_weeks_ranked integer Poll resume weeks ranked.
poll_resume_weeks_top_ten integer Poll resume weeks top ten.
record_splits_conference_games integer Record splits conference games.
record_splits_conference_wins integer Record splits conference wins.
record_splits_conference_losses integer Record splits conference losses.
record_splits_conference_ties integer Record splits conference ties.
record_splits_conference_win_percentage numeric Record splits conference win percentage.
record_splits_postseason_games integer Record splits postseason games.
record_splits_postseason_wins integer Record splits postseason wins.
record_splits_postseason_losses integer Record splits postseason losses.
record_splits_postseason_ties integer Record splits postseason ties.
record_splits_postseason_win_percentage numeric Record splits postseason win percentage.
record_splits_home_games integer Record splits home games.
record_splits_home_wins integer Record splits home wins.
record_splits_home_losses integer Record splits home losses.
record_splits_home_ties integer Record splits home ties.
record_splits_home_win_percentage numeric Record splits home win percentage.
record_splits_away_games integer Record splits away games.
record_splits_away_wins integer Record splits away wins.
record_splits_away_losses integer Record splits away losses.
record_splits_away_ties integer Record splits away ties.
record_splits_away_win_percentage numeric Record splits away win percentage.
record_splits_neutral_games integer Record splits neutral games.
record_splits_neutral_wins integer Record splits neutral wins.
record_splits_neutral_losses integer Record splits neutral losses.
record_splits_neutral_ties integer Record splits neutral ties.
record_splits_neutral_win_percentage numeric Record splits neutral win percentage.
scoring_points_for integer Scoring points for.
scoring_points_against integer Scoring points against.
scoring_average_point_differential numeric Scoring average point differential.
cfp_appeared logical Cfp appeared.
cfp_seed integer Cfp seed.
cfp_outcome character Cfp outcome.
draft_following_season_year integer Draft following season year.
draft_following_season_total_picks integer Draft following season total picks.
draft_following_season_first_round_picks integer Draft following season first round picks.

See Also

Other CFBD Coaches Functions: cfbd_coaches(), cfbd_coaches_profile(), cfbd_coaches_tenures()

Examples


  try(cfbd_coaches_seasons(team = "Georgia"))

Get coaching tenures

Description

Get coaching tenures Start and end of each coaching tenure.

Usage

cfbd_coaches_tenures(
  coach_id = NULL,
  team = NULL,
  year = NULL,
  active = NULL,
  proxy = NULL
)

Arguments

coach_id

(Integer optional): Coach identifier.

team

(String optional): Team filter.

year

(Integer optional): Season, 4 digits (YYYY).
Minimum value accepted: 1886

active

(Logical optional): Restrict to currently active tenures.

proxy

(List optional): Per-call proxy override passed to get_req(). NULL (default) falls back to getOption("cfbfastR.proxy") and then the ⁠http(s)_proxy⁠ environment variables, so a caller can override the shared setting for one endpoint.

Value

cfbd_coaches_tenures() - A tibble with 20 columns:

col_name types description
id integer Record identifier.
hire_date character Hire date of the coach (ISO date string).
start_year integer Start year.
end_year integer End year.
effective_start logical Effective start.
effective_end logical Effective end.
is_interim logical Is interim.
active logical Active.
seasons integer Seasons.
attribution_complete logical Attribution complete.
coach_id integer Coach identifier.
coach_first_name character Coach first name.
coach_last_name character Coach last name.
team_id integer Referencing team id.
team_school character School name of the team.
record_games integer Record games.
record_wins integer Record wins.
record_losses integer Record losses.
record_ties integer Record ties.
record_win_percentage numeric Record win percentage.

See Also

Other CFBD Coaches Functions: cfbd_coaches(), cfbd_coaches_profile(), cfbd_coaches_seasons()

Examples


  try(cfbd_coaches_tenures(team = "Georgia"))

Get conference affiliations by team and season

Description

Get conference affiliations by team and season Which conference each team belonged to, by season.

Usage

cfbd_conference_affiliations(
  team = NULL,
  conference = NULL,
  year = NULL,
  min_year = NULL,
  max_year = NULL,
  division = NULL,
  proxy = NULL
)

Arguments

team

(String optional): Team filter.

conference

(String optional): Conference abbreviation filter.

year

(Integer optional): Season, 4 digits (YYYY).
Minimum value accepted: 1869

min_year

(Integer optional): Earliest season to include.

max_year

(Integer optional): Latest season to include.

division

(String optional): Division/classification filter – fbs, fcs, ii, ii/iii, iii.

proxy

(List optional): Per-call proxy override passed to get_req(). NULL (default) falls back to getOption("cfbfastR.proxy") and then the ⁠http(s)_proxy⁠ environment variables, so a caller can override the shared setting for one endpoint.

Value

cfbd_conference_affiliations() - A tibble with 9 columns:

col_name types description
team_id integer Referencing team id.
team character Team name.
conference_id integer Referencing conference id.
conference character Conference name.
conference_abbreviation character Conference abbreviation.
classification character Division classification (fbs, fcs, ii, ii/iii, iii).
conference_division character Conference division.
start_year integer Start year.
end_year integer End year.

See Also

Other CFBD Conference Functions: cfbd_conference_changes(), cfbd_conferences()

Examples


  try(cfbd_conference_affiliations(team = "Georgia"))

Get conference realignment changes

Description

Get conference realignment changes Teams that changed conference in a given season.

Usage

cfbd_conference_changes(year, proxy = NULL)

Arguments

year

(Integer required): Season, 4 digits (YYYY).
Minimum value accepted: 1887

proxy

(List optional): Per-call proxy override passed to get_req(). NULL (default) falls back to getOption("cfbfastR.proxy") and then the ⁠http(s)_proxy⁠ environment variables, so a caller can override the shared setting for one endpoint.

Value

cfbd_conference_changes() - A tibble with 11 columns:

col_name types description
team_id integer Referencing team id.
team character Team name.
from_conference_id integer Prior referencing conference id.
from_conference character Prior conference.
from_conference_abbreviation character Prior conference abbreviation.
from_classification character Prior division classification.
to_conference_id integer New referencing conference id.
to_conference character New conference.
to_conference_abbreviation character New conference abbreviation.
to_classification character New division classification.
effective_year integer Season the conference change takes effect.

See Also

Other CFBD Conference Functions: cfbd_conference_affiliations(), cfbd_conferences()

Examples


  try(cfbd_conference_changes(year = 2024))

CFBD Conferences Endpoint Overview

Description

Get college football conference information Pulls all college football conferences and returns as data frame

Usage

cfbd_conferences(year = NULL, division = NULL)

Arguments

year

(Integer optional): Season filter, 4 digits (YYYY).
Minimum value accepted: 1869

division

(String optional): Division/classification filter – one of fbs, fcs, ii, ii/iii, iii. Sent to CFBD as classification.

Details

Get college football conference information

cfbd_conferences()

Get conference affiliations by team and season

cfbd_conference_affiliations(team = "Georgia")

Get conference realignment changes

cfbd_conference_changes(year = 2024)

Value

cfbd_conferences() - A data frame with 94 rows and 5 variables:

col_name types description
conference_id integer Referencing conference id.
name character Conference name.
long_name character Long name for Conference.
abbreviation character Conference abbreviation.
classification character Conference classification (fbs, fcs, ii, iii).

See Also

Other CFBD Conference Functions: cfbd_conference_affiliations(), cfbd_conference_changes()

Examples


  try(cfbd_conferences())

CFBD NFL Draft Endpoint Overview

Description

Details

Get list of NFL teams

cfbd_draft_teams()

Get list of NFL positions for mapping to collegiate

cfbd_draft_positions()

Get list of NFL Draft picks

cfbd_draft_picks(year = 2020, college = "Texas")

cfbd_draft_picks(nfl_team = "Cincinatti")

Get list of NFL draft picks

Description

Get list of NFL draft picks

Usage

cfbd_draft_picks(
  year = NULL,
  nfl_team = NULL,
  college = NULL,
  conference = NULL,
  position = NULL
)

Arguments

year

(Integer required): NFL draft class, 4 digit format (YYYY)
Minimum value accepted: 1967

nfl_team

(String): NFL drafting team, see cfbd_draft_teams() for valid selections.

college

(String): NFL draftee college team, see cfbd_team_info() for valid selections.

conference

(String): NFL draftee college team conference, see cfbd_conferences() for valid selections.

position

(String): NFL position abbreviation, see cfbd_draft_positions() for valid selections.

Value

cfbd_draft_picks() - A data frame with 24 variables:

col_name types description
college_athlete_id integer College athlete referencing id.
nfl_athlete_id integer NFL athlete referencing id.
college_id integer College team referencing id.
college_team character College team name.
college_conference character Conference of college team.
nfl_team_id integer NFL team ID.
nfl_team character NFL team name of drafted player.
year integer NFL draft class year.
overall integer Overall draft pick number.
round integer Round of NFL draft the draftee was picked in.
pick integer Pick number of the NFL draftee within the round they were picked in.
name character NFL draftee name.
position character NFL draftee position.
height numeric NFL draftee height.
weight integer NFL draftee weight.
pre_draft_ranking integer Pre-draft ranking (ESPN).
pre_draft_position_ranking integer Pre-draft position ranking (ESPN).
pre_draft_grade numeric Pre-draft scouts grade (ESPN).
hometown_info_city character Hometown of the NFL draftee.
hometown_info_state_province character Hometown state of the NFL draftee.
hometown_info_country character Hometown country of the NFL draftee.
hometown_info_latitude character Hometown latitude of the NFL draftee.
hometown_info_longitude character Hometown longitude of the NFL draftee.
hometown_info_county_fips character Hometown FIPS code of the NFL draftee.

See Also

Other CFBD Draft: cfbd_draft_positions(), cfbd_draft_teams()

Examples


  try(cfbd_draft_picks(year = 2020))

  try(cfbd_draft_picks(year = 2016, position = "PK"))

Get list of NFL positions

Description

Get list of NFL positions

Usage

cfbd_draft_positions()

Value

cfbd_draft_positions() - A data frame with 2 variables:

col_name types description
position_name character NFL Position group name.
position_abbreviation character NFL position group abbreviation.

See Also

Other CFBD Draft: cfbd_draft_picks(), cfbd_draft_teams()

Examples


  try(cfbd_draft_positions())

Get list of NFL teams

Description

Get list of NFL teams

Usage

cfbd_draft_teams()

Value

cfbd_draft_teams() - A data frame with 4 variables:

col_name types description
nfl_location character NFL team location (city).
nfl_nickname character NFL team nickname (mascot).
nfl_display_name character NFL team display name (usually more neat/complete).
nfl_logo character URL for NFL team logo.

See Also

Other CFBD Draft: cfbd_draft_picks(), cfbd_draft_positions()

Examples


  try(cfbd_draft_teams())

CFBD Drives Endpoint Overview

Description

Get college football game drives

Usage

cfbd_drives(
  year,
  season_type = "regular",
  week = NULL,
  team = NULL,
  offense_team = NULL,
  defense_team = NULL,
  conference = NULL,
  offense_conference = NULL,
  defense_conference = NULL,
  division = "fbs"
)

Arguments

year

(Integer required): Year, 4 digit format (YYYY)
Minimum value accepted: 2001

season_type

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

week

(Integer optional): Week - values from 1-15, 1-14 for seasons pre-playoff, i.e. 2013 or earlier

team

(String optional): D-I Team

offense_team

(String optional): Offense D-I Team

defense_team

(String optional): Defense D-I Team

conference

(String optional): DI Conference abbreviation - Select a valid FBS conference Conference abbreviations P5: ACC, B12, B1G, SEC, PAC Conference abbreviations G5 and FBS Independents: CUSA, MAC, MWC, Ind, SBC, AAC

offense_conference

(String optional): Offense DI Conference abbreviation - Select a valid FBS conference Conference abbreviations P5: ACC, B12, B1G, SEC, PAC Conference abbreviations G5 and FBS Independents: CUSA, MAC, MWC, Ind, SBC, AAC

defense_conference

(String optional): Defense DI Conference abbreviation - Select a valid FBS conference Conference abbreviations P5: ACC, B12, B1G, SEC, PAC Conference abbreviations G5 and FBS Independents: CUSA, MAC, MWC, Ind, SBC, AAC

division

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

Details

Get college football game drives

cfbd_drives(year = 2018, week = 1, team = "TCU")

cfbd_drives(2018, team = "Texas A&M", defense_conference = "SEC")

Value

cfbd_drives() - A data frame with 28 variables:

col_name types description
offense character Drive offense team name.
offense_conference character Drive offense team's conference.
defense character Drive defense team name.
defense_conference character Drive defense team's conference.
game_id integer Unique CFBD game identifier.
drive_id character Unique CFBD drive identifier.
drive_number integer Drive number within the game.
scoring logical Flag indicating whether the drive ended in a score.
start_period integer Period (quarter) in which the drive starts.
start_yardline integer Yard line at the drive start.
start_yards_to_goal integer Yards-to-goal at the drive start.
end_period integer Period (quarter) in which the drive ends.
end_yardline integer Yard line at drive end.
end_yards_to_goal integer Yards-to-goal at drive end.
plays integer Number of plays in the drive.
yards integer Total yards gained on the drive.
drive_result character Result of the drive (e.g. TD, FG, PUNT).
is_home_offense logical Flag indicating whether the offense on the field is the home team.
start_offense_score numeric Offense score at the start of the drive.
start_defense_score numeric Defense score at the start of the drive.
end_offense_score numeric Offense score at the end of the drive.
end_defense_score numeric Defense score at the end of the drive.
time_minutes_start integer Game clock minutes at drive start.
time_seconds_start integer Game clock seconds at drive start.
time_minutes_end integer Game clock minutes at drive end.
time_seconds_end integer Game clock seconds at drive end.
time_minutes_elapsed numeric Minutes elapsed during the drive.
time_seconds_elapsed integer Seconds elapsed during the drive.

Examples


  try(cfbd_drives(year=2018, week = 1, team = "TCU"))

  try(cfbd_drives(2018, team = "Texas A&M", defense_conference = "SEC"))

Get game advanced box score information.

Description

Get game advanced box score information.

Usage

cfbd_game_box_advanced(game_id, long = FALSE)

Arguments

game_id

(Integer required): Game ID filter for querying a single game Can be found using the cfbd_game_info() function

long

(Logical default FALSE): Return the data in a long format.

Value

cfbd_game_box_advanced() - A data frame with 2 rows and 69 variables:

col_name types description
team character Team name.
plays numeric Number of plays.
ppa_overall_total numeric Predicted points added (PPA) overall total.
ppa_overall_quarter1 numeric Predicted points added (PPA) overall Q1.
ppa_overall_quarter2 numeric Predicted points added (PPA) overall Q2.
ppa_overall_quarter3 numeric Predicted points added (PPA) overall Q3.
ppa_overall_quarter4 numeric Predicted points added (PPA) overall Q4.
ppa_passing_total numeric Passing predicted points added (PPA) total.
ppa_passing_quarter1 numeric Passing predicted points added (PPA) Q1.
ppa_passing_quarter2 numeric Passing predicted points added (PPA) Q2.
ppa_passing_quarter3 numeric Passing predicted points added (PPA) Q3.
ppa_passing_quarter4 numeric Passing predicted points added (PPA) Q4.
ppa_rushing_total numeric Rushing predicted points added (PPA) total.
ppa_rushing_quarter1 numeric Rushing predicted points added (PPA) Q1.
ppa_rushing_quarter2 numeric Rushing predicted points added (PPA) Q2.
ppa_rushing_quarter3 numeric Rushing predicted points added (PPA) Q3.
ppa_rushing_quarter4 numeric Rushing predicted points added (PPA) Q4.
cumulative_ppa_plays numeric Cumulative predicted points added (PPA) added total.
cumulative_ppa_overall_total numeric Cumulative predicted points added (PPA) total.
cumulative_ppa_overall_quarter1 numeric Cumulative predicted points added (PPA) Q1.
cumulative_ppa_overall_quarter2 numeric Cumulative predicted points added (PPA) Q2.
cumulative_ppa_overall_quarter3 numeric Cumulative predicted points added (PPA) Q3.
cumulative_ppa_overall_quarter4 numeric Cumulative predicted points added (PPA) Q4.
cumulative_ppa_passing_total numeric Cumulative passing predicted points added (PPA) total.
cumulative_ppa_passing_quarter1 numeric Cumulative passing predicted points added (PPA) Q1.
cumulative_ppa_passing_quarter2 numeric Cumulative passing predicted points added (PPA) Q2.
cumulative_ppa_passing_quarter3 numeric Cumulative passing predicted points added (PPA) Q3.
cumulative_ppa_passing_quarter4 numeric Cumulative passing predicted points added (PPA) Q4.
cumulative_ppa_rushing_total numeric Cumulative rushing predicted points added (PPA) total.
cumulative_ppa_rushing_quarter1 numeric Cumulative rushing predicted points added (PPA) Q1.
cumulative_ppa_rushing_quarter2 numeric Cumulative rushing predicted points added (PPA) Q2.
cumulative_ppa_rushing_quarter3 numeric Cumulative rushing predicted points added (PPA) Q3.
cumulative_ppa_rushing_quarter4 numeric Cumulative rushing predicted points added (PPA) Q4.
success_rates_overall_total numeric Success rates overall total.
success_rates_overall_quarter1 numeric Success rates overall Q1.
success_rates_overall_quarter2 numeric Success rates overall Q2.
success_rates_overall_quarter3 numeric Success rates overall Q3.
success_rates_overall_quarter4 numeric Success rates overall Q4.
success_rates_standard_downs_total numeric Success rates standard downs total.
success_rates_standard_downs_quarter1 numeric Success rates standard downs Q1.
success_rates_standard_downs_quarter2 numeric Success rates standard downs Q2.
success_rates_standard_downs_quarter3 numeric Success rates standard downs Q3.
success_rates_standard_downs_quarter4 numeric Success rates standard downs Q4.
success_rates_passing_downs_total numeric Success rates passing downs total.
success_rates_passing_downs_quarter1 numeric Success rates passing downs Q1.
success_rates_passing_downs_quarter2 numeric Success rates passing downs Q2.
success_rates_passing_downs_quarter3 numeric Success rates passing downs Q3.
success_rates_passing_downs_quarter4 numeric Success rates passing downs Q4.
explosiveness_overall_total numeric Explosiveness rates overall total.
explosiveness_overall_quarter1 numeric Explosiveness rates overall Q1.
explosiveness_overall_quarter2 numeric Explosiveness rates overall Q2.
explosiveness_overall_quarter3 numeric Explosiveness rates overall Q3.
explosiveness_overall_quarter4 numeric Explosiveness rates overall Q4.
rushing_power_success numeric Rushing power success rate.
rushing_stuff_rate numeric Rushing stuff rate.
rushing_line_yds numeric Rushing offensive line yards.
rushing_line_yds_avg numeric Rushing line yards average.
rushing_second_lvl_yds numeric Rushing second-level yards.
rushing_second_lvl_yds_avg numeric Average second level yards per rush.
rushing_open_field_yds numeric Rushing open field yards.
rushing_open_field_yds_avg numeric Average rushing open field yards average.
havoc_total numeric Total havoc rate.
havoc_front_seven numeric Front-7 players havoc rate.
havoc_db numeric Defensive back players havoc rate.
scoring_opps_opportunities numeric Number of scoring opportunities.
scoring_opps_points numeric Points on scoring opportunity drives.
scoring_opps_pts_per_opp numeric Points per scoring opportunity drives.
field_pos_avg_start numeric Average starting field position.
field_pos_avg_starting_predicted_pts numeric Average starting predicted points (PP) for the average starting field position.

See Also

Other CFBD Games: cfbd_calendar(), cfbd_game_info(), cfbd_game_media(), cfbd_game_player_stats(), cfbd_game_records(), cfbd_game_team_stats(), cfbd_game_weather(), cfbd_live_scoreboard()

Examples


  try(cfbd_game_box_advanced(game_id = 401114233))

Get results information from games.

Description

Get results information from games.

Usage

cfbd_game_info(
  year,
  week = NULL,
  season_type = "both",
  team = NULL,
  home_team = NULL,
  away_team = NULL,
  conference = NULL,
  division = "fbs",
  game_id = NULL,
  quarter_scores = FALSE,
  competition = NULL,
  round = NULL
)

Arguments

year

(Integer required): Year, 4 digit format(YYYY)
Minimum value accepted: 1869

week

(Integer optional): Week - values from 1-15, 1-14 for seasons pre-playoff (i.e. 2013 or earlier)

season_type

(String default both): Select Season Type: regular, postseason, both, allstar, spring_regular, spring_postseason

team

(String optional): D-I Team

home_team

(String optional): Home D-I Team

away_team

(String optional): Away D-I Team

conference

(String optional): Conference abbreviation - Select a valid FBS conference Conference abbreviations P5: ACC, B12, B1G, SEC, PAC Conference abbreviations G5 and FBS Independents: CUSA, MAC, MWC, Ind, SBC, AAC

division

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

game_id

(Integer optional): Game ID filter for querying a single game

quarter_scores

(Logical default FALSE): This is a parameter to return the list columns that give the score at each quarter: home_line_scores and away_line_scores. I have defaulted the parameter to false so that you will not have to go to the trouble of dropping it.

competition

(String optional): Competition filter; cfp restricts to College Football Playoff games.

round

(String optional): Playoff round – first_round, quarterfinal, semifinal, championship.

Value

cfbd_game_info() - A data frame with 30 variables:

col_name types description
game_id integer Referencing game id.
season integer Season of the game.
week integer Game week.
season_type character Season type of the game.
start_date character Game date.
start_time_tbd logical TRUE/FALSE flag for if the game's start time is to be determined.
neutral_site logical TRUE/FALSE flag for the game taking place at a neutral site.
conference_game logical TRUE/FALSE flag for this game qualifying as a conference game.
attendance integer Reported attendance at the game.
venue_id integer Referencing venue id.
venue character Venue name.
home_id integer Home team referencing id.
home_team character Home team name.
home_conference character Home team conference.
home_division character Home team division.
home_points integer Home team points.
home_post_win_prob character Home team post-game win probability.
home_pregame_elo character Home team pre-game ELO rating.
home_postgame_elo character Home team post-game ELO rating.
away_id integer Away team referencing id.
away_team character Away team name.
away_conference character Away team conference.
away_division character Away team division.
away_points integer Away team points.
away_post_win_prob character Away team post-game win probability.
away_pregame_elo character Away team pre-game ELO rating.
away_postgame_elo character Away team post-game ELO rating.
excitement_index character Game excitement index.
highlights character Game highlight urls.
notes character Game notes.

See Also

Other CFBD Games: cfbd_calendar(), cfbd_game_box_advanced(), cfbd_game_media(), cfbd_game_player_stats(), cfbd_game_records(), cfbd_game_team_stats(), cfbd_game_weather(), cfbd_live_scoreboard()

Examples


  try(cfbd_game_info(2018, week = 7, conference = "Ind"))

Get game media information (TV, radio, etc).

Description

Get game media information (TV, radio, etc).

Usage

cfbd_game_media(
  year,
  week = NULL,
  season_type = "both",
  team = NULL,
  conference = NULL,
  media_type = NULL,
  division = "fbs"
)

Arguments

year

(Integer required): Year, 4 digit format (YYYY)
Minimum value accepted: 2003

week

(Integer optional): Week, values from 1-15, 1-14 for seasons pre-playoff (i.e. 2013 or earlier)

season_type

(String default both): Select Season Type, regular, postseason, both, allstar, spring_regular, spring_postseason

team

(String optional): D-I Team

conference

(String optional): Conference abbreviation - Select a valid FBS conference Conference abbreviations P5: ACC, B12, B1G, SEC, PAC Conference abbreviations G5 and FBS Independents: CUSA, MAC, MWC, Ind, SBC, AAC

media_type

(String optional): Media type filter: tv, radio, web, ppv, or mobile

division

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

Value

cfbd_game_media() - A data frame with 13 variables:

col_name types description
game_id integer Referencing game id.
season integer Season of the game.
week integer Game week.
season_type character Season type of the game.
start_time character Game start time.
is_start_time_tbd logical TRUE/FALSE flag for if the start time is still to be determined.
home_team character Home team of the game.
home_conference character Conference of the home team.
away_team character Away team of the game.
away_conference character Conference of the away team.
tv list TV broadcast networks.
radio logical Radio broadcast networks.
web list Web viewing platforms carrying the game.

See Also

Other CFBD Games: cfbd_calendar(), cfbd_game_box_advanced(), cfbd_game_info(), cfbd_game_player_stats(), cfbd_game_records(), cfbd_game_team_stats(), cfbd_game_weather(), cfbd_live_scoreboard()

Examples


  try(cfbd_game_media(2019, week = 4, conference = "ACC"))

Get player statistics by game

Description

Get player statistics by game

Usage

cfbd_game_player_stats(
  year,
  week = NULL,
  season_type = "regular",
  team = NULL,
  conference = NULL,
  category = NULL,
  game_id = NULL,
  division = NULL
)

Arguments

year

(Integer required): Year, 4 digit format(YYYY)
Minimum value accepted: 2004

week

(Integer optional): Week - values from 1-15, 1-14 for seasons pre-playoff (i.e. 2013 or earlier)

season_type

(String default regular): Select Season Type: regular, postseason, both, allstar, spring_regular, spring_postseason

team

(String optional): D-I Team

conference

(String optional): Conference abbreviation - Select a valid FBS conference Conference abbreviations P5: ACC, B12, B1G, SEC, PAC Conference abbreviations G5 and FBS Independents: CUSA, MAC, MWC, Ind, SBC, AAC

category

(String optional): Category filter (e.g defensive) Offense: passing, receiving, rushing Defense: defensive, fumbles, interceptions Special Teams: punting, puntReturns, kicking, kickReturns

game_id

(Integer optional): Game ID filter for querying a single game Can be found using the cfbd_game_info() function

division

(String optional): Division/classification filter – one of fbs, fcs, ii, ii/iii, iii. Sent to CFBD as classification.

Value

cfbd_game_player_stats() - A data frame with 32 variables:

col_name types description
game_id integer CFBD-internal game id; join key to other CFBD endpoints.
team character Full team name (e.g. "Alabama") for the player's team.
conference character Conference name of the player's team (e.g. "SEC").
home_away character Whether the player's team played at home or away ("home"/"away").
team_points integer Total points scored by the player's team in this game.
athlete_id integer CFBD-internal athlete id for the player.
athlete_name character Player's display name as reported by CFBD.
defensive_td numeric Defensive touchdowns scored by the player.
defensive_qb_hur numeric Quarterback hurries credited to the player.
defensive_pd numeric Passes defended (pass breakups) by the player.
defensive_tfl numeric Tackles for loss credited to the player.
defensive_sacks numeric Sacks credited to the player.
defensive_solo numeric Solo (unassisted) tackles by the player.
defensive_tot numeric Total tackles (solo plus assisted) by the player.
fumbles_rec numeric Fumbles recovered by the player.
fumbles_lost numeric Fumbles by the player that were lost to the opposing team.
fumbles_fum numeric Fumbles committed by the player.
punting_long numeric Longest punt by the player, in yards.
punting_in_20 numeric Punts downed inside the opponent 20-yard line.
punting_tb numeric Punts resulting in a touchback.
punting_avg numeric Average yards per punt.
punting_yds numeric Total punting yards (gross).
punting_no numeric Number of punts attempted.
kicking_pts numeric Total points scored by the kicker (FGs + XPs).
kicking_long numeric Longest made field goal, in yards.
kicking_pct numeric Field-goal percentage (made / attempted), 0-100.
punt_returns_td numeric Touchdowns scored on punt returns.
punt_returns_long numeric Longest punt return, in yards.
punt_returns_avg numeric Average yards per punt return.
punt_returns_yds numeric Total punt-return yards.
punt_returns_no numeric Number of punt returns.
kick_returns_td numeric Touchdowns scored on kickoff returns.
kick_returns_long numeric Longest kickoff return, in yards.
kick_returns_avg numeric Average yards per kickoff return.
kick_returns_yds numeric Total kickoff-return yards.
kick_returns_no numeric Number of kickoff returns.
interceptions_td numeric Touchdowns scored on interception returns (pick-sixes).
interceptions_yds numeric Interception-return yards.
interceptions_int numeric Number of interceptions made by the player.
receiving_long numeric Longest reception by the player, in yards.
receiving_td numeric Receiving touchdowns.
receiving_avg numeric Average yards per reception.
receiving_yds numeric Total receiving yards.
receiving_rec numeric Number of receptions (catches).
rushing_long numeric Longest rush by the player, in yards.
rushing_td numeric Rushing touchdowns.
rushing_avg numeric Average yards per rushing attempt.
rushing_yds numeric Total rushing yards.
rushing_car numeric Rushing carries (attempts).
passing_int numeric Interceptions thrown by the passer.
passing_td numeric Passing touchdowns thrown.
passing_avg numeric Yards per pass attempt.
passing_yds numeric Total passing yards.
passing_completions numeric Pass completions (split from CFBD's C/ATT field).
passing_attempts numeric Pass attempts (split from CFBD's C/ATT field).
passing_qbr numeric ESPN Quarterback Rating (QBR) for the player in this game.
kicking_xpm numeric Extra points made (split from CFBD's XP field).
kicking_xpa numeric Extra points attempted (split from CFBD's XP field).
kicking_fgm numeric Field goals made (split from CFBD's FG field).
kicking_fga numeric Field goals attempted (split from CFBD's FG field).

See Also

Other CFBD Games: cfbd_calendar(), cfbd_game_box_advanced(), cfbd_game_info(), cfbd_game_media(), cfbd_game_records(), cfbd_game_team_stats(), cfbd_game_weather(), cfbd_live_scoreboard()

Examples


  try(cfbd_game_player_stats(year = 2020, week = 15, team = "Alabama"))

  try(cfbd_game_player_stats(2013, week = 1, team = "Florida State", category = "passing"))

Get team records by year

Description

Get team records by year

Usage

cfbd_game_records(year, team = NULL, conference = NULL)

Arguments

year

(Integer optional): Year, 4 digit format (YYYY)
Minimum value accepted: 1869

team

(String optional): Team - Select a valid team, D1 football

conference

(String optional): DI Conference abbreviation - Select a valid FBS conference Conference abbreviations P5: ACC, B12, B1G, SEC, PAC Conference abbreviations G5 and FBS Independents: CUSA, MAC, MWC, Ind, SBC, AAC

Value

cfbd_game_records() - A data frame with 35 variables:

col_name types description
year integer Season of the games.
team_id integer Referencing team id.
team character Team name.
classification character Conference classification (fbs, fcs, ii, iii).
conference character Conference of the team.
division character Division in the conference of the team.
expected_wins numeric Expected number of wins based on post-game win probability.
total_games integer Total number of games played.
total_wins integer Total wins.
total_losses integer Total losses.
total_ties integer Total ties.
conference_games integer Number of conference games.
conference_wins integer Total conference wins.
conference_losses integer Total conference losses.
conference_ties integer Total conference ties.
home_games integer Total home games.
home_wins integer Total home wins.
home_losses integer Total home losses.
home_ties integer Total home ties.
away_games integer Total away games.
away_wins integer Total away wins.
away_losses integer Total away losses.
away_ties integer Total away ties.
neutral_games integer Total neutral site games.
neutral_wins integer Total neutral site wins.
neutral_losses integer Total neutral site losses.
neutral_ties integer Total neutral site ties.
regular_season_games integer Total regular season games.
regular_season_wins integer Total regular season wins.
regular_season_losses integer Total regular season losses.
regular_season_ties integer Total regular season ties.
postseason_games integer Total postseason games.
postseason_wins integer Total postseason wins.
postseason_losses integer Total postseason losses.
postseason_ties integer Total postseason ties.

See Also

Other CFBD Games: cfbd_calendar(), cfbd_game_box_advanced(), cfbd_game_info(), cfbd_game_media(), cfbd_game_player_stats(), cfbd_game_team_stats(), cfbd_game_weather(), cfbd_live_scoreboard()

Examples


  try(cfbd_game_records(2018, team = "Notre Dame"))

  try(cfbd_game_records(2013, team = "Florida State"))

Get team statistics by game

Description

Get team statistics by game

Usage

cfbd_game_team_stats(
  year,
  week = NULL,
  season_type = "regular",
  team = NULL,
  conference = NULL,
  game_id = NULL,
  division = "fbs",
  rows_per_team = 1
)

Arguments

year

(Integer required): Year, 4 digit format (YYYY). Required year filter (along with one of week, team, or conference), unless game_id is specified
Minimum value accepted: 2004

week

(Integer optional): Week - values range from 1-15, 1-14 for seasons pre-playoff, i.e. 2013 or earlier. Required if team and conference not specified.

season_type

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

team

(String optional): D-I Team. Required if week and conference not specified.

conference

(String optional): Conference abbreviation - Select a valid FBS conference Conference abbreviations P5: ACC, B12, B1G, SEC, PAC Conference abbreviations G5 and FBS Independents: CUSA, MAC, MWC, Ind, SBC, AAC Required if week and team not specified.

game_id

(Integer optional): Game ID filter for querying a single game Can be found using the cfbd_game_info() function

division

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

rows_per_team

(Integer default 1): Both Teams for each game on one or two row(s), Options: 1 or 2

Value

cfbd_game_team_stats() - A data frame with 78 variables:

col_name types description
game_id integer Referencing game id.
team character Team name.
conference character Conference of the team.
home_away character Home/Away Flag.
opponent character Opponent team name.
opponent_conference character Conference of the opponent team.
points integer Team points.
total_yards character Team total yards.
net_passing_yards character Team net passing yards.
completion_attempts character Team completion attempts.
passing_tds character Team passing touchdowns.
yards_per_pass character Team game yards per pass.
passes_intercepted character Team passes intercepted.
interception_yards character Interception yards.
interception_tds character Interceptions returned for a touchdown.
rushing_attempts character Team rushing attempts.
rushing_yards character Team rushing yards.
rush_tds character Team rushing touchdowns.
yards_per_rush_attempt character Team yards per rush attempt.
first_downs character First downs earned by the team.
third_down_eff character Third down efficiency.
fourth_down_eff character Fourth down efficiency.
punt_returns character Team punt returns.
punt_return_yards character Team punt return yards.
punt_return_tds character Team punt return touchdowns.
kick_return_yards character Team kick return yards.
kick_return_tds character Team kick return touchdowns.
kick_returns character Team kick returns.
kicking_points character Team points from kicking the ball.
fumbles_recovered character Team fumbles recovered.
fumbles_lost character Team fumbles lost.
total_fumbles character Team total fumbles.
tackles character Team tackles.
tackles_for_loss character Team tackles for a loss.
sacks character Team sacks.
qb_hurries character Team QB hurries.
interceptions character Team interceptions.
passes_deflected character Team passes deflected.
turnovers character Team turnovers.
defensive_tds character Team defensive touchdowns.
total_penalties_yards character Team total penalty yards.
possession_time character Team time of possession.
points_allowed integer Points for the opponent.
total_yards_allowed character Opponent total yards.
net_passing_yards_allowed character Opponent net passing yards.
completion_attempts_allowed character Opponent completion attempts.
passing_tds_allowed character Opponent passing TDs.
yards_per_pass_allowed character Opponent yards per pass allowed.
passes_intercepted_allowed character Opponent passes intercepted.
interception_yards_allowed character Opponent interception yards.
interception_tds_allowed character Opponent interception TDs.
rushing_attempts_allowed character Opponent rushing attempts.
rushing_yards_allowed character Opponent rushing yards.
rush_tds_allowed character Opponent rushing touchdowns.
yards_per_rush_attempt_allowed character Opponent rushing yards per attempt.
first_downs_allowed character Opponent first downs.
third_down_eff_allowed character Opponent third down efficiency.
fourth_down_eff_allowed character Opponent fourth down efficiency.
punt_returns_allowed character Opponent punt returns.
punt_return_yards_allowed character Opponent punt return yards.
punt_return_tds_allowed character Opponent punt return touchdowns.
kick_return_yards_allowed character Opponent kick return yards.
kick_return_tds_allowed character Opponent kick return touchdowns.
kick_returns_allowed character Opponent kick returns.
kicking_points_allowed character Opponent points from kicking.
fumbles_recovered_allowed character Opponent fumbles recovered.
fumbles_lost_allowed character Opponent fumbles lost.
total_fumbles_allowed character Opponent total number of fumbles.
tackles_allowed character Opponent tackles.
tackles_for_loss_allowed character Opponent tackles for loss.
sacks_allowed character Opponent sacks.
qb_hurries_allowed character Opponent quarterback hurries.
interceptions_allowed character Opponent interceptions.
passes_deflected_allowed character Opponent passes deflected.
turnovers_allowed character Opponent turnovers.
defensive_tds_allowed character Opponent defensive touchdowns.
total_penalties_yards_allowed character Opponent total penalty yards.
possession_time_allowed character Opponent time of possession.

See Also

Other CFBD Games: cfbd_calendar(), cfbd_game_box_advanced(), cfbd_game_info(), cfbd_game_media(), cfbd_game_player_stats(), cfbd_game_records(), cfbd_game_weather(), cfbd_live_scoreboard()

Examples


  try(cfbd_game_team_stats(2022, team = "LSU"))

  try(cfbd_game_team_stats(2013, team = "Florida State"))

Get weather from games.

Description

Get weather from games.

Usage

cfbd_game_weather(
  year,
  week = NULL,
  season_type = "regular",
  team = NULL,
  conference = NULL,
  division = NULL
)

Arguments

year

(Integer required): Year, 4 digit format(YYYY)
Minimum value accepted: 2001

week

(Integer optional): Week - values from 1-15, 1-14 for seasons pre-playoff (i.e. 2013 or earlier)

season_type

(String default regular): Select Season Type: regular, postseason, both, allstar, spring_regular, spring_postseason

team

(String optional): D-I Team

conference

(String optional): Conference abbreviation - Select a valid FBS conference Conference abbreviations P5: ACC, B12, B1G, SEC, PAC Conference abbreviations G5 and FBS Independents: CUSA, MAC, MWC, Ind, SBC, AAC

division

(String optional): Division/classification filter – one of fbs, fcs, ii, ii/iii, iii. Sent to CFBD as classification.

Value

cfbd_game_weather() - A data frame with 23 variables:

col_name types description
game_id integer Referencing game id.
season integer Season of the game.
week integer Game week.
season_type character Season type of the game.
start_date character Game date.
start_time_tbd logical TRUE/FALSE flag for if the game's start time is to be determined.
game_indoors logical TRUE/FALSE flag for if the game is indoors.
home_team character Home team name.
home_conference character Home team conference.
away_team character Away team name.
away_conference character Away team conference.
venue_id integer Referencing venue id.
venue character Venue name.
temperature integer Game-time temperature, in degrees Fahrenheit.
dew_point integer Dew point at kickoff, in degrees Fahrenheit.
humidity integer Relative humidity at kickoff, as a percentage (0-100).
precipitation integer Precipitation total at kickoff, in inches.
snowfall integer Snowfall total at kickoff, in inches.
wind_direction integer Wind direction, in degrees (0-360, 0 = north).
wind_speed integer Wind speed, in miles per hour.
pressure integer Barometric pressure, in millibars.
weather_condition_code integer Weather condition code from the upstream weather provider.
weather_condition character Free-text weather condition (e.g. "Clear", "Light rain").

See Also

Other CFBD Games: cfbd_calendar(), cfbd_game_box_advanced(), cfbd_game_info(), cfbd_game_media(), cfbd_game_player_stats(), cfbd_game_records(), cfbd_game_team_stats(), cfbd_live_scoreboard()

CFBD Games Endpoint Overview

Description

Get results, statistics and information for games

Details

Get game advanced box score information.

cfbd_game_box_advanced(game_id = 401114233)

Get player statistics by game

cfbd_game_player_stats(2018, week = 15, conference = "Ind")

cfbd_game_player_stats(2013, week = 1, team = "Florida State", category = "passing")

Get team records by year

cfbd_game_records(2018, team = "Notre Dame")

cfbd_game_records(2013, team = "Florida State")

Get team statistics by game

cfbd_game_team_stats(2019, team = "LSU")

cfbd_game_team_stats(2013, team = "Florida State")

Get results information from games.

cfbd_game_info(2018, week = 1)

cfbd_game_info(2018, week = 7, conference = "Ind")

# 7 OTs LSU @ TAMU
cfbd_game_info(2018, week = 13, team = "Texas A&M", quarter_scores = TRUE)

Get weather from games.

cfbd_game_weather(2018, week = 1)

cfbd_game_info(2018, week = 7, conference = "Ind")

Get calendar of weeks by season.

cfbd_calendar(2019)

Get game media information (TV, radio, etc).

cfbd_game_media(2019, week = 4, conference = "ACC")

CFBD Info Endpoint Overview

Description

Get API key usage information

Description

Get API key usage information Call volume and remaining quota for the configured CFBD API key.

Usage

cfbd_info_usage(days = NULL, limit = NULL, api = NULL, proxy = NULL)

Arguments

days

(Integer optional): Look-back window in days.

limit

(Integer optional): Maximum rows to return.

api

(String optional): API filter – all, cfb or cbb.

proxy

(List optional): Per-call proxy override passed to get_req(). NULL (default) falls back to getOption("cfbfastR.proxy") and then the ⁠http(s)_proxy⁠ environment variables, so a caller can override the shared setting for one endpoint.

Value

cfbd_info_usage() - A tibble with 11 columns:

col_name types description
api character API the request was made against (cfb or cbb).
endpoint character API endpoint path.
kind character Row type -- top_endpoint (aggregated count) or recent_request (single event).
requests integer Number of requests recorded.
occurred_at character Timestamp for the row (last use for top_endpoint, request time for recent_request).
window_start character Start of the reporting window (ISO 8601).
window_end character End of the reporting window (ISO 8601).
total_requests integer Total requests in the window.
total_cfb_requests integer College football requests in the window.
total_cbb_requests integer College basketball requests in the window.
unique_endpoints integer Distinct endpoints called in the window.

Examples


  try(cfbd_info_usage())

Get live college football play-by-play data.

Description

Get live college football play-by-play data.

Usage

cfbd_live_plays(game_id)

Arguments

game_id

(Integer Required): Game ID filter for querying a single game Can be found using the cfbd_game_info() function

Value

cfbd_live_plays() - A data frame with 94 columns:

col_name types description
game_id integer CFBD game id for the live game.
home_team_id integer CFBD team id of the home team.
home_team character Name of the home team.
away_team_id integer CFBD team id of the away team.
away_team character Name of the away team.
play_id character Unique CFBD play id for this play.
home_score integer Home team score at the conclusion of the play.
away_score integer Away team score at the conclusion of the play.
period integer Quarter (1-4, or overtime period) in which the play occurred.
clock character Game clock at the snap, formatted as "MM:SS".
wall_clock character Real-world UTC timestamp when the play was recorded.
offense_team_id integer CFBD team id of the team on offense for this play.
offense_team character Name of the team on offense for this play.
down integer Down (1-4) at the start of the play.
distance integer Yards to gain for a first down at the snap.
yards_to_goal integer Yards from the offense to the opponent's end zone at the snap (0-100).
yards_gained integer Net yards gained by the offense on the play.
play_type_id integer CFBD play_type identifier; see cfbd_play_types().
play_type character Play type label (e.g. "Rush", "Pass Reception", "Punt").
ppa numeric Predicted Points Added (CFBD PPA/EPA) value for the play.
garbage_time logical TRUE if the play occurred during garbage time.
success logical TRUE if the play met CFBD success-rate criteria.
rush_pass character Classification of the play as "Rush" or "Pass".
down_type character Down/distance classification (e.g. "standard" vs "passing" down).
play_text character Free-text narrative description of the play.
drive_id character CFBD drive identifier for the drive containing this play.
drive_offense_id integer CFBD team id of the offense on the drive.
drive_offense_team character Name of the offensive team on the drive.
drive_defense_id integer CFBD team id of the defense on the drive.
drive_defense_team character Name of the defensive team on the drive.
drive_play_count integer Number of plays in the drive.
drive_yards_gained integer Total net yards gained on the drive.
drive_start_period integer Quarter in which the drive started.
drive_start_clock character Game clock ("MM:SS") when the drive started.
drive_start_yards_to_goal integer Yards to opponent's end zone at drive start (0-100).
drive_end_period integer Quarter in which the drive ended.
drive_end_clock character Game clock ("MM:SS") when the drive ended.
drive_end_yards_to_goal integer Yards to opponent's end zone at drive end (0-100).
drive_duration character Drive duration measured in elapsed game clock.
drive_scoring_opportunity logical TRUE if the drive reached scoring territory.
drive_result character Outcome of the drive (e.g. "TD", "FG", "PUNT", "INT").
drive_points_gained integer Points scored by the offense on the drive.
current_clock character Current game clock at the time of the live API snapshot.
current_possession character Team currently in possession at the snapshot time.
home_line_scores_q1 integer Home team points scored in the first quarter.
home_line_scores_q2 integer Home team points scored in the second quarter.
home_line_scores_q3 integer Home team points scored in the third quarter.
home_line_scores_q4 integer Home team points scored in the fourth quarter.
home_points integer Home team total points scored in the game so far.
home_drives integer Number of offensive drives by the home team.
home_scoring_opportunities integer Number of home drives that reached scoring territory.
home_points_per_opportunity numeric Home points scored per scoring opportunity.
home_average_start_yard_line numeric Average starting field position (yards from own goal) for home drives.
home_plays integer Total offensive plays run by the home team.
home_line_yards numeric Total offensive line yards credited to the home team's rushing attack.
home_line_yards_per_rush numeric Home offensive line yards per rush attempt.
home_second_level_yards integer Home rushing yards gained at the second level (5-10 yards past the line).
home_second_level_yards_per_rush numeric Home second-level rushing yards per rush attempt.
home_open_field_yards integer Home rushing yards gained in the open field (10+ yards past the line).
home_open_field_yards_per_rush numeric Home open-field rushing yards per rush attempt.
home_ppa_per_play numeric Average PPA per play for the home team (CFBD renames epa_per_play).
home_total_ppa numeric Cumulative PPA for the home team across all plays.
home_passing_ppa numeric Cumulative passing PPA for the home team.
home_ppa_per_pass numeric Average PPA per pass attempt for the home team.
home_rushing_ppa numeric Cumulative rushing PPA for the home team.
home_ppa_per_rush numeric Average PPA per rush attempt for the home team.
home_success_rate numeric Home team overall success rate (0-1).
home_standard_down_success_rate numeric Home success rate on standard downs (0-1).
home_passing_down_success_rate numeric Home success rate on passing downs (0-1).
home_explosiveness numeric Home explosiveness metric (average PPA on successful plays).
home_deserve_to_win numeric Home team "deserve-to-win" probability metric (0-1).
away_line_scores_q1 integer Away team points scored in the first quarter.
away_line_scores_q2 integer Away team points scored in the second quarter.
away_line_scores_q3 integer Away team points scored in the third quarter.
away_line_scores_q4 integer Away team points scored in the fourth quarter.
away_points integer Away team total points scored in the game so far.
away_drives integer Number of offensive drives by the away team.
away_scoring_opportunities integer Number of away drives that reached scoring territory.
away_points_per_opportunity numeric Away points scored per scoring opportunity.
away_average_start_yard_line numeric Average starting field position (yards from own goal) for away drives.
away_plays integer Total offensive plays run by the away team.
away_line_yards numeric Total offensive line yards credited to the away team's rushing attack.
away_line_yards_per_rush numeric Away offensive line yards per rush attempt.
away_second_level_yards integer Away rushing yards gained at the second level (5-10 yards past the line).
away_second_level_yards_per_rush numeric Away second-level rushing yards per rush attempt.
away_open_field_yards integer Away rushing yards gained in the open field (10+ yards past the line).
away_open_field_yards_per_rush numeric Away open-field rushing yards per rush attempt.
away_ppa_per_play numeric Average PPA per play for the away team (CFBD renames epa_per_play).
away_total_ppa numeric Cumulative PPA for the away team across all plays.
away_passing_ppa numeric Cumulative passing PPA for the away team.
away_ppa_per_pass numeric Average PPA per pass attempt for the away team.
away_rushing_ppa numeric Cumulative rushing PPA for the away team.
away_ppa_per_rush numeric Average PPA per rush attempt for the away team.
away_success_rate numeric Away team overall success rate (0-1).
away_standard_down_success_rate numeric Away success rate on standard downs (0-1).
away_passing_down_success_rate numeric Away success rate on passing downs (0-1).
away_explosiveness numeric Away explosiveness metric (average PPA on successful plays).
away_deserve_to_win numeric Away team "deserve-to-win" probability metric (0-1).

See Also

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

Examples


  try(cfbd_live_plays(game_id=401520182))

Get live game scoreboard information from games.

Description

Get live game scoreboard information from games.

Usage

cfbd_live_scoreboard(division = "fbs", conference = NULL)

Arguments

division

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

conference

(String optional): Conference abbreviation - Select a valid FBS conference Conference abbreviations P5: ACC, B12, B1G, SEC, PAC Conference abbreviations G5 and FBS Independents: CUSA, MAC, MWC, Ind, SBC, AAC

Value

cfbd_live_scoreboard() - A data frame with 41 variables:

col_name types description
game_id integer CFBD-internal game id; join key to other CFBD endpoints.
start_date character Scheduled kickoff timestamp (ISO 8601, UTC).
start_time_tbd logical TRUE if the scheduled kickoff time is still to be determined.
tv character Television network broadcasting the game (e.g. "ESPN", "ABC").
neutral_site logical TRUE if the game is being played at a neutral site.
conference_game logical TRUE if both teams are in the same conference.
status character Game status (e.g. "scheduled", "in_progress", "completed").
period integer Current period/quarter number (1-4, 5+ for overtime).
clock character Game clock display as "MM:SS" remaining in the current period.
situation character Free-text down-and-distance / field-position summary for the current play.
possession character Abbreviation of the team currently in possession.
last_play character Free-text description of the most recent play.
venue_name character Stadium / venue name.
venue_city character City where the venue is located.
venue_state character State (or province/country) where the venue is located.
home_team_id integer CFBD-internal team id for the home team.
home_team_name character Full home team name (e.g. "Georgia").
home_team_conference character Conference name of the home team.
home_team_classification character Division classification of the home team (fbs/fcs/ii/iii).
home_team_points integer Current total points scored by the home team.
home_team_line_scores_Q1 integer Home team points scored in the first quarter.
home_team_line_scores_Q2 integer Home team points scored in the second quarter.
home_team_line_scores_Q3 integer Home team points scored in the third quarter.
home_team_line_scores_Q4 integer Home team points scored in the fourth quarter.
away_team_id integer CFBD-internal team id for the away team.
away_team_name character Full away team name (e.g. "Auburn").
away_team_conference character Conference name of the away team.
away_team_classification character Division classification of the away team (fbs/fcs/ii/iii).
away_team_points integer Current total points scored by the away team.
away_team_line_scores_Q1 integer Away team points scored in the first quarter.
away_team_line_scores_Q2 integer Away team points scored in the second quarter.
away_team_line_scores_Q3 integer Away team points scored in the third quarter.
away_team_line_scores_Q4 integer Away team points scored in the fourth quarter.
weather_temperature numeric Temperature at kickoff, in degrees Fahrenheit.
weather_description character Free-text weather description (e.g. "Clear", "Light rain").
weather_wind_speed numeric Wind speed, in miles per hour.
weather_wind_direction integer Wind direction, in degrees (0-360, 0 = north).
betting_spread numeric Pre-game point spread relative to the home team (negative = home favored).
betting_over_under numeric Pre-game over/under (total) line in points.
betting_home_moneyline integer American-odds moneyline for the home team.
betting_away_moneyline integer American-odds moneyline for the away team.

See Also

Other CFBD Games: cfbd_calendar(), cfbd_game_box_advanced(), cfbd_game_info(), cfbd_game_media(), cfbd_game_player_stats(), cfbd_game_records(), cfbd_game_team_stats(), cfbd_game_weather()

Examples


  try(cfbd_live_scoreboard(division='fbs', conference = "B12"))

CFBD Metrics Endpoint Overview

Description

Details

Get expected points for field goals by yards to goal and distance

  cfbd_metrics_fg_ep()

Get opponent-adjusted team season statistics for predicted points added (PPA)

 cfbd_metrics_wepa_team_season(year = 2019, team = "TCU")

Get opponent-adjusted player passing statistics for predicted points added (PPA)

cfbd_metrics_wepa_players_passing(year = 2019, team = "TCU")

Get opponent-adjusted player rushing statistics for predicted points added (PPA)

cfbd_metrics_wepa_players_rushing(year = 2019, team = "TCU")

Get Points Added Above Replacement (PAAR) ratings for kickers

cfbd_metrics_wepa_players_kicking(year = 2019, team = "TCU")

Get team game averages for predicted points added (PPA)

  cfbd_metrics_ppa_games(year = 2019, team = "TCU")

Get player game averages for predicted points added (PPA)

  cfbd_metrics_ppa_players_games(year = 2019, week = 3, team = "TCU")

Get player season averages for predicted points added (PPA)

  cfbd_metrics_ppa_players_season(year = 2019, team = "TCU")

Get team averages for predicted points added (PPA)

  cfbd_metrics_ppa_teams(year = 2019, team = "TCU")

Get pre-game and post-game win probability data from CFBD API

  cfbd_metrics_wp_pregame(year = 2019, week = 9, team = "Texas A&M")
  cfbd_metrics_wp(game_id = 401012356)

Calculate predicted points using down and distance

cfbd_metrics_ppa_predicted(down = 1, distance = 10)

Get FG expected points from CFBD API

Description

Get FG expected points from CFBD API

Usage

cfbd_metrics_fg_ep()

Value

cfbd_metrics_fg_ep() - A data frame with 3 variables:

col_name types description
yards_to_goal integer Yards to the goal line (0-100).
distance integer Distance to goal posts from kicking location (17 yds further than yards to goal).
expected_points numeric Expected points given yards to goal / distance.

See Also

Other CFBD Metrics: cfbd_metrics_ppa_games(), cfbd_metrics_ppa_players_games(), cfbd_metrics_ppa_players_season(), cfbd_metrics_ppa_predicted(), cfbd_metrics_ppa_teams(), cfbd_metrics_wepa_players_kicking(), cfbd_metrics_wepa_players_passing(), cfbd_metrics_wepa_players_rushing(), cfbd_metrics_wepa_team_season(), cfbd_metrics_wp(), cfbd_metrics_wp_pregame()

Examples


  try(cfbd_metrics_fg_ep())

Get team game averages for predicted points added (PPA)

Description

Get team game averages for predicted points added (PPA)

Usage

cfbd_metrics_ppa_games(
  year,
  week = NULL,
  season_type = "both",
  team = NULL,
  conference = NULL,
  excl_garbage_time = FALSE,
  division = NULL
)

Arguments

year

(Integer required): Year, 4 digit format (YYYY)
Minimum value accepted: 2001

week

(Integer optional): Week - values range from 1-15, 1-14 for seasons pre-playoff, i.e. 2013 or earlier

season_type

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

team

(String optional): D-I Team

conference

(String optional): Conference abbreviation - Select a valid FBS conference Conference abbreviations P5: ACC, B12, B1G, SEC, PAC Conference abbreviations G5 and FBS Independents: CUSA, MAC, MWC, Ind, SBC, AAC

excl_garbage_time

(Logical default FALSE): Select whether to exclude Garbage Time (TRUE or FALSE)

division

(String optional): Division/classification filter – one of fbs, fcs, ii, ii/iii, iii. Sent to CFBD as classification.

Value

cfbd_metrics_ppa_games() - A data frame with 19 variables:

col_name types description
game_id integer Referencing game id.
season integer Season of the game.
week integer Game week of the season.
season_type character Season type (regular, postseason, etc.).
conference character Conference of the team.
team character Team name.
opponent character Team opponent name.
off_overall numeric Offense overall predicted points added (PPA).
off_passing numeric Offense passing predicted points added (PPA).
off_rushing numeric Offense rushing predicted points added (PPA).
off_first_down numeric Offense 1st down predicted points added (PPA).
off_second_down numeric Offense 2nd down predicted points added (PPA).
off_third_down numeric Offense 3rd down predicted points added (PPA).
def_overall numeric Defense overall predicted points added (PPA).
def_passing numeric Defense passing predicted points added (PPA).
def_rushing numeric Defense rushing predicted points added (PPA).
def_first_down numeric Defense 1st down predicted points added (PPA).
def_second_down numeric Defense 2nd down predicted points added (PPA).
def_third_down numeric Defense 3rd down predicted points added (PPA).

See Also

Other CFBD Metrics: cfbd_metrics_fg_ep(), cfbd_metrics_ppa_players_games(), cfbd_metrics_ppa_players_season(), cfbd_metrics_ppa_predicted(), cfbd_metrics_ppa_teams(), cfbd_metrics_wepa_players_kicking(), cfbd_metrics_wepa_players_passing(), cfbd_metrics_wepa_players_rushing(), cfbd_metrics_wepa_team_season(), cfbd_metrics_wp(), cfbd_metrics_wp_pregame()

Examples


  try(cfbd_metrics_ppa_games(year = 2019, team = "TCU"))

Get player game averages for predicted points added (PPA)

Description

Get player game averages for predicted points added (PPA)

Usage

cfbd_metrics_ppa_players_games(
  year = NULL,
  week = NULL,
  season_type = "both",
  team = NULL,
  position = NULL,
  athlete_id = NULL,
  threshold = NULL,
  excl_garbage_time = FALSE
)

Arguments

year

(Integer required): Year, 4 digit format (YYYY).
Minimum value accepted: 2013

week

(Integer optional): Week - values range from 1-15, 1-14 for seasons pre-playoff, i.e. 2013 or earlier. Required if team not provided.

season_type

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

team

(String optional): D-I Team. Required if week not provided.

position

(string optional): Position abbreviation of the player you are searching for. Position Group - options include:

  • Offense: QB, RB, FB, TE, OL, G, OT, C, WR

  • Defense: DB, CB, S, LB, DE, DT, NT, DL

  • Special Teams: K, P, LS, PK

athlete_id

(Integer optional): Athlete ID filter for querying a single athlete Can be found using the cfbd_player_info() function.

threshold

(Integer optional): Minimum threshold of plays.

excl_garbage_time

(Logical default FALSE): Select whether to exclude Garbage Time (TRUE or FALSE)

Value

cfbd_metrics_ppa_players_games() - A data frame with 10 variables:

col_name types description
season integer Season of the game.
week integer Game week of the season.
athlete_id character Athlete referencing id.
name character Athlete name.
position character Athlete position.
team character Team name.
opponent character Team opponent name.
avg_PPA_all numeric Average overall predicted points added (PPA).
avg_PPA_pass numeric Average passing predicted points added (PPA).
avg_PPA_rush numeric Average rushing predicted points added (PPA).

See Also

Other CFBD Metrics: cfbd_metrics_fg_ep(), cfbd_metrics_ppa_games(), cfbd_metrics_ppa_players_season(), cfbd_metrics_ppa_predicted(), cfbd_metrics_ppa_teams(), cfbd_metrics_wepa_players_kicking(), cfbd_metrics_wepa_players_passing(), cfbd_metrics_wepa_players_rushing(), cfbd_metrics_wepa_team_season(), cfbd_metrics_wp(), cfbd_metrics_wp_pregame()

Examples


  try(cfbd_metrics_ppa_players_games(year = 2019, week = 3, team = "TCU"))

Get player season averages for predicted points added (PPA)

Description

Get player season averages for predicted points added (PPA)

Usage

cfbd_metrics_ppa_players_season(
  year = NULL,
  team = NULL,
  conference = NULL,
  position = NULL,
  athlete_id = NULL,
  threshold = NULL,
  excl_garbage_time = FALSE
)

Arguments

year

(Integer optional): Year, 4 digit format (YYYY). Required if athlete_id not provided
Minimum value accepted: 2013

team

(String optional): D-I Team.

conference

(String optional): Conference abbreviation - S&P+ information by conference Conference abbreviations P5: ACC, B12, B1G, SEC, PAC Conference abbreviations G5 and FBS Independents: CUSA, MAC, MWC, Ind, SBC, AAC

position

(string optional): Position abbreviation of the player you are searching for. Position Group - options include:

  • Offense: QB, RB, FB, TE, OL, G, OT, C, WR

  • Defense: DB, CB, S, LB, DE, DT, NT, DL

  • Special Teams: K, P, LS, PK

athlete_id

(Integer optional): Athlete ID filter for querying a single athlete. Required if year not provided Can be found using the cfbd_player_info() function.

threshold

(Integer optional): Minimum threshold of plays.

excl_garbage_time

(Logical default FALSE): Select whether to exclude Garbage Time (TRUE or FALSE)

Value

cfbd_metrics_ppa_players_season() - A data frame with 23 variables:

col_name types description
season integer Four-digit season year.
athlete_id character Athlete referencing id.
name character Athlete name.
position character Athlete position abbreviation (e.g. "QB", "RB").
team character Team name.
conference character Team conference name.
countable_plays integer DEPRECATED Number of plays which can be counted.
avg_PPA_all numeric Average overall predicted points added (PPA).
avg_PPA_pass numeric Average passing predicted points added (PPA).
avg_PPA_rush numeric Average rushing predicted points added (PPA).
avg_PPA_first_down numeric Average 1st down predicted points added (PPA).
avg_PPA_second_down numeric Average 2nd down predicted points added (PPA).
avg_PPA_third_down numeric Average 3rd down predicted points added (PPA).
avg_PPA_standard_downs numeric Average standard down predicted points added (PPA).
avg_PPA_passing_downs numeric Average passing down predicted points added (PPA).
total_PPA_all numeric Total overall predicted points added (PPA).
total_PPA_pass numeric Total passing predicted points added (PPA).
total_PPA_rush numeric Total rushing predicted points added (PPA).
total_PPA_first_down numeric Total 1st down predicted points added (PPA).
total_PPA_second_down numeric Total 2nd down predicted points added (PPA).
total_PPA_third_down numeric Total 3rd down predicted points added (PPA).
total_PPA_standard_downs numeric Total standard down predicted points added (PPA).
total_PPA_passing_downs numeric Total passing down predicted points added (PPA).

See Also

Other CFBD Metrics: cfbd_metrics_fg_ep(), cfbd_metrics_ppa_games(), cfbd_metrics_ppa_players_games(), cfbd_metrics_ppa_predicted(), cfbd_metrics_ppa_teams(), cfbd_metrics_wepa_players_kicking(), cfbd_metrics_wepa_players_passing(), cfbd_metrics_wepa_players_rushing(), cfbd_metrics_wepa_team_season(), cfbd_metrics_wp(), cfbd_metrics_wp_pregame()

Examples


  try(cfbd_metrics_ppa_players_season(year = 2019, team = "TCU"))

Calculate predicted points using down and distance

Description

Calculate predicted points using down and distance

Usage

cfbd_metrics_ppa_predicted(down, distance)

Arguments

down

(Integer required): Down filter

distance

(Integer required): Distance filter

Value

cfbd_metrics_ppa_predicted() - A data frame with 2 variables:

col_name types description
yard_line integer Yards to goal.
predicted_points numeric Predicted points in that down-distance-yardline scenario.

See Also

Other CFBD Metrics: cfbd_metrics_fg_ep(), cfbd_metrics_ppa_games(), cfbd_metrics_ppa_players_games(), cfbd_metrics_ppa_players_season(), cfbd_metrics_ppa_teams(), cfbd_metrics_wepa_players_kicking(), cfbd_metrics_wepa_players_passing(), cfbd_metrics_wepa_players_rushing(), cfbd_metrics_wepa_team_season(), cfbd_metrics_wp(), cfbd_metrics_wp_pregame()

Examples


  try(cfbd_metrics_ppa_predicted(down = 1, distance = 10))

  try(cfbd_metrics_ppa_predicted(down = 3, distance = 10))

Get team averages for predicted points added (PPA)

Description

Get team averages for predicted points added (PPA)

Usage

cfbd_metrics_ppa_teams(
  year = NULL,
  team = NULL,
  conference = NULL,
  excl_garbage_time = FALSE,
  division = NULL
)

Arguments

year

(Integer optional): Year, 4 digit format (YYYY). Required if team not provided
Minimum value accepted: 2001

team

(String optional): D-I Team. Required if year not provided

conference

(String optional): Conference name - select a valid FBS conference Conference names P5: ACC, Big 12, Big Ten, SEC, Pac-12 Conference names G5 and FBS Independents: Conference USA, Mid-American, Mountain West, FBS Independents, American Athletic

excl_garbage_time

(Logical default FALSE): Select whether to exclude Garbage Time (TRUE or FALSE)

division

(String optional): Division/classification filter – one of fbs, fcs, ii, ii/iii, iii. Sent to CFBD as classification.

Value

cfbd_metrics_ppa_teams() - A data frame with 21 variables:

col_name types description
season integer Four-digit season year.
conference character Team conference name.
team character Team name.
off_overall numeric Offense overall predicted points added (PPA).
off_passing numeric Offense passing predicted points added (PPA).
off_rushing numeric Offense rushing predicted points added (PPA).
off_first_down numeric Offense 1st down predicted points added (PPA).
off_second_down numeric Offense 2nd down predicted points added (PPA).
off_third_down numeric Offense 3rd down predicted points added (PPA).
off_cumulative_total numeric Offense cumulative total predicted points added (PPA).
off_cumulative_passing numeric Offense cumulative total passing predicted points added (PPA).
off_cumulative_rushing numeric Offense cumulative total rushing predicted points added (PPA).
def_overall numeric Defense overall predicted points added (PPA).
def_passing numeric Defense passing predicted points added (PPA).
def_rushing numeric Defense rushing predicted points added (PPA).
def_first_down numeric Defense 1st down predicted points added (PPA).
def_second_down numeric Defense 2nd down predicted points added (PPA).
def_third_down numeric Defense 3rd down predicted points added (PPA).
def_cumulative_total numeric Defense cumulative total predicted points added (PPA).
def_cumulative_passing numeric Defense cumulative total passing predicted points added (PPA).
def_cumulative_rushing numeric Defense cumulative total rushing predicted points added (PPA).

See Also

Other CFBD Metrics: cfbd_metrics_fg_ep(), cfbd_metrics_ppa_games(), cfbd_metrics_ppa_players_games(), cfbd_metrics_ppa_players_season(), cfbd_metrics_ppa_predicted(), cfbd_metrics_wepa_players_kicking(), cfbd_metrics_wepa_players_passing(), cfbd_metrics_wepa_players_rushing(), cfbd_metrics_wepa_team_season(), cfbd_metrics_wp(), cfbd_metrics_wp_pregame()

Examples


  try(cfbd_metrics_ppa_teams(year = 2019, team = "TCU"))

Get Points Added Above Replacement (PAAR) ratings for kickers

Description

Get Points Added Above Replacement (PAAR) ratings for kickers

Usage

cfbd_metrics_wepa_players_kicking(year = NULL, team = NULL, conference = NULL)

Arguments

year

(Integer required): Year, 4 digit format (YYYY)
Minimum value accepted: 2016

team

(String optional): D-I Team

conference

(String optional): Conference abbreviation - Select a valid FBS conference Conference abbreviations P5: ACC, B12, B1G, SEC, PAC Conference abbreviations G5 and FBS Independents: CUSA, MAC, MWC, Ind, SBC, AAC

Value

cfbd_metrics_wepa_players_kicking() - A data frame with 7 variables:

col_name types description
year integer Four-digit season year (e.g. 2019).
athlete_id character CFBD athlete identifier (use with cfbd_player_info()).
athlete_name character Kicker full name.
team character Full team name (e.g. "TCU").
conference character Team conference name (e.g. "Big 12").
paar numeric Points Added Above Replacement on field goal attempts (kicker value vs baseline).
attempts integer Total field goal attempts included in the PAAR calculation.

See Also

Other CFBD Metrics: cfbd_metrics_fg_ep(), cfbd_metrics_ppa_games(), cfbd_metrics_ppa_players_games(), cfbd_metrics_ppa_players_season(), cfbd_metrics_ppa_predicted(), cfbd_metrics_ppa_teams(), cfbd_metrics_wepa_players_passing(), cfbd_metrics_wepa_players_rushing(), cfbd_metrics_wepa_team_season(), cfbd_metrics_wp(), cfbd_metrics_wp_pregame()

Examples


  try(cfbd_metrics_wepa_players_kicking(year = 2019, team = "TCU"))

Get opponent-adjusted player passing statistics for predicted points added (PPA)

Description

Get opponent-adjusted player passing statistics for predicted points added (PPA)

Usage

cfbd_metrics_wepa_players_passing(
  year = NULL,
  team = NULL,
  conference = NULL,
  position = NULL
)

Arguments

year

(Integer required): Year, 4 digit format (YYYY)
Minimum value accepted: 2013

team

(String optional): D-I Team

conference

(String optional): Conference abbreviation - Select a valid FBS conference Conference abbreviations P5: ACC, B12, B1G, SEC, PAC Conference abbreviations G5 and FBS Independents: CUSA, MAC, MWC, Ind, SBC, AAC

position

(string optional): Position abbreviation of the player you are searching for. Position Group - options include:

  • Offense: QB, RB, FB, TE, OL, G, OT, C, WR

  • Defense: DB, CB, S, LB, DE, DT, NT, DL

  • Special Teams: K, P, LS, PK

Value

cfbd_metrics_wepa_players_passing() - A data frame with 8 variables:

col_name types description
year integer Four-digit season year (e.g. 2019).
athlete_id character CFBD athlete identifier (use with cfbd_player_info()).
athlete_name character Player full name.
position character Player position abbreviation (e.g. "QB", "RB").
team character Full team name (e.g. "TCU").
conference character Team conference name (e.g. "Big 12").
wepa numeric Opponent-adjusted weighted EPA (passing predicted points added).
plays integer Total qualifying passing plays included in the WEPA calculation.

See Also

Other CFBD Metrics: cfbd_metrics_fg_ep(), cfbd_metrics_ppa_games(), cfbd_metrics_ppa_players_games(), cfbd_metrics_ppa_players_season(), cfbd_metrics_ppa_predicted(), cfbd_metrics_ppa_teams(), cfbd_metrics_wepa_players_kicking(), cfbd_metrics_wepa_players_rushing(), cfbd_metrics_wepa_team_season(), cfbd_metrics_wp(), cfbd_metrics_wp_pregame()

Examples


  try(cfbd_metrics_wepa_players_passing(year = 2019, team = "TCU"))

Get opponent-adjusted player rushing statistics for predicted points added (PPA)

Description

Get opponent-adjusted player rushing statistics for predicted points added (PPA)

Usage

cfbd_metrics_wepa_players_rushing(
  year = NULL,
  team = NULL,
  conference = NULL,
  position = NULL
)

Arguments

year

(Integer required): Year, 4 digit format (YYYY)
Minimum value accepted: 2013

team

(String optional): D-I Team

conference

(String optional): Conference abbreviation - Select a valid FBS conference Conference abbreviations P5: ACC, B12, B1G, SEC, PAC Conference abbreviations G5 and FBS Independents: CUSA, MAC, MWC, Ind, SBC, AAC

position

(string optional): Position abbreviation of the player you are searching for. Position Group - options include:

  • Offense: QB, RB, FB, TE, OL, G, OT, C, WR

  • Defense: DB, CB, S, LB, DE, DT, NT, DL

  • Special Teams: K, P, LS, PK

Value

cfbd_metrics_wepa_players_rushing() - A data frame with 8 variables:

col_name types description
year integer Four-digit season year (e.g. 2019).
athlete_id character CFBD athlete identifier (use with cfbd_player_info()).
athlete_name character Player full name.
position character Player position abbreviation (e.g. "RB", "QB").
team character Full team name (e.g. "TCU").
conference character Team conference name (e.g. "Big 12").
wepa numeric Opponent-adjusted weighted EPA (rushing predicted points added).
plays integer Total qualifying rushing plays included in the WEPA calculation.

See Also

Other CFBD Metrics: cfbd_metrics_fg_ep(), cfbd_metrics_ppa_games(), cfbd_metrics_ppa_players_games(), cfbd_metrics_ppa_players_season(), cfbd_metrics_ppa_predicted(), cfbd_metrics_ppa_teams(), cfbd_metrics_wepa_players_kicking(), cfbd_metrics_wepa_players_passing(), cfbd_metrics_wepa_team_season(), cfbd_metrics_wp(), cfbd_metrics_wp_pregame()

Examples


  try(cfbd_metrics_wepa_players_rushing(year = 2019, team = "TCU"))

Get opponent-adjusted team season statistics for predicted points added (PPA)

Description

Get opponent-adjusted team season statistics for predicted points added (PPA)

Usage

cfbd_metrics_wepa_team_season(year = NULL, team = NULL, conference = NULL)

Arguments

year

(Integer required): Year, 4 digit format (YYYY)
Minimum value accepted: 2008

team

(String optional): D-I Team

conference

(String optional): Conference abbreviation - Select a valid FBS conference Conference abbreviations P5: ACC, B12, B1G, SEC, PAC Conference abbreviations G5 and FBS Independents: CUSA, MAC, MWC, Ind, SBC, AAC

Value

cfbd_metrics_wepa_team_season() - A data frame with 26 variables:

col_name types description
year integer Four-digit season year (e.g. 2019).
team_id integer CFBD internal team identifier.
team character Full team name (e.g. "TCU").
conference character Team conference name (e.g. "Big 12").
explosiveness numeric Offensive opponent-adjusted explosiveness rate (higher = more big plays).
explosiveness_allowed numeric Defensive opponent-adjusted explosiveness rate allowed.
epa_total numeric Opponent-adjusted total offensive EPA per play (predicted points added).
epa_passing numeric Opponent-adjusted offensive passing EPA per play.
epa_rushing numeric Opponent-adjusted offensive rushing EPA per play.
epa_allowed_total numeric Opponent-adjusted total defensive EPA per play allowed.
epa_allowed_passing numeric Opponent-adjusted defensive passing EPA per play allowed.
epa_allowed_rushing numeric Opponent-adjusted defensive rushing EPA per play allowed.
success_rate_total numeric Opponent-adjusted offensive success rate across all plays (proportion 0-1).
success_rate_standard_downs numeric Opponent-adjusted offensive success rate on standard downs (proportion 0-1).
success_rate_passing_downs numeric Opponent-adjusted offensive success rate on passing downs (proportion 0-1).
success_rate_allowed_total numeric Opponent-adjusted defensive success rate allowed across all plays (proportion 0-1).
success_rate_allowed_standard_downs numeric Opponent-adjusted defensive success rate allowed on standard downs (proportion 0-1).
success_rate_allowed_passing_downs numeric Opponent-adjusted defensive success rate allowed on passing downs (proportion 0-1).
rushing_line_yards numeric Opponent-adjusted offensive line yards per rush (Football Outsiders methodology).
rushing_second_level_yards numeric Opponent-adjusted offensive second-level yards per rush (5-10 yards past line of scrimmage).
rushing_open_field_yards numeric Opponent-adjusted offensive open-field yards per rush (10+ yards past line of scrimmage).
rushing_highlight_yards numeric Opponent-adjusted offensive highlight yards per opportunity rush.
rushing_allowed_line_yards numeric Opponent-adjusted defensive line yards per rush allowed.
rushing_allowed_second_level_yards numeric Opponent-adjusted defensive second-level yards per rush allowed.
rushing_allowed_open_field_yards numeric Opponent-adjusted defensive open-field yards per rush allowed.
rushing_allowed_highlight_yards numeric Opponent-adjusted defensive highlight yards per opportunity rush allowed.

See Also

Other CFBD Metrics: cfbd_metrics_fg_ep(), cfbd_metrics_ppa_games(), cfbd_metrics_ppa_players_games(), cfbd_metrics_ppa_players_season(), cfbd_metrics_ppa_predicted(), cfbd_metrics_ppa_teams(), cfbd_metrics_wepa_players_kicking(), cfbd_metrics_wepa_players_passing(), cfbd_metrics_wepa_players_rushing(), cfbd_metrics_wp(), cfbd_metrics_wp_pregame()

Examples


  try(cfbd_metrics_wepa_team_season(year = 2019, team = "TCU"))

Get win probability chart data from API

Description

Get win probability chart data from API

Usage

cfbd_metrics_wp(game_id)

Arguments

game_id

(Integer required): Game ID filter for querying a single game Can be found using the cfbd_game_info() function

Value

cfbd_metrics_wp() - A data frame with 16 variables:

col_name types description
play_id character Play referencing id.
play_text character A text description of the play.
home_id integer Home team referencing id.
home character Home team name.
away_id integer Away team referencing id.
away character Away team name.
spread numeric Betting lines provider spread.
home_ball logical Home team has the ball.
home_score integer Home team score.
away_score integer Away team score.
down integer Down of the play.
distance integer Distance to the sticks (to 1st down marker or goal-line in goal-to-go situations).
home_win_prob numeric Home team win probability (0-1).
away_win_prob numeric Away team win probability (0-1).
play_number integer Game play number.
yard_line integer Yard line of the play (0-100 yards).

See Also

Other CFBD Metrics: cfbd_metrics_fg_ep(), cfbd_metrics_ppa_games(), cfbd_metrics_ppa_players_games(), cfbd_metrics_ppa_players_season(), cfbd_metrics_ppa_predicted(), cfbd_metrics_ppa_teams(), cfbd_metrics_wepa_players_kicking(), cfbd_metrics_wepa_players_passing(), cfbd_metrics_wepa_players_rushing(), cfbd_metrics_wepa_team_season(), cfbd_metrics_wp_pregame()

Examples


  try(cfbd_metrics_wp(game_id = 401012356))

Get pre-game win probability data from API

Description

Get pre-game win probability data from API

Usage

cfbd_metrics_wp_pregame(
  year = NULL,
  week = NULL,
  team = NULL,
  season_type = "both"
)

Arguments

year

(Integer optional): Year, 4 digit format (YYYY)
Minimum value accepted: 2013

week

(Integer optional): Week - values from 1-15, 1-14 for seasons pre-playoff, i.e. 2013 or earlier

team

(String optional): D-I Team

season_type

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

Value

cfbd_metrics_wp_pregame() - A data frame with 9 variables:

col_name types description
season integer Season of the game.
season_type character Season type of the game (regular, postseason, etc.).
week integer Game week of the season.
game_id integer Referencing game id.
home_team character Home team name.
away_team character Away team name.
spread numeric Betting line provider spread.
home_win_prob numeric Home win probability - pre-game prediction (0-1).
away_win_prob numeric Away win probability - pre-game prediction (0-1).

See Also

Other CFBD Metrics: cfbd_metrics_fg_ep(), cfbd_metrics_ppa_games(), cfbd_metrics_ppa_players_games(), cfbd_metrics_ppa_players_season(), cfbd_metrics_ppa_predicted(), cfbd_metrics_ppa_teams(), cfbd_metrics_wepa_players_kicking(), cfbd_metrics_wepa_players_passing(), cfbd_metrics_wepa_players_rushing(), cfbd_metrics_wepa_team_season(), cfbd_metrics_wp()

Examples


  try(cfbd_metrics_wp_pregame(year = 2019, week = 9, team = "Texas A&M"))

CFBD Play-by-Play Endpoint Overview

Description

Details

The modular successor cfbd_pbp_data_v2() ships in a sibling file and references the same CFBD upstream.

Get college football play by play data with cfbfastR expected points/win probability added

 # Get play by play data for 2025 regular season week 1
 cfbd_pbp_data(year = 2025, week = 1, season_type = 'regular', epa_wpa = TRUE)

Get college football play by play data with cfbfastR expected points/win probability added

Description

Extract college football (D-I) play by play Data - for plays

Usage

cfbd_pbp_data(
  year,
  season_type = "regular",
  week = 1,
  team = NULL,
  play_type = NULL,
  epa_wpa = FALSE,
  engine = NULL,
  ...,
  defense = NULL,
  offense_conference = NULL,
  defense_conference = NULL,
  conference = NULL,
  division = NULL
)

Arguments

year

Select year, (example: 2018)
Minimum value accepted: 2001

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)

play_type

Select play type (example: see the cfbd_play_type_df)

epa_wpa

Logical parameter (TRUE/FALSE) to return the Expected Points Added/Win Probability Added variables

engine

(Character optional): which play-by-play engine to run. One of "v2", "legacy" or "auto"; NULL (default) resolves from getOption("cfbfastR.pbp_engine"), which itself defaults to "v2" as of this release. On "v2" this delegates to cfbd_pbp_data_v2(), which adds penalty enforcement resolution, ESPN-resolved player names, the ⁠*_player_id⁠ columns and team attribution. "legacy" reproduces the pre-2.3.0 frame unchanged.

...

Additional arguments passed to cfbd_pbp_data_v2() when the call delegates – notably output, the "default" / "lean" / "full" modeled column-set selector. Ignored on the legacy path.

defense

(String optional): Defensive team filter.

offense_conference

(String optional): Offensive team conference filter.

defense_conference

(String optional): Defensive team conference filter.

conference

(String optional): Conference filter (either side of the ball).

division

(String optional): Division/classification filter – fbs, fcs, ii, ii/iii, iii.

Details

 # Get play by play data for 2025 regular season week 1
 cfbd_pbp_data(year = 2025, week = 1, season_type = 'regular', epa_wpa = TRUE)

Value

A data frame with 368 variables:

col_name types description
season numeric Four-digit season year (e.g. 2024).
wk numeric Season week number (1-15 regular season, 1 for bowl/postseason week).
id_play character Unique CFBD play identifier (concatenates game_id and play index).
game_id integer CFBD-internal game identifier.
game_play_number numeric Sequential play number within the game (excludes timeouts/end markers).
half_play_number numeric Sequential play number within the current half.
drive_play_number numeric Sequential play number within the current drive.
pos_team character Team name in possession at the start of the play (offense, kickoff-aware).
def_pos_team character Team name on defense at the start of the play.
pos_team_score integer Score for the team in possession at the start of the play.
def_pos_team_score integer Score for the defensive team at the start of the play.
half factor Half indicator (1 or 2).
period integer Quarter number (1-4, 5+ for overtime).
clock_minutes integer Minutes remaining on the period clock at the start of the play.
clock_seconds integer Seconds remaining on the period clock at the start of the play.
play_type character CFBD play type label (e.g. "Rush", "Pass Reception", "Field Goal Good").
play_text character Free-text description of the play from CFBD.
down numeric Down number at the start of the play (1-4).
distance numeric Yards to gain for a first down at the start of the play.
yards_to_goal numeric Yards from the offense to the opponent's end zone at the start of the play.
yards_gained numeric Yards gained (or lost) by the offense on the play.
EPA numeric Expected Points Added on the play (cfbfastR EPA model output).
ep_before numeric Expected points value before the play (cfbfastR EPA model).
ep_after numeric Expected points value after the play (cfbfastR EPA model).
wpa numeric Win Probability Added on the play (cfbfastR WP model output).
wp_before numeric Win probability for the possession team before the play (0-1).
wp_after numeric Win probability for the possession team after the play (0-1).
def_wp_before numeric Win probability for the defensive team before the play (0-1).
def_wp_after numeric Win probability for the defensive team after the play (0-1).
penalty_detail character Parsed penalty description extracted from play text.
yds_penalty numeric Yardage assessed on the penalty.
penalty_1st_conv logical TRUE when the penalty resulted in a first down conversion.
new_series numeric Binary flag for the start of a new series of downs.
firstD_by_kickoff numeric Binary flag for a new first down arising from a kickoff.
firstD_by_poss numeric Binary flag for a new first down via change of possession.
firstD_by_penalty numeric Binary flag for a new first down via penalty.
firstD_by_yards numeric Binary flag for a new first down via yards gained.
def_EPA numeric EPA for the defensive team on the play (sign-flipped offense EPA).
home_EPA numeric EPA for the home team on the play.
away_EPA numeric EPA for the away team on the play.
home_EPA_rush numeric Rushing EPA for the home team on the play.
away_EPA_rush numeric Rushing EPA for the away team on the play.
home_EPA_pass numeric Passing EPA for the home team on the play.
away_EPA_pass numeric Passing EPA for the away team on the play.
total_home_EPA numeric Cumulative total EPA for the home team through the play.
total_away_EPA numeric Cumulative total EPA for the away team through the play.
total_home_EPA_rush numeric Cumulative rushing EPA for the home team through the play.
total_away_EPA_rush numeric Cumulative rushing EPA for the away team through the play.
total_home_EPA_pass numeric Cumulative passing EPA for the home team through the play.
total_away_EPA_pass numeric Cumulative passing EPA for the away team through the play.
net_home_EPA numeric Net EPA differential (home minus away) through the play.
net_away_EPA numeric Net EPA differential (away minus home) through the play.
net_home_EPA_rush numeric Net rushing EPA differential for the home team through the play.
net_away_EPA_rush numeric Net rushing EPA differential for the away team through the play.
net_home_EPA_pass numeric Net passing EPA differential for the home team through the play.
net_away_EPA_pass numeric Net passing EPA differential for the away team through the play.
success numeric Binary success-rate flag using the 50/70/100 percent down-state thresholds.
epa_success numeric Binary flag for plays with positive EPA (EPA > 0).
rz_play numeric Binary flag for a red-zone play (yards_to_goal <= 20).
scoring_opp numeric Binary flag for a scoring opportunity (yards_to_goal <= 40).
middle_8 logical TRUE for plays in the middle-8 window (final 4 min of 1H, first 4 min of 2H).
stuffed_run numeric Binary flag for a stuffed run (zero or negative yards gained).
change_of_pos_team numeric Binary flag for change of possession-team on the play.
downs_turnover numeric Binary flag for a turnover on downs.
turnover numeric Binary flag for any turnover on the play.
pos_score_diff_start numeric Score differential for the possession team at the start of the play.
pos_score_pts numeric Points scored on the play attributed to the possession team.
log_ydstogo numeric Natural log of distance-to-go (model feature).
ExpScoreDiff numeric Expected score differential at the start of the play (EPA-adjusted).
ExpScoreDiff_Time_Ratio numeric Expected score differential scaled by share of time remaining.
half_clock_minutes numeric Minutes remaining in the half (15 + clock_minutes when in Q1/Q3).
TimeSecsRem numeric Seconds remaining in the half at the start of the play.
adj_TimeSecsRem numeric Adjusted seconds remaining used by the EPA/WP models.
Goal_To_Go logical TRUE when the offense is in a goal-to-go situation.
Under_two logical TRUE when under two minutes remain in the half.
home character Home team name.
away character Away team name.
home_wp_before numeric Home team win probability before the play (0-1).
away_wp_before numeric Away team win probability before the play (0-1).
home_wp_after numeric Home team win probability after the play (0-1).
away_wp_after numeric Away team win probability after the play (0-1).
end_of_half numeric Binary flag for the last play of a half.
pos_team_receives_2H_kickoff numeric Binary flag indicating possession team receives the second-half kickoff.
lead_pos_team character Possession team on the next play (lead value).
lead_play_type character Play type on the next play (lead value).
lag_pos_team character Possession team on the previous play (lag value).
lag_play_type character Play type on the previous play (lag value).
orig_play_type character Original CFBD play type label before cfbfastR cleaning.
Under_three logical TRUE when under three minutes remain in the half.
down_end factor Down number at the end of the play (post-play state).
distance_end numeric Distance-to-go at the end of the play (post-play state).
log_ydstogo_end numeric Natural log of post-play distance-to-go (model feature).
yards_to_goal_end numeric Yards to opponent end zone at the end of the play.
TimeSecsRem_end numeric Seconds remaining in the half at the end of the play.
Goal_To_Go_end logical TRUE when the post-play state is goal-to-go.
Under_two_end logical TRUE when the post-play state is under two minutes.
offense_score_play numeric Binary flag for an offensive scoring play.
defense_score_play numeric Binary flag for a defensive scoring play.
ppa numeric Predicted Points Added from the CFBD ppa endpoint (CFB-EPA analogue).
yard_line integer Yard line where the play started (raw CFBD yardline field).
scoring logical TRUE when the play resulted in a score (CFBD scoring flag).
pos_team_timeouts_rem_before numeric Possession team timeouts remaining before the play.
def_pos_team_timeouts_rem_before numeric Defensive team timeouts remaining before the play.
pos_team_timeouts integer Possession team timeouts remaining after the play.
def_pos_team_timeouts integer Defensive team timeouts remaining after the play.
pos_score_diff integer Score differential from the possession team's perspective.
pos_score_diff_start_end numeric Score differential aggregated from start to end of the play.
offense_play character Offensive team name as labeled by CFBD on the play.
defense_play character Defensive team name as labeled by CFBD on the play.
offense_receives_2H_kickoff numeric Binary flag indicating offense receives the second-half kickoff.
change_of_poss numeric Binary flag for change of possession on the play (CFBD offense field).
score_pts numeric Points scored on the play.
score_diff_start numeric Score differential at the start of the play.
score_diff integer Score differential (offense_score - defense_score) at the start.
offense_score integer Offense team score at the start of the play.
defense_score integer Defense team score at the start of the play.
offense_conference character Conference name of the offensive team.
defense_conference character Conference name of the defensive team.
off_timeout_called numeric Binary flag for an offensive timeout called during the play.
def_timeout_called numeric Binary flag for a defensive timeout called during the play.
offense_timeouts integer Offense timeouts remaining after the play (CFBD field).
defense_timeouts integer Defense timeouts remaining after the play (CFBD field).
off_timeouts_rem_before numeric Offense timeouts remaining before the play.
def_timeouts_rem_before numeric Defense timeouts remaining before the play.
rusher_player_name character Name of the rusher on a rushing play.
yds_rushed numeric Rushing yards gained on the play.
passer_player_name character Name of the passer on a passing play.
receiver_player_name character Name of the receiver on a passing play.
yds_receiving numeric Receiving yards gained on the play.
yds_sacked numeric Yards lost on the sack.
sack_players character Combined names of all sack participants.
sack_player_name character Primary sack player name.
sack_player_name2 character Secondary sack player name (when split between two defenders).
pass_breakup_player_name character Name of the defender credited with the pass breakup.
interception_player_name character Name of the defender credited with the interception.
yds_int_return numeric Yards gained on an interception return.
fumble_player_name character Name of the player who fumbled.
fumble_forced_player_name character Name of the player who forced the fumble.
fumble_recovered_player_name character Name of the player who recovered the fumble.
yds_fumble_return numeric Yards gained on a fumble return.
punter_player_name character Name of the punter.
yds_punted numeric Yards the ball traveled on the punt.
punt_returner_player_name character Name of the punt returner.
yds_punt_return numeric Yards gained on the punt return.
yds_punt_gained numeric Net yards gained on the punt (punt distance minus return).
punt_block_player_name character Name of the player credited with blocking the punt.
punt_block_return_player_name character Name of the player returning a blocked punt.
fg_kicker_player_name character Name of the field goal kicker.
yds_fg numeric Distance of the field goal attempt in yards.
fg_block_player_name character Name of the player credited with blocking the field goal.
fg_return_player_name character Name of the player returning the blocked/missed field goal.
kickoff_player_name character Name of the kickoff specialist.
yds_kickoff numeric Yards the ball traveled on the kickoff.
kickoff_returner_player_name character Name of the kickoff returner.
yds_kickoff_return numeric Yards gained on the kickoff return.
new_id numeric Numeric play index within the game (id_play with game_id stripped).
orig_drive_number integer Original CFBD drive number for the play.
drive_number integer cfbfastR-cleaned drive number for the play.
drive_result_detailed character Detailed drive result label (e.g. "Punt", "Passing Touchdown", "Downs Turnover").
new_drive_pts numeric Points scored on the drive (signed for offense/defense).
drive_id numeric CFBD drive identifier.
drive_result character CFBD drive result label.
drive_start_yards_to_goal numeric Yards to goal at the start of the drive.
drive_end_yards_to_goal integer Yards to goal at the end of the drive.
drive_yards integer Net yards gained on the drive.
drive_scoring numeric Binary flag for a scoring drive.
drive_pts numeric Points scored on the drive (CFBD/cfbfastR reconciled value).
drive_start_period integer Period (quarter) at the start of the drive.
drive_end_period integer Period (quarter) at the end of the drive.
drive_time_minutes_start integer Minutes on the clock at the start of the drive.
drive_time_seconds_start integer Seconds on the clock at the start of the drive.
drive_time_minutes_end integer Minutes on the clock at the end of the drive.
drive_time_seconds_end integer Seconds on the clock at the end of the drive.
drive_time_minutes_elapsed logical Minutes elapsed during the drive.
drive_time_seconds_elapsed logical Seconds elapsed during the drive.
drive_numbers numeric Binary flag marking the first play of a new drive.
number_of_drives numeric Cumulative count of drives in the game.
pts_scored numeric Points scored on the play, signed by play_type rule.
drive_result_detailed_flag character Pre-fill copy of drive_result_detailed used during drive reconciliation.
drive_result2 character Short-form drive result label (e.g. "TD", "PUNT", "DOWNS").
drive_num numeric Game-scoped drive sequence number.
lag_drive_result_detailed character Drive result detailed on the previous play (lag value).
lead_drive_result_detailed character Drive result detailed on the next play (lead value).
lag_new_drive_pts numeric Drive points on the previous play (lag value).
id_drive character Composite drive identifier (game_id concatenated with drive_num).
rush numeric Binary flag for a rushing play.
rush_td numeric Binary flag for a rushing touchdown.
pass numeric Binary flag for a passing play (includes sacks).
pass_td numeric Binary flag for a passing touchdown.
completion numeric Binary flag for a completed pass.
pass_attempt numeric Binary flag for a pass attempt.
target numeric Binary flag for a targeted receiver on the play.
sack_vec numeric Binary flag for a sack play.
sack numeric Binary flag for a sack (duplicate of sack_vec for downstream use).
int numeric Binary flag for an interception.
int_td numeric Binary flag for an interception returned for a touchdown.
turnover_vec numeric Binary flag for any play classified as a turnover.
turnover_vec_lag numeric Lag of turnover_vec (previous-play turnover flag).
turnover_indicator numeric Composite turnover indicator including failed 4th downs.
kickoff_play numeric Binary flag for a kickoff play.
receives_2H_kickoff numeric Binary flag for the team receiving the second-half kickoff.
missing_yard_flag logical TRUE when post-play yardage had to be imputed.
scoring_play numeric Binary flag for any scoring play.
td_play numeric Binary flag for a touchdown play.
touchdown numeric Binary flag for a touchdown (duplicate of td_play for downstream use).
safety numeric Binary flag for a safety.
fumble_vec numeric Binary flag for a play involving a fumble.
kickoff_tb numeric Binary flag for a kickoff touchback.
kickoff_onside numeric Binary flag for an onside kickoff attempt.
kickoff_oob numeric Binary flag for a kickoff out of bounds.
kickoff_fair_catch numeric Binary flag for a kickoff fair catch.
kickoff_downed numeric Binary flag for a kickoff downed in the field of play.
kickoff_safety numeric Binary flag for a kickoff safety.
kick_play numeric Binary flag for any kicking play (kickoff or field goal).
punt numeric Binary flag for a punt play.
punt_play numeric Binary flag for any punt-related play (includes blocks/returns).
punt_tb numeric Binary flag for a punt touchback.
punt_oob numeric Binary flag for a punt out of bounds.
punt_fair_catch numeric Binary flag for a punt fair catch.
punt_downed numeric Binary flag for a punt downed in the field of play.
punt_safety numeric Binary flag for a punt safety.
punt_blocked numeric Binary flag for a blocked punt.
penalty_safety numeric Binary flag for a safety scored on a penalty.
fg_inds numeric Binary flag for a field goal attempt.
fg_made logical TRUE when the field goal attempt was successful.
fg_make_prob numeric Predicted probability of making the field goal (cfbfastR FG model, 0-1).
No_Score_before numeric Pre-play predicted probability of no score before end of half (cfbfastR EP model, 0-1).
FG_before numeric Pre-play predicted probability of a posteam field goal next (0-1).
Opp_FG_before numeric Pre-play predicted probability of a defteam field goal next (0-1).
Opp_Safety_before numeric Pre-play predicted probability of a defteam safety next (0-1).
Opp_TD_before numeric Pre-play predicted probability of a defteam touchdown next (0-1).
Safety_before numeric Pre-play predicted probability of a posteam safety next (0-1).
TD_before numeric Pre-play predicted probability of a posteam touchdown next (0-1).
No_Score_after numeric Post-play predicted probability of no score before end of half (0-1).
FG_after numeric Post-play predicted probability of a posteam field goal next (0-1).
Opp_FG_after numeric Post-play predicted probability of a defteam field goal next (0-1).
Opp_Safety_after numeric Post-play predicted probability of a defteam safety next (0-1).
Opp_TD_after numeric Post-play predicted probability of a defteam touchdown next (0-1).
Safety_after numeric Post-play predicted probability of a posteam safety next (0-1).
TD_after numeric Post-play predicted probability of a posteam touchdown next (0-1).
penalty_flag logical TRUE when a penalty was flagged on the play.
penalty_declined logical TRUE when the penalty was declined.
penalty_no_play logical TRUE when the penalty nullified the play (no play counted).
penalty_offset logical TRUE when offsetting penalties were called.
penalty_text logical TRUE when penalty information is detectable in the play text.
penalty_play_text character Penalty-related substring extracted from the play text.
lead_wp_before2 numeric Win probability two plays ahead (lead 2 of wp_before).
wpa_half_end numeric WPA contribution from the end-of-half adjustment.
wpa_base numeric Base WPA component used to assemble the final wpa value.
wpa_base_nxt numeric WPA base component looking ahead one play.
wpa_change numeric WPA change-of-possession component for the current play.
wpa_change_nxt numeric WPA change-of-possession component for the next play.
wpa_base_ind numeric Indicator selecting the wpa_base path for the current play.
wpa_base_nxt_ind numeric Indicator selecting the wpa_base_nxt path for the next play.
wpa_change_ind numeric Indicator selecting the wpa_change path for the current play.
wpa_change_nxt_ind numeric Indicator selecting the wpa_change_nxt path for the next play.
lead_wp_before numeric Win probability on the next play (lead of wp_before).
lead_pos_team2 character Possession team two plays ahead (lead 2 of pos_team).
row integer Row index within the game grouping (sequencing helper).
drive_event_number numeric Sequential event number within the current drive.
lag_play_type2 character Play type two plays prior (lag 2 of play_type).
lag_play_type3 character Play type three plays prior (lag 3 of play_type).
lag_play_text character Play text from the previous play (lag value).
lag_play_text2 character Play text from two plays prior (lag 2 value).
lead_play_text character Play text from the next play (lead value).
lag_first_by_penalty numeric First-down-by-penalty flag from the previous play (lag value).
lag_first_by_penalty2 numeric First-down-by-penalty flag from two plays prior (lag 2 value).
lag_first_by_yards numeric First-down-by-yards flag from the previous play (lag value).
lag_first_by_yards2 numeric First-down-by-yards flag from two plays prior (lag 2 value).
first_by_penalty numeric Binary flag for a first down earned by penalty on the play.
first_by_yards numeric Binary flag for a first down earned by yards on the play.
play_after_turnover numeric Binary flag indicating the play immediately following a turnover.
lag_change_of_poss numeric change_of_poss from the previous play (lag value).
lag_change_of_pos_team numeric change_of_pos_team from the previous play (lag value).
lag_change_of_pos_team2 numeric change_of_pos_team from two plays prior (lag 2 value).
lag_kickoff_play numeric kickoff_play flag from the previous play (lag value).
lag_punt numeric punt flag from the previous play (lag value).
lag_punt2 numeric punt flag from two plays prior (lag 2 value).
lag_scoring_play numeric scoring_play flag from the previous play (lag value).
lag_turnover_vec numeric turnover_vec flag from the previous play (lag value).
lag_downs_turnover numeric downs_turnover flag from the previous play (lag value).
lag_defense_score_play numeric defense_score_play flag from the previous play (lag value).
lag_score_diff numeric score_diff from the previous play (lag value).
lag_offense_play character offense_play from the previous play (lag value).
lead_offense_play character offense_play from the next play (lead value).
lead_offense_play2 character offense_play from two plays ahead (lead 2 value).
lag_pos_score_diff numeric pos_score_diff from the previous play (lag value).
lag_off_timeouts numeric offense_timeouts from the previous play (lag value).
lag_def_timeouts numeric defense_timeouts from the previous play (lag value).
lag_TimeSecsRem2 numeric TimeSecsRem from two plays prior (lag 2 value).
lag_TimeSecsRem numeric TimeSecsRem from the previous play (lag value).
lead_TimeSecsRem numeric TimeSecsRem from the next play (lead value).
lead_TimeSecsRem2 numeric TimeSecsRem from two plays ahead (lead 2 value).
lag_yards_to_goal2 integer yards_to_goal from two plays prior (lag 2 value).
lag_yards_to_goal integer yards_to_goal from the previous play (lag value).
lead_yards_to_goal numeric yards_to_goal from the next play (lead value).
lead_yards_to_goal2 integer yards_to_goal from two plays ahead (lead 2 value).
lag_down2 integer Down number two plays prior (lag 2 value).
lag_down integer Down number from the previous play (lag value).
lead_down numeric Down number on the next play (lead value).
lead_down2 numeric Down number two plays ahead (lead 2 value).
lead_distance numeric Distance to go on the next play (lead value).
lead_distance2 integer Distance to go two plays ahead (lead 2 value).
lead_play_type2 character Play type two plays ahead (lead 2 value).
lead_play_type3 character Play type three plays ahead (lead 3 value).
lag_ep_before3 numeric ep_before from three plays prior (lag 3 value).
lag_ep_before2 numeric ep_before from two plays prior (lag 2 value).
lag_ep_before numeric ep_before from the previous play (lag value).
lead_ep_before numeric ep_before on the next play (lead value).
lead_ep_before2 numeric ep_before two plays ahead (lead 2 value).
lag_ep_after numeric ep_after from the previous play (lag value).
lag_ep_after2 numeric ep_after from two plays prior (lag 2 value).
lag_ep_after3 numeric ep_after from three plays prior (lag 3 value).
lead_ep_after numeric ep_after on the next play (lead value).
lead_ep_after2 numeric ep_after two plays ahead (lead 2 value).
play_number integer CFBD-supplied play number within the game.
wallclock character ISO 8601 wall-clock timestamp from CFBD for the play.
provider character Sportsbook provider used for spread/over_under joined onto the play.
spread numeric Pre-game point spread from the selected provider.
formatted_spread character Human-readable formatted spread string from the betting provider.
over_under numeric Pre-game over/under total from the selected provider.
drive_is_home_offense logical TRUE when the home team is on offense for the drive.
drive_start_offense_score integer Offense score at the start of the drive.
drive_start_defense_score integer Defense score at the start of the drive.
drive_end_offense_score integer Offense score at the end of the drive.
drive_end_defense_score integer Defense score at the end of the drive.
play numeric Binary flag indicating the row is a counted play (excludes end markers/timeouts/penalties).
event numeric Binary flag indicating the row is a counted game event (excludes end markers).
game_event_number numeric Sequential event number within the game.
game_row_number integer Row index within the game grouping.
half_play numeric Binary flag indicating a counted play within the half.
half_event numeric Binary flag indicating a counted event within the half.
half_event_number numeric Sequential event number within the half.
half_row_number integer Row index within the half grouping.
lag_distance3 integer distance three plays prior (lag 3 value).
lag_distance2 integer distance two plays prior (lag 2 value).
lag_distance integer distance from the previous play (lag value).
lag_yards_gained3 integer yards_gained three plays prior (lag 3 value).
lag_yards_gained2 integer yards_gained two plays prior (lag 2 value).
lag_yards_gained integer yards_gained from the previous play (lag value).
lead_yards_gained integer yards_gained on the next play (lead value).
lead_yards_gained2 integer yards_gained two plays ahead (lead 2 value).
lag_play_text3 character Play text from three plays prior (lag 3 value).
lead_play_text2 character Play text from two plays ahead (lead 2 value).
lead_play_text3 character Play text from three plays ahead (lead 3 value).
pos_unit character Possession-team unit label (offense or special teams).
def_pos_unit character Defensive possession-team unit label (defense or special teams).
lag_change_of_poss2 numeric change_of_poss from two plays prior (lag 2 value).
lag_change_of_poss3 numeric change_of_poss from three plays prior (lag 3 value).
lag_change_of_pos_team3 numeric change_of_pos_team from three plays prior (lag 3 value).
lag_kickoff_play2 numeric kickoff_play flag from two plays prior (lag 2 value).
lag_kickoff_play3 numeric kickoff_play flag from three plays prior (lag 3 value).
lag_punt3 numeric punt flag from three plays prior (lag 3 value).
lag_scoring_play2 numeric scoring_play flag from two plays prior (lag 2 value).
lag_scoring_play3 numeric scoring_play flag from three plays prior (lag 3 value).
lag_turnover_vec2 numeric turnover_vec flag from two plays prior (lag 2 value).
lag_turnover_vec3 numeric turnover_vec flag from three plays prior (lag 3 value).
lag_downs_turnover2 numeric downs_turnover flag from two plays prior (lag 2 value).
lag_downs_turnover3 numeric downs_turnover flag from three plays prior (lag 3 value).
drive_play numeric Binary flag indicating a counted play within the drive.
drive_event numeric Binary flag indicating a counted event within the drive.
lag_first_by_penalty3 numeric first_by_penalty flag from three plays prior (lag 3 value).
lag_first_by_yards3 numeric first_by_yards flag from three plays prior (lag 3 value).

See Also

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

Get college football play-by-play data — modular EPA/WPA pipeline (v2)

Description

Returns CFBD play-by-play data with optional Expected Points Added (EPA) and Win Probability Added (WPA) modeling. The modular successor to cfbd_pbp_data(): a thin orchestrator over the shared EPA/WPA engine (.run_epa_wpa()), the canonical play-type taxonomy (.pbp_play_types()), and the canonical output schema (.pbp_output_order). Side-by-side with the legacy entry point until the equivalence harness proves the new path matches.

Usage

cfbd_pbp_data_v2(
  year,
  season_type = "regular",
  week = 1,
  team = NULL,
  play_type = NULL,
  epa_wpa = FALSE,
  output = "default"
)

Arguments

year

(Numeric required): Season year (e.g. 2024).
Minimum value accepted: 2001

season_type

(Character): Season type — "regular" (default), "postseason", "both", "allstar", "spring_regular", "spring_postseason".

week

(Numeric): Week number.

team

(Character): Optional team filter (e.g. "Texas").

play_type

(Character): Optional play-type filter (see cfbd_play_type_df).

epa_wpa

(Logical): When TRUE, run the EPA/WPA pipeline and return the modeled frame; when FALSE (default) return the raw plays + drives + betting join.

output

(Character): controls the modeled-output column set when epa_wpa = TRUE. Ignored when epa_wpa = FALSE. Defaults to "default". Must be one of:

  • "default" (recommended) – drops pipeline lag/lead intermediates, redundant alternates (sack_vec, turnover_indicator, kick_play, missing_yard_flag), and drive-result aliases (drive_result2, drive_result_detailed_flag, lag_drive_result_detailed, lead_drive_result_detailed, lag_new_drive_pts). Keeps orig_play_type and pts_scored (they carry useful per-play information distinct from the canonical columns) and the per-branch WPA scratchpad (wpa_base/wpa_change etc.). ~75 columns lighter than "full" with no loss of information that isn't trivially rebuildable.

  • "lean" – everything "default" drops, plus the WPA computation scratchpad. For dashboards / leaderboards / game logs.

  • "full" – legacy behavior, drops only the player-name aliases. For sequential modeling that consumes pre-computed lag/lead shifts or the per-branch WPA decomposition.

Value

A cfbfastR_data tibble. The epa_wpa = TRUE output matches the legacy cfbd_pbp_data() pipeline-canonical column set on every column it carries; the output argument controls which intermediate columns are retained. Documented bug-fix sites are listed in the package vignette.

See Also

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

Examples


  x <- try(cfbd_pbp_data_v2(
    year = 2024, week = 1, season_type = "regular",
    epa_wpa = TRUE, output = "default"
  ))

CFBD Play-by-Play (v2 Modular EPA/WPA Pipeline) Overview

Description

Details

The v2 entry point is a thin wrapper around .run_epa_wpa() – the shared engine that powers both the modular (v2) and legacy paths. The output = "default" / "lean" / "full" tier argument selects which intermediate columns survive the final select: "default" drops pipeline lag/lead intermediates and redundant alternates, "lean" additionally drops the per-branch WPA scratchpad, and "full" is the legacy column set (drops only player-name aliases). The equivalence-harness allow-list is intentionally permissive about lag/lead intermediates and per-branch WPA scratchpad columns because those are mechanically rebuildable from the surviving canonical columns; the harness only enforces equality on user-facing values.

Get college football play-by-play data — modular EPA/WPA pipeline (v2)

cfbd_pbp_data_v2(
  year = 2024, week = 1, season_type = "regular",
  epa_wpa = TRUE, output = "default"
)

CFBD Plays Endpoint Overview

Description

College football plays data

Details

Pull first 3 weeks of 2020 season using cfbd_plays()

 year_vector <- 2020
 week_vector <- 1:3
 weekly_year_df <- expand.grid(year = year_vector, week = week_vector)
 tictoc::tic()
 year_split <- split(weekly_year_df, weekly_year_df$year)
 for (i in 1:length(year_split)) {
   i <- 1

   progressr::with_progress({
      year_split[[i]] <- year_split[[i]] |>
         dplyr::mutate(
            pbp = purrr::map2(
                .x = year,
                .y = week,
                cfbd_plays,
                season_type = "both"
            )
         )
     Sys.sleep(1)
   })
 }

 tictoc::toc()
 year_split <- lapply(year_split, function(x) {
     x |> tidyr::unnest(pbp, names_repair = "minimal")
 })

 all_years <- dplyr::bind_rows(year_split)
 glimpse(all_years)

Gets player info associated by play

cfbd_play_stats_player(game_id = 401110722)

Gets CFBD play stat types

cfbd_play_stats_types()

Gets CFBD play types

cfbd_play_types()

Gets player info associated by play

Description

Gets player info associated by play

Usage

cfbd_play_stats_player(
  year = NULL,
  week = NULL,
  team = NULL,
  game_id = NULL,
  athlete_id = NULL,
  stat_type_id = NULL,
  season_type = "both",
  conference = NULL
)

Arguments

year

(Integer optional): Year, 4 digit format (YYYY)
Minimum value accepted: 2012

week

(Integer optional): Week - values from 1-15, 1-14 for seasons pre-playoff, i.e. 2013 or earlier

team

(String optional): D-I Team

game_id

(Integer optional): Game ID filter for querying a single game Can be found using the cfbd_game_info() function

athlete_id

(Integer optional): Athlete ID filter for querying a single athlete Can be found using the cfbd_player_info() function.

stat_type_id

(Integer optional): Stat Type ID filter for querying a single stat type Can be found using the cfbd_play_stats_types() function

season_type

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

conference

(String optional): Conference abbreviation filter.

Value

cfbd_play_stats_player() - A data frame with 66 variables:

col_name types description
play_id character CFBD play identifier the stat is attributed to.
game_id integer CFBD game identifier the play belongs to.
season integer Four-digit season year (e.g. 2024).
week integer Season week number (1-15 regular season; 1 = postseason/bowl week).
opponent character Full name of the opponent on the play.
team_score integer Offense team score at the time of the play.
opponent_score integer Defense / opponent team score at the time of the play.
drive_id character CFBD drive identifier the play belongs to.
period integer Game period / quarter of the play (1-4 regulation, 5+ overtime).
yards_to_goal integer Distance in yards from the offense's spot to the opponent's goal line (0-100).
down integer Down of the play (1-4).
distance integer Yards to gain for a first down (or to the goal line in goal-to-go situations).
reception_player_id character CFBD athlete_id of the receiver credited with a reception.
reception_player character Name of the receiver credited with a reception.
reception_yds integer Reception yards gained on the play.
completion_player_id character CFBD athlete_id of the passer credited with a completion.
completion_player character Name of the passer credited with a completion.
completion_yds integer Passing yards gained on the completion.
rush_player_id character CFBD athlete_id of the player credited with a rush attempt.
rush_player character Name of the player credited with a rush attempt.
rush_yds integer Rushing yards gained on the play.
interception_player_id character CFBD athlete_id of the defender credited with an interception.
interception_player character Name of the defender credited with an interception.
interception_stat integer Interception stat value reported by CFBD (typically 1 per INT).
interception_thrown_player_id character CFBD athlete_id of the passer charged with the interception.
interception_thrown_player character Name of the passer charged with the interception.
interception_thrown_stat integer Interception-thrown stat value reported by CFBD (typically 1 per INT thrown).
touchdown_player_id character CFBD athlete_id of the player credited with the touchdown.
touchdown_player character Name of the player credited with the touchdown.
touchdown_stat integer Touchdown stat value reported by CFBD (typically 1 per TD scored).
incompletion_player_id character CFBD athlete_id of the targeted receiver on an incompletion.
incompletion_player character Name of the targeted receiver on an incompletion.
incompletion_stat integer Incompletion stat value reported by CFBD (typically 1 per incompletion).
target_player_id character CFBD athlete_id of the targeted receiver on a pass.
target_player character Name of the targeted receiver on a pass.
target_stat integer Target stat value reported by CFBD (typically 1 per target).
fumble_recovered_player_id logical CFBD athlete_id of the player recovering the fumble.
fumble_recovered_player logical Name of the player recovering the fumble.
fumble_recovered_stat logical Fumble-recovered stat value reported by CFBD (typically 1 per recovery).
fumble_forced_player_id logical CFBD athlete_id of the defender credited with forcing the fumble.
fumble_forced_player logical Name of the defender credited with forcing the fumble.
fumble_forced_stat logical Fumble-forced stat value reported by CFBD (typically 1 per forced fumble).
fumble_player_id logical CFBD athlete_id of the player who fumbled.
fumble_player logical Name of the player who fumbled.
fumble_stat logical Fumble stat value reported by CFBD (typically 1 per fumble).
sack_player_id character Comma-separated CFBD athlete_id(s) of the sacking defender(s).
sack_player character Comma-separated name(s) of the sacking defender(s).
sack_stat integer Sack stat value reported by CFBD (sack credit can be split between defenders).
sack_taken_player_id character CFBD athlete_id of the QB charged with taking the sack.
sack_taken_player character Name of the QB charged with taking the sack.
sack_taken_stat integer Sack-taken stat value reported by CFBD (typically 1 per sack taken).
pass_breakup_player_id logical CFBD athlete_id of the defender credited with the pass breakup (PBU).
pass_breakup_player logical Name of the defender credited with the pass breakup (PBU).
pass_breakup_stat logical Pass breakup (PBU) stat value reported by CFBD (typically 1 per PBU).
field_goal_attempt_player_id character CFBD athlete_id of the kicker attempting the field goal.
field_goal_attempt_player character Name of the kicker attempting the field goal.
field_goal_attempt_stat integer Field goal attempt distance in yards reported by CFBD.
field_goal_made_player_id character CFBD athlete_id of the kicker on a made field goal.
field_goal_made_player character Name of the kicker on a made field goal.
field_goal_made_stat integer Made-field-goal distance in yards reported by CFBD.
field_goal_missed_player_id character CFBD athlete_id of the kicker on a missed field goal.
field_goal_missed_player character Name of the kicker on a missed field goal.
field_goal_missed_stat integer Missed-field-goal distance in yards reported by CFBD.
field_goal_blocked_player_id character CFBD athlete_id of the defender credited with blocking the field goal.
field_goal_blocked_player character Name of the defender credited with blocking the field goal.
field_goal_blocked_stat integer Blocked-field-goal distance in yards reported by CFBD.

See Also

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

Examples


  try(cfbd_play_stats_player(game_id = 401628414))
  try(cfbd_play_stats_player(year = 2025, week = 1))

Get college football mapping for play stats types

Description

Get college football mapping for play stats types

Usage

cfbd_play_stats_types()

Value

cfbd_play_stats_types() - A data frame with 25 rows and 2 variables:

col_name types description
play_stat_type_id integer CFBD play stat type identifier (used as a filter in cfbd_play_stats_player()).
name character Human-readable name of the play stat type (e.g. "Reception", "Sack", "Touchdown").

See Also

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

Examples


  try(cfbd_play_stats_types())

Get college football mapping for play types

Description

Get college football mapping for play types

Usage

cfbd_play_types()

Value

cfbd_play_types() - A data frame with 48 rows and 3 variables:

col_name types description
play_type_id integer CFBD play type identifier (matches play_type IDs in cfbd_plays()).
text character Human-readable play type description (e.g. "Rush", "Pass Reception", "Field Goal").
abbreviation character Short play type abbreviation used as the play_type filter argument in API calls.

See Also

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

Examples


  try(cfbd_play_types())

Player information lookup

Description

Player information lookup

Usage

cfbd_player_info(search_term, position = NULL, team = NULL, year = NULL)

Arguments

search_term

(String required): Search term for the player you are trying to look up

position

(string optional): Position of the player you are searching for. Position Group - options include:

  • Offense: QB, RB, FB, TE, OL, G, OT, C, WR

  • Defense: DB, CB, S, LB, DE, DT, NT, DL

  • Special Teams: K, P, LS, PK

team

(String optional): Team - Select a valid team, D1 football

year

(Integer optional): Year, 4 digit format (YYYY). If left NULL, API default will only provide results for most recent year of final rosters: 2020
Minimum value accepted: 2004

Value

cfbd_player_info() - A data frame with 12 variables:

col_name types description
athlete_id character Unique CFBD player identifier.
team character Team of the player.
name character Player full name.
first_name character Player first name.
last_name character Player last name.
weight integer Player weight in pounds.
height integer Player height in inches.
jersey integer Player jersey number.
position character Player position abbreviation (e.g. QB, RB, WR).
home_town character Player home town.
team_color character Player team primary color (hex code).
team_color_secondary character Player team secondary color (hex code).

See Also

Other CFBD Players: cfbd_player_returning(), cfbd_player_usage()

Examples


  try(cfbd_player_info(search_term = "James", position = "DB", team = "Florida State", year = 2017))

  try(cfbd_player_info(search_term = "Lawrence", team = "Clemson"))

Get player returning production

Description

Get player returning production

Usage

cfbd_player_returning(
  year = most_recent_cfb_season(),
  team = NULL,
  conference = NULL
)

Arguments

year

(Integer required, default most recent season): Year, 4 digit format (YYYY).
Minimum value accepted: 2014

team

(String optional): Team - Select a valid team, D1 football

conference

(String optional): Conference abbreviation - Select a valid FBS conference Conference abbreviations P5: ACC, B12, B1G, SEC, PAC Conference abbreviations G5 and FBS Independents: CUSA, MAC, MWC, Ind, SBC, AAC

Value

cfbd_player_returning() - A data frame with 15 variables:

col_name types description
season integer Four-digit season year for returning production.
team character Team name.
conference character Conference of team.
total_ppa numeric Total predicted points added (PPA) returning.
total_passing_ppa numeric Total passing predicted points added returning.
total_receiving_ppa numeric Total receiving predicted points added returning.
total_rushing_ppa numeric Total rushing predicted points added returning.
percent_ppa numeric Percentage of prior year's predicted points added returning.
percent_passing_ppa numeric Percentage of prior year's passing predicted points added returning.
percent_receiving_ppa numeric Percentage of prior year's receiving predicted points added returning.
percent_rushing_ppa numeric Percentage of prior year's rushing predicted points added returning.
usage numeric Share of prior year's overall offensive usage returning.
passing_usage numeric Share of prior year's passing usage returning.
receiving_usage numeric Share of prior year's receiving usage returning.
rushing_usage numeric Share of prior year's rushing usage returning.

See Also

Other CFBD Players: cfbd_player_info(), cfbd_player_usage()

Examples


   try(cfbd_player_returning(year = 2019, team = "Florida State"))

Get a player season overview

Description

Get a player season overview Season overview for a single player.

Usage

cfbd_player_season_overview(year, athlete_id, proxy = NULL)

Arguments

year

(Integer required): Season, 4 digits (YYYY).
Minimum value accepted: 2004

athlete_id

(Integer required): Player identifier.

proxy

(List optional): Per-call proxy override passed to get_req(). NULL (default) falls back to getOption("cfbfastR.proxy") and then the ⁠http(s)_proxy⁠ environment variables, so a caller can override the shared setting for one endpoint.

Value

cfbd_player_season_overview() - A tibble with 31 columns:

col_name types description
season integer Four-digit season year.
id character Record identifier.
name character Display name.
position character Listed position.
team character Team name.
conference character Conference name.
games integer Games played in the season.
usage_overall numeric Share of team plays the player was involved in.
usage_pass numeric Share of team pass plays involving the player.
usage_rush numeric Share of team rush plays involving the player.
usage_first_down numeric Usage share on first down.
usage_second_down numeric Usage share on second down.
usage_third_down numeric Usage share on third down.
usage_standard_downs numeric Usage share on standard downs.
usage_passing_downs numeric Usage share on passing downs.
ppa_average_all numeric Ppa average all.
ppa_average_pass numeric Ppa average pass.
ppa_average_rush numeric Ppa average rush.
ppa_average_first_down numeric Ppa average first down.
ppa_average_second_down numeric Ppa average second down.
ppa_average_third_down numeric Ppa average third down.
ppa_average_standard_downs numeric Ppa average standard downs.
ppa_average_passing_downs numeric Ppa average passing downs.
ppa_total_all numeric Ppa total all.
ppa_total_pass numeric Ppa total pass.
ppa_total_rush numeric Ppa total rush.
ppa_total_first_down numeric Ppa total first down.
ppa_total_second_down numeric Ppa total second down.
ppa_total_third_down numeric Ppa total third down.
ppa_total_standard_downs numeric Ppa total standard downs.
ppa_total_passing_downs numeric Ppa total passing downs.

Examples


  try(cfbd_player_season_overview(year = 2024, athlete_id = 4429105))

Get player usage metrics

Description

Get player usage metrics

Usage

cfbd_player_usage(
  year = most_recent_cfb_season(),
  team = NULL,
  conference = NULL,
  position = NULL,
  athlete_id = NULL,
  excl_garbage_time = FALSE
)

Arguments

year

(Integer required, default most recent season): Year, 4 digit format (YYYY).
Minimum value accepted: 2013

team

(String optional): Team - Select a valid team, D1 football

conference

(String optional): Conference abbreviation - Select a valid FBS conference Conference abbreviations P5: ACC, B12, B1G, SEC, PAC Conference abbreviations G5 and FBS Independents: CUSA, MAC, MWC, Ind, SBC, AAC

position

(string optional): Position of the player you are searching for. Position Group - options include:

  • Offense: QB, RB, FB, TE, OL, G, OT, C, WR

  • Defense: DB, CB, S, LB, DE, DT, NT, DL

  • Special Teams: K, P, LS, PK

athlete_id

(Integer optional): Athlete ID filter for querying a single athlete Can be found using the cfbd_player_info() function.

excl_garbage_time

(Logical default FALSE): Select whether to exclude Garbage Time (TRUE/FALSE)

Value

cfbd_player_usage() - A data frame with 14 variables:

col_name types description
season integer Four-digit season year for player usage.
athlete_id character Unique CFBD athlete identifier.
name character Athlete full name.
position character Athlete position abbreviation (e.g. QB, RB, WR).
team character Team name.
conference character Conference of team.
usg_overall numeric Player share of overall offensive usage.
usg_pass numeric Player share of team passing usage.
usg_rush numeric Player share of team rushing usage.
usg_1st_down numeric Player share of team usage on first downs.
usg_2nd_down numeric Player share of team usage on second downs.
usg_3rd_down numeric Player share of team usage on third downs.
usg_standard_downs numeric Player share of team usage on standard downs.
usg_passing_downs numeric Player share of team usage on passing downs.

See Also

Other CFBD Players: cfbd_player_info(), cfbd_player_returning()

Examples


  try(cfbd_player_usage(year = 2019, position = "WR", team = "Florida State"))

CFBD Players Endpoint Overview

Description

Details

Player information lookup

 cfbd_player_info(search_term = "James", position = "DB", team = "Florida State", year = 2017)

 cfbd_player_info(search_term = "Lawrence", team = "Clemson")

Get player returning production

 cfbd_player_returning(year = 2019, team = "Florida State")

Get player usage metrics

 cfbd_player_usage(year = 2019, position = "WR", team = "Florida State")

Get a player season overview

cfbd_player_season_overview(year = 2024, athlete_id = 4429105)

CFBD Playoffs Endpoint Overview

Description

Get College Football Playoff bracket information

Description

Get College Football Playoff bracket information Returns the College Football Playoff bracket for a season.

Usage

cfbd_playoffs_cfp(year, proxy = NULL)

Arguments

year

(Integer required): Season, 4 digits (YYYY).
Minimum value accepted: 2014

proxy

(List optional): Per-call proxy override passed to get_req(). NULL (default) falls back to getOption("cfbfastR.proxy") and then the ⁠http(s)_proxy⁠ environment variables, so a caller can override the shared setting for one endpoint.

Value

cfbd_playoffs_cfp() - A tibble with 46 columns:

col_name types description
round_code character Playoff round code (first_round, quarterfinal, semifinal, championship).
round_name character Human-readable playoff round name.
round_order integer Ordinal position of the round in the bracket.
id integer Record identifier.
bracket_slot character Bracket position code for the matchup (e.g. FR1, QF2).
round character Playoff round code.
round_name_2 character Round name 2.
round_order_2 integer Round order 2.
matchup_order integer Ordinal position of the matchup within its round.
start_date character Scheduled start date and time (ISO 8601).
bowl_name character Bowl or site name hosting the matchup.
game_id integer Referencing game id.
game_start_date character Game scheduled start date and time (ISO 8601).
game_completed logical Game completion flag.
game_home_points integer Game home points.
game_away_points integer Game away points.
game_venue_id integer Game referencing venue id.
game_venue character Game venue name.
game_home_team_id integer Home team identifier.
game_home_team_school character Home team school name.
game_home_team_conference character Home team conference.
game_away_team_id integer Away team identifier.
game_away_team_school character Away team school name.
game_away_team_conference character Away team conference.
advances_to_matchup_id integer Next-matchup matchup id.
advances_to_bracket_slot character Next-matchup bracket position code for the matchup (e.g. FR1, QF2).
advances_to_position integer Next-matchup bracket position.
slot1_position integer First bracket slot bracket position.
slot1_seed integer First bracket slot seed.
slot1_team_id integer First bracket slot referencing team id.
slot1_school character First bracket slot school name.
slot1_conference character First bracket slot conference.
slot2_position integer Second bracket slot bracket position.
slot2_seed integer Second bracket slot seed.
slot2_team_id integer Second bracket slot referencing team id.
slot2_school character Second bracket slot school name.
slot2_conference character Second bracket slot conference.
season integer Four-digit season year.
competition character Competition identifier (e.g. cfp).
format character Bracket format descriptor.
team_count integer Number of teams in the field.
status character Status of the competition.
champion_id integer Referencing team id of the champion.
champion_school character School name of the champion.
champion_conference character Conference of the champion.
advances_to logical Advances to.

See Also

Other CFBD Playoff Functions: cfbd_playoffs_cfp_games(), cfbd_playoffs_cfp_participants()

Examples


  try(cfbd_playoffs_cfp(year = 2024))

Get College Football Playoff games

Description

Get College Football Playoff games Returns the games played in the College Football Playoff for a season.

Usage

cfbd_playoffs_cfp_games(year, round = NULL, proxy = NULL)

Arguments

year

(Integer required): Season, 4 digits (YYYY).
Minimum value accepted: 2014

round

(String optional): first_round, quarterfinal, semifinal or championship.

proxy

(List optional): Per-call proxy override passed to get_req(). NULL (default) falls back to getOption("cfbfastR.proxy") and then the ⁠http(s)_proxy⁠ environment variables, so a caller can override the shared setting for one endpoint.

Value

cfbd_playoffs_cfp_games() - A tibble with 34 columns:

col_name types description
id integer Record identifier.
bracket_slot character Bracket position code for the matchup (e.g. FR1, QF2).
round character Playoff round code.
round_name character Human-readable playoff round name.
round_order integer Ordinal position of the round in the bracket.
matchup_order integer Ordinal position of the matchup within its round.
start_date character Scheduled start date and time (ISO 8601).
bowl_name character Bowl or site name hosting the matchup.
game_id integer Referencing game id.
game_start_date character Game scheduled start date and time (ISO 8601).
game_completed logical Game completion flag.
game_home_points integer Game home points.
game_away_points integer Game away points.
game_venue_id integer Game referencing venue id.
game_venue character Game venue name.
game_home_team_id integer Home team identifier.
game_home_team_school character Home team school name.
game_home_team_conference character Home team conference.
game_away_team_id integer Away team identifier.
game_away_team_school character Away team school name.
game_away_team_conference character Away team conference.
advances_to_matchup_id integer Next-matchup matchup id.
advances_to_bracket_slot character Next-matchup bracket position code for the matchup (e.g. FR1, QF2).
advances_to_position integer Next-matchup bracket position.
slot1_position integer First bracket slot bracket position.
slot1_seed integer First bracket slot seed.
slot1_team_id integer First bracket slot referencing team id.
slot1_school character First bracket slot school name.
slot1_conference character First bracket slot conference.
slot2_position integer Second bracket slot bracket position.
slot2_seed integer Second bracket slot seed.
slot2_team_id integer Second bracket slot referencing team id.
slot2_school character Second bracket slot school name.
slot2_conference character Second bracket slot conference.

See Also

Other CFBD Playoff Functions: cfbd_playoffs_cfp(), cfbd_playoffs_cfp_participants()

Examples


  try(cfbd_playoffs_cfp_games(year = 2024))

Get College Football Playoff participants

Description

Get College Football Playoff participants Returns the teams that participated in the College Football Playoff for a season.

Usage

cfbd_playoffs_cfp_participants(year, proxy = NULL)

Arguments

year

(Integer required): Season, 4 digits (YYYY).
Minimum value accepted: 2014

proxy

(List optional): Per-call proxy override passed to get_req(). NULL (default) falls back to getOption("cfbfastR.proxy") and then the ⁠http(s)_proxy⁠ environment variables, so a caller can override the shared setting for one endpoint.

Value

cfbd_playoffs_cfp_participants() - A tibble with 12 columns:

col_name types description
committee_rank integer Selection-committee rank.
seed integer Seed in the bracket.
bid_type character How the team qualified (automatic or at_large).
qualification_reason character Stated reason the team qualified.
conference_champion logical TRUE if the team won its conference.
qualifying_conference character Conference through which the team qualified.
first_round_bye logical TRUE if the team received a first-round bye.
outcome character Outcome of the team's playoff run.
eliminated_round character Round in which the team was eliminated.
team_id integer Referencing team id.
team_school character School name of the team.
team_conference character Conference the team belongs to.

See Also

Other CFBD Playoff Functions: cfbd_playoffs_cfp(), cfbd_playoffs_cfp_games()

Examples


  try(cfbd_playoffs_cfp_participants(year = 2024))

Get college football play-by-play data.

Description

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)
Minimum value accepted: 2001

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_name types description
play_id character CFBD play identifier (unique within a game when combined with game_id).
offense character Full name of the offense (team in possession) on the play.
offense_conference character Conference name of the offense (e.g. "SEC", "ACC").
defense character Full name of the defense on the play.
defense_conference character Conference name of the defense (e.g. "SEC", "ACC").
home character Full home team name for the game.
away character Full away team name for the game.
offense_score integer Offense's score after the play (points).
defense_score integer Defense's score after the play (points).
game_id integer CFBD game identifier the play belongs to.
drive_id character CFBD drive identifier the play belongs to.
drive_number integer Sequential drive number within the game (1-indexed).
play_number integer Sequential play number within the game (1-indexed).
period integer Game period / quarter (1-4 regulation, 5+ overtime).
offense_timeouts integer Timeouts remaining for the offense at the end of the play.
defense_timeouts integer Timeouts remaining for the defense at the end of the play.
yard_line integer Field-position yard line at the start of the play (0-50 scale from the offense's side).
yards_to_goal integer Distance in yards from the offense's spot to the opponent's goal line (0-100).
down integer Down of the play (1-4).
distance integer Yards to gain for a first down (or to the goal line in goal-to-go situations).
scoring logical TRUE when the play results in a score (TD, FG, safety, two-point conversion).
yards_gained integer Net yards gained by the offense on the play.
play_type character CFBD categorical label for the play type (see cfbd_play_types()).
play_text character Free-form text description of the play from the CFBD feed.
ppa character Predicted Points Added (CFBD's CFB-EPA analogue) for the play.
clock_minutes integer Minutes remaining on the game clock at the start of the play.
clock_seconds integer Seconds 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


  try(cfbd_plays(year = 2021, week = 1))

Get historical Coaches and AP poll data

Description

Get historical Coaches and AP poll data

Usage

cfbd_rankings(
  year,
  week = NULL,
  season_type = "both",
  poll = NULL,
  latest = NULL,
  final = NULL
)

Arguments

year

(Integer required): Year, 4 digit format (YYYY)
Minimum value accepted: 1936

week

(Integer optional): Week, values from 1-15, 1-14 for seasons pre-playoff (i.e. 2013 or earlier)

season_type

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

poll

(String optional): Poll filter. CFBD accepts only "cfp" here – any other value returns HTTP 400, so it is validated rather than passed through. Omit it to get every poll (AP, Coaches, CFP) and filter the result frame.

latest

(Logical optional): Return the latest College Football Playoff snapshot, preferring the one marked final. Requires poll = "cfp" and cannot be combined with final.

final

(Logical optional): Return the College Football Playoff snapshot marked final. Requires poll = "cfp" and cannot be combined with latest.

Value

cfbd_rankings() - A data frame with 9 variables:

col_name types description
season integer Four-digit year of the season (e.g. 2019).
season_type character CFBD season type: "regular", "postseason", "both", or "allstar".
week integer Week number within the season (1-15 regular, 1 for postseason).
poll character Poll name (e.g. "AP Top 25", "Coaches Poll", "Playoff Committee Rankings").
rank integer Position of the school within the poll for the given week (1 = top-ranked).
school character Full school/team name as reported by the poll (e.g. "Georgia").
conference character Conference affiliation of the ranked school (e.g. "SEC", "ACC").
first_place_votes integer Number of first-place votes the school received in this poll week.
points integer Total points accumulated by the school in the poll's weighted voting.

See Also

Other CFBD Ratings and Rankings: cfbd_ratings_elo(), cfbd_ratings_fpi(), cfbd_ratings_sp(), cfbd_ratings_sp_conference(), cfbd_ratings_srs()

Examples


  try(cfbd_rankings(year = 2019, week = 12))

  try(cfbd_rankings(year = 2018, week = 14))

  try(cfbd_rankings(year = 2013, season_type = "postseason"))

CFBD Ratings and Rankings Endpoints Overview

Description

Get historical Coaches and AP poll data

cfbd_rankings(year = 2019, week = 12)

cfbd_rankings(year = 2018, week = 14)

cfbd_rankings(year = 2013, season_type = "postseason")

Get SP historical rating data

At least one of year or team must be specified for the function to run 

cfbd_ratings_sp(year = 2018)

cfbd_ratings_sp(team = "Texas A&M")

cfbd_ratings_sp(year = 2019, team = "Texas")

Get conference level SP historical rating data

cfbd_ratings_sp_conference(year = 2019)

cfbd_ratings_sp_conference(year = 2012, conference = "SEC")

cfbd_ratings_sp_conference(year = 2016, conference = "ACC")

Get SRS historical rating data

At least one of year or team must be specified for the function to run 

cfbd_ratings_srs(year = 2019, team = "Texas")

cfbd_ratings_srs(year = 2018, conference = "SEC")

Get Elo historical rating data

Acquire the CFBD calculated elo ratings data by team, year, week, and conference 

cfbd_ratings_elo(year = 2019, team = "Texas")

cfbd_ratings_elo(year = 2018, conference = "SEC")

Get FPI historical rating data

Acquire the ESPN FPI ratings data by team, year, and conference 

cfbd_ratings_fpi(year = 2019, team = "Texas")

cfbd_ratings_fpi(year = 2018, conference = "SEC")

Get core team ratings

cfbd_ratings_core(year = 2024)

Get expanded SRS ratings

cfbd_ratings_srs_expanded(year = 2024)

Get core team ratings

Description

Get core team ratings CFBD's core team rating measures.

Usage

cfbd_ratings_core(year = NULL, team = NULL, conference = NULL, proxy = NULL)

Arguments

year

(Integer optional): Season, 4 digits (YYYY).
Minimum value accepted: 2016

team

(String optional): Team filter.

conference

(String optional): Conference abbreviation filter.

proxy

(List optional): Per-call proxy override passed to get_req(). NULL (default) falls back to getOption("cfbfastR.proxy") and then the ⁠http(s)_proxy⁠ environment variables, so a caller can override the shared setting for one endpoint.

Value

cfbd_ratings_core() - A tibble with 11 columns:

col_name types description
year integer Four-digit season year.
through_season_type character Season type the rating is computed through.
through_week integer Week the rating is computed through.
team character Team name.
conference character Conference name.
overall numeric Overall rating.
offense numeric Offensive rating.
defense numeric Defensive rating.
offense_plays integer Offensive plays underlying the rating.
defense_plays integer Defensive plays underlying the rating.
model_version character Version of the rating model that produced the row.

See Also

Other CFBD Ratings Functions: cfbd_ratings_srs_expanded()

Examples


  try(cfbd_ratings_core(year = 2024))

Get Elo historical rating data

Description

Acquire the CFBD calculated elo ratings data by team, year, week, and conference

Usage

cfbd_ratings_elo(
  year = NULL,
  week = NULL,
  season_type = "both",
  team = NULL,
  conference = NULL
)

Arguments

year

(Integer optional): Year, 4 digit format (YYYY)
Minimum value accepted: 1890

week

(Integer optional): Maximum Week of ratings.

season_type

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

team

(String optional): D-I Team

conference

(String optional): Conference abbreviation - Elo information by conference Conference abbreviations P5: ACC, B12, B1G, SEC, PAC Conference abbreviations G5 and FBS Independents: CUSA, MAC, MWC, Ind, SBC, AAC

Value

cfbd_ratings_elo() - A data frame with 4 variables:

col_name types description
year integer Four-digit season year (e.g. 2019).
team character Full team name (e.g. "Texas").
conference character Conference affiliation for the team in the given season.
elo numeric CFBD-calculated Elo rating for the team as of the requested week.

See Also

Other CFBD Ratings and Rankings: cfbd_rankings(), cfbd_ratings_fpi(), cfbd_ratings_sp(), cfbd_ratings_sp_conference(), cfbd_ratings_srs()

Examples


  try(cfbd_ratings_elo(year = 2019, team = "Texas"))

  try(cfbd_ratings_elo(year = 2018, conference = "SEC"))

Get Football Power Index (FPI) historical rating data

Description

Acquire the ESPN calculated FPI ratings data by team, year, and conference

Usage

cfbd_ratings_fpi(year = NULL, team = NULL, conference = NULL)

Arguments

year

(Integer optional): Year, 4 digit format (YYYY). Required if team not provided
Minimum value accepted: 2005

team

(String optional): D-I Team. Required if year not provided

conference

(String optional): Conference name - select a valid FBS conference Conference names P5: ACC, Big 12, Big Ten, SEC, Pac-12 Conference names G5 and FBS Independents: Conference USA, Mid-American, Mountain West, FBS Independents, American Athletic

Value

cfbd_ratings_fpi() - A data frame with 14 variables:

col_name types description
year integer Four-digit season year (e.g. 2019).
team character Full team name (e.g. "Texas").
conference character Conference affiliation for the team in the given season.
fpi numeric ESPN Football Power Index rating (projected scoring margin vs. average team).
resume_ranks_strength_of_record integer National rank of the team's strength of record (1 = best).
resume_ranks_fpi integer National rank of the team's FPI rating (1 = best).
resume_ranks_average_win_probability integer National rank of the team's average single-game win probability (1 = best).
resume_ranks_strength_of_schedule integer National rank of the team's schedule strength to date (1 = toughest).
resume_ranks_remaining_strength_of_schedule integer National rank of the team's remaining schedule strength (1 = toughest).
resume_ranks_game_control integer National rank of the team's average in-game win probability (1 = best).
efficiencies_overall numeric Overall FPI efficiency rating (combined offense, defense, and special teams).
efficiencies_offense numeric FPI offensive efficiency rating.
efficiencies_defense numeric FPI defensive efficiency rating.
efficiencies_special_teams numeric FPI special teams efficiency rating.

See Also

Other CFBD Ratings and Rankings: cfbd_rankings(), cfbd_ratings_elo(), cfbd_ratings_sp(), cfbd_ratings_sp_conference(), cfbd_ratings_srs()

Examples


  try(cfbd_ratings_fpi(year = 2019, team = "Texas"))

  try(cfbd_ratings_fpi(year = 2018, conference = "SEC"))

Get SP historical rating data

Description

At least one of year or team must be specified for the function to run

Usage

cfbd_ratings_sp(year = NULL, team = NULL)

Arguments

year

(Integer optional): Year, 4 digit format (YYYY). Required if team not provided
Minimum value accepted: 1970

team

(String optional): D-I Team. Required if year not provided

Value

cfbd_ratings_sp() - A data frame with 26 variables:

col_name types description
year integer Four-digit season year (e.g. 2018).
team character Full team name (e.g. "Texas A&M").
conference character Conference affiliation for the team in the given season.
rating numeric Overall SP+ rating (Bill Connelly methodology, in points per game).
ranking integer National rank of the team's overall SP+ rating (1 = best).
second_order_wins numeric Estimated wins based on opponent-adjusted efficiency rather than actual results.
sos numeric Strength of schedule rating (SP+ scale).
offense_ranking integer National rank of the team's offensive SP+ rating (1 = best).
offense_rating numeric Offensive SP+ rating (points per drive adjusted for opponent).
offense_success numeric Offensive success rate component of SP+ (probability 0-1).
offense_explosiveness numeric Offensive explosiveness component of SP+ (EqPts/play on successful plays).
offense_rushing numeric Offensive rushing efficiency component of SP+.
offense_passing numeric Offensive passing efficiency component of SP+.
offense_standard_downs numeric Offensive SP+ on standard downs (1st, 2nd & <= 7, 3rd/4th & <= 4).
offense_passing_downs numeric Offensive SP+ on passing downs (2nd & >= 8, 3rd/4th & >= 5).
offense_run_rate numeric Share of offensive snaps that are designed runs (0-1).
offense_pace numeric Average seconds per play for the offense.
defense_ranking integer National rank of the team's defensive SP+ rating (1 = best).
defense_rating numeric Defensive SP+ rating (points per drive allowed, opponent-adjusted).
defense_success numeric Defensive success rate component of SP+ (probability 0-1).
defense_explosiveness numeric Defensive explosiveness component of SP+ (EqPts/play allowed on successes).
defense_rushing numeric Defensive rushing efficiency component of SP+.
defense_passing numeric Defensive passing efficiency component of SP+.
defense_standard_downs numeric Defensive SP+ on standard downs.
defense_passing_downs numeric Defensive SP+ on passing downs.
defense_havoc_total numeric Total havoc rate (TFLs + PBUs + forced fumbles divided by plays).
defense_havoc_front_seven numeric Havoc rate contributed by the defensive front seven.
defense_havoc_db numeric Havoc rate contributed by defensive backs.
special_teams_rating numeric Special teams SP+ rating (points per game).

See Also

Other CFBD Ratings and Rankings: cfbd_rankings(), cfbd_ratings_elo(), cfbd_ratings_fpi(), cfbd_ratings_sp_conference(), cfbd_ratings_srs()

Examples


  try(cfbd_ratings_sp(year = 2018))

  try(cfbd_ratings_sp(team = "Texas A&M"))

  try(cfbd_ratings_sp(year = 2019, team = "Texas"))

Get conference level SP historical rating data

Description

Get conference level SP historical rating data

Usage

cfbd_ratings_sp_conference(year = NULL, conference = NULL, division = NULL)

Arguments

year

(Integer optional): Year, 4 digit format (YYYY)
Minimum value accepted: 1970

conference

(String optional): Conference abbreviation - S&P+ information by conference Conference abbreviations P5: ACC, B12, B1G, SEC, PAC Conference abbreviations G5 and FBS Independents: CUSA, MAC, MWC, Ind, SBC, AAC

division

(String optional): Division/classification filter – one of fbs, fcs, ii, ii/iii, iii. Sent to CFBD as classification.

Value

cfbd_ratings_sp_conference() - A data frame with 25 variables:

col_name types description
year integer Season of the conference rating.
conference character Conference name.
rating numeric Conference SP+ rating.
second_order_wins logical Second-order wins for the conference - Not available for recent seasons.
sos logical Strength of schedule for the conference - Not available for recent seasons.
offense_rating numeric Overall offense rating for the conference.
offense_success logical Offense success rating for the conference - Not available for recent seasons.
offense_explosiveness logical Offense explosiveness rating for the conference - Not available for recent seasons.
offense_rushing logical Offense rushing rating for the conference - Not available for recent seasons.
offense_passing logical Offense passing rating for the conference - Not available for recent seasons.
offense_standard_downs logical Offense standard downs rating for the conference - Not available for recent seasons.
offense_passing_downs logical Offensive passing downs rating for the conference - Not available for recent seasons.
offense_run_rate logical Offense rushing rate for the conference - Not available for recent seasons.
offense_pace logical Offense pace factor for the conference - Not available for recent seasons.
defense_ranking integer Overall defense ranking for the conference.
defense_rating numeric Overall defense rating for the conference.
defense_success logical Defense success rating for the conference - Not available for recent seasons.
defense_explosiveness logical Defense explosiveness rating for the conference - Not available for recent seasons.
defense_rushing logical Defense rushing rating for the conference - Not available for recent seasons.
defense_passing logical Defense passing rating for the conference - Not available for recent seasons.
defense_standard_downs logical Defense standard downs rating for the conference - Not available for recent seasons.
defense_passing_downs logical Defensive passing downs rating for the conference - Not available for recent seasons.
defense_havoc_total logical Total defensive havoc rate for the conference - Not available for recent seasons.
defense_havoc_front_seven logical Defense havoc rate from front 7 players for the conference - Not available for recent seasons.
defense_havoc_db logical Defense havoc rate from defensive backs for the conference - Not available for recent seasons.
special_teams_rating numeric Special teams rating for the conference.

See Also

Other CFBD Ratings and Rankings: cfbd_rankings(), cfbd_ratings_elo(), cfbd_ratings_fpi(), cfbd_ratings_sp(), cfbd_ratings_srs()

Examples


  try(cfbd_ratings_sp_conference(year = 2019))

  try(cfbd_ratings_sp_conference(year = 2012, conference = "SEC"))

  try(cfbd_ratings_sp_conference(year = 2016, conference = "ACC"))

Get SRS historical rating data

Description

At least one of year or team must be specified for the function to run

Usage

cfbd_ratings_srs(year = NULL, team = NULL, conference = NULL)

Arguments

year

(Integer optional): Year, 4 digit format (YYYY). Required if team not provided
Minimum value accepted: 1897

team

(String optional): D-I Team. Required if year not provided

conference

(String optional): Conference abbreviation - SRS information by conference Conference abbreviations P5: ACC, B12, B1G, SEC, PAC Conference abbreviations G5 and FBS Independents: CUSA, MAC, MWC, Ind, SBC, AAC

Value

cfbd_ratings_srs() - A data frame with 6 variables:

col_name types description
year integer Season of the SRS rating.
team character Team name.
conference character Conference of the team.
division character Division in the conference for the team.
rating numeric Simple Rating System (SRS) rating.
ranking integer Simple Rating System ranking within the group returned.

See Also

Other CFBD Ratings and Rankings: cfbd_rankings(), cfbd_ratings_elo(), cfbd_ratings_fpi(), cfbd_ratings_sp(), cfbd_ratings_sp_conference()

Examples


  try(cfbd_ratings_srs(year = 2019, team = "Texas"))

  try(cfbd_ratings_srs(year = 2018, conference = "SEC"))

Get expanded SRS ratings

Description

Get expanded SRS ratings Simple Rating System with its component breakdown.

Usage

cfbd_ratings_srs_expanded(
  year = NULL,
  team = NULL,
  conference = NULL,
  division = NULL,
  proxy = NULL
)

Arguments

year

(Integer optional): Season, 4 digits (YYYY).
Minimum value accepted: 2003

team

(String optional): Team filter.

conference

(String optional): Conference abbreviation filter.

division

(String optional): Division/classification filter – fbs, fcs, ii, ii/iii, iii.

proxy

(List optional): Per-call proxy override passed to get_req(). NULL (default) falls back to getOption("cfbfastR.proxy") and then the ⁠http(s)_proxy⁠ environment variables, so a caller can override the shared setting for one endpoint.

Value

cfbd_ratings_srs_expanded() - A tibble with 7 columns:

col_name types description
year integer Four-digit season year.
team character Team name.
classification character Division classification (fbs, fcs, ii, ii/iii, iii).
conference character Conference name.
division logical Division.
ranking integer Rank by rating.
rating numeric Rating value.

See Also

Other CFBD Ratings Functions: cfbd_ratings_core()

Examples


  try(cfbd_ratings_srs_expanded(year = 2024))

CFB Recruiting Endpoint Overview

Description

Get player recruiting rankings

Get college football player recruiting information for a single year with filters available for team, recruit type, state and position. 

cfbd_recruiting_player(2018, team = "Texas")

cfbd_recruiting_player(2016, recruit_type = "JUCO")

cfbd_recruiting_player(2020, recruit_type = "HighSchool", position = "OT", state = "FL")

Get college football position group recruiting information.

cfbd_recruiting_position(2018, team = "Texas")

cfbd_recruiting_position(2016, 2020, team = "Virginia")

cfbd_recruiting_position(2015, 2020, conference = "SEC")

Get college football recruiting team rankings information.

cfbd_recruiting_team(2018, team = "Texas")

cfbd_recruiting_team(2016, team = "Virginia")

cfbd_recruiting_team(2016, team = "Texas A&M")

cfbd_recruiting_team(2011)

Details

Gets CFB team recruiting ranks with filters available for year and team. At least one of year or team must be specified for the function to run

If you would like CFB recruiting information for players, please see the cfbd_recruiting_player() function

If you would like to get CFB recruiting information based on position groups during a time period for all FBS teams, please see the cfbd_recruiting_position() function.

cfbd_recruiting_player() - At least one of year or team must be specified for the function to run

cfbd_recruiting_position() - If only start_year is provided, function will get CFB recruiting information based on position groups during that year for all FBS teams.

Get player recruiting rankings

Description

Get player recruiting rankings

Usage

cfbd_recruiting_player(
  year = NULL,
  team = NULL,
  recruit_type = "HighSchool",
  state = NULL,
  position = NULL,
  division = NULL
)

Arguments

year

(Integer optional): Year, 4 digit format (YYYY) Required if team not provided
Minimum value accepted: 2000

team

(String optional): D-I Team. Required if year not provided

recruit_type

(String optional): default API return is 'HighSchool', other options include 'JUCO' or 'PrepSchool' - For position group information

state

(String optional): Two letter State abbreviation

position

(String optional): Position Group - options include:

  • Offense: 'PRO', 'DUAL', 'RB', 'FB', 'TE', 'OT', 'OG', 'OC', 'WR'

  • Defense: 'CB', 'S', 'OLB', 'ILB', 'WDE', 'SDE', 'DT'

  • Special Teams: 'K', 'P'

division

(String optional): Division/classification filter – one of fbs, fcs, ii, ii/iii, iii. Sent to CFBD as classification.

Value

cfbd_recruiting_player() - A data frame with 19 variables:

col_name types description
id integer 247Sports referencing id for the recruit.
athlete_id integer CFBD athlete referencing id linking to player tables.
recruit_type character Recruit class: High School, Prep School, or Junior College.
year integer Recruiting class year (four-digit season).
ranking integer Recruit national ranking within the class.
name character Recruit full name.
school character High school, prep school, or JUCO program the recruit attended.
committed_to character College program the recruit is committed to.
position character Recruit position abbreviation (e.g. QB, WR, OT).
height numeric Recruit height in inches.
weight integer Recruit weight in pounds.
stars integer Recruit star rating on the 247Sports scale (2-5).
rating numeric 247Sports composite rating for the recruit.
city character Hometown city of the recruit.
state_province character Hometown state or province of the recruit.
country character Hometown country of the recruit.
hometown_info_latitude character Latitude of the recruit's hometown.
hometown_info_longitude character Longitude of the recruit's hometown.
hometown_info_fips_code character FIPS code of the recruit's hometown.

See Also

Other CFBD Recruiting: cfbd_recruiting_position(), cfbd_recruiting_team(), cfbd_recruiting_transfer_portal()

Examples


  try(cfbd_recruiting_player(2018, team = "Texas"))

  try(cfbd_recruiting_player(2016, recruit_type = "JUCO"))

  try(cfbd_recruiting_player(2020, recruit_type = "HighSchool", position = "OT", state = "FL"))

Get college football position group recruiting information.

Description

Get college football position group recruiting information.

Usage

cfbd_recruiting_position(
  start_year = NULL,
  end_year = NULL,
  team = NULL,
  conference = NULL,
  recruit_type = NULL
)

Arguments

start_year

(Integer optional): Start Year, 4 digit format (YYYY). Note: 2000 is the minimum value

end_year

(Integer optional): End Year, 4 digit format (YYYY). Note: 2020 is the maximum value currently

team

(String optional): Team - Select a valid team, D-I football

conference

(String optional): Conference abbreviation - Select a valid FBS conference Conference abbreviations P5: ACC, B12, B1G, SEC, PAC Conference abbreviations G5 and FBS Independents: CUSA, MAC, MWC, Ind, SBC, AAC

recruit_type

(String optional): HighSchool, PrepSchool or JUCO.

Value

cfbd_recruiting_position() - A data frame with 7 variables:

col_name types description
team character Recruiting team (school) name.
conference character Conference affiliation of the recruiting team.
position_group character Position group of the recruits (e.g. Offensive Line, Defensive Back).
avg_rating numeric Average 247Sports composite rating of recruits in the position group.
total_rating numeric Sum of the 247Sports composite ratings of recruits in the group.
commits integer Number of commits in the position group.
avg_stars numeric Average star rating of recruits in the position group.

See Also

Other CFBD Recruiting: cfbd_recruiting_player(), cfbd_recruiting_team(), cfbd_recruiting_transfer_portal()

Examples


  try(cfbd_recruiting_position(2018, team = "Texas"))

  try(cfbd_recruiting_position(2016, 2020, team = "Virginia"))

  try(cfbd_recruiting_position(2015, 2020, conference = "SEC"))

Get college football recruiting team rankings information.

Description

Get college football recruiting team rankings information.

Usage

cfbd_recruiting_team(year = NULL, team = NULL)

Arguments

year

(Integer optional): Recruiting Class Year, 4 digit format (YYYY) Required if team not provided.
Minimum value accepted: 2000

team

(String optional): Team - Select a valid team, D1 football. Required if year not provided.

Value

cfbd_recruiting_team() - A data frame with 4 variables:

col_name types description
year integer Recruiting class year (four-digit season).
rank integer National team recruiting rank for the class.
team character Recruiting team (school) name.
points character Team talent points totaled across the recruiting class.

See Also

Other CFBD Recruiting: cfbd_recruiting_player(), cfbd_recruiting_position(), cfbd_recruiting_transfer_portal()

Examples


  try(cfbd_recruiting_team(2018, team = "Texas"))

  try(cfbd_recruiting_team(2016, team = "Virginia"))

  try(cfbd_recruiting_team(2016, team = "Texas A&M"))

  try(cfbd_recruiting_team(2011))

Get Transfer Portal Data

Description

Get Transfer Portal Data

Usage

cfbd_recruiting_transfer_portal(year)

Arguments

year

(Integer required): Year of the offseason (2021 would return transfer portal data starting from the end of the 2020 season), 4 digit format (YYYY).
Minimum value accepted: 2021

Value

cfbd_recruiting_transfer_portal() - A data frame with 10 variables:

col_name types description
season integer Season of the transfer (four-digit year).
first_name character Player's first name.
last_name character Player's last name.
position character Player position abbreviation (e.g. QB, WR, OT).
origin character Original (transferring-from) team.
destination character New (transferring-to) team.
transfer_date character Date the transfer was reported (parsed downstream to POSIXct).
rating character Player's 247Sports transfer rating.
stars integer Player's 247Sports star rating (2-5).
eligibilty character Player's eligibility status at time of transfer.

See Also

Other CFBD Recruiting: cfbd_recruiting_player(), cfbd_recruiting_position(), cfbd_recruiting_team()

Examples


  try(cfbd_recruiting_transfer_portal(year = 2021))

CFBD Stats Endpoint Overview

Description

Details

Get game advanced stats

cfbd_stats_game_advanced(year = 2018, week = 12, team = "Texas A&M")

cfbd_stats_game_advanced(2019, team = "LSU")

cfbd_stats_game_advanced(2013, team = "Florida State")

Get season advanced statistics by team

cfbd_stats_season_advanced(2019, team = "LSU")

Get season statistics by player

cfbd_stats_season_player(year = 2018, conference = "B12", start_week = 1, end_week = 7)

cfbd_stats_season_player(2019, team = "LSU", category = "passing")

cfbd_stats_season_player(2013, team = "Florida State", category = "passing")

Get season statistics by team

cfbd_stats_season_team(year = 2018, conference = "B12", start_week = 1, end_week = 8)

cfbd_stats_season_team(2019, team = "LSU")

cfbd_stats_season_team(2013, team = "Florida State")

Get stats categories

This function identifies all Stats Categories identified in the regular stats endpoint. 

cfbd_stats_categories()

Get player success rates by season

cfbd_stats_player_success(year = 2024, team = "Georgia")

Get player success rates by game

cfbd_stats_player_success_game(year = 2024, week = 5)

Get stats categories

Description

This function identifies all Stats Categories identified in the regular stats endpoint.

Usage

cfbd_stats_categories()

Value

cfbd_stats_categories() A data frame with 1 variable:

col_name types description
category character CFBD stats category name (e.g. passing, rushing, defensive).

See Also

Other CFBD Stats: cfbd_stats_game_advanced(), cfbd_stats_game_havoc(), cfbd_stats_season_advanced(), cfbd_stats_season_player(), cfbd_stats_season_team()

Examples


   try(cfbd_stats_categories())

Get game advanced stats

Description

Get game advanced stats

Usage

cfbd_stats_game_advanced(
  year,
  week = NULL,
  team = NULL,
  opponent = NULL,
  excl_garbage_time = FALSE,
  season_type = "both"
)

Arguments

year

(Integer required): Year, 4 digit format(YYYY)
Minimum value accepted: 2001

week

(Integer optional): Week - values from 1-15, 1-14 for seasons pre-playoff (i.e. 2013 or earlier)

team

(String optional): D-I Team

opponent

(String optional): Opponent D-I Team

excl_garbage_time

(Logical default FALSE): Select whether to exclude Garbage Time (TRUE/FALSE)

season_type

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

Value

cfbd_stats_game_advanced() - A data frame with 60 variables:

col_name types description
game_id integer Referencing game id.
season integer Season of the game.
week integer Game week of the season.
team character Team name.
opponent character Opponent team name.
off_plays integer Offense plays in the game.
off_drives integer Offense drives in the game.
off_ppa double Offense predicted points added (PPA).
off_total_ppa double Offense total predicted points added (PPA).
off_success_rate double Offense success rate.
off_explosiveness double Offense explosiveness rate.
off_power_success double Offense power success rate.
off_stuff_rate double Opponent stuff rate.
off_line_yds double Offensive line yards.
off_line_yds_total integer Offensive line yards total.
off_second_lvl_yds double Offense second-level yards.
off_second_lvl_yds_total integer Offense second-level yards total.
off_open_field_yds integer Offense open field yards.
off_open_field_yds_total integer Offense open field yards total.
off_standard_downs_ppa double Offense standard downs predicted points added (PPA).
off_standard_downs_success_rate double Offense standard downs success rate.
off_standard_downs_explosiveness double Offense standard downs explosiveness rate.
off_passing_downs_ppa double Offense passing downs predicted points added (PPA).
off_passing_downs_success_rate double Offense passing downs success rate.
off_passing_downs_explosiveness double Offense passing downs explosiveness rate.
off_rushing_plays_ppa double Offense rushing plays predicted points added (PPA).
off_rushing_plays_total_ppa double Offense rushing plays total predicted points added (PPA).
off_rushing_plays_success_rate double Offense rushing plays success rate.
off_rushing_plays_explosiveness double Offense rushing plays explosiveness rate.
off_passing_plays_ppa double Offense passing plays predicted points added (PPA).
off_passing_plays_total_ppa double Offense passing plays total predicted points added (PPA).
off_passing_plays_success_rate double Offense passing plays success rate.
off_passing_plays_explosiveness double Offense passing plays explosiveness rate.
def_plays integer Defense plays in the game.
def_drives integer Defense drives in the game.
def_ppa double Defense predicted points added (PPA).
def_total_ppa double Defense total predicted points added (PPA).
def_success_rate double Defense success rate.
def_explosiveness double Defense explosiveness rate.
def_power_success double Defense power success rate.
def_stuff_rate double Opponent stuff rate.
def_line_yds double Offensive line yards.
def_line_yds_total integer Offensive line yards total.
def_second_lvl_yds double Defense second-level yards.
def_second_lvl_yds_total integer Defense second-level yards total.
def_open_field_yds integer Defense open field yards.
def_open_field_yds_total integer Defense open field yards total.
def_standard_downs_ppa double Defense standard downs predicted points added (PPA).
def_standard_downs_success_rate double Defense standard downs success rate.
def_standard_downs_explosiveness double Defense standard downs explosiveness rate.
def_passing_downs_ppa double Defense passing downs predicted points added (PPA).
def_passing_downs_success_rate double Defense passing downs success rate.
def_passing_downs_explosiveness double Defense passing downs explosiveness rate.
def_rushing_plays_ppa double Defense rushing plays predicted points added (PPA).
def_rushing_plays_total_ppa double Defense rushing plays total predicted points added (PPA).
def_rushing_plays_success_rate double Defense rushing plays success rate.
def_rushing_plays_explosiveness double Defense rushing plays explosiveness rate.
def_passing_plays_ppa double Defense passing plays predicted points added (PPA).
def_passing_plays_total_ppa double Defense passing plays total predicted points added (PPA).
def_passing_plays_success_rate double Defense passing plays success rate.
def_passing_plays_explosiveness double Defense passing plays explosiveness rate.

See Also

Other CFBD Stats: cfbd_stats_categories(), cfbd_stats_game_havoc(), cfbd_stats_season_advanced(), cfbd_stats_season_player(), cfbd_stats_season_team()

Examples


   try(cfbd_stats_game_advanced(year = 2018, week = 12, team = "Texas A&M"))

   try(cfbd_stats_game_advanced(2019, team = "LSU"))

   try(cfbd_stats_game_advanced(2013, team = "Florida State"))

Get game havoc statistics

Description

Get havoc-rate statistics aggregated by game. Havoc measures defensive disruption – the share of plays that end in a tackle for loss, a forced fumble, a pass defensed, or an interception – split into front-seven and defensive-back contributions. Each row carries both the team's own defensive havoc (⁠def_*⁠) and the havoc the team's offense allowed (⁠off_*⁠) in that game.

Usage

cfbd_stats_game_havoc(
  year = NULL,
  team = NULL,
  week = NULL,
  opponent = NULL,
  season_type = NULL
)

Arguments

year

(Integer optional): Year, 4 digit format (YYYY). Required if team is not specified.
Minimum value accepted: 2004

team

(String optional): D-I Team. Required if year is not specified.

week

(Integer optional): Week - values from 1-15, 1-14 for seasons pre-playoff (i.e. 2013 or earlier).

opponent

(String optional): Opponent D-I Team.

season_type

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

Value

cfbd_stats_game_havoc() - A data frame with 22 variables:

col_name types description
game_id integer Referencing game id.
season integer Season of the game.
season_type character Season type of the game.
week integer Game week of the season.
team character Team name.
conference character Conference of the team.
opponent character Opponent team name.
opponent_conference character Conference of the opponent.
off_total_plays integer Offense plays in the game.
off_total_havoc_events integer Total havoc events allowed by the offense.
off_front_seven_havoc_events integer Front-seven havoc events allowed by the offense.
off_db_havoc_events integer Defensive-back havoc events allowed by the offense.
off_havoc_rate double Total havoc rate allowed by the offense.
off_front_seven_havoc_rate double Front-seven havoc rate allowed by the offense.
off_db_havoc_rate double Defensive-back havoc rate allowed by the offense.
def_total_plays integer Defense plays in the game.
def_total_havoc_events integer Total havoc events created by the defense.
def_front_seven_havoc_events integer Front-seven havoc events created by the defense.
def_db_havoc_events integer Defensive-back havoc events created by the defense.
def_havoc_rate double Total havoc rate created by the defense.
def_front_seven_havoc_rate double Front-seven havoc rate created by the defense.
def_db_havoc_rate double Defensive-back havoc rate created by the defense.

See Also

Other CFBD Stats: cfbd_stats_categories(), cfbd_stats_game_advanced(), cfbd_stats_season_advanced(), cfbd_stats_season_player(), cfbd_stats_season_team()

Examples


   try(cfbd_stats_game_havoc(year = 2023, team = "Georgia"))

   try(cfbd_stats_game_havoc(2022, week = 1))

Get player success rates by season

Description

Get player success rates by season Season-level player success-rate metrics.

Usage

cfbd_stats_player_success(
  year = NULL,
  conference = NULL,
  team = NULL,
  athlete_id = NULL,
  season_type = "regular",
  start_week = NULL,
  end_week = NULL,
  threshold = NULL,
  excl_garbage_time = NULL,
  proxy = NULL
)

Arguments

year

(Integer optional): Season, 4 digits (YYYY).
Minimum value accepted: 2013

conference

(String optional): Conference abbreviation filter.

team

(String optional): Team filter.

athlete_id

(Integer optional): Player identifier.

season_type

(String optional): Season type – regular, postseason, both, allstar, spring_regular or spring_postseason.

start_week

(Integer optional): First week to include.

end_week

(Integer optional): Last week to include.

threshold

(Numeric optional): Minimum success-rate threshold.

excl_garbage_time

(Logical optional): Exclude garbage-time plays.

proxy

(List optional): Per-call proxy override passed to get_req(). NULL (default) falls back to getOption("cfbfastR.proxy") and then the ⁠http(s)_proxy⁠ environment variables, so a caller can override the shared setting for one endpoint.

Value

cfbd_stats_player_success() - A tibble with 12 columns:

col_name types description
season integer Four-digit season year.
id character Record identifier.
name character Display name.
position character Position.
team character Team name.
conference character Conference name.
passing_plays integer Passing plays.
passing_successes integer Passing successes.
passing_success_rate numeric Passing success rate.
rushing_plays integer Rushing plays.
rushing_successes integer Rushing successes.
rushing_success_rate numeric Rushing success rate.

See Also

Other CFBD Stats Functions: cfbd_stats_player_success_game()

Examples


  try(cfbd_stats_player_success(year = 2024, team = "Georgia"))

Get player success rates by game

Description

Get player success rates by game Game-level player success-rate metrics.

Usage

cfbd_stats_player_success_game(
  year,
  week = NULL,
  season_type = "regular",
  conference = NULL,
  team = NULL,
  athlete_id = NULL,
  threshold = NULL,
  excl_garbage_time = NULL,
  proxy = NULL
)

Arguments

year

(Integer required): Season, 4 digits (YYYY).
Minimum value accepted: 2013

week

(Integer optional): Week filter.

season_type

(String optional): Season type – regular, postseason, both, allstar, spring_regular or spring_postseason.

conference

(String optional): Conference abbreviation filter.

team

(String optional): Team filter.

athlete_id

(Integer optional): Player identifier.

threshold

(Numeric optional): Minimum success-rate threshold.

excl_garbage_time

(Logical optional): Exclude garbage-time plays.

proxy

(List optional): Per-call proxy override passed to get_req(). NULL (default) falls back to getOption("cfbfastR.proxy") and then the ⁠http(s)_proxy⁠ environment variables, so a caller can override the shared setting for one endpoint.

Value

cfbd_stats_player_success_game() - A tibble with 16 columns:

col_name types description
season integer Four-digit season year.
season_type character Season type (regular, postseason, both, allstar, spring_regular, spring_postseason).
week integer Week of the season.
game_id integer Referencing game id.
id character Record identifier.
name character Display name.
position character Position.
team character Team name.
conference character Conference name.
opponent character Opponent.
passing_plays integer Passing plays.
passing_successes integer Passing successes.
passing_success_rate numeric Passing success rate.
rushing_plays integer Rushing plays.
rushing_successes integer Rushing successes.
rushing_success_rate numeric Rushing success rate.

See Also

Other CFBD Stats Functions: cfbd_stats_player_success()

Examples


  try(cfbd_stats_player_success_game(year = 2024, week = 5))

Get season advanced statistics by team

Description

Get season advanced statistics by team

Usage

cfbd_stats_season_advanced(
  year,
  team = NULL,
  excl_garbage_time = FALSE,
  start_week = NULL,
  end_week = NULL,
  division = NULL
)

Arguments

year

(Integer required): Year, 4 digit format (YYYY)
Minimum value accepted: 2001

team

(String optional): D-I Team

excl_garbage_time

(Logical default FALSE): Select whether to exclude Garbage Time (TRUE/FALSE)

start_week

(Integer optional): Starting Week - values range from 1-15, 1-14 for seasons pre-playoff, i.e. 2013 or earlier

end_week

(Integer optional): Ending Week - values range from 1-15, 1-14 for seasons pre-playoff, i.e. 2013 or earlier

division

(String optional): Division/classification filter – one of fbs, fcs, ii, ii/iii, iii. Sent to CFBD as classification.

Value

cfbd_stats_season_advanced() - A data frame with 82 variables:

col_name types description
season integer Season of the statistics.
team character Team name.
conference character Conference of the team.
off_plays integer Offense plays in the game.
off_drives integer Offense drives in the game.
off_ppa double Offense predicted points added (PPA).
off_total_ppa double Offense total predicted points added (PPA).
off_success_rate double Offense success rate.
off_explosiveness double Offense explosiveness rate.
off_power_success double Offense power success rate.
off_stuff_rate double Offense rushing stuff rate.
off_line_yds double Offensive line yards.
off_line_yds_total integer Offensive line yards total.
off_second_lvl_yds double Offense second-level yards.
off_second_lvl_yds_total integer Offense second-level yards total.
off_open_field_yds integer Offense open field yards.
off_open_field_yds_total integer Offense open field yards total.
off_total_opportunities integer Offense opportunities.
off_pts_per_opp double Offense points per scoring opportunity.
off_field_pos_avg_start double Offense starting average field position.
off_field_pos_avg_predicted_points double Offense starting average field position predicted points (PP).
off_havoc_total double Offense havoc rate total.
off_havoc_front_seven double Offense front-7 havoc rate.
off_havoc_db double Offense defensive back havoc rate.
off_standard_downs_rate double Offense standard downs rate.
off_standard_downs_ppa double Offense standard downs predicted points added (PPA).
off_standard_downs_success_rate double Offense standard downs success rate.
off_standard_downs_explosiveness double Offense standard downs explosiveness rate.
off_passing_downs_rate double Offense passing downs rate.
off_passing_downs_ppa double Offense passing downs predicted points added (PPA).
off_passing_downs_success_rate double Offense passing downs success rate.
off_passing_downs_explosiveness double Offense passing downs explosiveness rate.
off_rushing_plays_rate double Offense rushing plays rate.
off_rushing_plays_ppa double Offense rushing plays predicted points added (PPA).
off_rushing_plays_total_ppa double Offense rushing plays total predicted points added (PPA).
off_rushing_plays_success_rate double Offense rushing plays success rate.
off_rushing_plays_explosiveness double Offense rushing plays explosiveness rate.
off_passing_plays_rate double Offense passing plays rate.
off_passing_plays_ppa double Offense passing plays predicted points added (PPA).
off_passing_plays_total_ppa double Offense passing plays total predicted points added (PPA).
off_passing_plays_success_rate double Offense passing plays success rate.
off_passing_plays_explosiveness double Offense passing plays explosiveness rate.
def_plays integer Defense plays in the game.
def_drives integer Defense drives in the game.
def_ppa double Defense predicted points added (PPA).
def_total_ppa double Defense total predicted points added (PPA).
def_success_rate double Defense success rate.
def_explosiveness double Defense explosiveness rate.
def_power_success double Defense power success rate.
def_stuff_rate double Defense rushing stuff rate.
def_line_yds double Defense Offensive line yards allowed.
def_line_yds_total integer Defense Offensive line yards total allowed.
def_second_lvl_yds double Defense second-level yards.
def_second_lvl_yds_total integer Defense second-level yards total.
def_open_field_yds integer Defense open field yards.
def_open_field_yds_total integer Defense open field yards total.
def_total_opportunities integer Defense opportunities.
def_pts_per_opp double Defense points per scoring opportunity.
def_field_pos_avg_start double Defense starting average field position.
def_field_pos_avg_predicted_points double Defense starting average field position predicted points (PP).
def_havoc_total double Defense havoc rate total.
def_havoc_front_seven double Defense front-7 havoc rate.
def_havoc_db double Defense defensive back havoc rate.
def_standard_downs_rate double Defense standard downs rate.
def_standard_downs_ppa double Defense standard downs predicted points added (PPA).
def_standard_downs_success_rate double Defense standard downs success rate.
def_standard_downs_explosiveness double Defense standard downs explosiveness rate.
def_passing_downs_rate double Defense passing downs rate.
def_passing_downs_ppa double Defense passing downs predicted points added (PPA).
def_passing_downs_success_rate double Defense passing downs success rate.
def_passing_downs_explosiveness double Defense passing downs explosiveness rate.
def_rushing_plays_rate double Defense rushing plays rate.
def_rushing_plays_ppa double Defense rushing plays predicted points added (PPA).
def_rushing_plays_total_ppa double Defense rushing plays total predicted points added (PPA).
def_rushing_plays_success_rate double Defense rushing plays success rate.
def_rushing_plays_explosiveness double Defense rushing plays explosiveness rate.
def_passing_plays_rate double Defense passing plays rate.
def_passing_plays_ppa double Defense passing plays predicted points added (PPA).
def_passing_plays_total_ppa double Defense passing plays total predicted points added (PPA).
def_passing_plays_success_rate double Defense passing plays success rate.
def_passing_plays_explosiveness double Defense passing plays explosiveness rate.

See Also

Other CFBD Stats: cfbd_stats_categories(), cfbd_stats_game_advanced(), cfbd_stats_game_havoc(), cfbd_stats_season_player(), cfbd_stats_season_team()

Examples


   try(cfbd_stats_season_advanced(2019, team = "LSU"))

Get season statistics by player

Description

Get season statistics by player

Usage

cfbd_stats_season_player(
  year,
  season_type = "both",
  team = NULL,
  conference = NULL,
  start_week = NULL,
  end_week = NULL,
  category = NULL
)

Arguments

year

(Integer required): Year, 4 digit format (YYYY)
Minimum value accepted: 2004

season_type

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

team

(String optional): D-I Team

conference

(String optional): Conference abbreviation - Select a valid FBS conference Conference abbreviations P5: ACC, B12, B1G, SEC, PAC Conference abbreviations G5 and FBS Independents: CUSA, MAC, MWC, Ind, SBC, AAC

start_week

(Integer optional): Starting Week - values range from 1-15, 1-14 for seasons pre-playoff, i.e. 2013 or earlier

end_week

(Integer optional): Ending Week - values range from 1-15, 1-14 for seasons pre-playoff, i.e. 2013 or earlier

category

(String optional): Category filter (e.g defensive) Offense: passing, receiving, rushing Defense: defensive, fumbles, interceptions Special Teams: punting, puntReturns, kicking, kickReturns

Value

cfbd_stats_season_player() - A data frame with 59 variables:

col_name types description
year integer Season of the player stats.
team character Team name.
conference character Conference of the team.
athlete_id character Athlete referencing id.
player character Player name.
position character Player position.
passing_completions double Passing completions.
passing_att double Passing attempts.
passing_pct double Passing completion percentage.
passing_yds double Passing yardage.
passing_td double Passing touchdowns.
passing_int double Passing interceptions.
passing_ypa double Passing yards per attempt.
rushing_car double Rushing yards per carry.
rushing_yds double Rushing yards total.
rushing_td double Rushing touchdowns.
rushing_ypc double Rushing yards per carry.
rushing_long double Rushing longest yardage attempt.
receiving_rec double Receiving - pass receptions.
receiving_yds double Receiving - pass reception yards.
receiving_td double Receiving - passing reception touchdowns.
receiving_ypr double Receiving - passing yards per reception.
receiving_long double Receiving - longest pass reception yardage.
fumbles_fum double Fumbles.
fumbles_rec double Fumbles recovered.
fumbles_lost double Fumbles lost.
defensive_solo double Defensive solo tackles.
defensive_tot double Defensive total tackles.
defensive_tfl double Defensive tackles for loss.
defensive_sacks double Defensive sacks.
defensive_qb_hur double Defensive quarterback hurries.
interceptions_int double Interceptions total.
interceptions_yds double Interception return yards.
interceptions_avg double Interception return yards average.
interceptions_td double Interception return touchdowns.
defensive_pd double Defense - passes defensed.
defensive_td double Defense - defensive touchdowns.
kicking_fgm double Kicking - field goals made.
kicking_fga double Kicking - field goals attempted.
kicking_pct double Kicking - field goal percentage.
kicking_xpa double Kicking - extra points attempted.
kicking_xpm double Kicking - extra points made.
kicking_pts double Kicking - total points.
kicking_long double Kicking - longest successful field goal attempt.
kick_returns_no double Kick Returns - number of kick returns.
kick_returns_yds double Kick Returns - kick return yards.
kick_returns_avg double Kick Returns - kick return average yards per return.
kick_returns_td double Kick Returns - kick return touchdowns.
kick_returns_long double Kick Returns - longest kick return yardage.
punting_no double Punting - number of punts.
punting_yds double Punting - punting yardage.
punting_ypp double Punting - yards per punt.
punting_long double Punting - longest punt yardage.
punting_in_20 double Punting - punt downed inside the 20 yard line.
punting_tb double Punting - punt caused a touchback.
punt_returns_no double Punt Returns - number of punt returns.
punt_returns_yds double Punt Returns - punt return yardage total.
punt_returns_avg double Punt Returns - punt return average yards per return.
punt_returns_td double Punt Returns - punt return touchdowns.
punt_returns_long double Punt Returns - longest punt return yardage.

See Also

Other CFBD Stats: cfbd_stats_categories(), cfbd_stats_game_advanced(), cfbd_stats_game_havoc(), cfbd_stats_season_advanced(), cfbd_stats_season_team()

Examples


   try(cfbd_stats_season_player(year = 2018, conference = "B12", start_week = 1, end_week = 7))

   try(cfbd_stats_season_player(2019, team = "LSU", category = "passing"))

   try(cfbd_stats_season_player(2013, team = "Florida State", category = "passing"))

Get season statistics by team

Description

Get season statistics by team

Usage

cfbd_stats_season_team(
  year,
  season_type = "both",
  team = NULL,
  conference = NULL,
  start_week = NULL,
  end_week = NULL,
  division = NULL
)

Arguments

year

(Integer required): Year, 4 digit format (YYYY)
Minimum value accepted: 1869

season_type

(String default: both): Select Season Type - regular, postseason, or both

team

(String optional): D-I Team

conference

(String optional): Conference abbreviation - Select a valid FBS conference Conference abbreviations P5: ACC, B12, B1G, SEC, PAC Conference abbreviations G5 and FBS Independents: CUSA, MAC, MWC, Ind, SBC, AAC

start_week

(Integer optional): Starting Week - values range from 1-15, 1-14 for seasons pre-playoff, i.e. 2013 or earlier

end_week

(Integer optional): Ending Week - values range from 1-15, 1-14 for seasons pre-playoff, i.e. 2013 or earlier

division

(String optional): Division/classification filter – one of fbs, fcs, ii, ii/iii, iii. Sent to CFBD as classification.

Value

cfbd_stats_season_team() - A data frame with 32 variables:

col_name types description
season integer Season for stats.
team character Team name.
conference character Conference of team.
games integer Number of games.
time_of_poss_total integer Time of possession total.
time_of_poss_pg double Time of possession per game.
pass_comps integer Total number of pass completions.
pass_atts integer Total number of pass attempts.
completion_pct double Passing completion percentage.
net_pass_yds integer Net passing yards.
pass_ypa double Passing yards per attempt.
pass_ypr double Passing yards per reception.
pass_TDs integer Passing touchdowns.
interceptions integer Passing interceptions.
int_pct double Interception percentage (of attempts).
rush_atts integer Rushing attempts.
rush_yds integer Rushing yards.
rush_TDs integer Rushing touchdowns.
rush_ypc double Rushing yards per carry.
total_yds integer Rushing total yards.
fumbles_lost integer Fumbles lost.
turnovers integer Turnovers total.
turnovers_pg double Turnovers per game.
first_downs integer Number of first downs.
third_downs integer Number of third downs.
third_down_convs integer Number of third down conversions.
third_conv_rate double Third down conversion rate.
fourth_down_convs integer Fourth down conversions.
fourth_downs integer Fourth downs.
fourth_conv_rate double Fourth down conversion rate.
penalties integer Total number of penalties.
penalty_yds integer Penalty yards total.
penalties_pg double Penalties per game.
penalty_yds_pg double Penalty yardage per game.
yards_per_penalty double Average yards per penalty.
kick_returns integer Number of kick returns.
kick_return_yds integer Total kick return yards.
kick_return_TDs integer Total kick return touchdowns.
kick_return_avg double Kick return yards average.
punt_returns integer Number of punt returns.
punt_return_yds integer Punt return total yards.
punt_return_TDs integer Punt return total touchdowns.
punt_return_avg double Punt return yards average.
passes_intercepted integer Passes intercepted.
passes_intercepted_yds integer Pass interception return yards.
passes_intercepted_TDs integer Pass interception return touchdowns.

See Also

Other CFBD Stats: cfbd_stats_categories(), cfbd_stats_game_advanced(), cfbd_stats_game_havoc(), cfbd_stats_season_advanced(), cfbd_stats_season_player()

Examples


   try(cfbd_stats_season_team(year = 2018, conference = "B12", start_week = 1, end_week = 8))

   try(cfbd_stats_season_team(2019, team = "LSU"))

   try(cfbd_stats_season_team(2013, team = "Florida State"))

Team info lookup

Description

Team info lookup

Usage

cfbd_team_info(
  conference = NULL,
  only_fbs = TRUE,
  year = most_recent_cfb_season()
)

Arguments

conference

(String optional): Conference abbreviation - Select a valid FBS conference Conference abbreviations P5: ACC, B12, B1G, SEC, PAC, Conference abbreviations G5 and FBS Independents: CUSA, MAC, MWC, Ind, SBC, AAC Required if year not provided

only_fbs

(Logical default TRUE): Filter for only returning FBS teams for a given year. If year is left blank while only_fbs is TRUE, then will return values for most current year

year

(Integer optional): Year, 4 digit format (YYYY). Filter for getting a list of major division team for a given year. Required if conference not provided and the year parameter is only supported if only_fbs is TRUE.
Minimum value accepted: 1869

Value

cfbd_team_info() - A data frame with 27 variables:

col_name types description
team_id integer Referencing team id.
school character Team name.
mascot character Team mascot.
abbreviation character Team abbreviations.
alt_name1 character Team alternate name 1 (as it appears in play_text).
alt_name2 character Team alternate name 2 (as it appears in play_text).
alt_name3 character Team alternate name 3 (as it appears in play_text).
conference character Conference of team.
division character Division of team within the conference.
classification character Conference classification (fbs, fcs, ii, iii).
color character Team color (primary).
alt_color character Team color (alternate).
logos character Team logos.
venue_id character Referencing venue id.
venue_name character Stadium name.
city character Team/venue city.
state character Team/venue state.
zip character Team/venue zip code.
country_code character Team/venue country code.
timezone character Team/venue timezone.
latitude numeric Venue latitude.
longitude numeric Venue longitude.
elevation numeric Venue elevation.
capacity integer Venue capacity.
year_constructed integer Year the venue was constructed.
grass logical TRUE/FALSE response on whether the field is grass or not.
dome logical TRUE/FALSE flag for if the venue is a domed stadium.

See Also

Other CFBD Teams: cfbd_team_matchup(), cfbd_team_matchup_records(), cfbd_team_roster(), cfbd_team_talent()

Examples


  try(cfbd_team_info(conference = "SEC"))

  try(cfbd_team_info(conference = "Ind"))

  try(cfbd_team_info(year = 2019))

Get matchup history between two teams.

Description

Get matchup history between two teams.

Usage

cfbd_team_matchup(team1, team2, min_year = NULL, max_year = NULL)

Arguments

team1

(String required): D-I Team 1

team2

(String required): D-I Team 2

min_year

(Integer optional): Minimum of year range, 4 digit format (YYYY)

max_year

(Integer optional): Maximum of year range, 4 digit format (YYYY)

Value

cfbd_team_matchup - A data frame with 11 variables:

col_name types description
season integer Season the game took place.
week integer Game week of the season.
season_type character Season type of the game.
date character Game date.
neutral_site logical TRUE/FALSE flag for if the game took place at a neutral site.
venue character Stadium name.
home_team character Home team of the game.
home_score integer Home score in the game.
away_team character Away team of the game.
away_score integer Away score in the game.
winner character Winner of the matchup.

See Also

Other CFBD Teams: cfbd_team_info(), cfbd_team_matchup_records(), cfbd_team_roster(), cfbd_team_talent()

Examples


  try(cfbd_team_matchup("Texas", "Oklahoma"))

  try(cfbd_team_matchup("Texas A&M", "TCU"))

  try(cfbd_team_matchup("Texas A&M", "TCU", min_year = 1975))

  try(cfbd_team_matchup("Florida State", "Florida", min_year = 1975))

Get matchup history records between two teams.

Description

Get matchup history records between two teams.

Usage

cfbd_team_matchup_records(team1, team2, min_year = NULL, max_year = NULL)

Arguments

team1

(String required): D-I Team 1

team2

(String required): D-I Team 2

min_year

(Integer optional): Minimum of year range, 4 digit format (YYYY)

max_year

(Integer optional): Maximum of year range, 4 digit format (YYYY)

Value

cfbd_team_matchup_records() - A data frame with 7 variables:

col_name types description
start_year integer Span starting year.
end_year integer Span ending year.
team1 character First team selected in query.
team1_wins integer First team wins in series against team2.
team2 character Second team selected in query.
team2_wins integer Second team wins in series against team1.
ties integer Number of ties in the series.

See Also

Other CFBD Teams: cfbd_team_info(), cfbd_team_matchup(), cfbd_team_roster(), cfbd_team_talent()

Examples


  try(cfbd_team_matchup_records("Texas", "Oklahoma"))

  try(cfbd_team_matchup_records("Texas A&M", "TCU", min_year = 1975))

Get team rosters

Description

Get a teams full roster by year. If team is not selected, API returns rosters for every team from the selected year.

Usage

cfbd_team_roster(year, team = NULL, division = NULL)

Arguments

year

(Integer required): Year, 4 digit format (YYYY)
Minimum value accepted: 2004

team

(String optional): Team, select a valid team in D-I football

division

(String optional): Division/classification filter – one of fbs, fcs, ii, ii/iii, iii. Sent to CFBD as classification.

Value

cfbd_team_roster() - A data frame with 16 variables:

col_name types description
athlete_id character Referencing athlete id.
first_name character Athlete first name.
last_name character Athlete last name.
team character Team name.
weight integer Athlete weight (lbs).
height integer Athlete height (inches).
jersey integer Athlete jersey number.
year integer Athlete year.
position character Athlete position.
home_city character Hometown of the athlete.
home_state character Hometown state of the athlete.
home_country character Hometown country of the athlete.
home_latitude numeric Hometown latitude.
home_longitude numeric Hometown longitude.
home_county_fips integer Hometown FIPS code.
headshot_url character Player ESPN headshot url.

See Also

Other CFBD Teams: cfbd_team_info(), cfbd_team_matchup(), cfbd_team_matchup_records(), cfbd_team_talent()

Examples


  try(cfbd_team_roster(year = 2013, team = "Florida State"))

Get composite team talent rankings for all teams in a given year

Description

Extracts team talent composite as sourced from 247 rankings

Usage

cfbd_team_talent(year = most_recent_cfb_season())

Arguments

year

(Integer optional): Year 4 digit format (YYYY)
Minimum value accepted: 2015

Value

cfbd_team_talent() - A data frame with 3 variables:

col_name types description
year integer Season for the talent rating.
school character Team name.
talent numeric Overall roster talent points (as determined by 247Sports).

See Also

Other CFBD Teams: cfbd_team_info(), cfbd_team_matchup(), cfbd_team_matchup_records(), cfbd_team_roster()

Examples


  try(cfbd_team_talent())

  try(cfbd_team_talent(year = 2018))

CFBD Teams Endpoint Overview

Description

Team info lookup

Lists all teams in conference or all D-I teams if conference is left NULL Currently, support is only provided for D-I 

cfbd_team_info(conference = "SEC")

cfbd_team_info(conference = "Ind")

cfbd_team_info(year = 2019)

Get team rosters

It is now possible to access yearly rosters
cfbd_team_roster(year = 2020)
Get a teams full roster by year. If team is not selected, API returns rosters for every team from the selected year.
cfbd_team_roster(year = 2013, team = "Florida State")
Get composite team talent rankings

Extracts team talent composite for all teams in a given year as sourced from 247 rankings 

cfbd_team_talent()

cfbd_team_talent(year = 2018)
Get matchup history between two teams.
cfbd_team_matchup("Texas A&M", "TCU")

cfbd_team_matchup("Texas A&M", "TCU", min_year = 1975)

cfbd_team_matchup("Florida State", "Florida", min_year = 1975)
Get matchup history records between two teams.
cfbd_team_matchup_records("Texas", "Oklahoma")

cfbd_team_matchup_records("Texas A&M", "TCU", min_year = 1975)

Get FBS teams

cfbd_teams_fbs(year = 2024)

Get FBS teams

Description

Get FBS teams Every FBS team for a season.

Usage

cfbd_teams_fbs(year = NULL, proxy = NULL)

Arguments

year

(Integer optional): Season, 4 digits (YYYY).
Minimum value accepted: 1869

proxy

(List optional): Per-call proxy override passed to get_req(). NULL (default) falls back to getOption("cfbfastR.proxy") and then the ⁠http(s)_proxy⁠ environment variables, so a caller can override the shared setting for one endpoint.

Value

cfbd_teams_fbs() - A tibble with 43 columns:

col_name types description
id integer Record identifier.
school character School name.
mascot character Team mascot.
abbreviation character Abbreviation.
alternate_names_1 character First alternate team name.
alternate_names_2 character Second alternate team name.
alternate_names_3 character Third alternate team name.
conference character Conference name.
division character Division.
classification character Division classification (fbs, fcs, ii, ii/iii, iii).
color character Primary team color (hex).
alternate_color character Alternate color.
logos_1 character Primary team logo URL.
logos_2 character Alternate (dark) team logo URL.
logos_3 character Logos 3.
logos_4 character Logos 4.
logos_5 character Logos 5.
logos_6 character Logos 6.
logos_7 character Logos 7.
logos_8 character Logos 8.
logos_9 character Logos 9.
logos_10 character Logos 10.
logos_11 character Logos 11.
logos_12 character Logos 12.
logos_13 character Logos 13.
logos_14 character Logos 14.
logos_15 character Logos 15.
logos_16 character Logos 16.
twitter character Team Twitter/X handle.
location_id integer Venue identifier.
location_name character Venue name.
location_city character Venue city.
location_state character Venue state.
location_zip character Venue zip.
location_country_code character Venue country code.
location_timezone character Venue timezone.
location_latitude numeric Venue latitude.
location_longitude numeric Venue longitude.
location_elevation character Venue elevation.
location_capacity integer Venue capacity.
location_construction_year integer Venue construction year.
location_grass logical Venue grass.
location_dome logical Venue dome.

Examples


  try(cfbd_teams_fbs(year = 2024))

CFBD Venues Endpoint Overview

Description

Pulls all college football venues and data on capacity, grass, city/state, location, elevation, dome, timezone and construction year.

Usage

cfbd_venues()

Details

CFB Venue Information

cfbd_venues()

CFB Venue Information 

 cfbd_venues()

Value

A data frame with 337 rows and 14 variables:

col_name types description
venue_id integer Referencing venue ID.
name character Venue name.
capacity integer Stadium capacity.
grass logical TRUE/FALSE response on whether the field is grass or not.
city character Venue city.
state character Venue state.
zip character Venue zip code.
country_code character Venue country code.
latitude numeric Venue latitude in decimal degrees.
longitude numeric Venue longitude in decimal degrees.
elevation character Venue elevation above sea level.
year_constructed integer Year in which the venue was constructed.
dome logical TRUE/FALSE response to whether the venue has a dome or not.
timezone character Time zone in which the venue resides (i.e. Eastern Time -> "America/New_York").

Examples


  try(cfbd_venues())

Create EPA

Description

Adds Expected Points calculations to Play-by-Play data.frame

Usage

create_epa(play_df, ep_model, fg_model)

epa_fg_probs(dat, current_probs, ep_model, fg_mod)

Arguments

play_df

(data.frame required): Clean PBP as input from cfbd_pbp_data()

ep_model

(model, default cfbfastR's ep_model): FG Model to be used for prediction on field goal (FG) attempts in Play-by-Play data.frame

fg_model

(model default cfbfastR's fg_model): Field Goal (FG) Model

dat

(data.frame required): Clean Play-By-Play data.frame as can be pulled from clean_pbp_dat()

current_probs

(data.frame required): Expected Points (EP) model raw probability outputs from initial prediction

fg_mod

(model, default cfbfastR's fg_model): FG Model to be used for prediction on field goal (FG) attempts in Play-by-Play data.frame

Details

Code Description

1. pred_df:

Use select before play model variables -> Make predictions.

2. epa_fg_probs:

Update expected points predictions from before variables with FG make/miss probability weighted adjustment.

3. pred_df_after:

Use select after play model variables -> Make predictions.

4. join_ep:

Join ep_before calcs pred_df with ep_after calcs pred_df_after on c("game_id","drive_id","new_id").

5. kickoffs:

Calculate ep_before for kickoffs as if the pre-play assumption is a touchback.

6. wpa_prep:

Prep variables for WPA.

Value

play_df with EPA variables added

Updated expected points probabilities with FG make/miss weighted adjustment

Create WPA

Description

Add Win Probability Added (WPA) calculations to Play-by-Play DataFrame This is only for D1 football

Usage

create_wpa_naive(df, wp_model)

wpa_calcs_naive(df)

Arguments

df

(data.frame required): Clean Play-by-Play data.frame with Expected Points Added (EPA) calculations

wp_model

(model default cfbfastR:wp_model): Win Probability (WP) Model

Details

Requires the following columns to be present in the input data frame.

Value

The original df with the following columns appended to it:

wp_before

.

def_wp_before

.

home_wp_before

.

away_wp_before

.

lead_wp_before

.

lead_wp_before2

.

wpa_base

.

wpa_base_nxt

.

wpa_base_ind

.

wpa_base_nxt_ind

.

wpa_change

.

wpa_change_nxt

.

wpa_change_ind

.

wpa_change_nxt_ind

.

wpa

.

wp_after

.

def_wp_after

.

home_wp_after

.

away_wp_after

.

Load .csv / .csv.gz file from a remote connection

Description

This is a thin wrapper on data.table::fread

Usage

csv_from_url(...)

Arguments

...

passed to data.table::fread

Data in the package for reference

Description

Data in the package for reference

College Football Mapping for Play Types

College Football Conferences

Minimum Season Accepted by Year-Taking Functions

Usage

cfbd_play_type_df

cfbd_conf_types_df

min_year_map_df

Format

A data frame with 45 rows and 3 variables:

A data frame with 11 rows and 4 variables:

A data frame with 85 rows and 4 variables:

Details

Generated by data-raw/min_year_map_df.R, which walks every exported function taking a year argument and probes backwards for the earliest season returning rows. Values are surfaced in each function's ⁠@param year⁠ documentation, so they are only as current as the last devtools::document() run following an update of this table.

ESPN College Football Award Detail

Description

Get the ESPN core-v2 detail record for a single college football award in a given season – name, description, history, and the athlete (and team) that won it.

Usage

espn_cfb_award(award_id = NULL, year = NULL, team_detail = TRUE)

Arguments

award_id

(Integer required): ESPN award id.

year

(Integer required): Season, 4 digit format (YYYY). Minimum value accepted: 1935

team_detail

(Logical): when TRUE (default), the ESPN team catalog (espn_cfb_teams()) is fetched once and friendly team fields are joined in next to the team_id column. The sibling columns team_name, team_abbreviation, team_location, team_display_name, team_short_display_name, team_nickname, team_color, team_alternate_color, team_logo_href, team_logo_dark_href are inserted immediately after team_id. A catalog failure degrades to NA rather than erroring the wrapper. Set FALSE to skip the catalog fetch and the join, reproducing the prior output exactly.

Details

Wraps the ESPN core-v2 endpoint sports.core.api.espn.com/v2/sports/football/leagues/college-football/seasons/{year}/awards/{award_id}. espn_cfb_awards() returns the season award index; this wrapper returns the single-award detail (including the long-form history text) for one id. Returns one row per (award x winner) – most awards have a single winner, so the table is typically one row. An award with no winner recorded yet still contributes one row with athlete_id/team_id left NA. Winners are returned as ESPN athlete and team ids only – join to an athlete source for names. Enumerate award_ids with espn_cfb_awards().

Value

A data frame with one row per award-winner:

col_name types description
season integer Season (4-digit year) queried.
award_id character ESPN award id.
name character Award name (e.g. ⁠Buck Buchanan Award⁠).
description character ESPN's short description of the award.
history character ESPN's long-form history text for the award.
athlete_id character ESPN id of the winning athlete (parsed from athlete_ref); NA if none.
team_id character ESPN id of the winner's team (parsed from team_ref); NA if none.
team_name character Team nickname; team_detail = TRUE only.
team_abbreviation character Team abbreviation; team_detail = TRUE only.
team_location character Team location / school name; team_detail = TRUE only.
team_display_name character Full team display name; team_detail = TRUE only.
team_short_display_name character Short team display name; team_detail = TRUE only.
team_nickname character Team nickname label; team_detail = TRUE only.
team_color character Primary team color; team_detail = TRUE only.
team_alternate_color character Alternate team color; team_detail = TRUE only.
team_logo_href character Default team logo URL; team_detail = TRUE only.
team_logo_dark_href character Dark-variant team logo URL; team_detail = TRUE only.
award_ref character ⁠$ref⁠ URL to the award resource.
athlete_ref character ⁠$ref⁠ URL to the winning athlete resource (may be NA).
team_ref character ⁠$ref⁠ URL to the winner's team resource (may be NA).

See Also

Other ESPN CFB Functions: espn_cfb_awards(), espn_cfb_clear_cache(), espn_cfb_coach(), espn_cfb_coach_record(), espn_cfb_coaches(), espn_cfb_franchise(), espn_cfb_franchises(), espn_cfb_futures(), espn_cfb_game_broadcasts(), espn_cfb_game_drive_plays(), espn_cfb_game_drives(), espn_cfb_game_leaders(), espn_cfb_game_odds(), espn_cfb_game_pbp(), espn_cfb_game_play(), espn_cfb_game_player_box(), espn_cfb_game_player_statistics(), espn_cfb_game_powerindex(), espn_cfb_game_predictor(), espn_cfb_game_probabilities(), espn_cfb_game_situation(), espn_cfb_game_status(), espn_cfb_game_team_leaders(), espn_cfb_game_team_linescores(), espn_cfb_game_team_records(), espn_cfb_game_team_roster(), espn_cfb_game_team_statistics(), espn_cfb_game_teams(), espn_cfb_groups(), espn_cfb_pbp_v2(), espn_cfb_player(), espn_cfb_player_career_stats(), espn_cfb_player_eventlog(), espn_cfb_player_gamelog(), espn_cfb_player_overview(), espn_cfb_player_seasons(), espn_cfb_player_splits(), espn_cfb_player_stats_v3(), espn_cfb_players(), espn_cfb_position(), espn_cfb_positions(), espn_cfb_powerindex(), espn_cfb_qbr(), espn_cfb_rankings(), espn_cfb_recruits(), espn_cfb_season_info(), espn_cfb_season_types(), espn_cfb_season_weeks(), espn_cfb_seasons(), espn_cfb_standings(), espn_cfb_team(), espn_cfb_team_ats(), espn_cfb_team_awards(), espn_cfb_team_coaches(), espn_cfb_team_events(), espn_cfb_team_leaders(), espn_cfb_team_powerindex(), espn_cfb_team_ranks(), espn_cfb_team_record(), espn_cfb_team_roster(), espn_cfb_team_schedule(), espn_cfb_teams(), espn_cfb_unnest_plays(), espn_cfb_venue(), espn_cfb_venues(), espn_cfb_week_rankings()

Examples


  try(espn_cfb_award(award_id = 1, year = 2024))
  try(espn_cfb_award(award_id = 1, year = 2024, team_detail = FALSE))

ESPN College Football Awards

Description

Get ESPN's college football awards for a season – the Heisman, position and player-of-the-year honors, and the athlete (and team) that won each.

Usage

espn_cfb_awards(year = NULL, team_detail = TRUE)

Arguments

year

(Integer required): Season, 4 digit format (YYYY).
Minimum value accepted: 1935

team_detail

(Logical): when TRUE (default), the ESPN team catalog (espn_cfb_teams()) is fetched once and friendly team fields are joined in next to the team_id column. The sibling columns team_name, team_abbreviation, team_location, team_display_name, team_short_display_name, team_nickname, team_color, team_alternate_color, team_logo_href, team_logo_dark_href are inserted immediately after team_id. A catalog failure degrades to NA rather than erroring the wrapper. Set FALSE to skip the catalog fetch and the join, reproducing the prior output exactly.

Details

Wraps the ESPN core-v2 endpoint sports.core.api.espn.com/v2/sports/football/leagues/college-football/seasons/{year}/awards. The index returns one ⁠$ref⁠ per award (~32); this wrapper dereferences each and returns one row per (award x winner). Most awards have a single winner, so the table is roughly one row per award. Winners are returned as ESPN athlete ids (and team ids) only – join to an athlete source for names. An award with no winner recorded yet still contributes one row with athlete_id/team_id left NA.

Value

A data frame with one row per award-winner:

col_name types description
season integer Season (4-digit year).
award_id character ESPN award id.
name character Award name (e.g. ⁠Heisman Trophy⁠).
description character ESPN's description of the award.
athlete_id character ESPN id of the winning athlete (parsed from athlete_ref); NA if none.
team_id character ESPN id of the winner's team (parsed from team_ref); NA if none.
team_name character Team nickname; team_detail = TRUE only.
team_abbreviation character Team abbreviation; team_detail = TRUE only.
team_location character Team location / school name; team_detail = TRUE only.
team_display_name character Full team display name; team_detail = TRUE only.
team_short_display_name character Short team display name; team_detail = TRUE only.
team_nickname character Team nickname label; team_detail = TRUE only.
team_color character Primary team color; team_detail = TRUE only.
team_alternate_color character Alternate team color; team_detail = TRUE only.
team_logo_href character Default team logo URL; team_detail = TRUE only.
team_logo_dark_href character Dark-variant team logo URL; team_detail = TRUE only.
award_ref character ⁠$ref⁠ URL to the award resource.
athlete_ref character ⁠$ref⁠ URL to the winning athlete resource (may be NA).
team_ref character ⁠$ref⁠ URL to the winner's team resource (may be NA).

See Also

Other ESPN CFB Functions: espn_cfb_award(), espn_cfb_clear_cache(), espn_cfb_coach(), espn_cfb_coach_record(), espn_cfb_coaches(), espn_cfb_franchise(), espn_cfb_franchises(), espn_cfb_futures(), espn_cfb_game_broadcasts(), espn_cfb_game_drive_plays(), espn_cfb_game_drives(), espn_cfb_game_leaders(), espn_cfb_game_odds(), espn_cfb_game_pbp(), espn_cfb_game_play(), espn_cfb_game_player_box(), espn_cfb_game_player_statistics(), espn_cfb_game_powerindex(), espn_cfb_game_predictor(), espn_cfb_game_probabilities(), espn_cfb_game_situation(), espn_cfb_game_status(), espn_cfb_game_team_leaders(), espn_cfb_game_team_linescores(), espn_cfb_game_team_records(), espn_cfb_game_team_roster(), espn_cfb_game_team_statistics(), espn_cfb_game_teams(), espn_cfb_groups(), espn_cfb_pbp_v2(), espn_cfb_player(), espn_cfb_player_career_stats(), espn_cfb_player_eventlog(), espn_cfb_player_gamelog(), espn_cfb_player_overview(), espn_cfb_player_seasons(), espn_cfb_player_splits(), espn_cfb_player_stats_v3(), espn_cfb_players(), espn_cfb_position(), espn_cfb_positions(), espn_cfb_powerindex(), espn_cfb_qbr(), espn_cfb_rankings(), espn_cfb_recruits(), espn_cfb_season_info(), espn_cfb_season_types(), espn_cfb_season_weeks(), espn_cfb_seasons(), espn_cfb_standings(), espn_cfb_team(), espn_cfb_team_ats(), espn_cfb_team_awards(), espn_cfb_team_coaches(), espn_cfb_team_events(), espn_cfb_team_leaders(), espn_cfb_team_powerindex(), espn_cfb_team_ranks(), espn_cfb_team_record(), espn_cfb_team_roster(), espn_cfb_team_schedule(), espn_cfb_teams(), espn_cfb_unnest_plays(), espn_cfb_venue(), espn_cfb_venues(), espn_cfb_week_rankings()

Examples


  try(espn_cfb_awards(year = 2024))
  try(espn_cfb_awards(year = 2024, team_detail = FALSE))

ESPN Calendar

Description

look up the men's college football calendar for a given season

Usage

espn_cfb_calendar(year = NULL, groups = NULL)

Arguments

year

(int): Used to define different seasons.
Minimum value accepted: 1999

groups

(string): Used to define different divisions. FBS or FCS.

Value

espn_cfb_calendar() - A data frame with 8 variables:

Examples


  try(espn_cfb_calendar(2021))

ESPN College Football Catalog Endpoint Overview

Description

Details

ESPN College Football Award Detail

espn_cfb_award(award_id = 1, year = 2024)

ESPN College Football Awards

espn_cfb_awards(year = 2024)

ESPN College Football Coach Detail

espn_cfb_coach(coach_id = 5120149, year = 2024)

ESPN College Football Coach Season Record

espn_cfb_coach_record(coach_id = 5120149, year = 2024)

ESPN College Football Coaches Index

espn_cfb_coaches(year = 2024)

ESPN College Football Franchise Detail

espn_cfb_franchise(franchise_id = 2)

ESPN College Football Franchises Index

espn_cfb_franchises()

ESPN College Football Position Detail

espn_cfb_position(position_id = 8)

ESPN College Football Positions Index

espn_cfb_positions()

ESPN College Football Venue Detail

espn_cfb_venue(venue_id = 3785)

ESPN College Football Venues Index

espn_cfb_venues(max_results = 50)

Clear the cfbfastR ESPN catalog cache

espn_cfb_clear_cache()

Clear the cfbfastR ESPN catalog cache

Description

The ESPN college football game wrappers enrich their output with team and position detail drawn from two static catalogs – espn_cfb_teams() (~750 teams) and espn_cfb_positions() (~74 positions). Because those catalogs do not change often, the internal lookups built from them are memoised with cachem + memoise, so a loop over many games does not re-hit ESPN for the catalogs on every call.

espn_cfb_clear_cache() forgets those memoised lookups. The next wrapper call that needs a catalog will fetch a fresh copy from ESPN. Use it when you want to force a refresh – for example after a long-running session, or when debugging.

Usage

espn_cfb_clear_cache()

Details

Clear the cfbfastR ESPN catalog cache

Caching is configured at package load via two options():

Set these with options() before the package is loaded, e.g. options(cfbfastR.cache = "filesystem"). When cfbfastR.cache is "off", the catalog helpers are never memoised and espn_cfb_clear_cache() is a no-op (it still returns invisibly without error).

Value

Invisibly returns NULL. Called for its side effect of forgetting the memoised catalog lookups.

See Also

Other ESPN CFB Functions: espn_cfb_award(), espn_cfb_awards(), espn_cfb_coach(), espn_cfb_coach_record(), espn_cfb_coaches(), espn_cfb_franchise(), espn_cfb_franchises(), espn_cfb_futures(), espn_cfb_game_broadcasts(), espn_cfb_game_drive_plays(), espn_cfb_game_drives(), espn_cfb_game_leaders(), espn_cfb_game_odds(), espn_cfb_game_pbp(), espn_cfb_game_play(), espn_cfb_game_player_box(), espn_cfb_game_player_statistics(), espn_cfb_game_powerindex(), espn_cfb_game_predictor(), espn_cfb_game_probabilities(), espn_cfb_game_situation(), espn_cfb_game_status(), espn_cfb_game_team_leaders(), espn_cfb_game_team_linescores(), espn_cfb_game_team_records(), espn_cfb_game_team_roster(), espn_cfb_game_team_statistics(), espn_cfb_game_teams(), espn_cfb_groups(), espn_cfb_pbp_v2(), espn_cfb_player(), espn_cfb_player_career_stats(), espn_cfb_player_eventlog(), espn_cfb_player_gamelog(), espn_cfb_player_overview(), espn_cfb_player_seasons(), espn_cfb_player_splits(), espn_cfb_player_stats_v3(), espn_cfb_players(), espn_cfb_position(), espn_cfb_positions(), espn_cfb_powerindex(), espn_cfb_qbr(), espn_cfb_rankings(), espn_cfb_recruits(), espn_cfb_season_info(), espn_cfb_season_types(), espn_cfb_season_weeks(), espn_cfb_seasons(), espn_cfb_standings(), espn_cfb_team(), espn_cfb_team_ats(), espn_cfb_team_awards(), espn_cfb_team_coaches(), espn_cfb_team_events(), espn_cfb_team_leaders(), espn_cfb_team_powerindex(), espn_cfb_team_ranks(), espn_cfb_team_record(), espn_cfb_team_roster(), espn_cfb_team_schedule(), espn_cfb_teams(), espn_cfb_unnest_plays(), espn_cfb_venue(), espn_cfb_venues(), espn_cfb_week_rankings()

Examples


  # Force the team / position catalogs to be re-fetched on next use
  espn_cfb_clear_cache()

ESPN College Football Coach Detail

Description

Get the ESPN core-v2 detail record for a single college football coach – name, the team coached in the requested season, and a count of career-record and coach-season entries ESPN has on file.

Usage

espn_cfb_coach(coach_id = NULL, year = NULL, team_detail = TRUE)

Arguments

coach_id

(Integer required): ESPN coach id.

year

(Integer required): Season, 4 digit format (YYYY). Used to resolve the team the coach led that season.
Minimum value accepted: 2001

team_detail

(Logical): when TRUE (default), the ESPN team catalog (espn_cfb_teams()) is fetched once and friendly team fields are joined in next to the team_id column. The sibling columns team_name, team_abbreviation, team_location, team_display_name, team_short_display_name, team_nickname, team_color, team_alternate_color, team_logo_href, team_logo_dark_href are inserted immediately after team_id. A catalog failure degrades to NA rather than erroring the wrapper. Set FALSE to skip the catalog fetch and the join, reproducing the prior output exactly.

Details

Wraps two ESPN core-v2 endpoints and merges them: the season-scoped coach resource seasons/{year}/coaches/{coach_id} (supplies the team coached that season) and the league-wide coach resource coaches/{coach_id} (supplies the career-record and coach-season counts). Returns a single-row tibble. Enumerate coach_ids with espn_cfb_coaches().

Value

A single-row data frame:

col_name types description
coach_id character ESPN coach id.
season integer Season (4-digit year) queried.
first_name character Coach first name.
last_name character Coach last name.
uid character ESPN coach UID string.
team_id character ESPN id of the team coached that season (parsed from team_ref).
team_name character Team nickname; team_detail = TRUE only.
team_abbreviation character Team abbreviation; team_detail = TRUE only.
team_location character Team location / school name; team_detail = TRUE only.
team_display_name character Full team display name; team_detail = TRUE only.
team_short_display_name character Short team display name; team_detail = TRUE only.
team_nickname character Team nickname label; team_detail = TRUE only.
team_color character Primary team color; team_detail = TRUE only.
team_alternate_color character Alternate team color; team_detail = TRUE only.
team_logo_href character Default team logo URL; team_detail = TRUE only.
team_logo_dark_href character Dark-variant team logo URL; team_detail = TRUE only.
n_career_records integer Number of career-record entries ESPN has on file.
n_coach_seasons integer Number of coach-season entries ESPN has on file.
team_ref character ⁠$ref⁠ URL to the per-season team resource.
person_ref character ⁠$ref⁠ URL to the league-wide coach (person) resource.

See Also

Other ESPN CFB Functions: espn_cfb_award(), espn_cfb_awards(), espn_cfb_clear_cache(), espn_cfb_coach_record(), espn_cfb_coaches(), espn_cfb_franchise(), espn_cfb_franchises(), espn_cfb_futures(), espn_cfb_game_broadcasts(), espn_cfb_game_drive_plays(), espn_cfb_game_drives(), espn_cfb_game_leaders(), espn_cfb_game_odds(), espn_cfb_game_pbp(), espn_cfb_game_play(), espn_cfb_game_player_box(), espn_cfb_game_player_statistics(), espn_cfb_game_powerindex(), espn_cfb_game_predictor(), espn_cfb_game_probabilities(), espn_cfb_game_situation(), espn_cfb_game_status(), espn_cfb_game_team_leaders(), espn_cfb_game_team_linescores(), espn_cfb_game_team_records(), espn_cfb_game_team_roster(), espn_cfb_game_team_statistics(), espn_cfb_game_teams(), espn_cfb_groups(), espn_cfb_pbp_v2(), espn_cfb_player(), espn_cfb_player_career_stats(), espn_cfb_player_eventlog(), espn_cfb_player_gamelog(), espn_cfb_player_overview(), espn_cfb_player_seasons(), espn_cfb_player_splits(), espn_cfb_player_stats_v3(), espn_cfb_players(), espn_cfb_position(), espn_cfb_positions(), espn_cfb_powerindex(), espn_cfb_qbr(), espn_cfb_rankings(), espn_cfb_recruits(), espn_cfb_season_info(), espn_cfb_season_types(), espn_cfb_season_weeks(), espn_cfb_seasons(), espn_cfb_standings(), espn_cfb_team(), espn_cfb_team_ats(), espn_cfb_team_awards(), espn_cfb_team_coaches(), espn_cfb_team_events(), espn_cfb_team_leaders(), espn_cfb_team_powerindex(), espn_cfb_team_ranks(), espn_cfb_team_record(), espn_cfb_team_roster(), espn_cfb_team_schedule(), espn_cfb_teams(), espn_cfb_unnest_plays(), espn_cfb_venue(), espn_cfb_venues(), espn_cfb_week_rankings()

Examples


  try(espn_cfb_coach(coach_id = 5120149, year = 2024))
  try(espn_cfb_coach(coach_id = 5120149, year = 2024, team_detail = FALSE))

ESPN College Football Coach Season Record

Description

Get a college football coach's win/loss record for a single season – the headline summary plus every stat category ESPN publishes for that coach-season (wins, losses, ties, overtime wins/losses), in long format.

Usage

espn_cfb_coach_record(coach_id = NULL, year = NULL, season_type = 2)

Arguments

coach_id

(Integer required): ESPN coach id.

year

(Integer required): Season, 4 digit format (YYYY).
Minimum value accepted: 2001

season_type

(Integer default 2): ESPN season type – 2 for regular season, 3 for postseason.

Details

Wraps the ESPN core-v2 endpoint sports.core.api.espn.com/v2/sports/football/leagues/college-football/seasons/{year}/types/{season_type}/coaches/{coach_id}/record. The records block is otherwise only reachable nested inside espn_cfb_coach(); this wrapper exposes it tabular. Returns one row per stat category. Each row carries the season-level summary/value alongside the per-stat fields, so the table is self-describing. Enumerate coach_ids with espn_cfb_coaches().

Value

A data frame with one row per stat category:

col_name types description
coach_id character ESPN coach id queried.
season integer Season (4-digit year) queried.
season_type integer ESPN season type queried (2 regular, 3 post).
record_id character ESPN record id (season-type id, e.g. 2).
record_name character Record name (e.g. ⁠Regular Season⁠).
record_type character Record type (e.g. ⁠Regular Season⁠).
record_summary character Season record summary (e.g. 7-6-0).
record_value numeric Season win-percentage value (may be NA).
stat_name character Stat key (e.g. wins, losses, OTWins).
display_name character Human-readable stat name (e.g. Wins).
short_display_name character Short stat name (e.g. W).
abbreviation character Stat abbreviation (e.g. W).
stat_type character Internal stat type key (e.g. wins).
description character ESPN's description of the stat.
value numeric Stat value.

See Also

Other ESPN CFB Functions: espn_cfb_award(), espn_cfb_awards(), espn_cfb_clear_cache(), espn_cfb_coach(), espn_cfb_coaches(), espn_cfb_franchise(), espn_cfb_franchises(), espn_cfb_futures(), espn_cfb_game_broadcasts(), espn_cfb_game_drive_plays(), espn_cfb_game_drives(), espn_cfb_game_leaders(), espn_cfb_game_odds(), espn_cfb_game_pbp(), espn_cfb_game_play(), espn_cfb_game_player_box(), espn_cfb_game_player_statistics(), espn_cfb_game_powerindex(), espn_cfb_game_predictor(), espn_cfb_game_probabilities(), espn_cfb_game_situation(), espn_cfb_game_status(), espn_cfb_game_team_leaders(), espn_cfb_game_team_linescores(), espn_cfb_game_team_records(), espn_cfb_game_team_roster(), espn_cfb_game_team_statistics(), espn_cfb_game_teams(), espn_cfb_groups(), espn_cfb_pbp_v2(), espn_cfb_player(), espn_cfb_player_career_stats(), espn_cfb_player_eventlog(), espn_cfb_player_gamelog(), espn_cfb_player_overview(), espn_cfb_player_seasons(), espn_cfb_player_splits(), espn_cfb_player_stats_v3(), espn_cfb_players(), espn_cfb_position(), espn_cfb_positions(), espn_cfb_powerindex(), espn_cfb_qbr(), espn_cfb_rankings(), espn_cfb_recruits(), espn_cfb_season_info(), espn_cfb_season_types(), espn_cfb_season_weeks(), espn_cfb_seasons(), espn_cfb_standings(), espn_cfb_team(), espn_cfb_team_ats(), espn_cfb_team_awards(), espn_cfb_team_coaches(), espn_cfb_team_events(), espn_cfb_team_leaders(), espn_cfb_team_powerindex(), espn_cfb_team_ranks(), espn_cfb_team_record(), espn_cfb_team_roster(), espn_cfb_team_schedule(), espn_cfb_teams(), espn_cfb_unnest_plays(), espn_cfb_venue(), espn_cfb_venues(), espn_cfb_week_rankings()

Examples


  try(espn_cfb_coach_record(coach_id = 5120149, year = 2024))

ESPN College Football Coaches Index

Description

Get every head coach ESPN tracks for a college football season, with their name, ESPN ids, and the team they coached that year.

Usage

espn_cfb_coaches(year = NULL, team_detail = TRUE)

Arguments

year

(Integer required): Season, 4 digit format (YYYY).
Minimum value accepted: 2001

team_detail

(Logical): when TRUE (default), the ESPN team catalog (espn_cfb_teams()) is fetched once and friendly team fields are joined in next to the team_id column. The sibling columns team_name, team_abbreviation, team_location, team_display_name, team_short_display_name, team_nickname, team_color, team_alternate_color, team_logo_href, team_logo_dark_href are inserted immediately after team_id. A catalog failure degrades to NA rather than erroring the wrapper. Set FALSE to skip the catalog fetch and the join, reproducing the prior output exactly.

Details

Wraps the ESPN core-v2 endpoint sports.core.api.espn.com/v2/sports/football/leagues/college-football/seasons/{year}/coaches. The index is ⁠$ref⁠-paginated (~268 coaches across three pages); this wrapper walks every page and dereferences each coach ⁠$ref⁠, returning one row per coach. The coach_id column is the value espn_cfb_coach() accepts for the full per-coach detail (date of birth, birthplace, career-record / coach-season counts).

Value

A data frame with one row per coach:

col_name types description
season integer Season (4-digit year).
coach_id character ESPN coach id.
first_name character Coach first name.
last_name character Coach last name.
team_id character ESPN id of the team coached that season (parsed from team_ref).
team_name character Team nickname; team_detail = TRUE only.
team_abbreviation character Team abbreviation; team_detail = TRUE only.
team_location character Team location / school name; team_detail = TRUE only.
team_display_name character Full team display name; team_detail = TRUE only.
team_short_display_name character Short team display name; team_detail = TRUE only.
team_nickname character Team nickname label; team_detail = TRUE only.
team_color character Primary team color; team_detail = TRUE only.
team_alternate_color character Alternate team color; team_detail = TRUE only.
team_logo_href character Default team logo URL; team_detail = TRUE only.
team_logo_dark_href character Dark-variant team logo URL; team_detail = TRUE only.
coach_ref character ⁠$ref⁠ URL to the season-scoped coach resource.
person_ref character ⁠$ref⁠ URL to the league-wide coach (person) resource.
team_ref character ⁠$ref⁠ URL to the per-season team resource.

See Also

Other ESPN CFB Functions: espn_cfb_award(), espn_cfb_awards(), espn_cfb_clear_cache(), espn_cfb_coach(), espn_cfb_coach_record(), espn_cfb_franchise(), espn_cfb_franchises(), espn_cfb_futures(), espn_cfb_game_broadcasts(), espn_cfb_game_drive_plays(), espn_cfb_game_drives(), espn_cfb_game_leaders(), espn_cfb_game_odds(), espn_cfb_game_pbp(), espn_cfb_game_play(), espn_cfb_game_player_box(), espn_cfb_game_player_statistics(), espn_cfb_game_powerindex(), espn_cfb_game_predictor(), espn_cfb_game_probabilities(), espn_cfb_game_situation(), espn_cfb_game_status(), espn_cfb_game_team_leaders(), espn_cfb_game_team_linescores(), espn_cfb_game_team_records(), espn_cfb_game_team_roster(), espn_cfb_game_team_statistics(), espn_cfb_game_teams(), espn_cfb_groups(), espn_cfb_pbp_v2(), espn_cfb_player(), espn_cfb_player_career_stats(), espn_cfb_player_eventlog(), espn_cfb_player_gamelog(), espn_cfb_player_overview(), espn_cfb_player_seasons(), espn_cfb_player_splits(), espn_cfb_player_stats_v3(), espn_cfb_players(), espn_cfb_position(), espn_cfb_positions(), espn_cfb_powerindex(), espn_cfb_qbr(), espn_cfb_rankings(), espn_cfb_recruits(), espn_cfb_season_info(), espn_cfb_season_types(), espn_cfb_season_weeks(), espn_cfb_seasons(), espn_cfb_standings(), espn_cfb_team(), espn_cfb_team_ats(), espn_cfb_team_awards(), espn_cfb_team_coaches(), espn_cfb_team_events(), espn_cfb_team_leaders(), espn_cfb_team_powerindex(), espn_cfb_team_ranks(), espn_cfb_team_record(), espn_cfb_team_roster(), espn_cfb_team_schedule(), espn_cfb_teams(), espn_cfb_unnest_plays(), espn_cfb_venue(), espn_cfb_venues(), espn_cfb_week_rankings()

Examples


  try(espn_cfb_coaches(year = 2024))
  try(espn_cfb_coaches(year = 2024, team_detail = FALSE))

ESPN College Football Franchise Detail

Description

Get the ESPN core-v2 detail record for a single college football franchise – location, nickname, abbreviation, color, the associated venue and current team, and active status.

Usage

espn_cfb_franchise(franchise_id = NULL, team_detail = TRUE)

Arguments

franchise_id

(Integer required): ESPN franchise id.

team_detail

(Logical): when TRUE (default), the ESPN team catalog (espn_cfb_teams()) is fetched once and friendly team fields are joined in next to the team_id column. The sibling columns team_name, team_abbreviation, team_location, team_display_name, team_short_display_name, team_nickname, team_color, team_alternate_color, team_logo_href, team_logo_dark_href are inserted immediately after team_id. A catalog failure degrades to NA rather than erroring the wrapper. Set FALSE to skip the catalog fetch and the join, reproducing the prior output exactly.

Details

Wraps the ESPN core-v2 endpoint sports.core.api.espn.com/v2/sports/football/leagues/college-football/franchises/{franchise_id}. A franchise is the stable program identity, distinct from ⁠/teams⁠ (which is season-scoped). Returns a single-row tibble. Enumerate franchise_ids with espn_cfb_franchises().

Value

A single-row data frame:

col_name types description
franchise_id character ESPN franchise id.
uid character ESPN franchise UID string.
slug character Franchise slug (e.g. auburn-tigers).
location character Franchise location (e.g. Auburn).
name character Franchise name (e.g. Tigers).
nickname character Franchise nickname (e.g. Auburn).
abbreviation character Franchise abbreviation (e.g. AUB).
display_name character Full display name (e.g. ⁠Auburn Tigers⁠).
short_display_name character Short display name (e.g. Auburn).
color character Primary team color (hex, no ⁠#⁠).
is_active logical TRUE if the franchise is currently active.
venue_id character ESPN id of the franchise's venue (NA if none).
venue_name character Full name of the franchise's venue.
team_id character ESPN id of the current team (parsed from team_ref).
team_name character Team nickname; team_detail = TRUE only.
team_abbreviation character Team abbreviation; team_detail = TRUE only.
team_location character Team location / school name; team_detail = TRUE only.
team_display_name character Full team display name; team_detail = TRUE only.
team_short_display_name character Short team display name; team_detail = TRUE only.
team_nickname character Team nickname label; team_detail = TRUE only.
team_color character Primary team color; team_detail = TRUE only.
team_alternate_color character Alternate team color; team_detail = TRUE only.
team_logo_href character Default team logo URL; team_detail = TRUE only.
team_logo_dark_href character Dark-variant team logo URL; team_detail = TRUE only.
team_ref character ⁠$ref⁠ URL to the current team-in-season resource.
franchise_ref character ⁠$ref⁠ URL to the franchise resource.

See Also

Other ESPN CFB Functions: espn_cfb_award(), espn_cfb_awards(), espn_cfb_clear_cache(), espn_cfb_coach(), espn_cfb_coach_record(), espn_cfb_coaches(), espn_cfb_franchises(), espn_cfb_futures(), espn_cfb_game_broadcasts(), espn_cfb_game_drive_plays(), espn_cfb_game_drives(), espn_cfb_game_leaders(), espn_cfb_game_odds(), espn_cfb_game_pbp(), espn_cfb_game_play(), espn_cfb_game_player_box(), espn_cfb_game_player_statistics(), espn_cfb_game_powerindex(), espn_cfb_game_predictor(), espn_cfb_game_probabilities(), espn_cfb_game_situation(), espn_cfb_game_status(), espn_cfb_game_team_leaders(), espn_cfb_game_team_linescores(), espn_cfb_game_team_records(), espn_cfb_game_team_roster(), espn_cfb_game_team_statistics(), espn_cfb_game_teams(), espn_cfb_groups(), espn_cfb_pbp_v2(), espn_cfb_player(), espn_cfb_player_career_stats(), espn_cfb_player_eventlog(), espn_cfb_player_gamelog(), espn_cfb_player_overview(), espn_cfb_player_seasons(), espn_cfb_player_splits(), espn_cfb_player_stats_v3(), espn_cfb_players(), espn_cfb_position(), espn_cfb_positions(), espn_cfb_powerindex(), espn_cfb_qbr(), espn_cfb_rankings(), espn_cfb_recruits(), espn_cfb_season_info(), espn_cfb_season_types(), espn_cfb_season_weeks(), espn_cfb_seasons(), espn_cfb_standings(), espn_cfb_team(), espn_cfb_team_ats(), espn_cfb_team_awards(), espn_cfb_team_coaches(), espn_cfb_team_events(), espn_cfb_team_leaders(), espn_cfb_team_powerindex(), espn_cfb_team_ranks(), espn_cfb_team_record(), espn_cfb_team_roster(), espn_cfb_team_schedule(), espn_cfb_teams(), espn_cfb_unnest_plays(), espn_cfb_venue(), espn_cfb_venues(), espn_cfb_week_rankings()

Examples


  try(espn_cfb_franchise(franchise_id = 2))
  try(espn_cfb_franchise(franchise_id = 2, team_detail = FALSE))

ESPN College Football Franchises Index

Description

Get the catalog of college football franchises ESPN tracks – the stable program identities (~797) that underpin ESPN's team resources.

Usage

espn_cfb_franchises()

Details

Wraps the ESPN core-v2 endpoint sports.core.api.espn.com/v2/sports/football/leagues/college-football/franchises. A franchise is the stable program identity, distinct from ⁠/teams⁠ (which is season-scoped). The index is ⁠$ref⁠-paginated and large (~797 franchises); dereferencing every franchise would be hundreds of HTTP calls, so this wrapper returns the lightweight index instead – one row per franchise with the franchise_id parsed from each ⁠$ref⁠. Pass an id to espn_cfb_franchise() to dereference the full detail record (slug, location, nickname, division, venue, colors, logos).

Value

A data frame with one row per franchise:

col_name types description
franchise_id character ESPN franchise id (parsed from franchise_ref).
franchise_ref character ⁠$ref⁠ URL to the franchise detail resource.

See Also

Other ESPN CFB Functions: espn_cfb_award(), espn_cfb_awards(), espn_cfb_clear_cache(), espn_cfb_coach(), espn_cfb_coach_record(), espn_cfb_coaches(), espn_cfb_franchise(), espn_cfb_futures(), espn_cfb_game_broadcasts(), espn_cfb_game_drive_plays(), espn_cfb_game_drives(), espn_cfb_game_leaders(), espn_cfb_game_odds(), espn_cfb_game_pbp(), espn_cfb_game_play(), espn_cfb_game_player_box(), espn_cfb_game_player_statistics(), espn_cfb_game_powerindex(), espn_cfb_game_predictor(), espn_cfb_game_probabilities(), espn_cfb_game_situation(), espn_cfb_game_status(), espn_cfb_game_team_leaders(), espn_cfb_game_team_linescores(), espn_cfb_game_team_records(), espn_cfb_game_team_roster(), espn_cfb_game_team_statistics(), espn_cfb_game_teams(), espn_cfb_groups(), espn_cfb_pbp_v2(), espn_cfb_player(), espn_cfb_player_career_stats(), espn_cfb_player_eventlog(), espn_cfb_player_gamelog(), espn_cfb_player_overview(), espn_cfb_player_seasons(), espn_cfb_player_splits(), espn_cfb_player_stats_v3(), espn_cfb_players(), espn_cfb_position(), espn_cfb_positions(), espn_cfb_powerindex(), espn_cfb_qbr(), espn_cfb_rankings(), espn_cfb_recruits(), espn_cfb_season_info(), espn_cfb_season_types(), espn_cfb_season_weeks(), espn_cfb_seasons(), espn_cfb_standings(), espn_cfb_team(), espn_cfb_team_ats(), espn_cfb_team_awards(), espn_cfb_team_coaches(), espn_cfb_team_events(), espn_cfb_team_leaders(), espn_cfb_team_powerindex(), espn_cfb_team_ranks(), espn_cfb_team_record(), espn_cfb_team_roster(), espn_cfb_team_schedule(), espn_cfb_teams(), espn_cfb_unnest_plays(), espn_cfb_venue(), espn_cfb_venues(), espn_cfb_week_rankings()

Examples


  try(espn_cfb_franchises())

ESPN College Football Betting Futures (Long Format)

Description

Get ESPN's full futures-betting board for a college football season – national championship, conference, and award markets with the American odds each sportsbook is offering on every team or player.

Usage

espn_cfb_futures(year = NULL)

Arguments

year

(Integer required): Season, 4 digit format (YYYY).
Minimum value accepted: 2014

Details

Wraps the ESPN core-v2 endpoint sports.core.api.espn.com/v2/sports/football/leagues/college-football/seasons/{year}/futures. The season index returns one ⁠$ref⁠ per futures market; this wrapper dereferences each market and flattens the nested market -> provider -> books tree into long format: one row per (market x provider x entry). Most markets are team markets (national championship, conference winners) and populate team_id; player markets (e.g. the Heisman) populate athlete_id instead, with the other id column left NA. odds_value is the raw American-odds string ESPN returns (e.g. -400, +150).

Value

A data frame with one row per market-provider-entry:

col_name types description
season integer Season (4-digit year).
market_id character ESPN futures-market identifier.
market_name character Internal market name (e.g. NCAA(F) - Championship).
market_type character Market type code (e.g. winLeague).
market_display character Human-readable market name (e.g. ⁠National Championship Winner⁠).
provider_id character Sportsbook / provider identifier.
provider_name character Sportsbook / provider name (e.g. ⁠ESPN BET⁠).
team_id character ESPN team id (parsed from team_ref); NA for player markets.
athlete_id character ESPN athlete id (parsed from athlete_ref); NA for team markets.
odds_value character American odds for the entry (e.g. -400, +150).
team_ref character ⁠$ref⁠ URL to the per-season team resource (may be NA).
athlete_ref character ⁠$ref⁠ URL to the per-season athlete resource (may be NA).

See Also

Other ESPN CFB Functions: espn_cfb_award(), espn_cfb_awards(), espn_cfb_clear_cache(), espn_cfb_coach(), espn_cfb_coach_record(), espn_cfb_coaches(), espn_cfb_franchise(), espn_cfb_franchises(), espn_cfb_game_broadcasts(), espn_cfb_game_drive_plays(), espn_cfb_game_drives(), espn_cfb_game_leaders(), espn_cfb_game_odds(), espn_cfb_game_pbp(), espn_cfb_game_play(), espn_cfb_game_player_box(), espn_cfb_game_player_statistics(), espn_cfb_game_powerindex(), espn_cfb_game_predictor(), espn_cfb_game_probabilities(), espn_cfb_game_situation(), espn_cfb_game_status(), espn_cfb_game_team_leaders(), espn_cfb_game_team_linescores(), espn_cfb_game_team_records(), espn_cfb_game_team_roster(), espn_cfb_game_team_statistics(), espn_cfb_game_teams(), espn_cfb_groups(), espn_cfb_pbp_v2(), espn_cfb_player(), espn_cfb_player_career_stats(), espn_cfb_player_eventlog(), espn_cfb_player_gamelog(), espn_cfb_player_overview(), espn_cfb_player_seasons(), espn_cfb_player_splits(), espn_cfb_player_stats_v3(), espn_cfb_players(), espn_cfb_position(), espn_cfb_positions(), espn_cfb_powerindex(), espn_cfb_qbr(), espn_cfb_rankings(), espn_cfb_recruits(), espn_cfb_season_info(), espn_cfb_season_types(), espn_cfb_season_weeks(), espn_cfb_seasons(), espn_cfb_standings(), espn_cfb_team(), espn_cfb_team_ats(), espn_cfb_team_awards(), espn_cfb_team_coaches(), espn_cfb_team_events(), espn_cfb_team_leaders(), espn_cfb_team_powerindex(), espn_cfb_team_ranks(), espn_cfb_team_record(), espn_cfb_team_roster(), espn_cfb_team_schedule(), espn_cfb_teams(), espn_cfb_unnest_plays(), espn_cfb_venue(), espn_cfb_venues(), espn_cfb_week_rankings()

Examples


  try(espn_cfb_futures(year = 2024))

ESPN College Football Game Endpoint Overview

Description

Details

Get ESPN college football PBP data (legacy)

espn_cfb_pbp(game_id = 401282614, epa_wpa = TRUE)

Get ESPN College Football Play-by-Play (core-v2)

espn_cfb_pbp_v2(game_id = 401628339, epa_wpa = TRUE)

Unnest ESPN CFB drive plays into a flat play-by-play table

espn_cfb_unnest_plays(espn_cfb_game_drives(401628339, plays = "list"))

ESPN College Football Game Broadcasts

espn_cfb_game_broadcasts(game_id = 401628339)

ESPN College Football Game Drive Plays

espn_cfb_game_drive_plays(game_id = 401628339, drive_id = 4016283391)

ESPN College Football Game Drives

espn_cfb_game_drives(game_id = 401628339)
espn_cfb_game_drives(game_id = 401628339, plays = "expand")

ESPN College Football Game Leaders

espn_cfb_game_leaders(game_id = 401628339)

ESPN College Football Game Odds

espn_cfb_game_odds(game_id = 401628339)
espn_cfb_game_odds(game_id = 401628339, line_history = TRUE)

ESPN College Football Game Plays (Core-v2 Play-by-Play)

espn_cfb_game_pbp(game_id = 401628339)
espn_cfb_game_pbp(game_id = 401628339, participants = "wide")

ESPN College Football Game Play (Single Play Detail)

espn_cfb_game_play(game_id = 401628339, play_id = "401628339101927401")

ESPN College Football Game Player Box Score

espn_cfb_game_player_box(game_id = 401628339)

ESPN College Football Game Player Statistics (Single Athlete)

espn_cfb_game_player_statistics(game_id = 401628339, athlete_id = 4429105)

ESPN College Football Game Power Index (Matchup FPI)

espn_cfb_game_powerindex(game_id = 401628339)

ESPN College Football Game Predictor (BPI Matchup Predictor)

espn_cfb_game_predictor(game_id = 401628339)

ESPN College Football Game Win Probabilities

espn_cfb_game_probabilities(game_id = 401628339)

ESPN College Football Game Situation

espn_cfb_game_situation(game_id = 401628339)

ESPN College Football Game Status

espn_cfb_game_status(game_id = 401628339)

ESPN College Football Game Team Leaders

espn_cfb_game_team_leaders(game_id = 401628339)

ESPN College Football Game Team Linescores

espn_cfb_game_team_linescores(game_id = 401628339)

ESPN College Football Game Team Records

espn_cfb_game_team_records(game_id = 401628339)
espn_cfb_game_team_records(game_id = 401628339, detail = TRUE)

ESPN College Football Game Team Roster

espn_cfb_game_team_roster(game_id = 401628339)

ESPN College Football Game Team Statistics

espn_cfb_game_team_statistics(game_id = 401628339)

ESPN College Football Game Teams

espn_cfb_game_teams(game_id = 401628339)
espn_cfb_game_teams(game_id = 401628339, format = "wide")

ESPN College Football Game Broadcasts

Description

Get the broadcast / streaming outlets carrying a single college football game.

Usage

espn_cfb_game_broadcasts(game_id = NULL)

Arguments

game_id

(Integer required): ESPN game identifier.

Details

Wraps the ESPN core-v2 endpoint events/{game_id}/competitions/{game_id}/broadcasts. Returns one row per broadcast outlet – a television network, streaming service, or radio station. type_name distinguishes TV / streaming / radio; market_type is the geographic market (e.g. National); priority is ESPN's display ordering of the outlets.

Value

A data frame with one row per broadcast outlet:

col_name types description
game_id character ESPN game identifier.
type_id character Broadcast-type id.
type_name character Broadcast-type name (e.g. TV, Streaming, Radio).
type_slug character Broadcast-type slug (e.g. streaming, tv).
station character Broadcast station / network name (e.g. ⁠ESPN+⁠).
slug character Broadcast outlet slug.
channel character Channel number, when published.
priority integer ESPN display priority of the outlet (1 = first).
partnered logical TRUE if the outlet is an ESPN broadcast partner.
market_id character Geographic market id.
market_type character Geographic market type (e.g. National).
lang character Broadcast language code.
region character Broadcast region code.
media_id character ESPN media id for the outlet.
media_name character ESPN media name for the outlet.
media_short_name character Short ESPN media name for the outlet.
media_call_letters character Broadcast call letters for the outlet.
media_slug character ESPN media slug for the outlet.
media_group_id character ESPN media-group id (e.g. corporate parent).
media_group_name character ESPN media-group name (e.g. Disney).
media_group_slug character ESPN media-group slug.
competition_ref character ⁠$ref⁠ URL to the competition resource.
media_ref character ⁠$ref⁠ URL to the media resource.

See Also

Other ESPN CFB Functions: espn_cfb_award(), espn_cfb_awards(), espn_cfb_clear_cache(), espn_cfb_coach(), espn_cfb_coach_record(), espn_cfb_coaches(), espn_cfb_franchise(), espn_cfb_franchises(), espn_cfb_futures(), espn_cfb_game_drive_plays(), espn_cfb_game_drives(), espn_cfb_game_leaders(), espn_cfb_game_odds(), espn_cfb_game_pbp(), espn_cfb_game_play(), espn_cfb_game_player_box(), espn_cfb_game_player_statistics(), espn_cfb_game_powerindex(), espn_cfb_game_predictor(), espn_cfb_game_probabilities(), espn_cfb_game_situation(), espn_cfb_game_status(), espn_cfb_game_team_leaders(), espn_cfb_game_team_linescores(), espn_cfb_game_team_records(), espn_cfb_game_team_roster(), espn_cfb_game_team_statistics(), espn_cfb_game_teams(), espn_cfb_groups(), espn_cfb_pbp_v2(), espn_cfb_player(), espn_cfb_player_career_stats(), espn_cfb_player_eventlog(), espn_cfb_player_gamelog(), espn_cfb_player_overview(), espn_cfb_player_seasons(), espn_cfb_player_splits(), espn_cfb_player_stats_v3(), espn_cfb_players(), espn_cfb_position(), espn_cfb_positions(), espn_cfb_powerindex(), espn_cfb_qbr(), espn_cfb_rankings(), espn_cfb_recruits(), espn_cfb_season_info(), espn_cfb_season_types(), espn_cfb_season_weeks(), espn_cfb_seasons(), espn_cfb_standings(), espn_cfb_team(), espn_cfb_team_ats(), espn_cfb_team_awards(), espn_cfb_team_coaches(), espn_cfb_team_events(), espn_cfb_team_leaders(), espn_cfb_team_powerindex(), espn_cfb_team_ranks(), espn_cfb_team_record(), espn_cfb_team_roster(), espn_cfb_team_schedule(), espn_cfb_teams(), espn_cfb_unnest_plays(), espn_cfb_venue(), espn_cfb_venues(), espn_cfb_week_rankings()

Examples


  try(espn_cfb_game_broadcasts(game_id = 401628339))

ESPN College Football Game Drive Plays

Description

Get the play-by-play for a single drive of a college football game – one row per play, scoped to one drive.

Usage

espn_cfb_game_drive_plays(
  game_id = NULL,
  drive_id = NULL,
  participants = c("none", "wide", "long"),
  participants_list = FALSE,
  team_participants = c("none", "wide"),
  team_participants_list = FALSE,
  team_detail = TRUE
)

Arguments

game_id

(Integer required): ESPN game identifier.

drive_id

(Integer required): ESPN drive id (from espn_cfb_game_drives()).

participants

(Character): controls whether each play's nested participants[] array (the athletes credited on the play) is attached. One of:

  • "none" (default) – the play frame is returned unchanged; no extra HTTP call is made.

  • "wide" – one row per play, with type-keyed ⁠{type}_player_*⁠ columns appended (see Details).

  • "long" – one row per play x participant (see Details).

participants_list

(Logical): when TRUE, append a single list-column named participants holding each play's full participant detail – including the per-participant stats[] that "wide" mode drops. Defaults to FALSE. This is independent of and combinable with the participants argument (see Details).

team_participants

(Character): controls whether each play's nested teamParticipants[] array (the team(s) credited on the play) is attached as type-keyed columns. One of:

  • "none" (default) – no team-participant columns are added.

  • "wide" – one row per play, with type-keyed ⁠{type}_team_*⁠ columns appended (see Details).

team_participants_list

(Logical): when TRUE, append a single list-column named team_participants holding each play's full teamParticipants[] detail as a nested tibble. Defaults to FALSE. This is independent of and combinable with the team_participants argument (see Details).

team_detail

(Logical): when TRUE (default), the ESPN team catalog (espn_cfb_teams()) is fetched once and friendly team fields are joined in next to every team-id column in the output (team_id, start_team_id, end_team_id, plus any optional ⁠{type}_team_id⁠ / ⁠{type}_player_team_id⁠ columns). For each id column X_id the sibling columns X_name, X_abbreviation, X_location, X_display_name, X_short_display_name, X_nickname, X_color, X_alternate_color, X_logo_href, X_logo_dark_href are inserted immediately after it. A catalog failure degrades to NA rather than erroring the wrapper. Set FALSE to skip the catalog fetch and the join.

Details

Wraps the ESPN core-v2 endpoint events/{game_id}/competitions/{game_id}/drives/{drive_id}/plays. The competition id always equals the game id. Returns the same play schema as the competition-level espn_cfb_game_pbp() feed, but partitioned to a single drive (typically 5-11 plays). Harvest the drive_id from espn_cfb_game_drives() – its drive_id column lists every drive in the game.

When participants = "wide", the base play schema is kept intact and six columns are appended for every participant type that appears anywhere in the drive. The column names are dynamic – one set per participant type present (e.g. passer, rusher, receiver, tackler, sacked_by, pass_defender, kicker, returner). ESPN's camelCase types are snake-cased (sackedBy -> sacked_by). For each type the appended columns are:

Participant stats[] are not carried in wide mode – use "long" for the per-participant stat lines.

When participants = "long", the frame is expanded to one row per play x participant with participant_index, participant_athlete_id, participant_type, participant_order, the roster-joined participant_athlete_name / participant_position / participant_jersey / participant_team_id, and the participant's stats pivoted to named ⁠pstat_<statname>⁠ columns. Plays with zero participants still yield one row (participant fields NA).

When participants_list = TRUE, a single list-column named participants is appended. Each cell is a tibble with one row per participant on that play and columns participant_index (1-based, ESPN order), type (snake_cased, e.g. sacked_by, pass_defender), athlete_id, athlete_name (roster-joined), order, position_id, plus one column per participant stat[] name (dplyr::bind_rows NA-fills participants whose stat sets differ). Plays with no participants carry an empty 0-row tibble, never NULL. This option is independent of participants and composes with any of its modes – e.g. ⁠participants = "wide", participants_list = TRUE⁠ yields the type-keyed ⁠{type}_player_*⁠ columns and the participants list-column, while ⁠participants = "none", participants_list = TRUE⁠ adds only the list-column. With participants = "long" the list-column repeats per play x participant row. The raw plays are fetched only once even when both options are active.

When team_participants = "wide", three columns are appended for every teamParticipants[] type present anywhere in the drive (ESPN ships offense / defense). The column names are dynamic – one set per type, snake-cased: ⁠{type}_team_id⁠ (scalar character, the first occurrence of that type on the play), ⁠{type}_team_order⁠ (scalar integer, ESPN's display order), and ⁠{type}_team_ref⁠ (scalar character, the ⁠$ref⁠ URL to that team resource). Plays with none of a type carry NA.

When team_participants_list = TRUE, a single list-column named team_participants is appended. Each cell is a tibble with one row per team credited on the play and columns team_participant_index (1-based, ESPN order), team_id, team_ref, order, and type (e.g. offense, defense). A play with no team participants carries an empty 0-row tibble, never NULL. This option is independent of team_participants and composes with it – e.g. ⁠team_participants = "wide", team_participants_list = TRUE⁠ yields both the type-keyed ⁠{type}_team_*⁠ columns and the team_participants list-column, while team_participants = "none" adds neither.

When team_detail = TRUE (the default), the ESPN team catalog (espn_cfb_teams()) is fetched once and joined onto every team-id column the output carries – the base team_id / start_team_id / end_team_id, plus any optional ⁠{type}_team_id⁠ (from team_participants = "wide") and ⁠{type}_player_team_id⁠ (from participants = "long") columns. For each id column X_id the friendly siblings X_name, X_abbreviation, X_location, X_display_name, X_short_display_name, X_nickname, X_color, X_alternate_color, X_logo_href, and X_logo_dark_href are inserted immediately after it (e.g. team_id -> team_name, team_abbreviation, ...; start_team_id -> start_team_name, ...). Rows whose id is missing or unmatched receive NA, and a catalog-fetch failure degrades the whole set to NA rather than erroring the wrapper. With team_detail = FALSE the friendly columns (and the catalog fetch) are skipped.

Value

A data frame with one row per play in the drive:

col_name types description
game_id character ESPN game identifier.
drive_id character ESPN drive id (the requested drive).
play_id character ESPN play id.
sequence_number character Play sequence number within the game.
type_id character Play-type id.
type_text character Play-type text (e.g. ⁠Pass Reception⁠).
type_abbreviation character Play-type abbreviation (e.g. RUSH, TD).
text character Full play description.
short_text character Short play description.
alternative_text character Alternative play description.
short_alternative_text character Short alternative play description.
period integer Period (quarter) number.
clock character Game clock display value at the play (MM:SS).
clock_seconds numeric Game clock value in seconds at the play.
home_score integer Home-team score after the play.
away_score integer Away-team score after the play.
scoring_play logical TRUE if the play resulted in a score.
score_value integer Points scored on the play.
priority logical TRUE if ESPN flags the play as a priority highlight.
is_penalty logical TRUE if the play was a penalty.
is_turnover logical TRUE if the play was a turnover.
stat_yardage integer Yards gained or lost on the play.
scoring_type_name character Scoring-type key on a scoring play (e.g. touchdown).
scoring_type_display_name character Human-readable scoring-type name.
scoring_type_abbreviation character Scoring-type abbreviation (e.g. TD, FG).
point_after_attempt_id integer Point-after-attempt id on a scoring play.
point_after_attempt_text character Point-after-attempt text (e.g. ⁠Extra Point Good⁠).
point_after_attempt_abbreviation character Point-after-attempt abbreviation.
point_after_attempt_value integer Points added by the point-after attempt.
start_down integer Down at the start of the play.
start_distance integer Yards to go at the start of the play.
start_yard_line integer Yard line at the start of the play.
start_yards_to_endzone integer Yards to the end zone at the start of the play.
start_down_distance_text character Down-and-distance text at the start of the play.
start_short_down_distance_text character Short down-and-distance text at the start of the play.
start_possession_text character Field-position text at the start of the play.
start_team_id character ESPN team id in possession at the start of the play.
end_down integer Down at the end of the play.
end_distance integer Yards to go at the end of the play.
end_yard_line integer Yard line at the end of the play.
end_yards_to_endzone integer Yards to the end zone at the end of the play.
end_down_distance_text character Down-and-distance text at the end of the play.
end_short_down_distance_text character Short down-and-distance text at the end of the play.
end_possession_text character Field-position text at the end of the play.
end_team_id character ESPN team id in possession at the end of the play.
team_id character ESPN team id of the offensive team (parsed from team_ref).
drive_play_id character ESPN drive id the play belongs to (parsed from drive_ref).
wallclock character Real-world ISO timestamp of the play.
modified character ISO timestamp the play record was last modified.
play_ref character ⁠$ref⁠ URL to the play resource itself.
team_ref character ⁠$ref⁠ URL to the offensive team resource.
start_team_ref character ⁠$ref⁠ URL to the team in possession at the play start.
end_team_ref character ⁠$ref⁠ URL to the team in possession at the play end.
drive_ref character ⁠$ref⁠ URL to the play's drive resource.
probability_ref character ⁠$ref⁠ URL to the play's win-probability resource.

The optional participant and team-participant columns are described in Details – they are added only when the corresponding argument requests them.

See Also

Other ESPN CFB Functions: espn_cfb_award(), espn_cfb_awards(), espn_cfb_clear_cache(), espn_cfb_coach(), espn_cfb_coach_record(), espn_cfb_coaches(), espn_cfb_franchise(), espn_cfb_franchises(), espn_cfb_futures(), espn_cfb_game_broadcasts(), espn_cfb_game_drives(), espn_cfb_game_leaders(), espn_cfb_game_odds(), espn_cfb_game_pbp(), espn_cfb_game_play(), espn_cfb_game_player_box(), espn_cfb_game_player_statistics(), espn_cfb_game_powerindex(), espn_cfb_game_predictor(), espn_cfb_game_probabilities(), espn_cfb_game_situation(), espn_cfb_game_status(), espn_cfb_game_team_leaders(), espn_cfb_game_team_linescores(), espn_cfb_game_team_records(), espn_cfb_game_team_roster(), espn_cfb_game_team_statistics(), espn_cfb_game_teams(), espn_cfb_groups(), espn_cfb_pbp_v2(), espn_cfb_player(), espn_cfb_player_career_stats(), espn_cfb_player_eventlog(), espn_cfb_player_gamelog(), espn_cfb_player_overview(), espn_cfb_player_seasons(), espn_cfb_player_splits(), espn_cfb_player_stats_v3(), espn_cfb_players(), espn_cfb_position(), espn_cfb_positions(), espn_cfb_powerindex(), espn_cfb_qbr(), espn_cfb_rankings(), espn_cfb_recruits(), espn_cfb_season_info(), espn_cfb_season_types(), espn_cfb_season_weeks(), espn_cfb_seasons(), espn_cfb_standings(), espn_cfb_team(), espn_cfb_team_ats(), espn_cfb_team_awards(), espn_cfb_team_coaches(), espn_cfb_team_events(), espn_cfb_team_leaders(), espn_cfb_team_powerindex(), espn_cfb_team_ranks(), espn_cfb_team_record(), espn_cfb_team_roster(), espn_cfb_team_schedule(), espn_cfb_teams(), espn_cfb_unnest_plays(), espn_cfb_venue(), espn_cfb_venues(), espn_cfb_week_rankings()

Examples


  try(espn_cfb_game_drive_plays(game_id = 401628339,
                                drive_id = 4016283391))
  try(espn_cfb_game_drive_plays(game_id = 401628339,
                                drive_id = 4016283391,
                                participants = "long"))
  try(espn_cfb_game_drive_plays(game_id = 401628339,
                                drive_id = 4016283391,
                                participants = "wide",
                                participants_list = TRUE))
  try(espn_cfb_game_drive_plays(game_id = 401628339,
                                drive_id = 4016283391,
                                team_participants = "wide",
                                team_participants_list = TRUE))
  try(espn_cfb_game_drive_plays(game_id = 401628339,
                                drive_id = 4016283391,
                                team_detail = FALSE))

ESPN College Football Game Drives

Description

Get the per-game drive log for a single college football game – one row per drive, with start/end field position, yardage, play count, result, and a ⁠$ref⁠ to that drive's plays. Optionally embed each drive's full-schema play-by-play as a nested list-column or as a flat one-row-per-play table.

Usage

espn_cfb_game_drives(
  game_id = NULL,
  plays = c("none", "list", "expand"),
  participants = c("none", "wide", "long"),
  participants_list = FALSE,
  team_participants = c("none", "wide"),
  team_participants_list = FALSE,
  position_detail = TRUE,
  team_detail = TRUE
)

Arguments

game_id

(Integer required): ESPN game identifier.

plays

(Character): controls whether each drive's plays are embedded. One of "none" (default), "list", or "expand" – see Details.

participants

(Character): participant-flattening mode for the embedded plays – one of "none" (default), "wide", or "long". Consulted only when plays != "none". See espn_cfb_game_pbp().

participants_list

(Logical): when TRUE, append the participants list-column to each embedded play. Defaults to FALSE. Consulted only when plays != "none".

team_participants

(Character): team-participant-flattening mode for the embedded plays – one of "none" (default) or "wide". Consulted only when plays != "none".

team_participants_list

(Logical): when TRUE, append the team_participants list-column to each embedded play. Defaults to FALSE. Consulted only when plays != "none".

position_detail

(Logical): when TRUE (default), the embedded plays' participants = "wide" output carries position detail joined from the ESPN position catalog. Consulted only when plays != "none" and participants = "wide".

team_detail

(Logical): when TRUE (default), the ESPN team catalog (espn_cfb_teams()) is fetched once and friendly team fields are joined in next to the drive-level team-id columns – team_id and end_team_id (which become drive_team_id / drive_end_team_id in plays = "expand" mode). For each id column X_id the sibling columns X_name, X_abbreviation, X_location, X_display_name, X_short_display_name, X_nickname, X_color, X_alternate_color, X_logo_href, X_logo_dark_href are inserted immediately after it. The embedded play tibbles keep the base espn_cfb_game_pbp() schema (not team-enriched), so a plays = "expand" result matches espn_cfb_unnest_plays() of a plays = "list" result. A catalog failure degrades to NA rather than erroring the wrapper. Set FALSE to skip the catalog fetch and the join.

Details

Wraps the ESPN core-v2 endpoint events/{game_id}/competitions/{game_id}/drives. The competition id always equals the game id. Returns one row per drive (typically 18-24 drives per game). Each drive carries the offensive team, the start and end period/clock/yard-line, total yards, offensive play count, the drive result, and a scoring flag. The plays_ref column is the ⁠$ref⁠ URL to that drive's plays – pass the drive_id to espn_cfb_game_drive_plays() to fetch the play-by-play partitioned to a single drive. This is the richest drive resource ESPN exposes; the site-v2 summary feed only carries a flattened subset.

The plays argument controls whether each drive's plays are embedded:

The participants, participants_list, team_participants, team_participants_list, and position_detail arguments shape the embedded plays and are consulted only when plays != "none". They have the same meaning as the identically named arguments on espn_cfb_game_pbp() – e.g. participants = "wide" appends the type-keyed ⁠{type}_player_*⁠ columns to every embedded play tibble. See espn_cfb_game_pbp() for the full description of each.

To get the plays efficiently the wrapper first probes the drives endpoint for inline plays (⁠items[].plays.items[]⁠); when ESPN embeds them, no extra request is made. When only a plays.$ref is present, the competition-level ⁠/plays⁠ feed is fetched once and the plays are partitioned into drives by matching each play's drive id. Per-drive plays_ref URLs are never dereferenced individually.

espn_cfb_unnest_plays() turns a plays = "list" result into the same flat table as plays = "expand" without any further HTTP.

Value

A data frame with one row per drive:

col_name types description
game_id character ESPN game identifier.
drive_id character ESPN drive id.
sequence_number character Drive sequence number within the game.
description character Drive summary text (e.g. ⁠9 plays, 75 yards, 4:12⁠).
team_id character ESPN team id of the offensive team (parsed from team_ref).
end_team_id character ESPN team id of the team in possession at drive end.
start_period integer Period (quarter) at the start of the drive.
start_period_type character Period type at the start of the drive (e.g. quarter).
start_clock character Game clock display value at the start of the drive.
start_clock_seconds numeric Game clock value in seconds at the start of the drive.
start_yard_line integer Yard line at the start of the drive.
start_text character Field-position text at the start of the drive.
end_period integer Period (quarter) at the end of the drive.
end_period_type character Period type at the end of the drive (e.g. quarter).
end_clock character Game clock display value at the end of the drive.
end_clock_seconds numeric Game clock value in seconds at the end of the drive.
end_yard_line integer Yard line at the end of the drive.
end_text character Field-position text at the end of the drive.
time_elapsed character Elapsed game time for the drive (MM:SS).
time_elapsed_seconds numeric Elapsed game time for the drive, in seconds.
yards integer Total yards gained on the drive.
offensive_plays integer Number of offensive plays on the drive.
is_score logical TRUE if the drive resulted in a score.
result character Drive result code (e.g. PUNT, TD).
short_display_result character Short drive-result label.
display_result character Drive-result label (e.g. Punt, Touchdown).
source_id character ESPN data-source id for the drive.
source_description character ESPN data-source description (e.g. Feed).
drive_ref character ⁠$ref⁠ URL to the drive resource itself.
team_ref character ⁠$ref⁠ URL to the offensive team resource.
end_team_ref character ⁠$ref⁠ URL to the team in possession at drive end.
plays_ref character ⁠$ref⁠ URL to the drive's plays resource.

When plays = "list", an additional plays list-column is appended – each cell a tibble in the full espn_cfb_game_pbp() schema. When plays = "expand", the flat one-row-per-play table is returned instead: every column of espn_cfb_game_pbp() plus the drive-level columns above carried alongside each play with a drive_ prefix.

See Also

Other ESPN CFB Functions: espn_cfb_award(), espn_cfb_awards(), espn_cfb_clear_cache(), espn_cfb_coach(), espn_cfb_coach_record(), espn_cfb_coaches(), espn_cfb_franchise(), espn_cfb_franchises(), espn_cfb_futures(), espn_cfb_game_broadcasts(), espn_cfb_game_drive_plays(), espn_cfb_game_leaders(), espn_cfb_game_odds(), espn_cfb_game_pbp(), espn_cfb_game_play(), espn_cfb_game_player_box(), espn_cfb_game_player_statistics(), espn_cfb_game_powerindex(), espn_cfb_game_predictor(), espn_cfb_game_probabilities(), espn_cfb_game_situation(), espn_cfb_game_status(), espn_cfb_game_team_leaders(), espn_cfb_game_team_linescores(), espn_cfb_game_team_records(), espn_cfb_game_team_roster(), espn_cfb_game_team_statistics(), espn_cfb_game_teams(), espn_cfb_groups(), espn_cfb_pbp_v2(), espn_cfb_player(), espn_cfb_player_career_stats(), espn_cfb_player_eventlog(), espn_cfb_player_gamelog(), espn_cfb_player_overview(), espn_cfb_player_seasons(), espn_cfb_player_splits(), espn_cfb_player_stats_v3(), espn_cfb_players(), espn_cfb_position(), espn_cfb_positions(), espn_cfb_powerindex(), espn_cfb_qbr(), espn_cfb_rankings(), espn_cfb_recruits(), espn_cfb_season_info(), espn_cfb_season_types(), espn_cfb_season_weeks(), espn_cfb_seasons(), espn_cfb_standings(), espn_cfb_team(), espn_cfb_team_ats(), espn_cfb_team_awards(), espn_cfb_team_coaches(), espn_cfb_team_events(), espn_cfb_team_leaders(), espn_cfb_team_powerindex(), espn_cfb_team_ranks(), espn_cfb_team_record(), espn_cfb_team_roster(), espn_cfb_team_schedule(), espn_cfb_teams(), espn_cfb_unnest_plays(), espn_cfb_venue(), espn_cfb_venues(), espn_cfb_week_rankings()

Examples


  try(espn_cfb_game_drives(game_id = 401628339))
  try(espn_cfb_game_drives(game_id = 401628339, plays = "list"))
  try(espn_cfb_game_drives(game_id = 401628339, plays = "expand"))
  try(espn_cfb_game_drives(game_id = 401628339, team_detail = FALSE))

ESPN College Football Game Leaders

Description

Get the per-game statistical leaders for a single college football game – one row per leader within each statistical category, both teams combined.

Usage

espn_cfb_game_leaders(game_id = NULL, team_detail = TRUE)

Arguments

game_id

(Integer required): ESPN game identifier.

team_detail

(Logical): when TRUE (default), fetch the ESPN team catalog once and join friendly team fields next to the team_id column (see Details). Set FALSE to skip the catalog fetch and the join.

Details

Wraps the ESPN core-v2 endpoint events/{game_id}/competitions/{game_id}/leaders. The competition id always equals the game id. Returns one row per leader within each leader category (passing, rushing, receiving, ...). ESPN publishes roughly 22 categories per game; each category lists a small number of leading athletes. This is the game-wide leaders resource – distinct from espn_cfb_game_team_leaders(), which returns the leaders for a single competitor (team).

When team_detail = TRUE (the default) the ESPN team catalog (espn_cfb_teams()) is fetched once and friendly team fields are joined in next to the team_id column – team_name, team_abbreviation, team_location, team_display_name, team_short_display_name, team_nickname, team_color, team_alternate_color, team_logo_href, and team_logo_dark_href, inserted immediately after team_id. A catalog failure degrades to NA rather than erroring the wrapper. Set team_detail = FALSE to skip the catalog fetch and the join.

Value

A data frame with one row per leader-in-category:

col_name types description
game_id character ESPN game identifier.
category_name character Leader-category key (e.g. passingLeader).
category_display_name character Human-readable leader-category name.
category_short_display_name character Short human-readable leader-category name.
category_abbreviation character Leader-category abbreviation.
leader_rank integer Rank of the athlete within the category (1 = top).
athlete_id character ESPN athlete id (parsed from athlete_ref).
team_id character ESPN team id of the athlete's team (parsed from team_ref).
team_name character Team nickname; team_detail = TRUE only.
team_abbreviation character Team abbreviation; team_detail = TRUE only.
team_location character Team location / school name; team_detail = TRUE only.
team_display_name character Full team display name; team_detail = TRUE only.
team_short_display_name character Short team display name; team_detail = TRUE only.
team_nickname character Team nickname label; team_detail = TRUE only.
team_color character Primary team color; team_detail = TRUE only.
team_alternate_color character Alternate team color; team_detail = TRUE only.
team_logo_href character Default team logo URL; team_detail = TRUE only.
team_logo_dark_href character Dark-variant team logo URL; team_detail = TRUE only.
display_value character Display-formatted stat line for the leader.
value numeric Numeric leading-stat value.
athlete_ref character ⁠$ref⁠ URL to the athlete resource.
team_ref character ⁠$ref⁠ URL to the team resource.
statistics_ref character ⁠$ref⁠ URL to the athlete's game-statistics resource.

See Also

Other ESPN CFB Functions: espn_cfb_award(), espn_cfb_awards(), espn_cfb_clear_cache(), espn_cfb_coach(), espn_cfb_coach_record(), espn_cfb_coaches(), espn_cfb_franchise(), espn_cfb_franchises(), espn_cfb_futures(), espn_cfb_game_broadcasts(), espn_cfb_game_drive_plays(), espn_cfb_game_drives(), espn_cfb_game_odds(), espn_cfb_game_pbp(), espn_cfb_game_play(), espn_cfb_game_player_box(), espn_cfb_game_player_statistics(), espn_cfb_game_powerindex(), espn_cfb_game_predictor(), espn_cfb_game_probabilities(), espn_cfb_game_situation(), espn_cfb_game_status(), espn_cfb_game_team_leaders(), espn_cfb_game_team_linescores(), espn_cfb_game_team_records(), espn_cfb_game_team_roster(), espn_cfb_game_team_statistics(), espn_cfb_game_teams(), espn_cfb_groups(), espn_cfb_pbp_v2(), espn_cfb_player(), espn_cfb_player_career_stats(), espn_cfb_player_eventlog(), espn_cfb_player_gamelog(), espn_cfb_player_overview(), espn_cfb_player_seasons(), espn_cfb_player_splits(), espn_cfb_player_stats_v3(), espn_cfb_players(), espn_cfb_position(), espn_cfb_positions(), espn_cfb_powerindex(), espn_cfb_qbr(), espn_cfb_rankings(), espn_cfb_recruits(), espn_cfb_season_info(), espn_cfb_season_types(), espn_cfb_season_weeks(), espn_cfb_seasons(), espn_cfb_standings(), espn_cfb_team(), espn_cfb_team_ats(), espn_cfb_team_awards(), espn_cfb_team_coaches(), espn_cfb_team_events(), espn_cfb_team_leaders(), espn_cfb_team_powerindex(), espn_cfb_team_ranks(), espn_cfb_team_record(), espn_cfb_team_roster(), espn_cfb_team_schedule(), espn_cfb_teams(), espn_cfb_unnest_plays(), espn_cfb_venue(), espn_cfb_venues(), espn_cfb_week_rankings()

Examples


  try(espn_cfb_game_leaders(game_id = 401628339))
  try(espn_cfb_game_leaders(game_id = 401628339, team_detail = FALSE))

ESPN College Football Game Odds

Description

Get the sportsbook betting lines (spread, over/under, moneyline) for a single college football game – one row per provider.

Usage

espn_cfb_game_odds(game_id = NULL, line_history = FALSE)

Arguments

game_id

(Integer required): ESPN game identifier.

line_history

(Logical): controls the output shape. One of:

  • FALSE (default) – the summary output, one row per odds provider, with the columns shown in the Value table below.

  • TRUE – a long frame capturing the open / close / current line snapshots, one row per (provider x snapshot x market) (see Details).

Details

Wraps the ESPN core-v2 endpoint events/{game_id}/competitions/{game_id}/odds. Returns one row per odds provider (sportsbook). details is ESPN's headline line string (e.g. "UGA -54.5"); spread and over_under are the numeric spread and total. Home/away spread odds and moneylines are pulled from the nested homeTeamOdds / awayTeamOdds blocks. The over_odds and under_odds are the American-odds prices on the game total. With line_history = TRUE the per-provider open / close / current line snapshots are expanded instead (see Details).

When line_history = TRUE the returned frame is in long format, one row per (provider x snapshot x market), with columns: game_id, provider_id, provider_name, snapshot (one of open, close, current), market (e.g. over, under, total, pointSpread, spread, moneyLine), side (game, home, or away), american (the American-odds string), value (the numeric/decimal value), and display_value.

Value

A data frame with one row per odds provider (when line_history = FALSE):

col_name types description
game_id character ESPN game identifier.
provider_id character ESPN odds-provider (sportsbook) id.
provider_name character Odds-provider name (e.g. ⁠ESPN BET⁠).
provider_priority integer ESPN display priority of the odds provider.
details character ESPN's headline line string (e.g. UGA -54.5).
over_under numeric Game total (over/under) points line.
spread numeric Point spread (negative favors the home team).
over_odds numeric American odds price on the over.
under_odds numeric American odds price on the under.
home_favorite logical TRUE if the home team is the favorite.
home_underdog logical TRUE if the home team is the underdog.
away_favorite logical TRUE if the away team is the favorite.
away_underdog logical TRUE if the away team is the underdog.
home_spread_odds numeric American odds price on the home-team spread.
away_spread_odds numeric American odds price on the away-team spread.
home_money_line character Home-team moneyline (American odds).
away_money_line character Away-team moneyline (American odds).
moneyline_winner logical TRUE if the moneyline favorite won.
spread_winner logical TRUE if the spread favorite covered.

See Also

Other ESPN CFB Functions: espn_cfb_award(), espn_cfb_awards(), espn_cfb_clear_cache(), espn_cfb_coach(), espn_cfb_coach_record(), espn_cfb_coaches(), espn_cfb_franchise(), espn_cfb_franchises(), espn_cfb_futures(), espn_cfb_game_broadcasts(), espn_cfb_game_drive_plays(), espn_cfb_game_drives(), espn_cfb_game_leaders(), espn_cfb_game_pbp(), espn_cfb_game_play(), espn_cfb_game_player_box(), espn_cfb_game_player_statistics(), espn_cfb_game_powerindex(), espn_cfb_game_predictor(), espn_cfb_game_probabilities(), espn_cfb_game_situation(), espn_cfb_game_status(), espn_cfb_game_team_leaders(), espn_cfb_game_team_linescores(), espn_cfb_game_team_records(), espn_cfb_game_team_roster(), espn_cfb_game_team_statistics(), espn_cfb_game_teams(), espn_cfb_groups(), espn_cfb_pbp_v2(), espn_cfb_player(), espn_cfb_player_career_stats(), espn_cfb_player_eventlog(), espn_cfb_player_gamelog(), espn_cfb_player_overview(), espn_cfb_player_seasons(), espn_cfb_player_splits(), espn_cfb_player_stats_v3(), espn_cfb_players(), espn_cfb_position(), espn_cfb_positions(), espn_cfb_powerindex(), espn_cfb_qbr(), espn_cfb_rankings(), espn_cfb_recruits(), espn_cfb_season_info(), espn_cfb_season_types(), espn_cfb_season_weeks(), espn_cfb_seasons(), espn_cfb_standings(), espn_cfb_team(), espn_cfb_team_ats(), espn_cfb_team_awards(), espn_cfb_team_coaches(), espn_cfb_team_events(), espn_cfb_team_leaders(), espn_cfb_team_powerindex(), espn_cfb_team_ranks(), espn_cfb_team_record(), espn_cfb_team_roster(), espn_cfb_team_schedule(), espn_cfb_teams(), espn_cfb_unnest_plays(), espn_cfb_venue(), espn_cfb_venues(), espn_cfb_week_rankings()

Examples


  try(espn_cfb_game_odds(game_id = 401628339))
  try(espn_cfb_game_odds(game_id = 401628339, line_history = TRUE))

ESPN College Football Game Plays (Core-v2 Play-by-Play)

Description

Get the full core-v2 play-by-play feed for a single college football game – one row per play, with down/distance, clock, score, and yardage.

Usage

espn_cfb_game_pbp(
  game_id = NULL,
  participants = c("none", "wide", "long"),
  participants_list = FALSE,
  team_participants = c("none", "wide"),
  team_participants_list = FALSE,
  team_detail = TRUE
)

Arguments

game_id

(Integer required): ESPN game identifier.

participants

(Character): controls whether each play's nested participants[] array (the athletes credited on the play) is attached. One of:

  • "none" (default) – the play frame is returned unchanged; no extra HTTP call is made.

  • "wide" – one row per play, with type-keyed ⁠{type}_player_*⁠ columns appended (see Details).

  • "long" – one row per play x participant (see Details).

participants_list

(Logical): when TRUE, append a single list-column named participants holding each play's full participant detail – including the per-participant stats[] that "wide" mode drops. Defaults to FALSE. This is independent of and combinable with the participants argument (see Details).

team_participants

(Character): controls whether each play's nested teamParticipants[] array (the team(s) credited on the play) is attached as type-keyed columns. One of:

  • "none" (default) – no team-participant columns are added.

  • "wide" – one row per play, with type-keyed ⁠{type}_team_*⁠ columns appended (see Details).

team_participants_list

(Logical): when TRUE, append a single list-column named team_participants holding each play's full teamParticipants[] detail as a nested tibble. Defaults to FALSE. This is independent of and combinable with the team_participants argument (see Details).

team_detail

(Logical): when TRUE (default), the ESPN team catalog (espn_cfb_teams()) is fetched once and friendly team fields are joined in next to every team-id column in the output (team_id, start_team_id, end_team_id, plus any optional ⁠{type}_team_id⁠ / ⁠{type}_player_team_id⁠ columns). For each id column X_id the sibling columns X_name, X_abbreviation, X_location, X_display_name, X_short_display_name, X_nickname, X_color, X_alternate_color, X_logo_href, X_logo_dark_href are inserted immediately after it. A catalog failure degrades to NA rather than erroring the wrapper. Set FALSE to skip the catalog fetch and the join.

Details

Wraps the paginated ESPN core-v2 endpoint events/{game_id}/competitions/{game_id}/plays. The endpoint is paginated; this wrapper loops every page and stacks the results into one frame – one row per play. Each play carries the start and end down/distance/yard-line, the play type, period and game clock, the running score, and the offensive team.

This is the core-v2 play feed, distinct from espn_cfb_pbp(), which parses the site-v2 game-summary feed and (optionally) computes EPA/WPA. Use this wrapper when you want the raw core-v2 play schema with stable ⁠$ref⁠-derived ids; use espn_cfb_pbp() for the modeled play-by-play.

When participants = "wide", the base play schema is kept intact and six columns are appended for every participant type that appears anywhere in the game. The column names are dynamic – one set per participant type present (e.g. passer, rusher, receiver, tackler, sacked_by, pass_defender, kicker, returner). ESPN's camelCase types are snake-cased (sackedBy -> sacked_by). For each type the appended columns are:

Participant stats[] are not carried in wide mode – use "long" for the per-participant stat lines.

When participants = "long", the frame is expanded to one row per play x participant with participant_index, participant_athlete_id, participant_type, participant_order, the roster-joined participant_athlete_name / participant_position / participant_jersey / participant_team_id, and the participant's stats pivoted to named ⁠pstat_<statname>⁠ columns. Plays with zero participants still yield one row (participant fields NA).

When participants_list = TRUE, a single list-column named participants is appended. Each cell is a tibble with one row per participant on that play and columns participant_index (1-based, ESPN order), type (snake_cased, e.g. sacked_by, pass_defender), athlete_id, athlete_name (roster-joined), order, position_id, plus one column per participant stat[] name (dplyr::bind_rows NA-fills participants whose stat sets differ). Plays with no participants carry an empty 0-row tibble, never NULL. This option is independent of participants and composes with any of its modes – e.g. ⁠participants = "wide", participants_list = TRUE⁠ yields the type-keyed ⁠{type}_player_*⁠ columns and the participants list-column, while ⁠participants = "none", participants_list = TRUE⁠ adds only the list-column. With participants = "long" the list-column repeats per play x participant row. The raw plays are fetched only once even when both options are active.

When team_participants = "wide", three columns are appended for every teamParticipants[] type present anywhere in the game (ESPN ships offense / defense). The column names are dynamic – one set per type, snake-cased: ⁠{type}_team_id⁠ (scalar character, the first occurrence of that type on the play), ⁠{type}_team_order⁠ (scalar integer, ESPN's display order), and ⁠{type}_team_ref⁠ (scalar character, the ⁠$ref⁠ URL to that team resource). Plays with none of a type carry NA.

When team_participants_list = TRUE, a single list-column named team_participants is appended. Each cell is a tibble with one row per team credited on the play and columns team_participant_index (1-based, ESPN order), team_id, team_ref, order, and type (e.g. offense, defense). A play with no team participants carries an empty 0-row tibble, never NULL. This option is independent of team_participants and composes with it – e.g. ⁠team_participants = "wide", team_participants_list = TRUE⁠ yields both the type-keyed ⁠{type}_team_*⁠ columns and the team_participants list-column, while team_participants = "none" adds neither.

When team_detail = TRUE (the default), the ESPN team catalog (espn_cfb_teams()) is fetched once and joined onto every team-id column the output carries – the base team_id / start_team_id / end_team_id, plus any optional ⁠{type}_team_id⁠ (from team_participants = "wide") and ⁠{type}_player_team_id⁠ (from participants = "long") columns. For each id column X_id the friendly siblings X_name, X_abbreviation, X_location, X_display_name, X_short_display_name, X_nickname, X_color, X_alternate_color, X_logo_href, and X_logo_dark_href are inserted immediately after it (e.g. team_id -> team_name, team_abbreviation, ...; start_team_id -> start_team_name, ...). Rows whose id is missing or unmatched receive NA, and a catalog-fetch failure degrades the whole set to NA rather than erroring the wrapper. With team_detail = FALSE the friendly columns (and the catalog fetch) are skipped.

Value

A data frame with one row per play:

col_name types description
game_id character ESPN game identifier.
play_id character ESPN play id.
sequence_number character Play sequence number within the game.
type_id character Play-type id.
type_text character Play-type text (e.g. ⁠Pass Reception⁠).
type_abbreviation character Play-type abbreviation (e.g. RUSH, TD).
text character Full play description.
short_text character Short play description.
alternative_text character Alternative play description.
short_alternative_text character Short alternative play description.
period integer Period (quarter) number.
clock character Game clock display value at the play (MM:SS).
clock_seconds numeric Game clock value in seconds at the play.
home_score integer Home-team score after the play.
away_score integer Away-team score after the play.
scoring_play logical TRUE if the play resulted in a score.
score_value integer Points scored on the play.
priority logical TRUE if ESPN flags the play as a priority highlight.
is_penalty logical TRUE if the play was a penalty.
is_turnover logical TRUE if the play was a turnover.
stat_yardage integer Yards gained or lost on the play.
scoring_type_name character Scoring-type key on a scoring play (e.g. touchdown).
scoring_type_display_name character Human-readable scoring-type name.
scoring_type_abbreviation character Scoring-type abbreviation (e.g. TD, FG).
point_after_attempt_id integer Point-after-attempt id on a scoring play.
point_after_attempt_text character Point-after-attempt text (e.g. ⁠Extra Point Good⁠).
point_after_attempt_abbreviation character Point-after-attempt abbreviation.
point_after_attempt_value integer Points added by the point-after attempt.
start_down integer Down at the start of the play.
start_distance integer Yards to go at the start of the play.
start_yard_line integer Yard line at the start of the play.
start_yards_to_endzone integer Yards to the end zone at the start of the play.
start_down_distance_text character Down-and-distance text at the start of the play.
start_short_down_distance_text character Short down-and-distance text at the start of the play.
start_possession_text character Field-position text at the start of the play.
start_team_id character ESPN team id in possession at the start of the play.
end_down integer Down at the end of the play.
end_distance integer Yards to go at the end of the play.
end_yard_line integer Yard line at the end of the play.
end_yards_to_endzone integer Yards to the end zone at the end of the play.
end_down_distance_text character Down-and-distance text at the end of the play.
end_short_down_distance_text character Short down-and-distance text at the end of the play.
end_possession_text character Field-position text at the end of the play.
end_team_id character ESPN team id in possession at the end of the play.
team_id character ESPN team id of the offensive team (parsed from team_ref).
drive_play_id character ESPN drive id the play belongs to (parsed from drive_ref).
wallclock character Real-world ISO timestamp of the play.
modified character ISO timestamp the play record was last modified.
play_ref character ⁠$ref⁠ URL to the play resource itself.
team_ref character ⁠$ref⁠ URL to the offensive team resource.
start_team_ref character ⁠$ref⁠ URL to the team in possession at the play start.
end_team_ref character ⁠$ref⁠ URL to the team in possession at the play end.
drive_ref character ⁠$ref⁠ URL to the play's drive resource.
probability_ref character ⁠$ref⁠ URL to the play's win-probability resource.

The optional participant and team-participant columns are described in Details – they are added only when the corresponding argument requests them.

See Also

Other ESPN CFB Functions: espn_cfb_award(), espn_cfb_awards(), espn_cfb_clear_cache(), espn_cfb_coach(), espn_cfb_coach_record(), espn_cfb_coaches(), espn_cfb_franchise(), espn_cfb_franchises(), espn_cfb_futures(), espn_cfb_game_broadcasts(), espn_cfb_game_drive_plays(), espn_cfb_game_drives(), espn_cfb_game_leaders(), espn_cfb_game_odds(), espn_cfb_game_play(), espn_cfb_game_player_box(), espn_cfb_game_player_statistics(), espn_cfb_game_powerindex(), espn_cfb_game_predictor(), espn_cfb_game_probabilities(), espn_cfb_game_situation(), espn_cfb_game_status(), espn_cfb_game_team_leaders(), espn_cfb_game_team_linescores(), espn_cfb_game_team_records(), espn_cfb_game_team_roster(), espn_cfb_game_team_statistics(), espn_cfb_game_teams(), espn_cfb_groups(), espn_cfb_pbp_v2(), espn_cfb_player(), espn_cfb_player_career_stats(), espn_cfb_player_eventlog(), espn_cfb_player_gamelog(), espn_cfb_player_overview(), espn_cfb_player_seasons(), espn_cfb_player_splits(), espn_cfb_player_stats_v3(), espn_cfb_players(), espn_cfb_position(), espn_cfb_positions(), espn_cfb_powerindex(), espn_cfb_qbr(), espn_cfb_rankings(), espn_cfb_recruits(), espn_cfb_season_info(), espn_cfb_season_types(), espn_cfb_season_weeks(), espn_cfb_seasons(), espn_cfb_standings(), espn_cfb_team(), espn_cfb_team_ats(), espn_cfb_team_awards(), espn_cfb_team_coaches(), espn_cfb_team_events(), espn_cfb_team_leaders(), espn_cfb_team_powerindex(), espn_cfb_team_ranks(), espn_cfb_team_record(), espn_cfb_team_roster(), espn_cfb_team_schedule(), espn_cfb_teams(), espn_cfb_unnest_plays(), espn_cfb_venue(), espn_cfb_venues(), espn_cfb_week_rankings()

Examples


  try(espn_cfb_game_pbp(game_id = 401628339))
  try(espn_cfb_game_pbp(game_id = 401628339, participants = "wide"))
  try(espn_cfb_game_pbp(game_id = 401628339, participants = "wide",
                        participants_list = TRUE))
  try(espn_cfb_game_pbp(game_id = 401628339, team_participants = "wide",
                        team_participants_list = TRUE))
  try(espn_cfb_game_pbp(game_id = 401628339, team_detail = FALSE))

ESPN College Football Game Play (Single Play Detail)

Description

Get the full detail object for a single play of a college football game – one row with the play type, text, score, clock, down/distance, and win-probability delta.

Usage

espn_cfb_game_play(
  game_id = NULL,
  play_id = NULL,
  participants = c("none", "wide", "long"),
  participants_list = FALSE,
  team_participants = c("none", "wide"),
  team_participants_list = FALSE,
  team_detail = TRUE
)

Arguments

game_id

(Integer required): ESPN game identifier.

play_id

(Character required): ESPN play id (from espn_cfb_game_pbp()). Supply as a character string – the id is too large for an exact numeric.

participants

(Character): controls whether the play's nested participants[] array (the athletes credited on the play) is attached. One of:

  • "none" (default) – the single-row play frame is returned unchanged; no extra HTTP call is made.

  • "wide" – the single row gains type-keyed ⁠{type}_player_*⁠ columns (see Details).

  • "long" – the frame is expanded to one row per participant (see Details).

participants_list

(Logical): when TRUE, append a single list-column named participants holding the play's full participant detail – including the per-participant stats[] that "wide" mode drops. Defaults to FALSE. This is independent of and combinable with the participants argument (see Details).

team_participants

(Character): controls whether the play's nested teamParticipants[] array (the team(s) credited on the play) is attached as type-keyed columns. One of:

  • "none" (default) – no team-participant columns are added.

  • "wide" – the single row gains type-keyed ⁠{type}_team_*⁠ columns (see Details).

team_participants_list

(Logical): when TRUE, append a single list-column named team_participants holding the play's full teamParticipants[] detail as a nested tibble. Defaults to FALSE. This is independent of and combinable with the team_participants argument (see Details).

team_detail

(Logical): when TRUE (default), the ESPN team catalog (espn_cfb_teams()) is fetched once and friendly team fields are joined in next to every team-id column in the output (team_id, start_team_id, end_team_id, plus any optional ⁠{type}_team_id⁠ / ⁠{type}_player_team_id⁠ columns). For each id column X_id the sibling columns X_name, X_abbreviation, X_location, X_display_name, X_short_display_name, X_nickname, X_color, X_alternate_color, X_logo_href, X_logo_dark_href are inserted immediately after it. A catalog failure degrades to NA rather than erroring the wrapper. Set FALSE to skip the catalog fetch and the join.

Details

Wraps the ESPN core-v2 endpoint events/{game_id}/competitions/{game_id}/plays/{play_id}. The competition id always equals the game id. Returns a single-row data frame describing one play in full. Harvest the play_id from the competition-level espn_cfb_game_pbp() feed (its play_id column) or from espn_cfb_game_drive_plays(). Use this wrapper for play drill-down when you need a single play's complete object rather than the whole game feed.

ESPN play ids are 18-digit integers that exceed R's exact double-precision range – pass play_id as a character string (e.g. "401628339101927401") so no precision is lost. A bare numeric literal will be silently rounded and the lookup will 404.

When participants = "wide", the base play schema is kept intact and six columns are appended for every participant type on the play. The column names are dynamic – one set per participant type present (e.g. passer, rusher, receiver, tackler, sacked_by, pass_defender). ESPN's camelCase types are snake-cased (sackedBy -> sacked_by). For each type the appended columns are ⁠{type}_player_id⁠ (scalar character, the first occurrence of that type on the play), ⁠{type}_player_name⁠ (scalar character, that athlete's roster-joined name), ⁠{type}_player_position⁠ (scalar character, that athlete's position abbreviation from the ESPN position catalog), ⁠{type}_player_position_name⁠ (scalar character, that athlete's position name), ⁠{type}_player_ids⁠ (a list-column: a character vector of every athlete id of that type, in ESPN order; character(0) if none), and ⁠{type}_player_names⁠ (a list-column: the parallel vector of roster-joined names). Participant stats[] are not carried in wide mode – use "long" for the per-participant stats.

When participants = "long", the frame is expanded to one row per participant with participant_index, participant_athlete_id, participant_type, participant_order, the roster-joined participant_athlete_name / participant_position / participant_jersey / participant_team_id, and the participant's stats pivoted to named ⁠pstat_<statname>⁠ columns. A play with zero participants still yields one row (participant fields NA).

When participants_list = TRUE, a single list-column named participants is appended. Its one cell is a tibble with one row per participant on the play and columns participant_index (1-based, ESPN order), type (snake_cased, e.g. sacked_by, pass_defender), athlete_id, athlete_name (roster-joined), order, position_id, plus one column per participant stat[] name (dplyr::bind_rows NA-fills participants whose stat sets differ). A play with no participants carries an empty 0-row tibble, never NULL. This option is independent of participants and composes with any of its modes – e.g. ⁠participants = "wide", participants_list = TRUE⁠ yields the type-keyed ⁠{type}_player_*⁠ columns and the participants list-column. With participants = "long" the list-column repeats per participant row.

When team_participants = "wide", three columns are appended for every teamParticipants[] type on the play (ESPN ships offense / defense). The column names are dynamic – one set per type, snake-cased: ⁠{type}_team_id⁠ (scalar character, the first occurrence of that type on the play), ⁠{type}_team_order⁠ (scalar integer, ESPN's display order), and ⁠{type}_team_ref⁠ (scalar character, the ⁠$ref⁠ URL to that team resource). A play with none of a type carries NA.

When team_participants_list = TRUE, a single list-column named team_participants is appended. Its one cell is a tibble with one row per team credited on the play and columns team_participant_index (1-based, ESPN order), team_id, team_ref, order, and type (e.g. offense, defense). A play with no team participants carries an empty 0-row tibble, never NULL. This option is independent of team_participants and composes with it – e.g. ⁠team_participants = "wide", team_participants_list = TRUE⁠ yields both the type-keyed ⁠{type}_team_*⁠ columns and the team_participants list-column, while team_participants = "none" adds neither.

When team_detail = TRUE (the default), the ESPN team catalog (espn_cfb_teams()) is fetched once and joined onto every team-id column the output carries – the base team_id / start_team_id / end_team_id, plus any optional ⁠{type}_team_id⁠ (from team_participants = "wide") and ⁠{type}_player_team_id⁠ (from participants = "long") columns. For each id column X_id the friendly siblings X_name, X_abbreviation, X_location, X_display_name, X_short_display_name, X_nickname, X_color, X_alternate_color, X_logo_href, and X_logo_dark_href are inserted immediately after it (e.g. team_id -> team_name, team_abbreviation, ...; start_team_id -> start_team_name, ...). Rows whose id is missing or unmatched receive NA, and a catalog-fetch failure degrades the whole set to NA rather than erroring the wrapper. With team_detail = FALSE the friendly columns (and the catalog fetch) are skipped.

Value

A data frame with one row describing the play:

col_name types description
game_id character ESPN game identifier.
play_id character ESPN play id.
sequence_number character Play sequence number within the game.
type_id character Play-type id.
type_text character Play-type text (e.g. ⁠Pass Reception⁠).
type_abbreviation character Play-type abbreviation (e.g. RUSH, TD).
text character Full play description.
short_text character Short play description.
alternative_text character Alternative play description.
short_alternative_text character Short alternative play description.
period integer Period (quarter) number.
clock character Game clock display value at the play (MM:SS).
clock_seconds numeric Game clock value in seconds at the play.
home_score integer Home-team score after the play.
away_score integer Away-team score after the play.
scoring_play logical TRUE if the play resulted in a score.
score_value integer Points scored on the play.
priority logical TRUE if ESPN flags the play as a priority highlight.
is_penalty logical TRUE if the play was a penalty.
is_turnover logical TRUE if the play was a turnover.
stat_yardage integer Yards gained or lost on the play.
scoring_type_name character Scoring-type key on a scoring play (e.g. touchdown).
scoring_type_display_name character Human-readable scoring-type name.
scoring_type_abbreviation character Scoring-type abbreviation (e.g. TD, FG).
point_after_attempt_id integer Point-after-attempt id on a scoring play.
point_after_attempt_text character Point-after-attempt text (e.g. ⁠Extra Point Good⁠).
point_after_attempt_abbreviation character Point-after-attempt abbreviation.
point_after_attempt_value integer Points added by the point-after attempt.
start_down integer Down at the start of the play.
start_distance integer Yards to go at the start of the play.
start_yard_line integer Yard line at the start of the play.
start_yards_to_endzone integer Yards to the end zone at the start of the play.
start_down_distance_text character Down-and-distance text at the start of the play.
start_short_down_distance_text character Short down-and-distance text at the start of the play.
start_possession_text character Field-position text at the start of the play.
start_team_id character ESPN team id in possession at the start of the play.
end_down integer Down at the end of the play.
end_distance integer Yards to go at the end of the play.
end_yard_line integer Yard line at the end of the play.
end_yards_to_endzone integer Yards to the end zone at the end of the play.
end_down_distance_text character Down-and-distance text at the end of the play.
end_short_down_distance_text character Short down-and-distance text at the end of the play.
end_possession_text character Field-position text at the end of the play.
end_team_id character ESPN team id in possession at the end of the play.
team_id character ESPN team id of the offensive team (parsed from team_ref).
drive_play_id character ESPN drive id the play belongs to (parsed from drive_ref).
wallclock character Real-world ISO timestamp of the play.
modified character ISO timestamp the play record was last modified.
play_ref character ⁠$ref⁠ URL to the play resource itself.
team_ref character ⁠$ref⁠ URL to the offensive team resource.
start_team_ref character ⁠$ref⁠ URL to the team in possession at the play start.
end_team_ref character ⁠$ref⁠ URL to the team in possession at the play end.
drive_ref character ⁠$ref⁠ URL to the play's drive resource.
probability_ref character ⁠$ref⁠ URL to the play's win-probability resource.

The optional participant and team-participant columns are described in Details – they are added only when the corresponding argument requests them.

See Also

Other ESPN CFB Functions: espn_cfb_award(), espn_cfb_awards(), espn_cfb_clear_cache(), espn_cfb_coach(), espn_cfb_coach_record(), espn_cfb_coaches(), espn_cfb_franchise(), espn_cfb_franchises(), espn_cfb_futures(), espn_cfb_game_broadcasts(), espn_cfb_game_drive_plays(), espn_cfb_game_drives(), espn_cfb_game_leaders(), espn_cfb_game_odds(), espn_cfb_game_pbp(), espn_cfb_game_player_box(), espn_cfb_game_player_statistics(), espn_cfb_game_powerindex(), espn_cfb_game_predictor(), espn_cfb_game_probabilities(), espn_cfb_game_situation(), espn_cfb_game_status(), espn_cfb_game_team_leaders(), espn_cfb_game_team_linescores(), espn_cfb_game_team_records(), espn_cfb_game_team_roster(), espn_cfb_game_team_statistics(), espn_cfb_game_teams(), espn_cfb_groups(), espn_cfb_pbp_v2(), espn_cfb_player(), espn_cfb_player_career_stats(), espn_cfb_player_eventlog(), espn_cfb_player_gamelog(), espn_cfb_player_overview(), espn_cfb_player_seasons(), espn_cfb_player_splits(), espn_cfb_player_stats_v3(), espn_cfb_players(), espn_cfb_position(), espn_cfb_positions(), espn_cfb_powerindex(), espn_cfb_qbr(), espn_cfb_rankings(), espn_cfb_recruits(), espn_cfb_season_info(), espn_cfb_season_types(), espn_cfb_season_weeks(), espn_cfb_seasons(), espn_cfb_standings(), espn_cfb_team(), espn_cfb_team_ats(), espn_cfb_team_awards(), espn_cfb_team_coaches(), espn_cfb_team_events(), espn_cfb_team_leaders(), espn_cfb_team_powerindex(), espn_cfb_team_ranks(), espn_cfb_team_record(), espn_cfb_team_roster(), espn_cfb_team_schedule(), espn_cfb_teams(), espn_cfb_unnest_plays(), espn_cfb_venue(), espn_cfb_venues(), espn_cfb_week_rankings()

Examples


  try(espn_cfb_game_play(game_id = 401628339,
                         play_id = "401628339101927401"))
  try(espn_cfb_game_play(game_id = 401628339,
                         play_id = "401628339101927401",
                         participants = "long"))
  try(espn_cfb_game_play(game_id = 401628339,
                         play_id = "401628339101927401",
                         participants = "wide",
                         participants_list = TRUE))
  try(espn_cfb_game_play(game_id = 401628339,
                         play_id = "401628339101927401",
                         team_participants = "wide",
                         team_participants_list = TRUE))
  try(espn_cfb_game_play(game_id = 401628339,
                         play_id = "401628339101927401",
                         team_detail = FALSE))

ESPN College Football Game Player Box Score

Description

Get the full per-player box score for both teams in a single college football game – one row per (team x athlete x category x stat), in long format.

Usage

espn_cfb_game_player_box(
  game_id = NULL,
  position_detail = TRUE,
  team_detail = TRUE
)

Arguments

game_id

(Integer required): ESPN game identifier.

position_detail

(Logical): when TRUE (default), fetch the ESPN position catalog once and join it onto position_id, appending the five ⁠position_*⁠ detail columns shown in the Value table. A catalog failure degrades to NA rather than erroring the wrapper. Set FALSE to skip the extra fetch and the join.

team_detail

(Logical): when TRUE (default), fetch the ESPN team catalog (espn_cfb_teams()) once and join friendly team fields next to the team_id column – team_name, team_abbreviation, team_location, team_display_name, team_short_display_name, team_nickname, team_color, team_alternate_color, team_logo_href, and team_logo_dark_href, inserted immediately after team_id. A catalog failure degrades to NA rather than erroring the wrapper. Set FALSE to skip the catalog fetch and the join.

Details

Wraps the ESPN core-v2 endpoint events/{game_id}/competitions/{game_id}/competitors/{team_id}/statistics. This wrapper reads the teams list for the game, fetches the team statistics resource for both teams, and walks the per-category splits -> categories -> athletes arrays – the per-player box-score tree that the team-level espn_cfb_game_team_statistics() wrapper (which walks categories -> stats) drops entirely.

Each athlete entry under a category carries only a ⁠$ref⁠ to that athlete's per-game statistics resource; this wrapper dereferences each unique athlete statistics ⁠$ref⁠ and flattens the nested splits -> categories -> stats tree into one long frame: one row per (team x athlete x category x stat). Athlete display names and position ids are joined from espn_cfb_game_team_roster(); a roster failure degrades to NA names rather than erroring. The long shape absorbs ESPN's habit of adding and retiring stat keys across seasons.

When position_detail = TRUE (the default) the ESPN position catalog (espn_cfb_positions()) is fetched once and joined onto position_id, so the output carries the full position name / abbreviation (see Details).

When position_detail = TRUE (the default), the position_id column (roster-joined per athlete) is enriched with five columns from the ESPN position catalog (espn_cfb_positions()): position_name, position_display_name, position_abbreviation, position_leaf, and position_parent_id. The catalog is fetched once per call. A row whose position_id is missing or unmatched receives NA for all five, and a catalog-fetch failure degrades the whole set to NA rather than erroring the wrapper. With position_detail = FALSE the five columns (and the catalog fetch) are skipped.

Value

A data frame with one row per team-athlete-category-stat:

col_name types description
game_id character ESPN game identifier.
team_id character ESPN team id (competitor id) for the team.
team_name character Team nickname; team_detail = TRUE only.
team_abbreviation character Team abbreviation; team_detail = TRUE only.
team_location character Team location / school name; team_detail = TRUE only.
team_display_name character Full team display name; team_detail = TRUE only.
team_short_display_name character Short team display name; team_detail = TRUE only.
team_nickname character Team nickname label; team_detail = TRUE only.
team_color character Primary team color; team_detail = TRUE only.
team_alternate_color character Alternate team color; team_detail = TRUE only.
team_logo_href character Default team logo URL; team_detail = TRUE only.
team_logo_dark_href character Dark-variant team logo URL; team_detail = TRUE only.
home_away character home or away.
athlete_id character ESPN athlete id (parsed from the athlete ⁠$ref⁠).
athlete_name character Athlete display name (roster-joined).
position_id character ESPN position id (roster-joined; NA if unmatched).
category_name character Stat category key (e.g. passing, rushing).
category_display character Human-readable category name.
category_short_display character Short human-readable category name.
category_summary character ESPN's summary string for the category.
stat_name character Internal stat key (e.g. passingYards).
abbreviation character Stat abbreviation.
display_name character Human-readable stat name.
short_display_name character Short human-readable stat name.
description character ESPN's description of the stat.
value numeric Stat value.
display_value character Display-formatted stat value as shown on ESPN.
statistics_ref character ⁠$ref⁠ URL to the athlete's game-statistics resource.
position_name character Position name (e.g. Quarterback); position_detail = TRUE only.
position_display_name character Human-readable position name; position_detail = TRUE only.
position_abbreviation character Position abbreviation (e.g. QB); position_detail = TRUE only.
position_leaf logical TRUE for a most-specific (leaf) position; position_detail = TRUE only.
position_parent_id character ESPN id of the parent position; position_detail = TRUE only.

See Also

Other ESPN CFB Functions: espn_cfb_award(), espn_cfb_awards(), espn_cfb_clear_cache(), espn_cfb_coach(), espn_cfb_coach_record(), espn_cfb_coaches(), espn_cfb_franchise(), espn_cfb_franchises(), espn_cfb_futures(), espn_cfb_game_broadcasts(), espn_cfb_game_drive_plays(), espn_cfb_game_drives(), espn_cfb_game_leaders(), espn_cfb_game_odds(), espn_cfb_game_pbp(), espn_cfb_game_play(), espn_cfb_game_player_statistics(), espn_cfb_game_powerindex(), espn_cfb_game_predictor(), espn_cfb_game_probabilities(), espn_cfb_game_situation(), espn_cfb_game_status(), espn_cfb_game_team_leaders(), espn_cfb_game_team_linescores(), espn_cfb_game_team_records(), espn_cfb_game_team_roster(), espn_cfb_game_team_statistics(), espn_cfb_game_teams(), espn_cfb_groups(), espn_cfb_pbp_v2(), espn_cfb_player(), espn_cfb_player_career_stats(), espn_cfb_player_eventlog(), espn_cfb_player_gamelog(), espn_cfb_player_overview(), espn_cfb_player_seasons(), espn_cfb_player_splits(), espn_cfb_player_stats_v3(), espn_cfb_players(), espn_cfb_position(), espn_cfb_positions(), espn_cfb_powerindex(), espn_cfb_qbr(), espn_cfb_rankings(), espn_cfb_recruits(), espn_cfb_season_info(), espn_cfb_season_types(), espn_cfb_season_weeks(), espn_cfb_seasons(), espn_cfb_standings(), espn_cfb_team(), espn_cfb_team_ats(), espn_cfb_team_awards(), espn_cfb_team_coaches(), espn_cfb_team_events(), espn_cfb_team_leaders(), espn_cfb_team_powerindex(), espn_cfb_team_ranks(), espn_cfb_team_record(), espn_cfb_team_roster(), espn_cfb_team_schedule(), espn_cfb_teams(), espn_cfb_unnest_plays(), espn_cfb_venue(), espn_cfb_venues(), espn_cfb_week_rankings()

Examples


  try(espn_cfb_game_player_box(game_id = 401628339))
  try(espn_cfb_game_player_box(game_id = 401628339,
                               position_detail = FALSE))
  try(espn_cfb_game_player_box(game_id = 401628339,
                               team_detail = FALSE))

ESPN College Football Game Player Statistics (Single Athlete)

Description

Get one athlete's box-score line for a single college football game – one row per stat, in long format.

Usage

espn_cfb_game_player_statistics(
  game_id = NULL,
  athlete_id = NULL,
  position_detail = TRUE,
  team_detail = TRUE
)

Arguments

game_id

(Integer required): ESPN game identifier.

athlete_id

(Integer required): ESPN athlete id (from espn_cfb_game_leaders() or a roster wrapper).

position_detail

(Logical): when TRUE (default), fetch the ESPN position catalog once and join it onto position_id, appending the five ⁠position_*⁠ detail columns shown in the Value table. A catalog failure degrades to NA rather than erroring the wrapper. Set FALSE to skip the extra fetch and the join.

team_detail

(Logical): when TRUE (default), fetch the ESPN team catalog (espn_cfb_teams()) once and join friendly team fields next to the team_id column – team_name, team_abbreviation, team_location, team_display_name, team_short_display_name, team_nickname, team_color, team_alternate_color, team_logo_href, and team_logo_dark_href, inserted immediately after team_id. A catalog failure degrades to NA rather than erroring the wrapper. Set FALSE to skip the catalog fetch and the join.

Details

Wraps the ESPN core-v2 per-game, per-player statistics resource events/{game_id}/competitions/{game_id}/competitors/{t}/roster/{a}/statistics/{s}. The competition id always equals the game id.

ESPN reaches per-player game stats through the competitor roster tree – dereferencing all ~250 athletes on the two rosters per game is impractical, so this wrapper is scoped to one athlete. It fetches the two competitor rosters, finds the entry whose athlete_id matches the supplied athlete_id, follows that athlete's statistics ⁠$ref⁠, and returns that player's stat line in long format – one row per stat, with the stat category, name, value, and display value.

For a full all-players game box score, the site-v2 game-summary feed is the better source – it returns every player's box line in one call. Use this core-v2 wrapper when you need a single athlete's stats in the core-v2 id space, e.g. drilling down from espn_cfb_game_leaders().

If the athlete is not found on either roster, or did not record stats for the game (no statistics ⁠$ref⁠), an empty data frame is returned.

When position_detail = TRUE (the default) the ESPN position catalog (espn_cfb_positions()) is fetched once and joined onto the athlete's position_id, so the output carries the full position name / abbreviation (see Details).

When position_detail = TRUE (the default), the athlete's position_id (read from the roster entry) is enriched with five columns from the ESPN position catalog (espn_cfb_positions()): position_name, position_display_name, position_abbreviation, position_leaf, and position_parent_id. The catalog is fetched once per call. If the athlete carries no position_id or it is unmatched, all five are NA, and a catalog-fetch failure degrades the whole set to NA rather than erroring the wrapper. With position_detail = FALSE the five columns (and the catalog fetch) are skipped.

Value

A data frame with one row per stat for the athlete:

col_name types description
game_id character ESPN game identifier.
athlete_id character ESPN athlete id.
team_id character ESPN team id of the athlete's team (competitor id).
team_name character Team nickname; team_detail = TRUE only.
team_abbreviation character Team abbreviation; team_detail = TRUE only.
team_location character Team location / school name; team_detail = TRUE only.
team_display_name character Full team display name; team_detail = TRUE only.
team_short_display_name character Short team display name; team_detail = TRUE only.
team_nickname character Team nickname label; team_detail = TRUE only.
team_color character Primary team color; team_detail = TRUE only.
team_alternate_color character Alternate team color; team_detail = TRUE only.
team_logo_href character Default team logo URL; team_detail = TRUE only.
team_logo_dark_href character Dark-variant team logo URL; team_detail = TRUE only.
athlete_display_name character Athlete display name (from the roster entry).
jersey character Athlete jersey number (from the roster entry).
starter logical TRUE if the athlete started the game.
did_not_play logical TRUE if the athlete did not play.
position_id character ESPN position id (from the roster entry; NA if none).
category_name character Stat-category key (e.g. passing, rushing).
category_display_name character Human-readable stat-category name.
category_short_display_name character Short human-readable stat-category name.
category_summary character ESPN's summary string for the category.
stat_name character Stat key (e.g. completions, rushingYards).
stat_display_name character Human-readable stat name.
stat_short_display_name character Short human-readable stat name.
abbreviation character Stat abbreviation.
value numeric Numeric stat value.
display_value character Display-formatted stat value.
description character ESPN's description of the stat.
position_name character Position name (e.g. Quarterback); position_detail = TRUE only.
position_display_name character Human-readable position name; position_detail = TRUE only.
position_abbreviation character Position abbreviation (e.g. QB); position_detail = TRUE only.
position_leaf logical TRUE for a most-specific (leaf) position; position_detail = TRUE only.
position_parent_id character ESPN id of the parent position; position_detail = TRUE only.

See Also

Other ESPN CFB Functions: espn_cfb_award(), espn_cfb_awards(), espn_cfb_clear_cache(), espn_cfb_coach(), espn_cfb_coach_record(), espn_cfb_coaches(), espn_cfb_franchise(), espn_cfb_franchises(), espn_cfb_futures(), espn_cfb_game_broadcasts(), espn_cfb_game_drive_plays(), espn_cfb_game_drives(), espn_cfb_game_leaders(), espn_cfb_game_odds(), espn_cfb_game_pbp(), espn_cfb_game_play(), espn_cfb_game_player_box(), espn_cfb_game_powerindex(), espn_cfb_game_predictor(), espn_cfb_game_probabilities(), espn_cfb_game_situation(), espn_cfb_game_status(), espn_cfb_game_team_leaders(), espn_cfb_game_team_linescores(), espn_cfb_game_team_records(), espn_cfb_game_team_roster(), espn_cfb_game_team_statistics(), espn_cfb_game_teams(), espn_cfb_groups(), espn_cfb_pbp_v2(), espn_cfb_player(), espn_cfb_player_career_stats(), espn_cfb_player_eventlog(), espn_cfb_player_gamelog(), espn_cfb_player_overview(), espn_cfb_player_seasons(), espn_cfb_player_splits(), espn_cfb_player_stats_v3(), espn_cfb_players(), espn_cfb_position(), espn_cfb_positions(), espn_cfb_powerindex(), espn_cfb_qbr(), espn_cfb_rankings(), espn_cfb_recruits(), espn_cfb_season_info(), espn_cfb_season_types(), espn_cfb_season_weeks(), espn_cfb_seasons(), espn_cfb_standings(), espn_cfb_team(), espn_cfb_team_ats(), espn_cfb_team_awards(), espn_cfb_team_coaches(), espn_cfb_team_events(), espn_cfb_team_leaders(), espn_cfb_team_powerindex(), espn_cfb_team_ranks(), espn_cfb_team_record(), espn_cfb_team_roster(), espn_cfb_team_schedule(), espn_cfb_teams(), espn_cfb_unnest_plays(), espn_cfb_venue(), espn_cfb_venues(), espn_cfb_week_rankings()

Examples


  try(espn_cfb_game_player_statistics(game_id = 401628339,
                                      athlete_id = 4429105))
  try(espn_cfb_game_player_statistics(game_id = 401628339,
                                      athlete_id = 4429105,
                                      position_detail = FALSE))
  try(espn_cfb_game_player_statistics(game_id = 401628339,
                                      athlete_id = 4429105,
                                      team_detail = FALSE))

ESPN College Football Game Power Index (Matchup FPI)

Description

Get ESPN's Football Power Index (FPI) matchup projections for both teams in a single college football game, in long format.

Usage

espn_cfb_game_powerindex(game_id = NULL, team_detail = TRUE)

Arguments

game_id

(Integer required): ESPN game identifier.

team_detail

(Logical): when TRUE (default), fetch the ESPN team catalog once and join friendly team fields next to the team_id column (see Details). Set FALSE to skip the catalog fetch and the join.

Details

Wraps the ESPN core-v2 endpoint events/{game_id}/competitions/{game_id}/powerindex. The endpoint returns one ⁠$ref⁠ per team; this wrapper dereferences each and flattens the per-team stats array into one long frame – one row per (team x FPI metric). Metrics include the predicted point differential, matchup quality, and game-projection components ESPN derives from FPI for that specific game. The long shape absorbs ESPN's habit of adding and retiring metrics across seasons.

When team_detail = TRUE (the default) the ESPN team catalog (espn_cfb_teams()) is fetched once and friendly team fields are joined in next to the team_id column – team_name, team_abbreviation, team_location, team_display_name, team_short_display_name, team_nickname, team_color, team_alternate_color, team_logo_href, and team_logo_dark_href. A catalog failure degrades to NA rather than erroring the wrapper. Set team_detail = FALSE to skip the catalog fetch and the join.

Value

A data frame with one row per team-metric:

col_name types description
game_id character ESPN game identifier.
season integer Season (4-digit year) of the game.
team_id character ESPN team id (parsed from team_ref).
team_name character Team nickname; team_detail = TRUE only.
team_abbreviation character Team abbreviation; team_detail = TRUE only.
team_location character Team location / school name; team_detail = TRUE only.
team_display_name character Full team display name; team_detail = TRUE only.
team_short_display_name character Short team display name; team_detail = TRUE only.
team_nickname character Team nickname label; team_detail = TRUE only.
team_color character Primary team color; team_detail = TRUE only.
team_alternate_color character Alternate team color; team_detail = TRUE only.
team_logo_href character Default team logo URL; team_detail = TRUE only.
team_logo_dark_href character Dark-variant team logo URL; team_detail = TRUE only.
stat_name character FPI metric key (e.g. teampredptdiff).
abbreviation character Metric abbreviation.
display_name character Human-readable metric name.
short_display_name character Short human-readable metric name.
value numeric Metric value.
display_value character Display-formatted metric value as shown on ESPN.
description character ESPN's description of the metric.
powerindex_ref character ⁠$ref⁠ URL to the per-team power-index resource.
team_ref character ⁠$ref⁠ URL to the team-in-season resource.

See Also

Other ESPN CFB Functions: espn_cfb_award(), espn_cfb_awards(), espn_cfb_clear_cache(), espn_cfb_coach(), espn_cfb_coach_record(), espn_cfb_coaches(), espn_cfb_franchise(), espn_cfb_franchises(), espn_cfb_futures(), espn_cfb_game_broadcasts(), espn_cfb_game_drive_plays(), espn_cfb_game_drives(), espn_cfb_game_leaders(), espn_cfb_game_odds(), espn_cfb_game_pbp(), espn_cfb_game_play(), espn_cfb_game_player_box(), espn_cfb_game_player_statistics(), espn_cfb_game_predictor(), espn_cfb_game_probabilities(), espn_cfb_game_situation(), espn_cfb_game_status(), espn_cfb_game_team_leaders(), espn_cfb_game_team_linescores(), espn_cfb_game_team_records(), espn_cfb_game_team_roster(), espn_cfb_game_team_statistics(), espn_cfb_game_teams(), espn_cfb_groups(), espn_cfb_pbp_v2(), espn_cfb_player(), espn_cfb_player_career_stats(), espn_cfb_player_eventlog(), espn_cfb_player_gamelog(), espn_cfb_player_overview(), espn_cfb_player_seasons(), espn_cfb_player_splits(), espn_cfb_player_stats_v3(), espn_cfb_players(), espn_cfb_position(), espn_cfb_positions(), espn_cfb_powerindex(), espn_cfb_qbr(), espn_cfb_rankings(), espn_cfb_recruits(), espn_cfb_season_info(), espn_cfb_season_types(), espn_cfb_season_weeks(), espn_cfb_seasons(), espn_cfb_standings(), espn_cfb_team(), espn_cfb_team_ats(), espn_cfb_team_awards(), espn_cfb_team_coaches(), espn_cfb_team_events(), espn_cfb_team_leaders(), espn_cfb_team_powerindex(), espn_cfb_team_ranks(), espn_cfb_team_record(), espn_cfb_team_roster(), espn_cfb_team_schedule(), espn_cfb_teams(), espn_cfb_unnest_plays(), espn_cfb_venue(), espn_cfb_venues(), espn_cfb_week_rankings()

Examples


  try(espn_cfb_game_powerindex(game_id = 401628339))
  try(espn_cfb_game_powerindex(game_id = 401628339, team_detail = FALSE))

ESPN College Football Game Predictor (BPI Matchup Predictor)

Description

Get ESPN's pre-game matchup predictor (Football Power Index game projection) for a single college football game.

Usage

espn_cfb_game_predictor(game_id = NULL, team_detail = TRUE)

Arguments

game_id

(Integer required): ESPN game identifier for a completed game.

team_detail

(Logical): when TRUE (default), fetch the ESPN team catalog once and join friendly team fields next to the team_id column (see Details). Set FALSE to skip the catalog fetch and the join.

Details

Wraps the ESPN core-v2 endpoint events/{game_id}/competitions/{game_id}/predictor. ESPN's predictor resource carries one statistics block per team (home and away); this wrapper flattens both into one long frame – one row per (team x predictor metric). Metrics include each team's projected win probability (gameProjection), predicted point total, and matchup-quality scores.

This endpoint responds ⁠HTTP 400⁠ for future / not-yet-scheduled games and is only reliably populated for completed games. The ⁠@examples⁠ use a finished game; pass game_id values for completed games.

When team_detail = TRUE (the default) the ESPN team catalog (espn_cfb_teams()) is fetched once and friendly team fields are joined in next to the team_id column – team_name, team_abbreviation, team_location, team_display_name, team_short_display_name, team_nickname, team_color, team_alternate_color, team_logo_href, and team_logo_dark_href. A catalog failure degrades to NA rather than erroring the wrapper. Set team_detail = FALSE to skip the catalog fetch and the join.

Value

A data frame with one row per team-predictor metric:

col_name types description
game_id character ESPN game identifier.
matchup_name character Predictor matchup name (e.g. ⁠TNTC at Georgia⁠).
matchup_short_name character Short predictor matchup name (e.g. TNTC @ UGA).
last_modified character ISO timestamp the predictor was last run.
team_side character home or away.
team_id character ESPN team id (parsed from team_ref).
team_name character Team nickname; team_detail = TRUE only.
team_abbreviation character Team abbreviation; team_detail = TRUE only.
team_location character Team location / school name; team_detail = TRUE only.
team_display_name character Full team display name; team_detail = TRUE only.
team_short_display_name character Short team display name; team_detail = TRUE only.
team_nickname character Team nickname label; team_detail = TRUE only.
team_color character Primary team color; team_detail = TRUE only.
team_alternate_color character Alternate team color; team_detail = TRUE only.
team_logo_href character Default team logo URL; team_detail = TRUE only.
team_logo_dark_href character Dark-variant team logo URL; team_detail = TRUE only.
stat_name character Predictor metric key (e.g. gameProjection).
abbreviation character Metric abbreviation.
display_name character Human-readable metric name.
short_display_name character Short human-readable metric name.
value numeric Metric value.
display_value character Display-formatted metric value as shown on ESPN.
description character ESPN's description of the metric.
team_ref character ⁠$ref⁠ URL to the team-in-season resource.

See Also

Other ESPN CFB Functions: espn_cfb_award(), espn_cfb_awards(), espn_cfb_clear_cache(), espn_cfb_coach(), espn_cfb_coach_record(), espn_cfb_coaches(), espn_cfb_franchise(), espn_cfb_franchises(), espn_cfb_futures(), espn_cfb_game_broadcasts(), espn_cfb_game_drive_plays(), espn_cfb_game_drives(), espn_cfb_game_leaders(), espn_cfb_game_odds(), espn_cfb_game_pbp(), espn_cfb_game_play(), espn_cfb_game_player_box(), espn_cfb_game_player_statistics(), espn_cfb_game_powerindex(), espn_cfb_game_probabilities(), espn_cfb_game_situation(), espn_cfb_game_status(), espn_cfb_game_team_leaders(), espn_cfb_game_team_linescores(), espn_cfb_game_team_records(), espn_cfb_game_team_roster(), espn_cfb_game_team_statistics(), espn_cfb_game_teams(), espn_cfb_groups(), espn_cfb_pbp_v2(), espn_cfb_player(), espn_cfb_player_career_stats(), espn_cfb_player_eventlog(), espn_cfb_player_gamelog(), espn_cfb_player_overview(), espn_cfb_player_seasons(), espn_cfb_player_splits(), espn_cfb_player_stats_v3(), espn_cfb_players(), espn_cfb_position(), espn_cfb_positions(), espn_cfb_powerindex(), espn_cfb_qbr(), espn_cfb_rankings(), espn_cfb_recruits(), espn_cfb_season_info(), espn_cfb_season_types(), espn_cfb_season_weeks(), espn_cfb_seasons(), espn_cfb_standings(), espn_cfb_team(), espn_cfb_team_ats(), espn_cfb_team_awards(), espn_cfb_team_coaches(), espn_cfb_team_events(), espn_cfb_team_leaders(), espn_cfb_team_powerindex(), espn_cfb_team_ranks(), espn_cfb_team_record(), espn_cfb_team_roster(), espn_cfb_team_schedule(), espn_cfb_teams(), espn_cfb_unnest_plays(), espn_cfb_venue(), espn_cfb_venues(), espn_cfb_week_rankings()

Examples


  try(espn_cfb_game_predictor(game_id = 401628339))
  try(espn_cfb_game_predictor(game_id = 401628339, team_detail = FALSE))

ESPN College Football Game Win Probabilities

Description

Get ESPN's play-by-play win-probability series for a single college football game – one row per play.

Usage

espn_cfb_game_probabilities(game_id = NULL, team_detail = TRUE)

Arguments

game_id

(Integer required): ESPN game identifier for a completed game.

team_detail

(Logical): when TRUE (default), fetch the ESPN team catalog once and join friendly team fields next to the home_team_id / away_team_id columns (see Details). Set FALSE to skip the catalog fetch and the join.

Details

Wraps the paginated ESPN core-v2 endpoint events/{game_id}/competitions/{game_id}/probabilities. The endpoint is paginated; this wrapper loops every page and stacks the results into one frame – one row per play, each carrying the home / away / tie win percentages at that point in the game, plus spread-cover and total (over/under) probabilities. play_id is parsed from each row's play ⁠$ref⁠ so the series can be joined to espn_cfb_game_pbp().

This endpoint responds ⁠HTTP 400⁠ for future / not-yet-played games and is only populated for completed games. The ⁠@examples⁠ use a finished game; pass game_id values for completed games.

When team_detail = TRUE (the default) the ESPN team catalog (espn_cfb_teams()) is fetched once and friendly team fields are joined in next to both the home_team_id and away_team_id columns – e.g. home_team_name, home_team_abbreviation, ..., away_team_name, away_team_abbreviation, .... A catalog failure degrades to NA rather than erroring the wrapper. Set team_detail = FALSE to skip the catalog fetch and the join.

Value

A data frame with one row per play:

col_name types description
game_id character ESPN game identifier.
play_id character ESPN play id (parsed from the play ⁠$ref⁠).
sequence_number character Play sequence number within the game.
home_team_id character ESPN home team id (parsed from home_team_ref).
home_team_name character Home team nickname; team_detail = TRUE only.
home_team_abbreviation character Home team abbreviation; team_detail = TRUE only.
home_team_location character Home team location / school; team_detail = TRUE only.
home_team_display_name character Home team full display name; team_detail = TRUE only.
home_team_short_display_name character Home team short display name; team_detail = TRUE only.
home_team_nickname character Home team nickname label; team_detail = TRUE only.
home_team_color character Home team primary color; team_detail = TRUE only.
home_team_alternate_color character Home team alternate color; team_detail = TRUE only.
home_team_logo_href character Home team default logo URL; team_detail = TRUE only.
home_team_logo_dark_href character Home team dark logo URL; team_detail = TRUE only.
away_team_id character ESPN away team id (parsed from away_team_ref).
away_team_name character Away team nickname; team_detail = TRUE only.
away_team_abbreviation character Away team abbreviation; team_detail = TRUE only.
away_team_location character Away team location / school; team_detail = TRUE only.
away_team_display_name character Away team full display name; team_detail = TRUE only.
away_team_short_display_name character Away team short display name; team_detail = TRUE only.
away_team_nickname character Away team nickname label; team_detail = TRUE only.
away_team_color character Away team primary color; team_detail = TRUE only.
away_team_alternate_color character Away team alternate color; team_detail = TRUE only.
away_team_logo_href character Away team default logo URL; team_detail = TRUE only.
away_team_logo_dark_href character Away team dark logo URL; team_detail = TRUE only.
home_win_percentage numeric Home-team win probability after the play (0-1).
away_win_percentage numeric Away-team win probability after the play (0-1).
tie_percentage numeric Tie probability after the play (0-1).
seconds_left integer Seconds left in the game at the play.
spread_cover_prob_home numeric Probability the home team covers the spread.
spread_push_prob numeric Probability of a spread push.
total_over_prob numeric Probability the game total goes over.
total_push_prob numeric Probability of a total push.
source_id character ESPN data-source id for the probability row.
source_description character ESPN data-source description (e.g. feed).
source_state character ESPN data-source state (e.g. full).
last_modified character ISO timestamp the probability row was last modified.
play_ref character ⁠$ref⁠ URL to the play resource for the row.
competition_ref character ⁠$ref⁠ URL to the competition resource.
home_team_ref character ⁠$ref⁠ URL to the home team resource.
away_team_ref character ⁠$ref⁠ URL to the away team resource.

See Also

Other ESPN CFB Functions: espn_cfb_award(), espn_cfb_awards(), espn_cfb_clear_cache(), espn_cfb_coach(), espn_cfb_coach_record(), espn_cfb_coaches(), espn_cfb_franchise(), espn_cfb_franchises(), espn_cfb_futures(), espn_cfb_game_broadcasts(), espn_cfb_game_drive_plays(), espn_cfb_game_drives(), espn_cfb_game_leaders(), espn_cfb_game_odds(), espn_cfb_game_pbp(), espn_cfb_game_play(), espn_cfb_game_player_box(), espn_cfb_game_player_statistics(), espn_cfb_game_powerindex(), espn_cfb_game_predictor(), espn_cfb_game_situation(), espn_cfb_game_status(), espn_cfb_game_team_leaders(), espn_cfb_game_team_linescores(), espn_cfb_game_team_records(), espn_cfb_game_team_roster(), espn_cfb_game_team_statistics(), espn_cfb_game_teams(), espn_cfb_groups(), espn_cfb_pbp_v2(), espn_cfb_player(), espn_cfb_player_career_stats(), espn_cfb_player_eventlog(), espn_cfb_player_gamelog(), espn_cfb_player_overview(), espn_cfb_player_seasons(), espn_cfb_player_splits(), espn_cfb_player_stats_v3(), espn_cfb_players(), espn_cfb_position(), espn_cfb_positions(), espn_cfb_powerindex(), espn_cfb_qbr(), espn_cfb_rankings(), espn_cfb_recruits(), espn_cfb_season_info(), espn_cfb_season_types(), espn_cfb_season_weeks(), espn_cfb_seasons(), espn_cfb_standings(), espn_cfb_team(), espn_cfb_team_ats(), espn_cfb_team_awards(), espn_cfb_team_coaches(), espn_cfb_team_events(), espn_cfb_team_leaders(), espn_cfb_team_powerindex(), espn_cfb_team_ranks(), espn_cfb_team_record(), espn_cfb_team_roster(), espn_cfb_team_schedule(), espn_cfb_teams(), espn_cfb_unnest_plays(), espn_cfb_venue(), espn_cfb_venues(), espn_cfb_week_rankings()

Examples


  try(espn_cfb_game_probabilities(game_id = 401628339))
  try(espn_cfb_game_probabilities(game_id = 401628339,
                                  team_detail = FALSE))

ESPN College Football Game Situation

Description

Get the current (or final) game situation for a single college football game – down, distance, yard line, red-zone flag, timeouts, and a ⁠$ref⁠ to the last play.

Usage

espn_cfb_game_situation(game_id = NULL)

Arguments

game_id

(Integer required): ESPN game identifier.

Details

Wraps the ESPN core-v2 endpoint events/{game_id}/competitions/{game_id}/situation. The competition id always equals the game id. Returns a single-row data frame describing the live game situation. For an in-progress game this is the current state; for a completed game it is static – the final play state. The last_play_ref column is the ⁠$ref⁠ URL to the last play; parse its id and pass it to espn_cfb_game_play() for the full play detail.

Value

A data frame with one row describing the game situation:

col_name types description
game_id character ESPN game identifier.
down integer Current down.
distance integer Yards to go for a first down.
yard_line integer Current yard line.
is_red_zone logical TRUE if the offense is in the red zone.
home_timeouts integer Home-team timeouts remaining.
away_timeouts integer Away-team timeouts remaining.
last_play_id character ESPN play id of the last play (parsed from last_play_ref).
situation_ref character ⁠$ref⁠ URL to the situation resource itself.
last_play_ref character ⁠$ref⁠ URL to the last-play resource.

See Also

Other ESPN CFB Functions: espn_cfb_award(), espn_cfb_awards(), espn_cfb_clear_cache(), espn_cfb_coach(), espn_cfb_coach_record(), espn_cfb_coaches(), espn_cfb_franchise(), espn_cfb_franchises(), espn_cfb_futures(), espn_cfb_game_broadcasts(), espn_cfb_game_drive_plays(), espn_cfb_game_drives(), espn_cfb_game_leaders(), espn_cfb_game_odds(), espn_cfb_game_pbp(), espn_cfb_game_play(), espn_cfb_game_player_box(), espn_cfb_game_player_statistics(), espn_cfb_game_powerindex(), espn_cfb_game_predictor(), espn_cfb_game_probabilities(), espn_cfb_game_status(), espn_cfb_game_team_leaders(), espn_cfb_game_team_linescores(), espn_cfb_game_team_records(), espn_cfb_game_team_roster(), espn_cfb_game_team_statistics(), espn_cfb_game_teams(), espn_cfb_groups(), espn_cfb_pbp_v2(), espn_cfb_player(), espn_cfb_player_career_stats(), espn_cfb_player_eventlog(), espn_cfb_player_gamelog(), espn_cfb_player_overview(), espn_cfb_player_seasons(), espn_cfb_player_splits(), espn_cfb_player_stats_v3(), espn_cfb_players(), espn_cfb_position(), espn_cfb_positions(), espn_cfb_powerindex(), espn_cfb_qbr(), espn_cfb_rankings(), espn_cfb_recruits(), espn_cfb_season_info(), espn_cfb_season_types(), espn_cfb_season_weeks(), espn_cfb_seasons(), espn_cfb_standings(), espn_cfb_team(), espn_cfb_team_ats(), espn_cfb_team_awards(), espn_cfb_team_coaches(), espn_cfb_team_events(), espn_cfb_team_leaders(), espn_cfb_team_powerindex(), espn_cfb_team_ranks(), espn_cfb_team_record(), espn_cfb_team_roster(), espn_cfb_team_schedule(), espn_cfb_teams(), espn_cfb_unnest_plays(), espn_cfb_venue(), espn_cfb_venues(), espn_cfb_week_rankings()

Examples


  try(espn_cfb_game_situation(game_id = 401628339))

ESPN College Football Game Status

Description

Get the competition status for a single college football game – clock, period, and the status type/state (scheduled, in-progress, final).

Usage

espn_cfb_game_status(game_id = NULL)

Arguments

game_id

(Integer required): ESPN game identifier.

Details

Wraps the ESPN core-v2 endpoint events/{game_id}/competitions/{game_id}/status. The competition id always equals the game id. Returns a single-row data frame describing the game's status. For a completed game state is post and completed is TRUE; for an in-progress game the clock and period reflect live game time.

Value

A data frame with one row describing the game status:

col_name types description
game_id character ESPN game identifier.
clock numeric Game clock value in seconds.
display_clock character Game clock display value (MM:SS).
period integer Period (quarter) number.
status_id character ESPN status-type id.
status_name character Status-type key (e.g. STATUS_FINAL).
status_state character Status state (pre, ⁠in⁠, or post).
completed logical TRUE if the game is complete.
description character Status description (e.g. Final).
detail character Detailed status text.
short_detail character Short status text.
status_ref character ⁠$ref⁠ URL to the status resource itself.

See Also

Other ESPN CFB Functions: espn_cfb_award(), espn_cfb_awards(), espn_cfb_clear_cache(), espn_cfb_coach(), espn_cfb_coach_record(), espn_cfb_coaches(), espn_cfb_franchise(), espn_cfb_franchises(), espn_cfb_futures(), espn_cfb_game_broadcasts(), espn_cfb_game_drive_plays(), espn_cfb_game_drives(), espn_cfb_game_leaders(), espn_cfb_game_odds(), espn_cfb_game_pbp(), espn_cfb_game_play(), espn_cfb_game_player_box(), espn_cfb_game_player_statistics(), espn_cfb_game_powerindex(), espn_cfb_game_predictor(), espn_cfb_game_probabilities(), espn_cfb_game_situation(), espn_cfb_game_team_leaders(), espn_cfb_game_team_linescores(), espn_cfb_game_team_records(), espn_cfb_game_team_roster(), espn_cfb_game_team_statistics(), espn_cfb_game_teams(), espn_cfb_groups(), espn_cfb_pbp_v2(), espn_cfb_player(), espn_cfb_player_career_stats(), espn_cfb_player_eventlog(), espn_cfb_player_gamelog(), espn_cfb_player_overview(), espn_cfb_player_seasons(), espn_cfb_player_splits(), espn_cfb_player_stats_v3(), espn_cfb_players(), espn_cfb_position(), espn_cfb_positions(), espn_cfb_powerindex(), espn_cfb_qbr(), espn_cfb_rankings(), espn_cfb_recruits(), espn_cfb_season_info(), espn_cfb_season_types(), espn_cfb_season_weeks(), espn_cfb_seasons(), espn_cfb_standings(), espn_cfb_team(), espn_cfb_team_ats(), espn_cfb_team_awards(), espn_cfb_team_coaches(), espn_cfb_team_events(), espn_cfb_team_leaders(), espn_cfb_team_powerindex(), espn_cfb_team_ranks(), espn_cfb_team_record(), espn_cfb_team_roster(), espn_cfb_team_schedule(), espn_cfb_teams(), espn_cfb_unnest_plays(), espn_cfb_venue(), espn_cfb_venues(), espn_cfb_week_rankings()

Examples


  try(espn_cfb_game_status(game_id = 401628339))

ESPN College Football Game Team Leaders

Description

Get each team's statistical leaders (passing, rushing, receiving, ...) for a single college football game.

Usage

espn_cfb_game_team_leaders(game_id = NULL, team_detail = TRUE)

Arguments

game_id

(Integer required): ESPN game identifier.

team_detail

(Logical): when TRUE (default), fetch the ESPN team catalog once and join friendly team fields next to the team_id and leader_team_id columns (see Details). Set FALSE to skip the catalog fetch and the join.

Details

Wraps the ESPN core-v2 endpoint events/{game_id}/competitions/{game_id}/competitors/{team_id}/leaders. This wrapper reads the teams list for the game and fetches the leaders resource for both teams, flattening the nested categories -> leaders tree into one long frame: one row per (team x category x leader). rank is the leader's position within the category (1 = top performer). display_value is ESPN's pre-formatted stat line (e.g. "18/25, 242 YDS, 5 TD").

When team_detail = TRUE (the default) the ESPN team catalog (espn_cfb_teams()) is fetched once and friendly team fields are joined in next to both team-id columns – team_id gains team_name, team_abbreviation, ..., and leader_team_id gains leader_team_name, leader_team_abbreviation, .... A catalog failure degrades to NA rather than erroring the wrapper. Set team_detail = FALSE to skip the catalog fetch and the join.

Value

A data frame with one row per team-category-leader:

col_name types description
game_id character ESPN game identifier.
team_id character ESPN team id for the team.
team_name character Team nickname; team_detail = TRUE only.
team_abbreviation character Team abbreviation; team_detail = TRUE only.
team_location character Team location / school name; team_detail = TRUE only.
team_display_name character Full team display name; team_detail = TRUE only.
team_short_display_name character Short team display name; team_detail = TRUE only.
team_nickname character Team nickname label; team_detail = TRUE only.
team_color character Primary team color; team_detail = TRUE only.
team_alternate_color character Alternate team color; team_detail = TRUE only.
team_logo_href character Default team logo URL; team_detail = TRUE only.
team_logo_dark_href character Dark-variant team logo URL; team_detail = TRUE only.
home_away character home or away.
category_name character Leader category key (e.g. passingLeader).
category_display character Human-readable category name.
category_short_display character Short human-readable category name.
category_abbrev character Category abbreviation.
rank integer Leader rank within the category (1 = top performer).
athlete_id character ESPN athlete id (parsed from athlete_ref).
leader_team_id character ESPN team id of the leader (parsed from leader_team_ref).
leader_team_name character Leader's team nickname; team_detail = TRUE only.
leader_team_abbreviation character Leader's team abbreviation; team_detail = TRUE only.
leader_team_location character Leader's team location; team_detail = TRUE only.
leader_team_display_name character Leader's team full display name; team_detail = TRUE only.
leader_team_short_display_name character Leader's team short display name; team_detail = TRUE only.
leader_team_nickname character Leader's team nickname label; team_detail = TRUE only.
leader_team_color character Leader's team primary color; team_detail = TRUE only.
leader_team_alternate_color character Leader's team alternate color; team_detail = TRUE only.
leader_team_logo_href character Leader's team default logo URL; team_detail = TRUE only.
leader_team_logo_dark_href character Leader's team dark logo URL; team_detail = TRUE only.
value numeric Leading statistic value.
display_value character ESPN's pre-formatted stat line for the leader.
athlete_ref character ⁠$ref⁠ URL to the athlete-in-event resource.
leader_team_ref character ⁠$ref⁠ URL to the leader's team resource.
statistics_ref character ⁠$ref⁠ URL to the leader's game-statistics resource.

See Also

Other ESPN CFB Functions: espn_cfb_award(), espn_cfb_awards(), espn_cfb_clear_cache(), espn_cfb_coach(), espn_cfb_coach_record(), espn_cfb_coaches(), espn_cfb_franchise(), espn_cfb_franchises(), espn_cfb_futures(), espn_cfb_game_broadcasts(), espn_cfb_game_drive_plays(), espn_cfb_game_drives(), espn_cfb_game_leaders(), espn_cfb_game_odds(), espn_cfb_game_pbp(), espn_cfb_game_play(), espn_cfb_game_player_box(), espn_cfb_game_player_statistics(), espn_cfb_game_powerindex(), espn_cfb_game_predictor(), espn_cfb_game_probabilities(), espn_cfb_game_situation(), espn_cfb_game_status(), espn_cfb_game_team_linescores(), espn_cfb_game_team_records(), espn_cfb_game_team_roster(), espn_cfb_game_team_statistics(), espn_cfb_game_teams(), espn_cfb_groups(), espn_cfb_pbp_v2(), espn_cfb_player(), espn_cfb_player_career_stats(), espn_cfb_player_eventlog(), espn_cfb_player_gamelog(), espn_cfb_player_overview(), espn_cfb_player_seasons(), espn_cfb_player_splits(), espn_cfb_player_stats_v3(), espn_cfb_players(), espn_cfb_position(), espn_cfb_positions(), espn_cfb_powerindex(), espn_cfb_qbr(), espn_cfb_rankings(), espn_cfb_recruits(), espn_cfb_season_info(), espn_cfb_season_types(), espn_cfb_season_weeks(), espn_cfb_seasons(), espn_cfb_standings(), espn_cfb_team(), espn_cfb_team_ats(), espn_cfb_team_awards(), espn_cfb_team_coaches(), espn_cfb_team_events(), espn_cfb_team_leaders(), espn_cfb_team_powerindex(), espn_cfb_team_ranks(), espn_cfb_team_record(), espn_cfb_team_roster(), espn_cfb_team_schedule(), espn_cfb_teams(), espn_cfb_unnest_plays(), espn_cfb_venue(), espn_cfb_venues(), espn_cfb_week_rankings()

Examples


  try(espn_cfb_game_team_leaders(game_id = 401628339))
  try(espn_cfb_game_team_leaders(game_id = 401628339,
                                 team_detail = FALSE))

ESPN College Football Game Team Linescores

Description

Get the quarter-by-quarter linescores for both teams in a single college football game.

Usage

espn_cfb_game_team_linescores(game_id = NULL, team_detail = TRUE)

Arguments

game_id

(Integer required): ESPN game identifier.

team_detail

(Logical): when TRUE (default), fetch the ESPN team catalog once and join friendly team fields next to the team_id column (see Details). Set FALSE to skip the catalog fetch and the join.

Details

Wraps the ESPN core-v2 endpoint events/{game_id}/competitions/{game_id}/competitors/{team_id}/linescores. This wrapper first reads the teams list for the game and then fetches the linescores resource for both teams, stacking the results into one long frame – one row per (team x period). home_away identifies which team a row belongs to. Periods 1-4 are quarters; periods 5+ are overtime sessions.

When team_detail = TRUE (the default) the ESPN team catalog (espn_cfb_teams()) is fetched once and friendly team fields are joined in next to the team_id column – team_name, team_abbreviation, team_location, team_display_name, team_short_display_name, team_nickname, team_color, team_alternate_color, team_logo_href, and team_logo_dark_href. A catalog failure degrades to NA rather than erroring the wrapper. Set team_detail = FALSE to skip the catalog fetch and the join.

Value

A data frame with one row per team-period:

col_name types description
game_id character ESPN game identifier.
team_id character ESPN team id for the team.
team_name character Team nickname; team_detail = TRUE only.
team_abbreviation character Team abbreviation; team_detail = TRUE only.
team_location character Team location / school name; team_detail = TRUE only.
team_display_name character Full team display name; team_detail = TRUE only.
team_short_display_name character Short team display name; team_detail = TRUE only.
team_nickname character Team nickname label; team_detail = TRUE only.
team_color character Primary team color; team_detail = TRUE only.
team_alternate_color character Alternate team color; team_detail = TRUE only.
team_logo_href character Default team logo URL; team_detail = TRUE only.
team_logo_dark_href character Dark-variant team logo URL; team_detail = TRUE only.
home_away character home or away.
period integer Period number (1-4 quarters; 5+ overtime).
value numeric Points scored by the team in that period.
display_value character Display-formatted period score.
source_id character ESPN data-source id for the linescore.
source_state character ESPN data-source state (e.g. full).
source_description character ESPN data-source description (e.g. Basic/Manual).
linescore_ref character ⁠$ref⁠ URL to the per-period linescore resource.

See Also

Other ESPN CFB Functions: espn_cfb_award(), espn_cfb_awards(), espn_cfb_clear_cache(), espn_cfb_coach(), espn_cfb_coach_record(), espn_cfb_coaches(), espn_cfb_franchise(), espn_cfb_franchises(), espn_cfb_futures(), espn_cfb_game_broadcasts(), espn_cfb_game_drive_plays(), espn_cfb_game_drives(), espn_cfb_game_leaders(), espn_cfb_game_odds(), espn_cfb_game_pbp(), espn_cfb_game_play(), espn_cfb_game_player_box(), espn_cfb_game_player_statistics(), espn_cfb_game_powerindex(), espn_cfb_game_predictor(), espn_cfb_game_probabilities(), espn_cfb_game_situation(), espn_cfb_game_status(), espn_cfb_game_team_leaders(), espn_cfb_game_team_records(), espn_cfb_game_team_roster(), espn_cfb_game_team_statistics(), espn_cfb_game_teams(), espn_cfb_groups(), espn_cfb_pbp_v2(), espn_cfb_player(), espn_cfb_player_career_stats(), espn_cfb_player_eventlog(), espn_cfb_player_gamelog(), espn_cfb_player_overview(), espn_cfb_player_seasons(), espn_cfb_player_splits(), espn_cfb_player_stats_v3(), espn_cfb_players(), espn_cfb_position(), espn_cfb_positions(), espn_cfb_powerindex(), espn_cfb_qbr(), espn_cfb_rankings(), espn_cfb_recruits(), espn_cfb_season_info(), espn_cfb_season_types(), espn_cfb_season_weeks(), espn_cfb_seasons(), espn_cfb_standings(), espn_cfb_team(), espn_cfb_team_ats(), espn_cfb_team_awards(), espn_cfb_team_coaches(), espn_cfb_team_events(), espn_cfb_team_leaders(), espn_cfb_team_powerindex(), espn_cfb_team_ranks(), espn_cfb_team_record(), espn_cfb_team_roster(), espn_cfb_team_schedule(), espn_cfb_teams(), espn_cfb_unnest_plays(), espn_cfb_venue(), espn_cfb_venues(), espn_cfb_week_rankings()

Examples


  try(espn_cfb_game_team_linescores(game_id = 401628339))
  try(espn_cfb_game_team_linescores(game_id = 401628339,
                                    team_detail = FALSE))

ESPN College Football Game Team Records

Description

Get each team's win-loss records (overall, home, road, conference) as they stood at the time of a single college football game.

Usage

espn_cfb_game_team_records(game_id = NULL, detail = FALSE, team_detail = TRUE)

Arguments

game_id

(Integer required): ESPN game identifier.

detail

(Logical): controls the output shape. One of:

  • FALSE (default) – the summary output, one row per (team x record type), with the columns shown in the Value table below.

  • TRUE – a long frame, one row per (team x record x stat) expanding each record's nested stats[] array (see Details).

team_detail

(Logical): when TRUE (default), fetch the ESPN team catalog (espn_cfb_teams()) once and join friendly team fields next to the team_id column – team_name, team_abbreviation, team_location, team_display_name, team_short_display_name, team_nickname, team_color, team_alternate_color, team_logo_href, and team_logo_dark_href, inserted immediately after team_id. Composes with detail – both output shapes carry team_id. A catalog failure degrades to NA rather than erroring the wrapper. Set FALSE to skip the catalog fetch and the join.

Details

Wraps the ESPN core-v2 endpoint events/{game_id}/competitions/{game_id}/competitors/{team_id}/records. This wrapper reads the teams list for the game and fetches the records resource for both teams, stacking the items arrays into one long frame – one row per (team x record type). Each record type carries a summary string (e.g. "2-0"). With detail = TRUE the per-record statistic breakdown (points-per-game, streak, ...) nested under each record is also expanded. home_away identifies which team a row belongs to.

When detail = TRUE the returned frame is in long format with one row per (team x record x stat), with columns: game_id, team_id, home_away, record_type (the record-type key, e.g. overall), record_summary (the record's win-loss summary string), stat_name, stat_type (the stat-type key, e.g. wins), abbreviation, display_name, short_display_name, description (ESPN's description of the stat), value, and display_value.

Value

A data frame with one row per team-record type (when detail = FALSE):

col_name types description
game_id character ESPN game identifier.
team_id character ESPN team id for the team.
team_name character Team nickname; team_detail = TRUE only.
team_abbreviation character Team abbreviation; team_detail = TRUE only.
team_location character Team location / school name; team_detail = TRUE only.
team_display_name character Full team display name; team_detail = TRUE only.
team_short_display_name character Short team display name; team_detail = TRUE only.
team_nickname character Team nickname label; team_detail = TRUE only.
team_color character Primary team color; team_detail = TRUE only.
team_alternate_color character Alternate team color; team_detail = TRUE only.
team_logo_href character Default team logo URL; team_detail = TRUE only.
team_logo_dark_href character Dark-variant team logo URL; team_detail = TRUE only.
home_away character home or away.
record_id character ESPN record-type id.
name character Record-type key (e.g. overall, Home, Road).
abbreviation character Record-type abbreviation.
display_name character Human-readable record-type name.
short_display_name character Short human-readable record-type name.
description character ESPN's description of the record type.
type character Record-type category (e.g. total, home, road).
summary character Win-loss summary string (e.g. 2-0).
display_value character Display-formatted record value.
value numeric Numeric record value.
record_ref character ⁠$ref⁠ URL to the record resource.

See Also

Other ESPN CFB Functions: espn_cfb_award(), espn_cfb_awards(), espn_cfb_clear_cache(), espn_cfb_coach(), espn_cfb_coach_record(), espn_cfb_coaches(), espn_cfb_franchise(), espn_cfb_franchises(), espn_cfb_futures(), espn_cfb_game_broadcasts(), espn_cfb_game_drive_plays(), espn_cfb_game_drives(), espn_cfb_game_leaders(), espn_cfb_game_odds(), espn_cfb_game_pbp(), espn_cfb_game_play(), espn_cfb_game_player_box(), espn_cfb_game_player_statistics(), espn_cfb_game_powerindex(), espn_cfb_game_predictor(), espn_cfb_game_probabilities(), espn_cfb_game_situation(), espn_cfb_game_status(), espn_cfb_game_team_leaders(), espn_cfb_game_team_linescores(), espn_cfb_game_team_roster(), espn_cfb_game_team_statistics(), espn_cfb_game_teams(), espn_cfb_groups(), espn_cfb_pbp_v2(), espn_cfb_player(), espn_cfb_player_career_stats(), espn_cfb_player_eventlog(), espn_cfb_player_gamelog(), espn_cfb_player_overview(), espn_cfb_player_seasons(), espn_cfb_player_splits(), espn_cfb_player_stats_v3(), espn_cfb_players(), espn_cfb_position(), espn_cfb_positions(), espn_cfb_powerindex(), espn_cfb_qbr(), espn_cfb_rankings(), espn_cfb_recruits(), espn_cfb_season_info(), espn_cfb_season_types(), espn_cfb_season_weeks(), espn_cfb_seasons(), espn_cfb_standings(), espn_cfb_team(), espn_cfb_team_ats(), espn_cfb_team_awards(), espn_cfb_team_coaches(), espn_cfb_team_events(), espn_cfb_team_leaders(), espn_cfb_team_powerindex(), espn_cfb_team_ranks(), espn_cfb_team_record(), espn_cfb_team_roster(), espn_cfb_team_schedule(), espn_cfb_teams(), espn_cfb_unnest_plays(), espn_cfb_venue(), espn_cfb_venues(), espn_cfb_week_rankings()

Examples


  try(espn_cfb_game_team_records(game_id = 401628339))
  try(espn_cfb_game_team_records(game_id = 401628339, detail = TRUE))
  try(espn_cfb_game_team_records(game_id = 401628339,
                                 team_detail = FALSE))

ESPN College Football Game Team Roster

Description

Get the game-day roster for both teams in a single college football game, including each player's jersey number, starter flag, and active/did-not-play status.

Usage

espn_cfb_game_team_roster(
  game_id = NULL,
  position_detail = TRUE,
  team_detail = TRUE
)

Arguments

game_id

(Integer required): ESPN game identifier.

position_detail

(Logical): when TRUE (default), fetch the ESPN position catalog once and join it onto position_id, appending the five ⁠position_*⁠ detail columns shown in the Value table. A catalog failure degrades to NA rather than erroring the wrapper. Set FALSE to skip the extra fetch and return the original column set.

team_detail

(Logical): when TRUE (default), fetch the ESPN team catalog (espn_cfb_teams()) once and join friendly team fields next to the team_id column – team_name, team_abbreviation, team_location, team_display_name, team_short_display_name, team_nickname, team_color, team_alternate_color, team_logo_href, and team_logo_dark_href, inserted immediately after team_id. A catalog failure degrades to NA rather than erroring the wrapper. Set FALSE to skip the catalog fetch and the join.

Details

Wraps the ESPN core-v2 endpoint events/{game_id}/competitions/{game_id}/competitors/{team_id}/roster. This wrapper reads the teams list for the game and fetches the roster resource for both teams, stacking the entries arrays into one long frame – one row per (team x rostered player). home_away identifies which team a row belongs to. Players are returned as ESPN athlete ids; join to another athlete source for names.

When position_detail = TRUE (the default) the ESPN position catalog (espn_cfb_positions()) is fetched once and joined onto position_id, so the output carries the full position name / abbreviation rather than the bare id (see Details).

When position_detail = TRUE (the default), five columns are appended by joining the ESPN position catalog (espn_cfb_positions()) on position_id: position_name, position_display_name, position_abbreviation, position_leaf, and position_parent_id. The catalog is fetched once per call. A roster entry whose position_id is missing or unmatched receives NA for all five, and a catalog-fetch failure degrades the whole set to NA rather than erroring the wrapper. With position_detail = FALSE the five columns are omitted and the original roster schema is returned unchanged.

Value

A data frame with one row per rostered player:

col_name types description
game_id character ESPN game identifier.
team_id character ESPN team id for the team.
team_name character Team nickname; team_detail = TRUE only.
team_abbreviation character Team abbreviation; team_detail = TRUE only.
team_location character Team location / school name; team_detail = TRUE only.
team_display_name character Full team display name; team_detail = TRUE only.
team_short_display_name character Short team display name; team_detail = TRUE only.
team_nickname character Team nickname label; team_detail = TRUE only.
team_color character Primary team color; team_detail = TRUE only.
team_alternate_color character Alternate team color; team_detail = TRUE only.
team_logo_href character Default team logo URL; team_detail = TRUE only.
team_logo_dark_href character Dark-variant team logo URL; team_detail = TRUE only.
home_away character home or away.
athlete_id character ESPN athlete id (parsed from athlete_ref).
player_id character ESPN player id from the roster entry.
display_name character Player display name as shown by ESPN.
jersey character Jersey number.
position_id character ESPN position id (parsed from position_ref).
period integer Period the player entered the game (0 if none).
starter logical TRUE if the player started the game.
active logical TRUE if the player was active for the game.
did_not_play logical TRUE if the player did not play.
valid logical TRUE if the roster entry is flagged valid by ESPN.
athlete_ref character ⁠$ref⁠ URL to the athlete-in-season resource.
position_ref character ⁠$ref⁠ URL to the position resource.
position_name character Position name (e.g. Quarterback); position_detail = TRUE only.
position_display_name character Human-readable position name; position_detail = TRUE only.
position_abbreviation character Position abbreviation (e.g. QB); position_detail = TRUE only.
position_leaf logical TRUE for a most-specific (leaf) position; position_detail = TRUE only.
position_parent_id character ESPN id of the parent position; position_detail = TRUE only.

See Also

Other ESPN CFB Functions: espn_cfb_award(), espn_cfb_awards(), espn_cfb_clear_cache(), espn_cfb_coach(), espn_cfb_coach_record(), espn_cfb_coaches(), espn_cfb_franchise(), espn_cfb_franchises(), espn_cfb_futures(), espn_cfb_game_broadcasts(), espn_cfb_game_drive_plays(), espn_cfb_game_drives(), espn_cfb_game_leaders(), espn_cfb_game_odds(), espn_cfb_game_pbp(), espn_cfb_game_play(), espn_cfb_game_player_box(), espn_cfb_game_player_statistics(), espn_cfb_game_powerindex(), espn_cfb_game_predictor(), espn_cfb_game_probabilities(), espn_cfb_game_situation(), espn_cfb_game_status(), espn_cfb_game_team_leaders(), espn_cfb_game_team_linescores(), espn_cfb_game_team_records(), espn_cfb_game_team_statistics(), espn_cfb_game_teams(), espn_cfb_groups(), espn_cfb_pbp_v2(), espn_cfb_player(), espn_cfb_player_career_stats(), espn_cfb_player_eventlog(), espn_cfb_player_gamelog(), espn_cfb_player_overview(), espn_cfb_player_seasons(), espn_cfb_player_splits(), espn_cfb_player_stats_v3(), espn_cfb_players(), espn_cfb_position(), espn_cfb_positions(), espn_cfb_powerindex(), espn_cfb_qbr(), espn_cfb_rankings(), espn_cfb_recruits(), espn_cfb_season_info(), espn_cfb_season_types(), espn_cfb_season_weeks(), espn_cfb_seasons(), espn_cfb_standings(), espn_cfb_team(), espn_cfb_team_ats(), espn_cfb_team_awards(), espn_cfb_team_coaches(), espn_cfb_team_events(), espn_cfb_team_leaders(), espn_cfb_team_powerindex(), espn_cfb_team_ranks(), espn_cfb_team_record(), espn_cfb_team_roster(), espn_cfb_team_schedule(), espn_cfb_teams(), espn_cfb_unnest_plays(), espn_cfb_venue(), espn_cfb_venues(), espn_cfb_week_rankings()

Examples


  try(espn_cfb_game_team_roster(game_id = 401628339))
  try(espn_cfb_game_team_roster(game_id = 401628339,
                                position_detail = FALSE))
  try(espn_cfb_game_team_roster(game_id = 401628339,
                                team_detail = FALSE))

ESPN College Football Game Team Statistics

Description

Get the full team box-score statistics for both teams in a single college football game, in long format.

Usage

espn_cfb_game_team_statistics(game_id = NULL, team_detail = TRUE)

Arguments

game_id

(Integer required): ESPN game identifier.

team_detail

(Logical): when TRUE (default), fetch the ESPN team catalog once and join friendly team fields next to the team_id column (see Details). Set FALSE to skip the catalog fetch and the join.

Details

Wraps the ESPN core-v2 endpoint events/{game_id}/competitions/{game_id}/competitors/{team_id}/statistics. This wrapper reads the teams list for the game and fetches the statistics resource for both teams, flattening the nested splits -> categories -> stats tree into one long frame: one row per (team x category x stat). The long shape absorbs ESPN's habit of adding and retiring stat keys across seasons. Pivot wider with tidyr::pivot_wider() keyed on stat_name when a wide team box is wanted.

When team_detail = TRUE (the default) the ESPN team catalog (espn_cfb_teams()) is fetched once and friendly team fields are joined in next to the team_id column – team_name, team_abbreviation, team_location, team_display_name, team_short_display_name, team_nickname, team_color, team_alternate_color, team_logo_href, and team_logo_dark_href. A catalog failure degrades to NA rather than erroring the wrapper. Set team_detail = FALSE to skip the catalog fetch and the join.

Value

A data frame with one row per team-category-stat:

col_name types description
game_id character ESPN game identifier.
team_id character ESPN team id for the team.
team_name character Team nickname; team_detail = TRUE only.
team_abbreviation character Team abbreviation; team_detail = TRUE only.
team_location character Team location / school name; team_detail = TRUE only.
team_display_name character Full team display name; team_detail = TRUE only.
team_short_display_name character Short team display name; team_detail = TRUE only.
team_nickname character Team nickname label; team_detail = TRUE only.
team_color character Primary team color; team_detail = TRUE only.
team_alternate_color character Alternate team color; team_detail = TRUE only.
team_logo_href character Default team logo URL; team_detail = TRUE only.
team_logo_dark_href character Dark-variant team logo URL; team_detail = TRUE only.
home_away character home or away.
split_id character ESPN statistics-split id.
split_name character ESPN statistics-split name (e.g. Total).
split_abbreviation character ESPN statistics-split abbreviation.
category_name character Stat category key (e.g. general, passing).
category_display character Human-readable category name.
category_short_display character Short human-readable category name.
category_abbreviation character Stat-category abbreviation.
category_summary character ESPN's summary string for the category.
stat_name character Internal stat key (e.g. passingYards).
abbreviation character Stat abbreviation.
display_name character Human-readable stat name.
short_display_name character Short human-readable stat name.
value numeric Stat value.
display_value character Display-formatted stat value as shown on ESPN.
description character ESPN's description of the stat.
statistics_ref character ⁠$ref⁠ URL to the team's statistics resource.
team_ref character ⁠$ref⁠ URL to the team-in-season resource.

See Also

Other ESPN CFB Functions: espn_cfb_award(), espn_cfb_awards(), espn_cfb_clear_cache(), espn_cfb_coach(), espn_cfb_coach_record(), espn_cfb_coaches(), espn_cfb_franchise(), espn_cfb_franchises(), espn_cfb_futures(), espn_cfb_game_broadcasts(), espn_cfb_game_drive_plays(), espn_cfb_game_drives(), espn_cfb_game_leaders(), espn_cfb_game_odds(), espn_cfb_game_pbp(), espn_cfb_game_play(), espn_cfb_game_player_box(), espn_cfb_game_player_statistics(), espn_cfb_game_powerindex(), espn_cfb_game_predictor(), espn_cfb_game_probabilities(), espn_cfb_game_situation(), espn_cfb_game_status(), espn_cfb_game_team_leaders(), espn_cfb_game_team_linescores(), espn_cfb_game_team_records(), espn_cfb_game_team_roster(), espn_cfb_game_teams(), espn_cfb_groups(), espn_cfb_pbp_v2(), espn_cfb_player(), espn_cfb_player_career_stats(), espn_cfb_player_eventlog(), espn_cfb_player_gamelog(), espn_cfb_player_overview(), espn_cfb_player_seasons(), espn_cfb_player_splits(), espn_cfb_player_stats_v3(), espn_cfb_players(), espn_cfb_position(), espn_cfb_positions(), espn_cfb_powerindex(), espn_cfb_qbr(), espn_cfb_rankings(), espn_cfb_recruits(), espn_cfb_season_info(), espn_cfb_season_types(), espn_cfb_season_weeks(), espn_cfb_seasons(), espn_cfb_standings(), espn_cfb_team(), espn_cfb_team_ats(), espn_cfb_team_awards(), espn_cfb_team_coaches(), espn_cfb_team_events(), espn_cfb_team_leaders(), espn_cfb_team_powerindex(), espn_cfb_team_ranks(), espn_cfb_team_record(), espn_cfb_team_roster(), espn_cfb_team_schedule(), espn_cfb_teams(), espn_cfb_unnest_plays(), espn_cfb_venue(), espn_cfb_venues(), espn_cfb_week_rankings()

Examples


  try(espn_cfb_game_team_statistics(game_id = 401628339))
  try(espn_cfb_game_team_statistics(game_id = 401628339,
                                    team_detail = FALSE))

ESPN College Football Game Teams

Description

Get the two teams (home and away teams) for a single college football game, with team identifiers, home/away designation, winner flag, and the ⁠$ref⁠ URLs to every per-team sub-resource.

Usage

espn_cfb_game_teams(
  game_id = NULL,
  team_detail = TRUE,
  format = c("long", "wide")
)

Arguments

game_id

(Integer required): ESPN game identifier.

team_detail

(Logical): when TRUE (default), fetch the ESPN team catalog once and join friendly team fields next to every team-id column (team_id, competitor_id; see Details). Set FALSE to skip the catalog fetch and the join.

format

(Character): output shape, one of "long" (default, one row per competitor) or "wide" (one row per game with ⁠home_*⁠ / ⁠away_*⁠ columns). See Details.

Details

Wraps the ESPN core-v2 endpoint events/{game_id}/competitions/{game_id}/competitors. The competition id always equals the game id. By default returns one row per team (two rows per game). Each row carries the ⁠$ref⁠ URLs ESPN publishes for that team's score, linescores, roster, statistics, leaders, and record resources – the dedicated ⁠espn_cfb_game_team_*()⁠ wrappers fetch and flatten those resources for you. curated_rank is the AP/Coaches-poll style rank ESPN attaches to the team at game time.

The format argument controls the output shape:

When team_detail = TRUE (the default) the ESPN team catalog (espn_cfb_teams()) is fetched once and friendly team fields are joined in next to every team-id column – team_id and competitor_id. For team_id the siblings are team_name, team_abbreviation, team_location, team_display_name, team_short_display_name, team_nickname, team_color, team_alternate_color, team_logo_href, team_logo_dark_href; competitor_id gains the parallel competitor_name, competitor_abbreviation, .... team_detail composes with format – in "wide" mode the home_team_id / away_team_id columns get home_team_name / away_team_name / etc. too. A catalog failure degrades to NA rather than erroring the wrapper. Set team_detail = FALSE to skip the catalog fetch and the join.

Value

A data frame. When format = "long" (default), one row per team (two per game):

col_name types description
game_id character ESPN game identifier.
competitor_id character ESPN competitor id (equals the team id).
competitor_name character Team nickname; team_detail = TRUE only.
competitor_abbreviation character Team abbreviation; team_detail = TRUE only.
competitor_location character Team location / school; team_detail = TRUE only.
competitor_display_name character Full team display name; team_detail = TRUE only.
competitor_short_display_name character Short team display name; team_detail = TRUE only.
competitor_nickname character Team nickname label; team_detail = TRUE only.
competitor_color character Primary team color; team_detail = TRUE only.
competitor_alternate_color character Alternate team color; team_detail = TRUE only.
competitor_logo_href character Default team logo URL; team_detail = TRUE only.
competitor_logo_dark_href character Dark-variant team logo URL; team_detail = TRUE only.
team_id character ESPN team id (parsed from team_ref).
team_name character Team nickname; team_detail = TRUE only.
team_abbreviation character Team abbreviation; team_detail = TRUE only.
team_location character Team location / school name; team_detail = TRUE only.
team_display_name character Full team display name; team_detail = TRUE only.
team_short_display_name character Short team display name; team_detail = TRUE only.
team_nickname character Team nickname label; team_detail = TRUE only.
team_color character Primary team color; team_detail = TRUE only.
team_alternate_color character Alternate team color; team_detail = TRUE only.
team_logo_href character Default team logo URL; team_detail = TRUE only.
team_logo_dark_href character Dark-variant team logo URL; team_detail = TRUE only.
order integer Team order within the competition (0 = first).
home_away character home or away.
winner logical TRUE if this team won the game.
competitor_type character Competitor type (e.g. team).
curated_rank integer Curated poll rank at game time (99 if unranked).
uid character ESPN universal identifier for the team.
team_ref character ⁠$ref⁠ URL to the team-in-season resource.
score_ref character ⁠$ref⁠ URL to the team score resource.
linescores_ref character ⁠$ref⁠ URL to the team linescores resource.
roster_ref character ⁠$ref⁠ URL to the team roster resource.
statistics_ref character ⁠$ref⁠ URL to the team statistics resource.
leaders_ref character ⁠$ref⁠ URL to the team leaders resource.
record_ref character ⁠$ref⁠ URL to the team record resource.
ranks_ref character ⁠$ref⁠ URL to the team week-ranks resource.
competitor_ref character ⁠$ref⁠ URL to the competitor resource itself.

When format = "wide" the result is a single row per game: game_id stays one key column and every other column above is emitted twice, prefixed home_ and away_ (e.g. home_team_id, home_team_name, home_winner, home_curated_rank, away_team_id, away_team_name, ...).

See Also

Other ESPN CFB Functions: espn_cfb_award(), espn_cfb_awards(), espn_cfb_clear_cache(), espn_cfb_coach(), espn_cfb_coach_record(), espn_cfb_coaches(), espn_cfb_franchise(), espn_cfb_franchises(), espn_cfb_futures(), espn_cfb_game_broadcasts(), espn_cfb_game_drive_plays(), espn_cfb_game_drives(), espn_cfb_game_leaders(), espn_cfb_game_odds(), espn_cfb_game_pbp(), espn_cfb_game_play(), espn_cfb_game_player_box(), espn_cfb_game_player_statistics(), espn_cfb_game_powerindex(), espn_cfb_game_predictor(), espn_cfb_game_probabilities(), espn_cfb_game_situation(), espn_cfb_game_status(), espn_cfb_game_team_leaders(), espn_cfb_game_team_linescores(), espn_cfb_game_team_records(), espn_cfb_game_team_roster(), espn_cfb_game_team_statistics(), espn_cfb_groups(), espn_cfb_pbp_v2(), espn_cfb_player(), espn_cfb_player_career_stats(), espn_cfb_player_eventlog(), espn_cfb_player_gamelog(), espn_cfb_player_overview(), espn_cfb_player_seasons(), espn_cfb_player_splits(), espn_cfb_player_stats_v3(), espn_cfb_players(), espn_cfb_position(), espn_cfb_positions(), espn_cfb_powerindex(), espn_cfb_qbr(), espn_cfb_rankings(), espn_cfb_recruits(), espn_cfb_season_info(), espn_cfb_season_types(), espn_cfb_season_weeks(), espn_cfb_seasons(), espn_cfb_standings(), espn_cfb_team(), espn_cfb_team_ats(), espn_cfb_team_awards(), espn_cfb_team_coaches(), espn_cfb_team_events(), espn_cfb_team_leaders(), espn_cfb_team_powerindex(), espn_cfb_team_ranks(), espn_cfb_team_record(), espn_cfb_team_roster(), espn_cfb_team_schedule(), espn_cfb_teams(), espn_cfb_unnest_plays(), espn_cfb_venue(), espn_cfb_venues(), espn_cfb_week_rankings()

Examples


  try(espn_cfb_game_teams(game_id = 401628339))
  try(espn_cfb_game_teams(game_id = 401628339, format = "wide"))
  try(espn_cfb_game_teams(game_id = 401628339, team_detail = FALSE))

ESPN College Football Groups & Conferences

Description

Get the full ESPN group hierarchy for a college football season – the division roll-ups (Division I, FBS, FCS) and every conference nested beneath them, flattened into one catalog table.

Usage

espn_cfb_groups(year = NULL, season_type = 2)

Arguments

year

(Integer required): Season, 4 digit format (YYYY).
Minimum value accepted: 2001

season_type

(Integer default 2): ESPN season type id. 2 = regular season is the sensible default.

Details

Wraps the ESPN core-v2 endpoint sports.core.api.espn.com/v2/sports/football/leagues/college-football/seasons/{year}/types/{season_type}/groups. ESPN's group index only exposes two top-level groups; the conferences sit several levels deep under children. This wrapper walks the tree recursively, dereferencing every node, and returns one row per group. Filter is_conference == TRUE for the actual conferences (ACC, SEC, Big Ten, ...); the group_id of a conference is what espn_cfb_standings() accepts as group_id. The parent_group_id column lets you reconstruct the division -> conference nesting.

Value

A data frame with one row per group:

col_name types description
season integer Season (4-digit year).
season_type integer ESPN season type id queried.
group_id character ESPN group id.
name character Group / conference name.
abbreviation character Group abbreviation.
short_name character Group short name.
is_conference logical TRUE for an actual conference, FALSE for a division roll-up.
parent_group_id character group_id of the parent node (NA at the root).
slug character Group slug.
group_ref character ⁠$ref⁠ URL to the group resource.
standings_ref character ⁠$ref⁠ URL to the group standings resource.
teams_ref character ⁠$ref⁠ URL to the group teams index.

See Also

Other ESPN CFB Functions: espn_cfb_award(), espn_cfb_awards(), espn_cfb_clear_cache(), espn_cfb_coach(), espn_cfb_coach_record(), espn_cfb_coaches(), espn_cfb_franchise(), espn_cfb_franchises(), espn_cfb_futures(), espn_cfb_game_broadcasts(), espn_cfb_game_drive_plays(), espn_cfb_game_drives(), espn_cfb_game_leaders(), espn_cfb_game_odds(), espn_cfb_game_pbp(), espn_cfb_game_play(), espn_cfb_game_player_box(), espn_cfb_game_player_statistics(), espn_cfb_game_powerindex(), espn_cfb_game_predictor(), espn_cfb_game_probabilities(), espn_cfb_game_situation(), espn_cfb_game_status(), espn_cfb_game_team_leaders(), espn_cfb_game_team_linescores(), espn_cfb_game_team_records(), espn_cfb_game_team_roster(), espn_cfb_game_team_statistics(), espn_cfb_game_teams(), espn_cfb_pbp_v2(), espn_cfb_player(), espn_cfb_player_career_stats(), espn_cfb_player_eventlog(), espn_cfb_player_gamelog(), espn_cfb_player_overview(), espn_cfb_player_seasons(), espn_cfb_player_splits(), espn_cfb_player_stats_v3(), espn_cfb_players(), espn_cfb_position(), espn_cfb_positions(), espn_cfb_powerindex(), espn_cfb_qbr(), espn_cfb_rankings(), espn_cfb_recruits(), espn_cfb_season_info(), espn_cfb_season_types(), espn_cfb_season_weeks(), espn_cfb_seasons(), espn_cfb_standings(), espn_cfb_team(), espn_cfb_team_ats(), espn_cfb_team_awards(), espn_cfb_team_coaches(), espn_cfb_team_events(), espn_cfb_team_leaders(), espn_cfb_team_powerindex(), espn_cfb_team_ranks(), espn_cfb_team_record(), espn_cfb_team_roster(), espn_cfb_team_schedule(), espn_cfb_teams(), espn_cfb_unnest_plays(), espn_cfb_venue(), espn_cfb_venues(), espn_cfb_week_rankings()

Examples


  try(espn_cfb_groups(year = 2024))

Get ESPN college football PBP data

Description

Get ESPN college football PBP data

Usage

espn_cfb_pbp(game_id, epa_wpa = FALSE, engine = NULL, output = "default")

Arguments

game_id

Game ID

epa_wpa

Logical parameter (TRUE/FALSE) to return the Expected Points Added/Win Probability Added variables

engine

(Character optional): which play-by-play engine to run. One of "v2", "legacy" or "auto"; NULL (default) resolves from getOption("cfbfastR.pbp_engine"), which itself defaults to "v2" as of this release. "legacy" is the escape hatch that reproduces the pre-2.3.0 frame; "auto" means whatever this version of the package considers current, so it is carried forward by future default flips.

output

(Character): modeled-output column set, one of "default", "lean" or "full". Only meaningful when the call reaches the v2 engine; it is accepted here so a delegating caller can reach the tier selector without switching to the espn_cfb_pbp_v2() name.

Value

A data frame with college football play-by-play data

Author(s)

Saiem Gilani

Examples

 
   try(espn_cfb_pbp(game_id = 401282614, epa_wpa = TRUE))

Get ESPN College Football Play-by-Play (core-v2)

Description

The core-v2-sourced successor to espn_cfb_pbp(). Returns one tidy row per play for a single college football game, optionally with the full Expected Points Added (EPA) / Win Probability Added (WPA) modeling attached. It supersedes the legacy site-v2 espn_cfb_pbp(): instead of parsing the deeply-nested site-v2 summary feed, it sources the play-by-play from the structured ESPN core-v2 drives endpoint in a single request via espn_cfb_game_drives() – one structured call rather than a sprawling summary parse, so it is faster and more robust to the site-v2 feed's column drift.

Usage

espn_cfb_pbp_v2(
  game_id,
  epa_wpa = FALSE,
  output = "default",
  resolve_names = TRUE
)

Arguments

game_id

(Integer required): ESPN game identifier.

epa_wpa

(Logical): when TRUE, run the full EPA/WPA modeling pipeline and return the modeled frame; when FALSE (default) return the assembled core-v2 play-by-play frame.

output

(Character): controls the modeled-output column set when epa_wpa = TRUE. Ignored when epa_wpa = FALSE. Defaults to "default". Must be one of:

  • "default" (recommended) – drops pipeline lag/lead intermediates, redundant alternates (sack_vec, turnover_indicator, kick_play, missing_yard_flag), and drive-result aliases (drive_result2, drive_result_detailed_flag, lag_drive_result_detailed, lead_drive_result_detailed, lag_new_drive_pts). Keeps orig_play_type and pts_scored (they carry useful per-play information distinct from the canonical columns) and the per-branch WPA scratchpad. ~75 columns lighter than "full".

  • "lean" – everything "default" drops, plus the WPA computation scratchpad. For dashboards / game logs.

  • "full" – legacy behavior, drops only the player-name aliases.

resolve_names

(Logical): when TRUE (default) and epa_wpa = TRUE, spend one extra request per game on ESPN's play-by-play sidecar to (a) render participant names in full ("Jalen Mitchell" rather than the core-v2 roster's "J. Mitchell") and (b) add the per-player box score as a second identity source, which is the only one available on the large share of games where ESPN 404s the roster resource. Memoised per game_id, so the two uses cost one request between them. Set FALSE for a bulk sweep that would rather have the short names than the requests. Ignored when epa_wpa = FALSE.

Details

Play-by-play assembly (always). The play rows come from espn_cfb_game_drives(game_id, plays = "expand", team_detail = TRUE) – one row per play, in the full espn_cfb_game_pbp() schema, with each play's drive-level context carried alongside (⁠drive_*⁠ columns) and the ESPN team catalog joined onto every team-id column. Game-level metadata matching the legacy espn_cfb_pbp() output – season, season_type, week, neutral_site, conference_competition, game_date, and the home_team_id / home_team / away_team_id / away_team (plus abbreviations) – is attached from the core-v2 event resource and espn_cfb_game_teams().

Game-meta bridge. Season / season_type / week / neutral_site / conference_competition / game_date and the full home/away block – including ⁠*_team_name⁠, ⁠*_team_color⁠, ⁠*_team_alternate_color⁠, and the week-specific ⁠*_team_rank⁠ – are sourced via .espn_pbp_game_meta(), which queries the core-v2 event resource. This makes espn_cfb_pbp_v2() a strict meta-column superset of legacy espn_cfb_pbp().

Native participant columns. This wrapper requests participants = "wide" and team_participants = "wide" from espn_cfb_game_drives(), so the play frame carries type-keyed ⁠{type}_player_id⁠ / ⁠{type}_player_name⁠ / ⁠{type}_player_position⁠ columns (e.g. passer_player_id, rusher_player_id, tackler_player_id) and ⁠{type}_team_*⁠ columns. Wide mode also emits the ⁠{type}_player_ids⁠ / ⁠{type}_player_names⁠ list-columns; downstream parquet/CSV writers must drop or stringify these before serialization. One additional roster fetch + position-catalog fetch per game.

epa_wpa behaviour. When epa_wpa = FALSE (default) the assembled core-v2 frame is returned as-is. When epa_wpa = TRUE the core-v2 columns are mapped into the exact column schema the legacy espn_cfb_pbp() hands to its EPA/WPA pipeline, and the same modeling stack is run verbatim – penalty_detection(), add_play_counts(), clean_pbp_dat(), clean_drive_dat(), add_yardage(), add_player_cols(), prep_epa_df_after(), create_epa() and create_wpa_naive(). The statistical models (the mgcv GAMs, the multinomial EP model, the FG model and the WP model shipped with the package) are reused unchanged; this wrapper only supplies the column adapter between the core-v2 play schema and the modeling input contract. The modeled EPA/WPA columns the pipeline emits – ep_before, ep_after, EPA, wp_before, wp_after, wpa, and the supporting probability and cumulative columns – are then joined back onto the full epa_wpa = FALSE context frame by play_id. The epa_wpa = TRUE output is therefore a strict superset of the epa_wpa = FALSE output: every game-metadata and drive-context column the default path produces, plus the EPA/WPA model columns. The join is a left join from the context frame, so no play row is dropped and the row count is identical to the epa_wpa = FALSE result.

Value

A data frame with one row per play. When epa_wpa = FALSE, the assembled core-v2 play-by-play frame:

col_name types description
game_id character ESPN game identifier.
play_id character ESPN play id.
type_text character Play type label (e.g. Rush, ⁠Pass Reception⁠).

(plus the full espn_cfb_game_drives() plays = "expand" column set – play start/end down, distance, yard line, clock, scores, the ⁠drive_*⁠ drive context, team detail – and the attached game-metadata columns season, season_type, week, neutral_site, conference_competition, game_date, home_team_id, home_team, away_team_id, away_team).

When epa_wpa = TRUE, every column from the epa_wpa = FALSE frame above (game metadata, ⁠drive_*⁠ context, team detail and the full espn_cfb_game_drives() play schema) plus the modeled EPA/WPA columns produced by the existing pipeline – ep_before, ep_after, EPA, wp_before, wp_after, wpa and the supporting probability and cumulative columns. The epa_wpa = TRUE columns are a strict superset of the epa_wpa = FALSE columns, and the row count is unchanged.

See Also

Other ESPN CFB Functions: espn_cfb_award(), espn_cfb_awards(), espn_cfb_clear_cache(), espn_cfb_coach(), espn_cfb_coach_record(), espn_cfb_coaches(), espn_cfb_franchise(), espn_cfb_franchises(), espn_cfb_futures(), espn_cfb_game_broadcasts(), espn_cfb_game_drive_plays(), espn_cfb_game_drives(), espn_cfb_game_leaders(), espn_cfb_game_odds(), espn_cfb_game_pbp(), espn_cfb_game_play(), espn_cfb_game_player_box(), espn_cfb_game_player_statistics(), espn_cfb_game_powerindex(), espn_cfb_game_predictor(), espn_cfb_game_probabilities(), espn_cfb_game_situation(), espn_cfb_game_status(), espn_cfb_game_team_leaders(), espn_cfb_game_team_linescores(), espn_cfb_game_team_records(), espn_cfb_game_team_roster(), espn_cfb_game_team_statistics(), espn_cfb_game_teams(), espn_cfb_groups(), espn_cfb_player(), espn_cfb_player_career_stats(), espn_cfb_player_eventlog(), espn_cfb_player_gamelog(), espn_cfb_player_overview(), espn_cfb_player_seasons(), espn_cfb_player_splits(), espn_cfb_player_stats_v3(), espn_cfb_players(), espn_cfb_position(), espn_cfb_positions(), espn_cfb_powerindex(), espn_cfb_qbr(), espn_cfb_rankings(), espn_cfb_recruits(), espn_cfb_season_info(), espn_cfb_season_types(), espn_cfb_season_weeks(), espn_cfb_seasons(), espn_cfb_standings(), espn_cfb_team(), espn_cfb_team_ats(), espn_cfb_team_awards(), espn_cfb_team_coaches(), espn_cfb_team_events(), espn_cfb_team_leaders(), espn_cfb_team_powerindex(), espn_cfb_team_ranks(), espn_cfb_team_record(), espn_cfb_team_roster(), espn_cfb_team_schedule(), espn_cfb_teams(), espn_cfb_unnest_plays(), espn_cfb_venue(), espn_cfb_venues(), espn_cfb_week_rankings()

Examples


  try(espn_cfb_pbp_v2(game_id = 401628339, epa_wpa = TRUE))

ESPN College Football Player Endpoint Overview

Description

Get the full ESPN record for a single college football player in a given season – biographical fields, physical measurements, position, team, status, and the ⁠$ref⁠ URLs to the player's nested resources (statistics, event log, college).

Usage

espn_cfb_player(
  athlete_id = NULL,
  year = NULL,
  team_detail = TRUE,
  position_detail = TRUE
)

Arguments

athlete_id

(Character/Integer required): ESPN athlete id.

year

(Integer required): Season, 4 digit format (YYYY).
Minimum value accepted: 2004

team_detail

(Logical): when TRUE (default), fetch the ESPN team catalog once and join friendly team fields next to the team_id column (see Details). Set FALSE to skip the catalog fetch and the join.

position_detail

(Logical): when TRUE (default), fetch the ESPN position catalog once and join it onto position_id, appending the position_display_name / position_leaf / position_parent_id detail columns. A catalog failure degrades to NA rather than erroring the wrapper. Set FALSE to skip the extra fetch and the join.

Details

ESPN College Football Player Detail

espn_cfb_player(athlete_id = 102597, year = 2024)

ESPN College Football Players Index

espn_cfb_players(year = 2024, page = 1, max_pages = 1)

ESPN College Football Player Event Log

espn_cfb_player_eventlog(athlete_id = 102597, year = 2024)

ESPN College Football Player Game Log

espn_cfb_player_gamelog(athlete_id = 102597, year = 2024)

ESPN College Football Player Statistics Overview

espn_cfb_player_overview(athlete_id = 102597, year = 2024)

ESPN College Football Player Seasons

espn_cfb_player_seasons(athlete_id = 102597)

ESPN College Football Player Statistical Splits

espn_cfb_player_splits(athlete_id = 102597, year = 2024)

ESPN College Football Player Season Statistics (Long Format)

espn_cfb_player_career_stats(athlete_id = 102597, year = 2024)

Get ESPN college football player stats data

espn_cfb_player_stats(athlete_id = 530308, year = 2013)

ESPN College Football Recruits

espn_cfb_recruits(year = 2024, max_results = 25)

Wraps the ESPN core-v2 endpoint sports.core.api.espn.com/v2/sports/football/leagues/college-football/seasons/{year}/athletes/{athlete_id}. The season-scoped path is used so the returned team_id reflects the team the player was on that season. The wrapper returns a single-row tibble: scalar bio fields are flattened inline, nested objects (position, status, birthPlace, experience) are flattened with a prefix, and the nested ⁠$ref⁠ URLs are surfaced as ⁠*_ref⁠ columns rather than auto-dereferenced. Harvest athlete ids from espn_cfb_players().

When team_detail = TRUE (the default) the ESPN team catalog (espn_cfb_teams()) is fetched once and friendly team fields are joined in next to the team_id column – team_name, team_abbreviation, team_location, team_display_name, team_short_display_name, team_nickname, team_color, team_alternate_color, team_logo_href, and team_logo_dark_href, inserted immediately after team_id. A catalog failure degrades to NA rather than erroring the wrapper. Set team_detail = FALSE to skip the catalog fetch and the join.

When position_detail = TRUE (the default) the ESPN position catalog (espn_cfb_positions()) is fetched once and joined onto position_id, appending position_display_name, position_leaf, and position_parent_id (the existing position_name / position_abbreviation columns are left in place). A catalog failure degrades to NA rather than erroring the wrapper. Set position_detail = FALSE to skip the catalog fetch and the join.

Value

A one-row data frame describing the player:

col_name types description
athlete_id character ESPN athlete id.
season integer Season (4-digit year).
uid character ESPN athlete UID.
guid character ESPN athlete GUID.
first_name character Player first name.
last_name character Player last name.
full_name character Player full name.
display_name character Player display name.
short_name character Player short name.
weight numeric Listed weight (lbs).
display_weight character Display-formatted weight.
height numeric Listed height (inches).
display_height character Display-formatted height.
jersey character Jersey number.
slug character ESPN athlete URL slug.
active logical Whether the player is currently active.
date_of_birth character Player date of birth (if published).
birth_city character Birthplace city.
birth_state character Birthplace state.
birth_country character Birthplace country.
position_id character ESPN position id.
position_name character Position name.
position_abbreviation character Position abbreviation.
position_display_name character Human-readable position name; position_detail = TRUE only.
position_leaf logical TRUE for a most-specific (leaf) position; position_detail = TRUE only.
position_parent_id character ESPN id of the parent position; position_detail = TRUE only.
experience_years integer Years of experience.
status_id character ESPN status id.
status_name character Status name (e.g. Active).
status_type character Status type.
headshot_href character URL of the player headshot image.
team_id character ESPN team id for the season (from team_ref).
team_name character Team nickname; team_detail = TRUE only.
team_abbreviation character Team abbreviation; team_detail = TRUE only.
team_location character Team location / school name; team_detail = TRUE only.
team_display_name character Full team display name; team_detail = TRUE only.
team_short_display_name character Short team display name; team_detail = TRUE only.
team_nickname character Team nickname label; team_detail = TRUE only.
team_color character Primary team color; team_detail = TRUE only.
team_alternate_color character Alternate team color; team_detail = TRUE only.
team_logo_href character Default team logo URL; team_detail = TRUE only.
team_logo_dark_href character Dark-variant team logo URL; team_detail = TRUE only.
team_ref character ⁠$ref⁠ URL to the team-in-season resource.
statistics_ref character ⁠$ref⁠ URL to the player statistics resource.
eventlog_ref character ⁠$ref⁠ URL to the player event log resource.
college_ref character ⁠$ref⁠ URL to the player college resource.

See Also

Other ESPN CFB Functions: espn_cfb_award(), espn_cfb_awards(), espn_cfb_clear_cache(), espn_cfb_coach(), espn_cfb_coach_record(), espn_cfb_coaches(), espn_cfb_franchise(), espn_cfb_franchises(), espn_cfb_futures(), espn_cfb_game_broadcasts(), espn_cfb_game_drive_plays(), espn_cfb_game_drives(), espn_cfb_game_leaders(), espn_cfb_game_odds(), espn_cfb_game_pbp(), espn_cfb_game_play(), espn_cfb_game_player_box(), espn_cfb_game_player_statistics(), espn_cfb_game_powerindex(), espn_cfb_game_predictor(), espn_cfb_game_probabilities(), espn_cfb_game_situation(), espn_cfb_game_status(), espn_cfb_game_team_leaders(), espn_cfb_game_team_linescores(), espn_cfb_game_team_records(), espn_cfb_game_team_roster(), espn_cfb_game_team_statistics(), espn_cfb_game_teams(), espn_cfb_groups(), espn_cfb_pbp_v2(), espn_cfb_player_career_stats(), espn_cfb_player_eventlog(), espn_cfb_player_gamelog(), espn_cfb_player_overview(), espn_cfb_player_seasons(), espn_cfb_player_splits(), espn_cfb_player_stats_v3(), espn_cfb_players(), espn_cfb_position(), espn_cfb_positions(), espn_cfb_powerindex(), espn_cfb_qbr(), espn_cfb_rankings(), espn_cfb_recruits(), espn_cfb_season_info(), espn_cfb_season_types(), espn_cfb_season_weeks(), espn_cfb_seasons(), espn_cfb_standings(), espn_cfb_team(), espn_cfb_team_ats(), espn_cfb_team_awards(), espn_cfb_team_coaches(), espn_cfb_team_events(), espn_cfb_team_leaders(), espn_cfb_team_powerindex(), espn_cfb_team_ranks(), espn_cfb_team_record(), espn_cfb_team_roster(), espn_cfb_team_schedule(), espn_cfb_teams(), espn_cfb_unnest_plays(), espn_cfb_venue(), espn_cfb_venues(), espn_cfb_week_rankings()

Examples


  try(espn_cfb_player(athlete_id = 102597, year = 2024))
  try(espn_cfb_player(athlete_id = 102597, year = 2024,
                      team_detail = FALSE, position_detail = FALSE))

ESPN College Football Player Season Statistics (Long Format)

Description

Get a single college football player's full season statistics from ESPN – every published stat across every category, in long format (one row per stat).

Usage

espn_cfb_player_career_stats(
  athlete_id = NULL,
  year = NULL,
  season_type = 2,
  athlete_detail = TRUE
)

Arguments

athlete_id

(Character/Integer required): ESPN athlete id.

year

(Integer required): Season, 4 digit format (YYYY).
Minimum value accepted: 2004

season_type

(Integer optional, default 2): ESPN season type. 2 = regular season, 3 = postseason.

athlete_detail

(Logical): when TRUE (default), fetch the requested athlete's ESPN record once and append the ⁠athlete_*⁠ name columns (see Details). Set FALSE to skip the fetch, reproducing the prior output exactly.

Details

Wraps the ESPN core-v2 endpoint sports.core.api.espn.com/v2/sports/football/leagues/college-football/seasons/{year}/types/{season_type}/athletes/{athlete_id}/statistics. ESPN nests a player's season stats under splits -> categories[] -> stats[]; this wrapper flattens that tree to long format – each row is one stat, tagged with its category (e.g. passing, rushing, defensive). The long shape is deliberate: ESPN adds and retires stats and whole categories across positions and seasons, and a long frame absorbs that drift without breaking column expectations. Pivot wider with tidyr::pivot_wider() keyed on stat_name for a wide table. Each stat carries both a season-total value (value) and a per-game value (per_game_value).

When athlete_detail = TRUE (the default) the requested athlete's ESPN record is fetched once and the human-readable name columns athlete_display_name, athlete_first_name, athlete_last_name, athlete_jersey, athlete_position, and athlete_position_abbreviation are appended to every row. This is a single cheap fetch – the wrapper already takes one athlete_id. A fetch failure degrades the name columns to NA rather than erroring the wrapper. Set athlete_detail = FALSE to skip the fetch and reproduce the prior output exactly.

Value

A data frame with one row per stat:

col_name types description
athlete_id character ESPN athlete id.
season integer Season (4-digit year).
season_type integer ESPN season type (2 = regular, 3 = postseason).
category character Stat category (e.g. passing, rushing).
category_display character Human-readable category name.
stat_name character Internal stat key (e.g. passingYards).
display_name character Human-readable stat name.
abbreviation character Stat abbreviation.
description character ESPN's description of the stat.
value numeric Season-total value of the stat.
display_value character Display-formatted season-total value.
per_game_value numeric Per-game value of the stat.
per_game_display_value character Display-formatted per-game value.
athlete_display_name character Player display name; athlete_detail = TRUE only.
athlete_first_name character Player first name; athlete_detail = TRUE only.
athlete_last_name character Player last name; athlete_detail = TRUE only.
athlete_jersey character Player jersey number; athlete_detail = TRUE only.
athlete_position character Player position name; athlete_detail = TRUE only.
athlete_position_abbreviation character Player position abbreviation; athlete_detail = TRUE only.

See Also

Other ESPN CFB Functions: espn_cfb_award(), espn_cfb_awards(), espn_cfb_clear_cache(), espn_cfb_coach(), espn_cfb_coach_record(), espn_cfb_coaches(), espn_cfb_franchise(), espn_cfb_franchises(), espn_cfb_futures(), espn_cfb_game_broadcasts(), espn_cfb_game_drive_plays(), espn_cfb_game_drives(), espn_cfb_game_leaders(), espn_cfb_game_odds(), espn_cfb_game_pbp(), espn_cfb_game_play(), espn_cfb_game_player_box(), espn_cfb_game_player_statistics(), espn_cfb_game_powerindex(), espn_cfb_game_predictor(), espn_cfb_game_probabilities(), espn_cfb_game_situation(), espn_cfb_game_status(), espn_cfb_game_team_leaders(), espn_cfb_game_team_linescores(), espn_cfb_game_team_records(), espn_cfb_game_team_roster(), espn_cfb_game_team_statistics(), espn_cfb_game_teams(), espn_cfb_groups(), espn_cfb_pbp_v2(), espn_cfb_player(), espn_cfb_player_eventlog(), espn_cfb_player_gamelog(), espn_cfb_player_overview(), espn_cfb_player_seasons(), espn_cfb_player_splits(), espn_cfb_player_stats_v3(), espn_cfb_players(), espn_cfb_position(), espn_cfb_positions(), espn_cfb_powerindex(), espn_cfb_qbr(), espn_cfb_rankings(), espn_cfb_recruits(), espn_cfb_season_info(), espn_cfb_season_types(), espn_cfb_season_weeks(), espn_cfb_seasons(), espn_cfb_standings(), espn_cfb_team(), espn_cfb_team_ats(), espn_cfb_team_awards(), espn_cfb_team_coaches(), espn_cfb_team_events(), espn_cfb_team_leaders(), espn_cfb_team_powerindex(), espn_cfb_team_ranks(), espn_cfb_team_record(), espn_cfb_team_roster(), espn_cfb_team_schedule(), espn_cfb_teams(), espn_cfb_unnest_plays(), espn_cfb_venue(), espn_cfb_venues(), espn_cfb_week_rankings()

Examples


  try(espn_cfb_player_career_stats(athlete_id = 102597, year = 2024))
  try(espn_cfb_player_career_stats(athlete_id = 102597, year = 2024,
                                 athlete_detail = FALSE))

ESPN College Football Player Event Log

Description

Get the per-game event log for a single college football player in a season – one row per game, with the ⁠$ref⁠ URLs to each game's event, competition, and the player's per-game statistics.

Usage

espn_cfb_player_eventlog(
  athlete_id = NULL,
  year = NULL,
  team_detail = TRUE,
  athlete_detail = TRUE
)

Arguments

athlete_id

(Character/Integer required): ESPN athlete id.

year

(Integer required): Season, 4 digit format (YYYY).
Minimum value accepted: 2004

team_detail

(Logical): when TRUE (default), fetch the ESPN team catalog once and join friendly team fields next to the team_id column (see Details). Set FALSE to skip the catalog fetch and the join.

athlete_detail

(Logical): when TRUE (default), fetch the requested athlete's ESPN record once and append the ⁠athlete_*⁠ name columns (see Details). Set FALSE to skip the fetch, reproducing the prior output exactly.

Details

Wraps the ESPN core-v2 endpoint sports.core.api.espn.com/v2/sports/football/leagues/college-football/seasons/{year}/athletes/{athlete_id}/eventlog. The event log lists every game the player appeared on a roster for in the requested season. Per-game statistics are referenced by a statistics_ref URL rather than being inlined – they are not auto-dereferenced, since one fetch per game would be costly; resolve a particular game with a direct request to that URL when needed. If the player did not play in the requested season ESPN returns an empty payload and this wrapper returns an empty data frame.

When team_detail = TRUE (the default) the ESPN team catalog (espn_cfb_teams()) is fetched once and friendly team fields are joined in next to the team_id column – team_name, team_abbreviation, team_location, team_display_name, team_short_display_name, team_nickname, team_color, team_alternate_color, team_logo_href, and team_logo_dark_href, inserted immediately after team_id. A catalog failure degrades to NA rather than erroring the wrapper. Set team_detail = FALSE to skip the catalog fetch and the join.

When athlete_detail = TRUE (the default) the requested athlete's ESPN record is fetched once and the human-readable name columns athlete_display_name, athlete_first_name, athlete_last_name, athlete_jersey, athlete_position, and athlete_position_abbreviation are appended to every row. This is a single cheap fetch – the wrapper already takes one athlete_id. A fetch failure degrades the name columns to NA rather than erroring the wrapper. Set athlete_detail = FALSE to skip the fetch and reproduce the prior output exactly.

Value

A data frame with one row per game:

col_name types description
athlete_id character ESPN athlete id.
season integer Season (4-digit year).
game_id character ESPN event (game) id (parsed from event_ref).
team_id character ESPN team id the player played for in the game.
team_name character Team nickname; team_detail = TRUE only.
team_abbreviation character Team abbreviation; team_detail = TRUE only.
team_location character Team location / school name; team_detail = TRUE only.
team_display_name character Full team display name; team_detail = TRUE only.
team_short_display_name character Short team display name; team_detail = TRUE only.
team_nickname character Team nickname label; team_detail = TRUE only.
team_color character Primary team color; team_detail = TRUE only.
team_alternate_color character Alternate team color; team_detail = TRUE only.
team_logo_href character Default team logo URL; team_detail = TRUE only.
team_logo_dark_href character Dark-variant team logo URL; team_detail = TRUE only.
played logical Whether the player played in the game.
event_ref character ⁠$ref⁠ URL to the event resource.
competition_ref character ⁠$ref⁠ URL to the competition resource.
statistics_ref character ⁠$ref⁠ URL to the player's per-game statistics.
athlete_display_name character Player display name; athlete_detail = TRUE only.
athlete_first_name character Player first name; athlete_detail = TRUE only.
athlete_last_name character Player last name; athlete_detail = TRUE only.
athlete_jersey character Player jersey number; athlete_detail = TRUE only.
athlete_position character Player position name; athlete_detail = TRUE only.
athlete_position_abbreviation character Player position abbreviation; athlete_detail = TRUE only.

See Also

Other ESPN CFB Functions: espn_cfb_award(), espn_cfb_awards(), espn_cfb_clear_cache(), espn_cfb_coach(), espn_cfb_coach_record(), espn_cfb_coaches(), espn_cfb_franchise(), espn_cfb_franchises(), espn_cfb_futures(), espn_cfb_game_broadcasts(), espn_cfb_game_drive_plays(), espn_cfb_game_drives(), espn_cfb_game_leaders(), espn_cfb_game_odds(), espn_cfb_game_pbp(), espn_cfb_game_play(), espn_cfb_game_player_box(), espn_cfb_game_player_statistics(), espn_cfb_game_powerindex(), espn_cfb_game_predictor(), espn_cfb_game_probabilities(), espn_cfb_game_situation(), espn_cfb_game_status(), espn_cfb_game_team_leaders(), espn_cfb_game_team_linescores(), espn_cfb_game_team_records(), espn_cfb_game_team_roster(), espn_cfb_game_team_statistics(), espn_cfb_game_teams(), espn_cfb_groups(), espn_cfb_pbp_v2(), espn_cfb_player(), espn_cfb_player_career_stats(), espn_cfb_player_gamelog(), espn_cfb_player_overview(), espn_cfb_player_seasons(), espn_cfb_player_splits(), espn_cfb_player_stats_v3(), espn_cfb_players(), espn_cfb_position(), espn_cfb_positions(), espn_cfb_powerindex(), espn_cfb_qbr(), espn_cfb_rankings(), espn_cfb_recruits(), espn_cfb_season_info(), espn_cfb_season_types(), espn_cfb_season_weeks(), espn_cfb_seasons(), espn_cfb_standings(), espn_cfb_team(), espn_cfb_team_ats(), espn_cfb_team_awards(), espn_cfb_team_coaches(), espn_cfb_team_events(), espn_cfb_team_leaders(), espn_cfb_team_powerindex(), espn_cfb_team_ranks(), espn_cfb_team_record(), espn_cfb_team_roster(), espn_cfb_team_schedule(), espn_cfb_teams(), espn_cfb_unnest_plays(), espn_cfb_venue(), espn_cfb_venues(), espn_cfb_week_rankings()

Examples


  try(espn_cfb_player_eventlog(athlete_id = 102597, year = 2024))
  try(espn_cfb_player_eventlog(athlete_id = 102597, year = 2024,
                               team_detail = FALSE,
                               athlete_detail = FALSE))

ESPN College Football Player Game Log

Description

Get a single college football player's game-by-game statistical log for a season – one row per game, with the player's stat line joined to opponent, score, and result metadata.

Usage

espn_cfb_player_gamelog(
  athlete_id = NULL,
  year = NULL,
  team_detail = TRUE,
  athlete_detail = TRUE
)

Arguments

athlete_id

(Character/Integer required): ESPN athlete id.

year

(Integer required): Season, 4 digit format (YYYY).
Minimum value accepted: 2004

team_detail

(Logical): when TRUE (default), fetch the ESPN team catalog once and join friendly team fields next to the team_id column (see Details). Set FALSE to skip the catalog fetch and the join.

athlete_detail

(Logical): when TRUE (default), fetch the requested athlete's ESPN record once and append the ⁠athlete_*⁠ name columns (see Details). Set FALSE to skip the fetch, reproducing the prior output exactly.

Details

Wraps the ESPN web-v3 endpoint site.web.api.espn.com/apis/common/v3/sports/football/college-football/athletes/{athlete_id}/gamelog. Unlike the core-v2 espn_cfb_player_eventlog() (which returns only ⁠$ref⁠ URLs), this endpoint ships fully-resolved per-game stat lines. The wrapper joins three blocks of the payload: the events map (game metadata – opponent, date, score, result), the seasonTypes -> categories -> events block (the per-game stat values), and the top-level labels / names arrays (the stat column names). Stat columns are named from the names array (e.g. completions, passing_yards); they vary by the player's position. If the player did not play in the requested season ESPN returns only a filters object and this wrapper returns an empty data frame.

When team_detail = TRUE (the default) the ESPN team catalog (espn_cfb_teams()) is fetched once and friendly team fields are joined in next to the team_id column – team_name, team_abbreviation, team_location, team_display_name, team_short_display_name, team_nickname, team_color, team_alternate_color, team_logo_href, and team_logo_dark_href, inserted immediately after team_id. A catalog failure degrades to NA rather than erroring the wrapper. Set team_detail = FALSE to skip the catalog fetch and the join.

When athlete_detail = TRUE (the default) the requested athlete's ESPN record is fetched once and the human-readable name columns athlete_display_name, athlete_first_name, athlete_last_name, athlete_jersey, athlete_position, and athlete_position_abbreviation are appended to every row. This is a single cheap fetch – the wrapper already takes one athlete_id. A fetch failure degrades the name columns to NA rather than erroring the wrapper. Set athlete_detail = FALSE to skip the fetch and reproduce the prior output exactly.

Value

A data frame with one row per game. The leading columns are fixed; the trailing stat columns vary by position:

col_name types description
athlete_id character ESPN athlete id.
season integer Season (4-digit year).
season_type character Season-type label (e.g. ⁠2024 Regular Season⁠).
game_id character ESPN event (game) id.
game_date character Game date (ISO 8601).
week integer Week number.
at_vs character vs (home) or @ (away).
opponent_id character ESPN team id of the opponent.
opponent_name character Opponent display name.
opponent_abbr character Opponent abbreviation.
team_id character ESPN team id the player played for.
team_name character Team nickname; team_detail = TRUE only.
team_abbreviation character Team abbreviation; team_detail = TRUE only.
team_location character Team location / school name; team_detail = TRUE only.
team_display_name character Full team display name; team_detail = TRUE only.
team_short_display_name character Short team display name; team_detail = TRUE only.
team_nickname character Team nickname label; team_detail = TRUE only.
team_color character Primary team color; team_detail = TRUE only.
team_alternate_color character Alternate team color; team_detail = TRUE only.
team_logo_href character Default team logo URL; team_detail = TRUE only.
team_logo_dark_href character Dark-variant team logo URL; team_detail = TRUE only.
home_team_score character Home team final score.
away_team_score character Away team final score.
game_result character Game result for the player's team (W/L).
score character Final score string.
athlete_display_name character Player display name; athlete_detail = TRUE only.
athlete_first_name character Player first name; athlete_detail = TRUE only.
athlete_last_name character Player last name; athlete_detail = TRUE only.
athlete_jersey character Player jersey number; athlete_detail = TRUE only.
athlete_position character Player position name; athlete_detail = TRUE only.
athlete_position_abbreviation character Player position abbreviation; athlete_detail = TRUE only.
... character One column per stat in the names array (varies).

See Also

Other ESPN CFB Functions: espn_cfb_award(), espn_cfb_awards(), espn_cfb_clear_cache(), espn_cfb_coach(), espn_cfb_coach_record(), espn_cfb_coaches(), espn_cfb_franchise(), espn_cfb_franchises(), espn_cfb_futures(), espn_cfb_game_broadcasts(), espn_cfb_game_drive_plays(), espn_cfb_game_drives(), espn_cfb_game_leaders(), espn_cfb_game_odds(), espn_cfb_game_pbp(), espn_cfb_game_play(), espn_cfb_game_player_box(), espn_cfb_game_player_statistics(), espn_cfb_game_powerindex(), espn_cfb_game_predictor(), espn_cfb_game_probabilities(), espn_cfb_game_situation(), espn_cfb_game_status(), espn_cfb_game_team_leaders(), espn_cfb_game_team_linescores(), espn_cfb_game_team_records(), espn_cfb_game_team_roster(), espn_cfb_game_team_statistics(), espn_cfb_game_teams(), espn_cfb_groups(), espn_cfb_pbp_v2(), espn_cfb_player(), espn_cfb_player_career_stats(), espn_cfb_player_eventlog(), espn_cfb_player_overview(), espn_cfb_player_seasons(), espn_cfb_player_splits(), espn_cfb_player_stats_v3(), espn_cfb_players(), espn_cfb_position(), espn_cfb_positions(), espn_cfb_powerindex(), espn_cfb_qbr(), espn_cfb_rankings(), espn_cfb_recruits(), espn_cfb_season_info(), espn_cfb_season_types(), espn_cfb_season_weeks(), espn_cfb_seasons(), espn_cfb_standings(), espn_cfb_team(), espn_cfb_team_ats(), espn_cfb_team_awards(), espn_cfb_team_coaches(), espn_cfb_team_events(), espn_cfb_team_leaders(), espn_cfb_team_powerindex(), espn_cfb_team_ranks(), espn_cfb_team_record(), espn_cfb_team_roster(), espn_cfb_team_schedule(), espn_cfb_teams(), espn_cfb_unnest_plays(), espn_cfb_venue(), espn_cfb_venues(), espn_cfb_week_rankings()

Examples


  try(espn_cfb_player_gamelog(athlete_id = 102597, year = 2024))
  try(espn_cfb_player_gamelog(athlete_id = 102597, year = 2024,
                              team_detail = FALSE,
                              athlete_detail = FALSE))

ESPN College Football Player Statistics Overview

Description

Get the season-by-season statistics overview ESPN shows on a college football player's player page – one row per season the player has played, with the headline stat line for each.

Usage

espn_cfb_player_overview(athlete_id = NULL, year = NULL, athlete_detail = TRUE)

Arguments

athlete_id

(Character/Integer required): ESPN athlete id.

year

(Integer required): Season, 4 digit format (YYYY).
Minimum value accepted: 2004

athlete_detail

(Logical): when TRUE (default), fetch the requested athlete's ESPN record once and append the ⁠athlete_*⁠ name columns (see Details). Set FALSE to skip the fetch, reproducing the prior output exactly.

Details

Wraps the ESPN web-v3 endpoint site.web.api.espn.com/apis/common/v3/sports/football/college-football/athletes/{athlete_id}/overview. The overview payload's statistics block is the player's career summary table: it carries a splits array with one entry per season the player has played (most recent first), plus the names array of stat keys. This wrapper returns that career table – one row per season – joining each season's stat values to the names columns. Note that the season argument selects the player's player-page context but the statistics block is always the player's full multi-season career table; the returned stat_season column identifies which season each row describes. Stat columns vary by the player's position. For game-by-game data use espn_cfb_player_gamelog().

When athlete_detail = TRUE (the default) the requested athlete's ESPN record is fetched once and the human-readable name columns athlete_display_name, athlete_first_name, athlete_last_name, athlete_jersey, athlete_position, and athlete_position_abbreviation are appended to every row. This is a single cheap fetch – the wrapper already takes one athlete_id. A fetch failure degrades the name columns to NA rather than erroring the wrapper. Set athlete_detail = FALSE to skip the fetch and reproduce the prior output exactly.

Value

A data frame with one row per season in the player's career table. The leading columns are fixed; the trailing stat columns vary by position:

col_name types description
athlete_id character ESPN athlete id.
season integer Season passed as the player-page context argument.
stat_season character Season this row's stat line describes.
athlete_display_name character Player display name; athlete_detail = TRUE only.
athlete_first_name character Player first name; athlete_detail = TRUE only.
athlete_last_name character Player last name; athlete_detail = TRUE only.
athlete_jersey character Player jersey number; athlete_detail = TRUE only.
athlete_position character Player position name; athlete_detail = TRUE only.
athlete_position_abbreviation character Player position abbreviation; athlete_detail = TRUE only.
... character One column per stat in the names array (varies).

See Also

Other ESPN CFB Functions: espn_cfb_award(), espn_cfb_awards(), espn_cfb_clear_cache(), espn_cfb_coach(), espn_cfb_coach_record(), espn_cfb_coaches(), espn_cfb_franchise(), espn_cfb_franchises(), espn_cfb_futures(), espn_cfb_game_broadcasts(), espn_cfb_game_drive_plays(), espn_cfb_game_drives(), espn_cfb_game_leaders(), espn_cfb_game_odds(), espn_cfb_game_pbp(), espn_cfb_game_play(), espn_cfb_game_player_box(), espn_cfb_game_player_statistics(), espn_cfb_game_powerindex(), espn_cfb_game_predictor(), espn_cfb_game_probabilities(), espn_cfb_game_situation(), espn_cfb_game_status(), espn_cfb_game_team_leaders(), espn_cfb_game_team_linescores(), espn_cfb_game_team_records(), espn_cfb_game_team_roster(), espn_cfb_game_team_statistics(), espn_cfb_game_teams(), espn_cfb_groups(), espn_cfb_pbp_v2(), espn_cfb_player(), espn_cfb_player_career_stats(), espn_cfb_player_eventlog(), espn_cfb_player_gamelog(), espn_cfb_player_seasons(), espn_cfb_player_splits(), espn_cfb_player_stats_v3(), espn_cfb_players(), espn_cfb_position(), espn_cfb_positions(), espn_cfb_powerindex(), espn_cfb_qbr(), espn_cfb_rankings(), espn_cfb_recruits(), espn_cfb_season_info(), espn_cfb_season_types(), espn_cfb_season_weeks(), espn_cfb_seasons(), espn_cfb_standings(), espn_cfb_team(), espn_cfb_team_ats(), espn_cfb_team_awards(), espn_cfb_team_coaches(), espn_cfb_team_events(), espn_cfb_team_leaders(), espn_cfb_team_powerindex(), espn_cfb_team_ranks(), espn_cfb_team_record(), espn_cfb_team_roster(), espn_cfb_team_schedule(), espn_cfb_teams(), espn_cfb_unnest_plays(), espn_cfb_venue(), espn_cfb_venues(), espn_cfb_week_rankings()

Examples


  try(espn_cfb_player_overview(athlete_id = 102597, year = 2024))
  try(espn_cfb_player_overview(athlete_id = 102597, year = 2024,
                               athlete_detail = FALSE))

ESPN College Football Player Seasons

Description

Get the list of seasons a single college football player has a statistical record for on ESPN – one row per season, with the ⁠$ref⁠ URLs to that season's statistics.

Usage

espn_cfb_player_seasons(athlete_id = NULL, athlete_detail = TRUE)

Arguments

athlete_id

(Character/Integer required): ESPN athlete id.

athlete_detail

(Logical): when TRUE (default), fetch the requested athlete's ESPN record once and append the ⁠athlete_*⁠ name columns (see Details). Set FALSE to skip the fetch, reproducing the prior output exactly.

Details

Wraps the ESPN core-v2 endpoint sports.core.api.espn.com/v2/sports/football/leagues/college-football/athletes/{athlete_id}/statisticslog. ESPN exposes no dedicated ⁠/athletes/{id}/seasons⁠ resource for college football (that path 404s); the statistics log is the closest thing – it returns one entry per season the player accumulated statistics in, which is exactly the player's season list. Each entry carries the season ⁠$ref⁠ and one or more statistics references (split by stat type, e.g. total). The statistics themselves are not auto-dereferenced; use espn_cfb_player_career_stats() for a resolved, long-format stat table for a given season.

When athlete_detail = TRUE (the default) the requested athlete's ESPN record is fetched once (from the league-wide athlete resource, since this wrapper takes no year) and the human-readable name columns athlete_display_name, athlete_first_name, athlete_last_name, athlete_jersey, athlete_position, and athlete_position_abbreviation are appended to every row. This is a single cheap fetch – the wrapper already takes one athlete_id. A fetch failure degrades the name columns to NA rather than erroring the wrapper. Set athlete_detail = FALSE to skip the fetch and reproduce the prior output exactly.

Value

A data frame with one row per season-stat-type entry:

col_name types description
athlete_id character ESPN athlete id.
season integer Season (4-digit year) the player has a record in.
stat_type character Statistics type for the entry (e.g. total).
season_ref character ⁠$ref⁠ URL to the season resource.
statistics_ref character ⁠$ref⁠ URL to the season statistics resource.
athlete_display_name character Player display name; athlete_detail = TRUE only.
athlete_first_name character Player first name; athlete_detail = TRUE only.
athlete_last_name character Player last name; athlete_detail = TRUE only.
athlete_jersey character Player jersey number; athlete_detail = TRUE only.
athlete_position character Player position name; athlete_detail = TRUE only.
athlete_position_abbreviation character Player position abbreviation; athlete_detail = TRUE only.

See Also

Other ESPN CFB Functions: espn_cfb_award(), espn_cfb_awards(), espn_cfb_clear_cache(), espn_cfb_coach(), espn_cfb_coach_record(), espn_cfb_coaches(), espn_cfb_franchise(), espn_cfb_franchises(), espn_cfb_futures(), espn_cfb_game_broadcasts(), espn_cfb_game_drive_plays(), espn_cfb_game_drives(), espn_cfb_game_leaders(), espn_cfb_game_odds(), espn_cfb_game_pbp(), espn_cfb_game_play(), espn_cfb_game_player_box(), espn_cfb_game_player_statistics(), espn_cfb_game_powerindex(), espn_cfb_game_predictor(), espn_cfb_game_probabilities(), espn_cfb_game_situation(), espn_cfb_game_status(), espn_cfb_game_team_leaders(), espn_cfb_game_team_linescores(), espn_cfb_game_team_records(), espn_cfb_game_team_roster(), espn_cfb_game_team_statistics(), espn_cfb_game_teams(), espn_cfb_groups(), espn_cfb_pbp_v2(), espn_cfb_player(), espn_cfb_player_career_stats(), espn_cfb_player_eventlog(), espn_cfb_player_gamelog(), espn_cfb_player_overview(), espn_cfb_player_splits(), espn_cfb_player_stats_v3(), espn_cfb_players(), espn_cfb_position(), espn_cfb_positions(), espn_cfb_powerindex(), espn_cfb_qbr(), espn_cfb_rankings(), espn_cfb_recruits(), espn_cfb_season_info(), espn_cfb_season_types(), espn_cfb_season_weeks(), espn_cfb_seasons(), espn_cfb_standings(), espn_cfb_team(), espn_cfb_team_ats(), espn_cfb_team_awards(), espn_cfb_team_coaches(), espn_cfb_team_events(), espn_cfb_team_leaders(), espn_cfb_team_powerindex(), espn_cfb_team_ranks(), espn_cfb_team_record(), espn_cfb_team_roster(), espn_cfb_team_schedule(), espn_cfb_teams(), espn_cfb_unnest_plays(), espn_cfb_venue(), espn_cfb_venues(), espn_cfb_week_rankings()

Examples


  try(espn_cfb_player_seasons(athlete_id = 102597))
  try(espn_cfb_player_seasons(athlete_id = 102597, athlete_detail = FALSE))

ESPN College Football Player Statistical Splits

Description

Get a single college football player's statistical splits for a season – stat lines broken out by situation (by month, by quarter, by half, by down, by field position, and more).

Usage

espn_cfb_player_splits(athlete_id = NULL, year = NULL, athlete_detail = TRUE)

Arguments

athlete_id

(Character/Integer required): ESPN athlete id.

year

(Integer required): Season, 4 digit format (YYYY).
Minimum value accepted: 2004

athlete_detail

(Logical): when TRUE (default), fetch the requested athlete's ESPN record once and append the ⁠athlete_*⁠ name columns (see Details). Set FALSE to skip the fetch, reproducing the prior output exactly.

Details

Wraps the ESPN web-v3 endpoint site.web.api.espn.com/apis/common/v3/sports/football/college-football/athletes/{athlete_id}/splits. ESPN groups splits under splitCategories[] (e.g. byMonth, byQuarter, byDown, byFieldPosition); each category holds one or more individual splits (e.g. the rows under byQuarter are ⁠1st Quarter⁠, ⁠2nd Quarter⁠, ...). This wrapper returns one row per individual split, tagged with its parent category, and joins the split's stat values to the top-level names array for column names. Stat columns vary by the player's position.

When athlete_detail = TRUE (the default) the requested athlete's ESPN record is fetched once and the human-readable name columns athlete_display_name, athlete_first_name, athlete_last_name, athlete_jersey, athlete_position, and athlete_position_abbreviation are appended to every row. This is a single cheap fetch – the wrapper already takes one athlete_id. A fetch failure degrades the name columns to NA rather than erroring the wrapper. Set athlete_detail = FALSE to skip the fetch and reproduce the prior output exactly.

Value

A data frame with one row per split. The leading columns are fixed; the trailing stat columns vary by position:

col_name types description
athlete_id character ESPN athlete id.
season integer Season (4-digit year).
category character Split category key (e.g. byQuarter, byDown).
category_display character Human-readable split category name.
split_name character Individual split name (e.g. ⁠1st Quarter⁠).
split_abbr character Individual split abbreviation.
athlete_display_name character Player display name; athlete_detail = TRUE only.
athlete_first_name character Player first name; athlete_detail = TRUE only.
athlete_last_name character Player last name; athlete_detail = TRUE only.
athlete_jersey character Player jersey number; athlete_detail = TRUE only.
athlete_position character Player position name; athlete_detail = TRUE only.
athlete_position_abbreviation character Player position abbreviation; athlete_detail = TRUE only.
... character One column per stat in the names array (varies).

See Also

Other ESPN CFB Functions: espn_cfb_award(), espn_cfb_awards(), espn_cfb_clear_cache(), espn_cfb_coach(), espn_cfb_coach_record(), espn_cfb_coaches(), espn_cfb_franchise(), espn_cfb_franchises(), espn_cfb_futures(), espn_cfb_game_broadcasts(), espn_cfb_game_drive_plays(), espn_cfb_game_drives(), espn_cfb_game_leaders(), espn_cfb_game_odds(), espn_cfb_game_pbp(), espn_cfb_game_play(), espn_cfb_game_player_box(), espn_cfb_game_player_statistics(), espn_cfb_game_powerindex(), espn_cfb_game_predictor(), espn_cfb_game_probabilities(), espn_cfb_game_situation(), espn_cfb_game_status(), espn_cfb_game_team_leaders(), espn_cfb_game_team_linescores(), espn_cfb_game_team_records(), espn_cfb_game_team_roster(), espn_cfb_game_team_statistics(), espn_cfb_game_teams(), espn_cfb_groups(), espn_cfb_pbp_v2(), espn_cfb_player(), espn_cfb_player_career_stats(), espn_cfb_player_eventlog(), espn_cfb_player_gamelog(), espn_cfb_player_overview(), espn_cfb_player_seasons(), espn_cfb_player_stats_v3(), espn_cfb_players(), espn_cfb_position(), espn_cfb_positions(), espn_cfb_powerindex(), espn_cfb_qbr(), espn_cfb_rankings(), espn_cfb_recruits(), espn_cfb_season_info(), espn_cfb_season_types(), espn_cfb_season_weeks(), espn_cfb_seasons(), espn_cfb_standings(), espn_cfb_team(), espn_cfb_team_ats(), espn_cfb_team_awards(), espn_cfb_team_coaches(), espn_cfb_team_events(), espn_cfb_team_leaders(), espn_cfb_team_powerindex(), espn_cfb_team_ranks(), espn_cfb_team_record(), espn_cfb_team_roster(), espn_cfb_team_schedule(), espn_cfb_teams(), espn_cfb_unnest_plays(), espn_cfb_venue(), espn_cfb_venues(), espn_cfb_week_rankings()

Examples


  try(espn_cfb_player_splits(athlete_id = 102597, year = 2024))
  try(espn_cfb_player_splits(athlete_id = 102597, year = 2024,
                             athlete_detail = FALSE))

Get ESPN college football player stats data

Description

Get ESPN college football player stats data

Usage

espn_cfb_player_stats(athlete_id, year, season_type = "regular", total = FALSE)

Arguments

athlete_id

Athlete ID

year

Year
Minimum value accepted: 2004

season_type

(character, default: regular): Season type - regular or postseason

total

(boolean, default: FALSE): Totals

Value

Returns a tibble with the following columns:

col_name types
athlete_id character
athlete_uid character
athlete_guid character
athlete_type character
sdr character
first_name character
last_name character
full_name character
display_name character
short_name character
weight numeric
display_weight character
height numeric
display_height character
age integer
date_of_birth character
birth_place_city character
birth_place_state character
birth_place_country character
birth_country_alternate_id character
birth_country_abbreviation character
slug character
jersey character
flag_href character
flag_alt character
flag_x_country_flag character
position_id character
position_name character
position_display_name character
position_abbreviation character
position_leaf logical
linked logical
experience_years integer
experience_display_value character
experience_abbreviation character
active logical
status_id character
status_name character
status_type character
status_abbreviation character
headshot_href character
headshot_alt character
general_fumbles numeric
general_fumbles_lost numeric
general_fumbles_touchdowns numeric
general_games_played numeric
general_offensive_two_pt_returns numeric
general_offensive_fumbles_touchdowns numeric
general_defensive_fumbles_touchdowns numeric
passing_avg_gain numeric
passing_completion_pct numeric
passing_completions numeric
passing_espnqb_rating numeric
passing_interception_pct numeric
passing_interceptions numeric
passing_long_passing numeric
passing_net_passing_yards numeric
passing_net_passing_yards_per_game numeric
passing_net_total_yards numeric
passing_net_yards_per_game numeric
passing_passing_attempts numeric
passing_passing_big_plays numeric
passing_passing_first_downs numeric
passing_passing_fumbles numeric
passing_passing_fumbles_lost numeric
passing_passing_touchdown_pct numeric
passing_passing_touchdowns numeric
passing_passing_yards numeric
passing_passing_yards_after_catch numeric
passing_passing_yards_at_catch numeric
passing_passing_yards_per_game numeric
passing_qb_rating numeric
passing_sacks numeric
passing_sack_yards_lost numeric
passing_team_games_played numeric
passing_total_offensive_plays numeric
passing_total_points_per_game numeric
passing_total_touchdowns numeric
passing_total_yards numeric
passing_total_yards_from_scrimmage numeric
passing_two_point_pass_convs numeric
passing_two_pt_pass numeric
passing_two_pt_pass_attempts numeric
passing_yards_from_scrimmage_per_game numeric
passing_yards_per_completion numeric
passing_yards_per_game numeric
passing_yards_per_pass_attempt numeric
passing_net_yards_per_pass_attempt numeric
passing_qbr numeric
passing_adj_qbr numeric
passing_quarterback_rating numeric
rushing_avg_gain numeric
rushing_espnrb_rating numeric
rushing_long_rushing numeric
rushing_net_total_yards numeric
rushing_net_yards_per_game numeric
rushing_rushing_attempts numeric
rushing_rushing_big_plays numeric
rushing_rushing_first_downs numeric
rushing_rushing_fumbles numeric
rushing_rushing_fumbles_lost numeric
rushing_rushing_touchdowns numeric
rushing_rushing_yards numeric
rushing_rushing_yards_per_game numeric
rushing_stuffs numeric
rushing_stuff_yards_lost numeric
rushing_team_games_played numeric
rushing_total_offensive_plays numeric
rushing_total_points_per_game numeric
rushing_total_touchdowns numeric
rushing_total_yards numeric
rushing_total_yards_from_scrimmage numeric
rushing_two_point_rush_convs numeric
rushing_two_pt_rush numeric
rushing_two_pt_rush_attempts numeric
rushing_yards_from_scrimmage_per_game numeric
rushing_yards_per_game numeric
rushing_yards_per_rush_attempt numeric
receiving_avg_gain numeric
receiving_espnwr_rating numeric
receiving_long_reception numeric
receiving_net_total_yards numeric
receiving_net_yards_per_game numeric
receiving_receiving_big_plays numeric
receiving_receiving_first_downs numeric
receiving_receiving_fumbles numeric
receiving_receiving_fumbles_lost numeric
receiving_receiving_targets numeric
receiving_receiving_touchdowns numeric
receiving_receiving_yards numeric
receiving_receiving_yards_after_catch numeric
receiving_receiving_yards_at_catch numeric
receiving_receiving_yards_per_game numeric
receiving_receptions numeric
receiving_team_games_played numeric
receiving_total_offensive_plays numeric
receiving_total_points_per_game numeric
receiving_total_touchdowns numeric
receiving_total_yards numeric
receiving_total_yards_from_scrimmage numeric
receiving_two_point_rec_convs numeric
receiving_two_pt_reception numeric
receiving_two_pt_reception_attempts numeric
receiving_yards_from_scrimmage_per_game numeric
receiving_yards_per_game numeric
receiving_yards_per_reception numeric
scoring_defensive_points numeric
scoring_field_goals numeric
scoring_kick_extra_points numeric
scoring_kick_extra_points_made numeric
scoring_misc_points numeric
scoring_passing_touchdowns numeric
scoring_receiving_touchdowns numeric
scoring_return_touchdowns numeric
scoring_rushing_touchdowns numeric
scoring_total_points numeric
scoring_total_points_per_game numeric
scoring_total_touchdowns numeric
scoring_total_two_point_convs numeric
scoring_two_point_pass_convs numeric
scoring_two_point_rec_convs numeric
scoring_two_point_rush_convs numeric
scoring_one_pt_safeties_made numeric
general_fumbles_forced logical
general_fumbles_recovered logical
passing_misc_yards logical
passing_total_points logical
rushing_misc_yards logical
rushing_total_points logical
receiving_misc_yards logical
receiving_total_points logical
defensive_assist_tackles logical
defensive_avg_interception_yards logical
defensive_avg_sack_yards logical
defensive_avg_stuff_yards logical
defensive_blocked_field_goal_touchdowns logical
defensive_blocked_punt_touchdowns logical
defensive_defensive_touchdowns logical
defensive_hurries logical
defensive_kicks_blocked logical
defensive_long_interception logical
defensive_misc_touchdowns logical
defensive_missed_field_goal_return_td numeric
defensive_blocked_punt_ez_rec_td numeric
defensive_passes_batted_down logical
defensive_passes_defended logical
defensive_two_pt_returns logical
defensive_sacks logical
defensive_sack_yards logical
defensive_safeties logical
defensive_solo_tackles logical
defensive_stuffs logical
defensive_stuff_yards logical
defensive_tackles_for_loss logical
defensive_team_games_played logical
defensive_total_tackles logical
defensive_yards_allowed logical
defensive_points_allowed logical
defensive_one_pt_safeties_made logical
defensive_interceptions_interceptions logical
defensive_interceptions_interception_touchdowns logical
defensive_interceptions_interception_yards logical
kicking_avg_kickoff_return_yards logical
kicking_avg_kickoff_yards logical
kicking_extra_point_attempts logical
kicking_extra_point_pct logical
kicking_extra_points_blocked logical
kicking_extra_points_blocked_pct logical
kicking_extra_points_made logical
kicking_fair_catches logical
kicking_fair_catch_pct logical
kicking_field_goal_attempts logical
kicking_field_goal_attempts1_19 logical
kicking_field_goal_attempts20_29 logical
kicking_field_goal_attempts30_39 logical
kicking_field_goal_attempts40_49 logical
kicking_field_goal_attempts50_59 logical
kicking_field_goal_attempts60_99 logical
kicking_field_goal_attempts50 logical
kicking_field_goal_attempt_yards logical
kicking_field_goal_pct logical
kicking_field_goals_blocked logical
kicking_field_goals_blocked_pct logical
kicking_field_goals_made logical
kicking_field_goals_made1_19 logical
kicking_field_goals_made20_29 logical
kicking_field_goals_made30_39 logical
kicking_field_goals_made40_49 logical
kicking_field_goals_made50_59 logical
kicking_field_goals_made60_99 logical
kicking_field_goals_made50 logical
kicking_field_goals_made_yards logical
kicking_field_goals_missed_yards logical
kicking_kickoff_returns logical
kicking_kickoff_return_touchdowns logical
kicking_kickoff_return_yards logical
kicking_kickoffs logical
kicking_kickoff_yards logical
kicking_long_field_goal_attempt logical
kicking_long_field_goal_made logical
kicking_long_kickoff logical
kicking_team_games_played logical
kicking_total_kicking_points logical
kicking_touchback_pct logical
kicking_touchbacks logical
returning_def_fumble_returns logical
returning_def_fumble_return_yards logical
returning_fumble_recoveries logical
returning_fumble_recovery_yards logical
returning_kick_return_fair_catches logical
returning_kick_return_fair_catch_pct logical
returning_kick_return_fumbles logical
returning_kick_return_fumbles_lost logical
returning_kick_returns logical
returning_kick_return_touchdowns logical
returning_kick_return_yards logical
returning_long_kick_return logical
returning_long_punt_return logical
returning_misc_fumble_returns logical
returning_misc_fumble_return_yards logical
returning_opp_fumble_recoveries logical
returning_opp_fumble_recovery_yards logical
returning_opp_special_team_fumble_returns logical
returning_opp_special_team_fumble_return_yards logical
returning_punt_return_fair_catches logical
returning_punt_return_fair_catch_pct logical
returning_punt_return_fumbles logical
returning_punt_return_fumbles_lost logical
returning_punt_returns logical
returning_punt_returns_started_inside_the10 logical
returning_punt_returns_started_inside_the20 logical
returning_punt_return_touchdowns logical
returning_punt_return_yards logical
returning_special_team_fumble_returns logical
returning_special_team_fumble_return_yards logical
returning_team_games_played logical
returning_yards_per_kick_return logical
returning_yards_per_punt_return logical
returning_yards_per_return logical
punting_avg_punt_return_yards logical
punting_fair_catches logical
punting_gross_avg_punt_yards logical
punting_long_punt logical
punting_net_avg_punt_yards logical
punting_punt_returns logical
punting_punt_return_yards logical
punting_punts logical
punting_punts_blocked logical
punting_punts_blocked_pct logical
punting_punts_inside10 logical
punting_punts_inside10pct logical
punting_punts_inside20 logical
punting_punts_inside20pct logical
punting_punt_yards logical
punting_team_games_played logical
punting_touchback_pct logical
punting_touchbacks logical
miscellaneous_first_downs logical
miscellaneous_first_downs_passing logical
miscellaneous_first_downs_penalty logical
miscellaneous_first_downs_per_game logical
miscellaneous_first_downs_rushing logical
miscellaneous_fourth_down_attempts logical
miscellaneous_fourth_down_conv_pct logical
miscellaneous_fourth_down_convs logical
miscellaneous_fumbles_lost logical
miscellaneous_possession_time_seconds logical
miscellaneous_redzone_efficiency_pct logical
miscellaneous_redzone_field_goal_pct logical
miscellaneous_redzone_scoring_pct logical
miscellaneous_redzone_touchdown_pct logical
miscellaneous_third_down_attempts logical
miscellaneous_third_down_conv_pct logical
miscellaneous_third_down_convs logical
miscellaneous_total_giveaways logical
miscellaneous_total_penalties logical
miscellaneous_total_penalty_yards logical
miscellaneous_total_takeaways logical
miscellaneous_total_drives logical
miscellaneous_turn_over_differential logical
team_id character
team_guid character
team_uid character
team_sdr character
team_slug character
team_location character
team_name character
team_nickname character
team_abbreviation character
team_display_name character
team_short_display_name character
team_color character
team_alternate_color character
is_active logical
is_all_star logical
logo_href character
logo_dark_href character

Author(s)

Saiem Gilani

Examples


  try(espn_cfb_player_stats(athlete_id = 530308, year = 2013))
  try(espn_cfb_player_stats(athlete_id = 4360799, year = 2022))

ESPN College Football Player Stats (web v3, all categories)

Description

Get a single college football player's web-common-v3 statistics from ESPN – the comprehensive ⁠/athletes/{id}/stats⁠ payload (every category: passing, rushing, receiving, defensive, etc.) in long format (one row per stat). This is the richer "v3" companion to espn_cfb_player_stats() (core-v2 season statistics) and espn_cfb_player_career_stats().

Usage

espn_cfb_player_stats_v3(athlete_id = NULL, year = NULL, athlete_detail = TRUE)

Arguments

athlete_id

(Character/Integer required): ESPN athlete id.

year

(Integer required): Season, 4 digit format (YYYY).
Minimum value accepted: 2004

athlete_detail

(Logical): when TRUE (default), append the ⁠athlete_*⁠ name columns via one extra athlete fetch.

Value

A data frame with one row per (category x team-season x stat):

col_name types description
athlete_id character ESPN athlete id.
season integer Requested season (4-digit year).
category character Stat category key (e.g. passing).
category_display character Human-readable category name.
team_id character ESPN team id for the stat row.
team_slug character Team slug for the stat row.
stat_season integer Season of the stat row (per ESPN).
position character Player position for the stat row.
stat_name character Stat key (from the category names).
stat_label character Stat short label (from labels).
stat_display_name character Stat display name (from displayNames).
value character Stat value (as published).

See Also

Other ESPN CFB Functions: espn_cfb_award(), espn_cfb_awards(), espn_cfb_clear_cache(), espn_cfb_coach(), espn_cfb_coach_record(), espn_cfb_coaches(), espn_cfb_franchise(), espn_cfb_franchises(), espn_cfb_futures(), espn_cfb_game_broadcasts(), espn_cfb_game_drive_plays(), espn_cfb_game_drives(), espn_cfb_game_leaders(), espn_cfb_game_odds(), espn_cfb_game_pbp(), espn_cfb_game_play(), espn_cfb_game_player_box(), espn_cfb_game_player_statistics(), espn_cfb_game_powerindex(), espn_cfb_game_predictor(), espn_cfb_game_probabilities(), espn_cfb_game_situation(), espn_cfb_game_status(), espn_cfb_game_team_leaders(), espn_cfb_game_team_linescores(), espn_cfb_game_team_records(), espn_cfb_game_team_roster(), espn_cfb_game_team_statistics(), espn_cfb_game_teams(), espn_cfb_groups(), espn_cfb_pbp_v2(), espn_cfb_player(), espn_cfb_player_career_stats(), espn_cfb_player_eventlog(), espn_cfb_player_gamelog(), espn_cfb_player_overview(), espn_cfb_player_seasons(), espn_cfb_player_splits(), espn_cfb_players(), espn_cfb_position(), espn_cfb_positions(), espn_cfb_powerindex(), espn_cfb_qbr(), espn_cfb_rankings(), espn_cfb_recruits(), espn_cfb_season_info(), espn_cfb_season_types(), espn_cfb_season_weeks(), espn_cfb_seasons(), espn_cfb_standings(), espn_cfb_team(), espn_cfb_team_ats(), espn_cfb_team_awards(), espn_cfb_team_coaches(), espn_cfb_team_events(), espn_cfb_team_leaders(), espn_cfb_team_powerindex(), espn_cfb_team_ranks(), espn_cfb_team_record(), espn_cfb_team_roster(), espn_cfb_team_schedule(), espn_cfb_teams(), espn_cfb_unnest_plays(), espn_cfb_venue(), espn_cfb_venues(), espn_cfb_week_rankings()

Examples


  try(espn_cfb_player_stats_v3(athlete_id = 4431611, year = 2023))

ESPN College Football Players Index

Description

Get a paginated index of ESPN college football players for a season. Each row is one player reference (id + ⁠$ref⁠ URL); dereference a row with espn_cfb_player() to retrieve the full player record.

Usage

espn_cfb_players(
  year = NULL,
  page = 1,
  max_pages = 1,
  limit = 100,
  athlete_detail = FALSE
)

Arguments

year

(Integer required): Season, 4 digit format (YYYY).
Minimum value accepted: 1936

page

(Integer optional, default 1): First page of the index to fetch.

max_pages

(Integer optional, default 1): Number of consecutive pages to fetch starting at page. Each page holds limit players.

limit

(Integer optional, default 100): Players per page (ESPN page size).

athlete_detail

(Logical): when TRUE, dereference each player returned and append the ⁠athlete_*⁠ name columns (see Details). This costs one HTTP call per player, so it defaults to FALSE; setting it FALSE reproduces the prior output exactly.

Details

Wraps the ESPN core-v2 endpoint sports.core.api.espn.com/v2/sports/football/leagues/college-football/seasons/{year}/athletes. The season-scoped index contains roughly 99,500 players, returned in fixed-size pages – this wrapper deliberately returns id + ⁠$ref⁠ rows only and never dereferences the individual player records, because a full crawl would be tens of thousands of HTTP calls. Walk the index a page at a time with page, and cap how far a single call goes with max_pages. The total page count for the season is reported in the page_count column so a caller can drive its own pagination loop. To resolve an individual player to a full record, pass its athlete_id to espn_cfb_player().

When athlete_detail = TRUE the index is enriched with the human-readable name columns athlete_display_name, athlete_first_name, athlete_last_name, athlete_jersey, athlete_position, and athlete_position_abbreviation. There is no bulk athlete-name catalog, so resolving names here costs one HTTP call per player returned – with the default limit = 100 that is 100 extra requests per page. It therefore defaults to FALSE. A per-athlete fetch failure leaves that player's name columns NA rather than erroring the wrapper. Keep limit small (or athlete_detail = FALSE) when walking many pages.

Value

A data frame with one row per player reference:

col_name types description
season integer Season (4-digit year).
athlete_id character ESPN athlete id (parsed from athlete_ref).
athlete_ref character ⁠$ref⁠ URL to the athlete-in-season resource.
page integer Index page this player was returned on.
page_count integer Total number of pages in the season index.
count integer Total number of players in the season index.
athlete_display_name character Player display name; athlete_detail = TRUE only.
athlete_first_name character Player first name; athlete_detail = TRUE only.
athlete_last_name character Player last name; athlete_detail = TRUE only.
athlete_jersey character Player jersey number; athlete_detail = TRUE only.
athlete_position character Player position name; athlete_detail = TRUE only.
athlete_position_abbreviation character Player position abbreviation; athlete_detail = TRUE only.

See Also

Other ESPN CFB Functions: espn_cfb_award(), espn_cfb_awards(), espn_cfb_clear_cache(), espn_cfb_coach(), espn_cfb_coach_record(), espn_cfb_coaches(), espn_cfb_franchise(), espn_cfb_franchises(), espn_cfb_futures(), espn_cfb_game_broadcasts(), espn_cfb_game_drive_plays(), espn_cfb_game_drives(), espn_cfb_game_leaders(), espn_cfb_game_odds(), espn_cfb_game_pbp(), espn_cfb_game_play(), espn_cfb_game_player_box(), espn_cfb_game_player_statistics(), espn_cfb_game_powerindex(), espn_cfb_game_predictor(), espn_cfb_game_probabilities(), espn_cfb_game_situation(), espn_cfb_game_status(), espn_cfb_game_team_leaders(), espn_cfb_game_team_linescores(), espn_cfb_game_team_records(), espn_cfb_game_team_roster(), espn_cfb_game_team_statistics(), espn_cfb_game_teams(), espn_cfb_groups(), espn_cfb_pbp_v2(), espn_cfb_player(), espn_cfb_player_career_stats(), espn_cfb_player_eventlog(), espn_cfb_player_gamelog(), espn_cfb_player_overview(), espn_cfb_player_seasons(), espn_cfb_player_splits(), espn_cfb_player_stats_v3(), espn_cfb_position(), espn_cfb_positions(), espn_cfb_powerindex(), espn_cfb_qbr(), espn_cfb_rankings(), espn_cfb_recruits(), espn_cfb_season_info(), espn_cfb_season_types(), espn_cfb_season_weeks(), espn_cfb_seasons(), espn_cfb_standings(), espn_cfb_team(), espn_cfb_team_ats(), espn_cfb_team_awards(), espn_cfb_team_coaches(), espn_cfb_team_events(), espn_cfb_team_leaders(), espn_cfb_team_powerindex(), espn_cfb_team_ranks(), espn_cfb_team_record(), espn_cfb_team_roster(), espn_cfb_team_schedule(), espn_cfb_teams(), espn_cfb_unnest_plays(), espn_cfb_venue(), espn_cfb_venues(), espn_cfb_week_rankings()

Examples


  try(espn_cfb_players(year = 2024, page = 1, max_pages = 1))
  try(espn_cfb_players(year = 2024, page = 1, max_pages = 1, limit = 5,
                       athlete_detail = TRUE))

ESPN College Football Position Detail

Description

Get the ESPN core-v2 detail record for a single college football player position – name, display name, abbreviation, leaf flag, and the parent position id.

Usage

espn_cfb_position(position_id = NULL)

Arguments

position_id

(Integer required): ESPN position id.

Details

Wraps the ESPN core-v2 endpoint sports.core.api.espn.com/v2/sports/football/leagues/college-football/positions/{position_id}. espn_cfb_positions() returns the position index; this wrapper returns the single-position detail for one id. ESPN's position table is a tree – specific positions roll up under broader ones; the leaf flag marks the most specific positions and parent_id (when present) reconstructs the grouping. Returns a single-row tibble. Enumerate position_ids with espn_cfb_positions().

Value

A single-row data frame:

col_name types description
position_id character ESPN position id.
name character Position name (e.g. Quarterback).
display_name character Human-readable position name.
abbreviation character Position abbreviation (e.g. QB).
leaf logical TRUE for a most-specific (leaf) position.
parent_id character ESPN id of the parent position (NA at the root).
position_ref character ⁠$ref⁠ URL to the position resource.

See Also

Other ESPN CFB Functions: espn_cfb_award(), espn_cfb_awards(), espn_cfb_clear_cache(), espn_cfb_coach(), espn_cfb_coach_record(), espn_cfb_coaches(), espn_cfb_franchise(), espn_cfb_franchises(), espn_cfb_futures(), espn_cfb_game_broadcasts(), espn_cfb_game_drive_plays(), espn_cfb_game_drives(), espn_cfb_game_leaders(), espn_cfb_game_odds(), espn_cfb_game_pbp(), espn_cfb_game_play(), espn_cfb_game_player_box(), espn_cfb_game_player_statistics(), espn_cfb_game_powerindex(), espn_cfb_game_predictor(), espn_cfb_game_probabilities(), espn_cfb_game_situation(), espn_cfb_game_status(), espn_cfb_game_team_leaders(), espn_cfb_game_team_linescores(), espn_cfb_game_team_records(), espn_cfb_game_team_roster(), espn_cfb_game_team_statistics(), espn_cfb_game_teams(), espn_cfb_groups(), espn_cfb_pbp_v2(), espn_cfb_player(), espn_cfb_player_career_stats(), espn_cfb_player_eventlog(), espn_cfb_player_gamelog(), espn_cfb_player_overview(), espn_cfb_player_seasons(), espn_cfb_player_splits(), espn_cfb_player_stats_v3(), espn_cfb_players(), espn_cfb_positions(), espn_cfb_powerindex(), espn_cfb_qbr(), espn_cfb_rankings(), espn_cfb_recruits(), espn_cfb_season_info(), espn_cfb_season_types(), espn_cfb_season_weeks(), espn_cfb_seasons(), espn_cfb_standings(), espn_cfb_team(), espn_cfb_team_ats(), espn_cfb_team_awards(), espn_cfb_team_coaches(), espn_cfb_team_events(), espn_cfb_team_leaders(), espn_cfb_team_powerindex(), espn_cfb_team_ranks(), espn_cfb_team_record(), espn_cfb_team_roster(), espn_cfb_team_schedule(), espn_cfb_teams(), espn_cfb_unnest_plays(), espn_cfb_venue(), espn_cfb_venues(), espn_cfb_week_rankings()

Examples


  try(espn_cfb_position(position_id = 8))

ESPN College Football Positions Index

Description

Get the catalog of player positions ESPN tracks for college football – the position names, abbreviations, and ids used throughout ESPN's athlete and roster resources.

Usage

espn_cfb_positions()

Details

Wraps the ESPN core-v2 endpoint sports.core.api.espn.com/v2/sports/football/leagues/college-football/positions. The index returns one ⁠$ref⁠ per position (~74); this wrapper dereferences each and returns one row per position. ESPN's position table is a tree – specific positions (e.g. left tackle) roll up under broader ones (e.g. offensive line). The leaf flag marks the most specific positions; parent_id (when present) reconstructs the grouping.

Value

A data frame with one row per position:

col_name types description
position_id character ESPN position id.
name character Position name (e.g. Quarterback).
display_name character Human-readable position name.
abbreviation character Position abbreviation (e.g. QB).
leaf logical TRUE for a most-specific (leaf) position.
parent_id character ESPN id of the parent position (NA at the root).
position_ref character ⁠$ref⁠ URL to the position resource.

See Also

Other ESPN CFB Functions: espn_cfb_award(), espn_cfb_awards(), espn_cfb_clear_cache(), espn_cfb_coach(), espn_cfb_coach_record(), espn_cfb_coaches(), espn_cfb_franchise(), espn_cfb_franchises(), espn_cfb_futures(), espn_cfb_game_broadcasts(), espn_cfb_game_drive_plays(), espn_cfb_game_drives(), espn_cfb_game_leaders(), espn_cfb_game_odds(), espn_cfb_game_pbp(), espn_cfb_game_play(), espn_cfb_game_player_box(), espn_cfb_game_player_statistics(), espn_cfb_game_powerindex(), espn_cfb_game_predictor(), espn_cfb_game_probabilities(), espn_cfb_game_situation(), espn_cfb_game_status(), espn_cfb_game_team_leaders(), espn_cfb_game_team_linescores(), espn_cfb_game_team_records(), espn_cfb_game_team_roster(), espn_cfb_game_team_statistics(), espn_cfb_game_teams(), espn_cfb_groups(), espn_cfb_pbp_v2(), espn_cfb_player(), espn_cfb_player_career_stats(), espn_cfb_player_eventlog(), espn_cfb_player_gamelog(), espn_cfb_player_overview(), espn_cfb_player_seasons(), espn_cfb_player_splits(), espn_cfb_player_stats_v3(), espn_cfb_players(), espn_cfb_position(), espn_cfb_powerindex(), espn_cfb_qbr(), espn_cfb_rankings(), espn_cfb_recruits(), espn_cfb_season_info(), espn_cfb_season_types(), espn_cfb_season_weeks(), espn_cfb_seasons(), espn_cfb_standings(), espn_cfb_team(), espn_cfb_team_ats(), espn_cfb_team_awards(), espn_cfb_team_coaches(), espn_cfb_team_events(), espn_cfb_team_leaders(), espn_cfb_team_powerindex(), espn_cfb_team_ranks(), espn_cfb_team_record(), espn_cfb_team_roster(), espn_cfb_team_schedule(), espn_cfb_teams(), espn_cfb_unnest_plays(), espn_cfb_venue(), espn_cfb_venues(), espn_cfb_week_rankings()

Examples


  try(espn_cfb_positions())

ESPN College Football Power Index (Long Format)

Description

Get ESPN's College Football Power Index (FPI) ratings for a season, including the full set of predictive metrics and efficiency components ESPN publishes alongside the headline FPI number.

Usage

espn_cfb_powerindex(year = NULL)

Arguments

year

(Integer required): Season, 4 digit format (YYYY).
Minimum value accepted: 2005

Details

Wraps the ESPN core-v2 endpoint sports.core.api.espn.com/v2/sports/football/leagues/college-football/seasons/{year}/powerindex. Returns one row per team-metric in long format: each team contributes one row for every predictive metric (FPI, projected wins, strength of record, ...) and every efficiency component (offensive, defensive, and special-teams efficiency, ...). The long shape is deliberate – ESPN adds and retires metrics across seasons, and a long frame absorbs that drift without breaking column expectations. Pivot wider with tidyr::pivot_wider() keyed on stat_name when a wide table is wanted.

Value

A data frame with one row per team-metric:

col_name types description
season integer Season (4-digit year).
team_id character ESPN team id (parsed from team_ref).
team_ref character ⁠$ref⁠ URL to the team-in-season resource.
metric_group character predictive or efficiency.
stat_name character Internal metric key (e.g. fpi, offefficiency).
abbreviation character Metric abbreviation.
display_name character Human-readable metric name.
value numeric Metric value.
display_value character Display-formatted metric value as shown on ESPN.
description character ESPN's description of the metric.

See Also

Other ESPN CFB Functions: espn_cfb_award(), espn_cfb_awards(), espn_cfb_clear_cache(), espn_cfb_coach(), espn_cfb_coach_record(), espn_cfb_coaches(), espn_cfb_franchise(), espn_cfb_franchises(), espn_cfb_futures(), espn_cfb_game_broadcasts(), espn_cfb_game_drive_plays(), espn_cfb_game_drives(), espn_cfb_game_leaders(), espn_cfb_game_odds(), espn_cfb_game_pbp(), espn_cfb_game_play(), espn_cfb_game_player_box(), espn_cfb_game_player_statistics(), espn_cfb_game_powerindex(), espn_cfb_game_predictor(), espn_cfb_game_probabilities(), espn_cfb_game_situation(), espn_cfb_game_status(), espn_cfb_game_team_leaders(), espn_cfb_game_team_linescores(), espn_cfb_game_team_records(), espn_cfb_game_team_roster(), espn_cfb_game_team_statistics(), espn_cfb_game_teams(), espn_cfb_groups(), espn_cfb_pbp_v2(), espn_cfb_player(), espn_cfb_player_career_stats(), espn_cfb_player_eventlog(), espn_cfb_player_gamelog(), espn_cfb_player_overview(), espn_cfb_player_seasons(), espn_cfb_player_splits(), espn_cfb_player_stats_v3(), espn_cfb_players(), espn_cfb_position(), espn_cfb_positions(), espn_cfb_qbr(), espn_cfb_rankings(), espn_cfb_recruits(), espn_cfb_season_info(), espn_cfb_season_types(), espn_cfb_season_weeks(), espn_cfb_seasons(), espn_cfb_standings(), espn_cfb_team(), espn_cfb_team_ats(), espn_cfb_team_awards(), espn_cfb_team_coaches(), espn_cfb_team_events(), espn_cfb_team_leaders(), espn_cfb_team_powerindex(), espn_cfb_team_ranks(), espn_cfb_team_record(), espn_cfb_team_roster(), espn_cfb_team_schedule(), espn_cfb_teams(), espn_cfb_unnest_plays(), espn_cfb_venue(), espn_cfb_venues(), espn_cfb_week_rankings()

Examples


  try(espn_cfb_powerindex(year = 2024))

ESPN College Football Total Quarterback Rating (QBR)

Description

Get ESPN's Total Quarterback Rating (QBR) and its full set of clutch-weighted EPA components for a college football season.

Usage

espn_cfb_qbr(year = NULL, group = 80, athlete_detail = FALSE)

Arguments

year

(Integer required): Season, 4 digit format (YYYY).
Minimum value accepted: 2004

group

(Integer default 80): ESPN group id. 80 = all FBS. Conference group ids (e.g. 4 ACC, 8 Big 12, 12 SEC, 21 Big Ten) also work.

athlete_detail

(Logical): when TRUE, dereference each quarterback and append the ⁠athlete_*⁠ name columns (see Details). This costs one HTTP call per quarterback, so it defaults to FALSE; setting it FALSE reproduces the prior output exactly.

Details

Wraps the ESPN core-v2 QBR endpoint seasons/{year}/types/2/groups/{group}/qbr/0. It returns season-to-date regular-season QBR for every qualified passer in the requested group (conference / division). group = 80 is the all-FBS bucket and is the sensible default; conference group ids (e.g. 4 ACC, 8 Big 12, 12 SEC, 21 Big Ten) also work.

Two parameters ESPN's QBR path technically accepts are deliberately not exposed, because neither carries data for college football:

The result is wide – one row per quarterback – with the headline qbr column plus the 18 component metrics ESPN derives it from. Players are returned as ESPN athlete ids only (athlete_id) unless name resolution is requested.

When athlete_detail = TRUE the human-readable name columns athlete_display_name, athlete_first_name, athlete_last_name, athlete_jersey, athlete_position, and athlete_position_abbreviation are appended. There is no bulk athlete-name catalog, so resolving names here costs one HTTP call per quarterback – roughly 130 extra requests for an all-FBS pull. It therefore defaults to FALSE. A per-athlete fetch failure leaves that quarterback's name columns NA rather than erroring the wrapper. To resolve names without these extra calls, join athlete_id to another athlete source (e.g. cfbd_team_roster()).

Value

A data frame with one row per quarterback:

col_name types description
season integer Season (4-digit year).
season_type integer ESPN season type (2 = regular season).
group_id character ESPN group id queried (80 = all FBS).
athlete_id character ESPN athlete id (parsed from athlete_ref).
team_id character ESPN team id (parsed from team_ref).
qbpaa numeric QB Points Added Above Average.
cwepa_passes_condensed numeric Clutch-weighted EPA from passes (condensed).
cwepa_rushes numeric Clutch-weighted EPA from designed rushes.
cwepa_sacked_condensed numeric Clutch-weighted EPA lost to sacks (condensed).
cwepa_penalties numeric Clutch-weighted EPA from penalties.
cwepa_total numeric Total clutch-weighted EPA.
action_plays numeric Action plays charged to the quarterback.
cw_average numeric Clutch-weighted average win value per play.
qbr numeric Total Quarterback Rating (0-100).
cwepa_passes numeric Clutch-weighted EPA from pass attempts.
cwepa_interceptions numeric Clutch-weighted EPA lost to interceptions.
cwepa_yards_after_carry numeric Clutch-weighted EPA from yards after carry.
cwepa_runs numeric Clutch-weighted EPA from runs.
cwepa_scrambles numeric Clutch-weighted EPA from scrambles.
cwepa_sacked numeric Clutch-weighted EPA lost to sacks.
cwepa_fumbles numeric Clutch-weighted EPA lost to fumbles.
avg_opp_dqbr numeric Average opponent defensive QBR faced.
sched_adj_qbr numeric Schedule-adjusted QBR.
unqualified_rank numeric QBR rank including unqualified passers.
athlete_ref character ⁠$ref⁠ URL to the athlete-in-season resource.
team_ref character ⁠$ref⁠ URL to the team-in-season resource.
athlete_display_name character Player display name; athlete_detail = TRUE only.
athlete_first_name character Player first name; athlete_detail = TRUE only.
athlete_last_name character Player last name; athlete_detail = TRUE only.
athlete_jersey character Player jersey number; athlete_detail = TRUE only.
athlete_position character Player position name; athlete_detail = TRUE only.
athlete_position_abbreviation character Player position abbreviation; athlete_detail = TRUE only.

See Also

Other ESPN CFB Functions: espn_cfb_award(), espn_cfb_awards(), espn_cfb_clear_cache(), espn_cfb_coach(), espn_cfb_coach_record(), espn_cfb_coaches(), espn_cfb_franchise(), espn_cfb_franchises(), espn_cfb_futures(), espn_cfb_game_broadcasts(), espn_cfb_game_drive_plays(), espn_cfb_game_drives(), espn_cfb_game_leaders(), espn_cfb_game_odds(), espn_cfb_game_pbp(), espn_cfb_game_play(), espn_cfb_game_player_box(), espn_cfb_game_player_statistics(), espn_cfb_game_powerindex(), espn_cfb_game_predictor(), espn_cfb_game_probabilities(), espn_cfb_game_situation(), espn_cfb_game_status(), espn_cfb_game_team_leaders(), espn_cfb_game_team_linescores(), espn_cfb_game_team_records(), espn_cfb_game_team_roster(), espn_cfb_game_team_statistics(), espn_cfb_game_teams(), espn_cfb_groups(), espn_cfb_pbp_v2(), espn_cfb_player(), espn_cfb_player_career_stats(), espn_cfb_player_eventlog(), espn_cfb_player_gamelog(), espn_cfb_player_overview(), espn_cfb_player_seasons(), espn_cfb_player_splits(), espn_cfb_player_stats_v3(), espn_cfb_players(), espn_cfb_position(), espn_cfb_positions(), espn_cfb_powerindex(), espn_cfb_rankings(), espn_cfb_recruits(), espn_cfb_season_info(), espn_cfb_season_types(), espn_cfb_season_weeks(), espn_cfb_seasons(), espn_cfb_standings(), espn_cfb_team(), espn_cfb_team_ats(), espn_cfb_team_awards(), espn_cfb_team_coaches(), espn_cfb_team_events(), espn_cfb_team_leaders(), espn_cfb_team_powerindex(), espn_cfb_team_ranks(), espn_cfb_team_record(), espn_cfb_team_roster(), espn_cfb_team_schedule(), espn_cfb_teams(), espn_cfb_unnest_plays(), espn_cfb_venue(), espn_cfb_venues(), espn_cfb_week_rankings()

Examples


  try(espn_cfb_qbr(year = 2024))
  try(espn_cfb_qbr(year = 2024, athlete_detail = TRUE))

ESPN College Football Ranking Sources

Description

Get the index of poll / ranking sources ESPN publishes for a college football season – the AP Top 25, the Coaches Poll, the CFP committee rankings, and the computer-derived polls.

Usage

espn_cfb_rankings(year = NULL)

Arguments

year

(Integer required): Season, 4 digit format (YYYY).
Minimum value accepted: 2000

Details

Wraps the ESPN core-v2 endpoint sports.core.api.espn.com/v2/sports/football/leagues/college-football/seasons/{year}/rankings. The index returns one ⁠$ref⁠ per ranking source (~6-7); this wrapper dereferences each and returns one row per source, with a count of how many weekly snapshots that source published in the season. To pull the actual ranked teams for a given week, feed season, season_type, and a week to espn_cfb_week_rankings().

Value

A data frame with one row per ranking source:

col_name types description
season integer Season (4-digit year).
ranking_id character ESPN ranking source id.
name character Ranking source name (e.g. ⁠AP Top 25⁠).
short_name character Ranking source short name (e.g. ⁠AP Poll⁠).
type character Ranking source type code (e.g. ap, cfp).
n_snapshots integer Number of weekly snapshots published by the source.
ranking_ref character ⁠$ref⁠ URL to the ranking source resource.

See Also

Other ESPN CFB Functions: espn_cfb_award(), espn_cfb_awards(), espn_cfb_clear_cache(), espn_cfb_coach(), espn_cfb_coach_record(), espn_cfb_coaches(), espn_cfb_franchise(), espn_cfb_franchises(), espn_cfb_futures(), espn_cfb_game_broadcasts(), espn_cfb_game_drive_plays(), espn_cfb_game_drives(), espn_cfb_game_leaders(), espn_cfb_game_odds(), espn_cfb_game_pbp(), espn_cfb_game_play(), espn_cfb_game_player_box(), espn_cfb_game_player_statistics(), espn_cfb_game_powerindex(), espn_cfb_game_predictor(), espn_cfb_game_probabilities(), espn_cfb_game_situation(), espn_cfb_game_status(), espn_cfb_game_team_leaders(), espn_cfb_game_team_linescores(), espn_cfb_game_team_records(), espn_cfb_game_team_roster(), espn_cfb_game_team_statistics(), espn_cfb_game_teams(), espn_cfb_groups(), espn_cfb_pbp_v2(), espn_cfb_player(), espn_cfb_player_career_stats(), espn_cfb_player_eventlog(), espn_cfb_player_gamelog(), espn_cfb_player_overview(), espn_cfb_player_seasons(), espn_cfb_player_splits(), espn_cfb_player_stats_v3(), espn_cfb_players(), espn_cfb_position(), espn_cfb_positions(), espn_cfb_powerindex(), espn_cfb_qbr(), espn_cfb_recruits(), espn_cfb_season_info(), espn_cfb_season_types(), espn_cfb_season_weeks(), espn_cfb_seasons(), espn_cfb_standings(), espn_cfb_team(), espn_cfb_team_ats(), espn_cfb_team_awards(), espn_cfb_team_coaches(), espn_cfb_team_events(), espn_cfb_team_leaders(), espn_cfb_team_powerindex(), espn_cfb_team_ranks(), espn_cfb_team_record(), espn_cfb_team_roster(), espn_cfb_team_schedule(), espn_cfb_teams(), espn_cfb_unnest_plays(), espn_cfb_venue(), espn_cfb_venues(), espn_cfb_week_rankings()

Examples


  try(espn_cfb_rankings(year = 2024))

ESPN College Football Recruits

Description

Get the ESPN recruiting-class catalog for a college football signing class – one row per recruit, with athlete identity, position, physical measurements, ESPN grade, the overall / position / state / region rankings, the committed school, and the recruit's hometown and high school.

Usage

espn_cfb_recruits(year = NULL, max_results = 100)

Arguments

year

(Integer required): Recruiting class / signing year, 4 digit format (YYYY).
Minimum value accepted: 2006

max_results

(Integer default 100): Maximum number of recruits to dereference and return. The index is alphabetical, so this returns the alphabetically-first max_results recruits; raise it to pull more of the class.

Details

Wraps the ESPN core-v2 endpoint sports.core.api.espn.com/v2/sports/football/leagues/college-football/seasons/{year}/recruits. The season index is ⁠$ref⁠-paginated and large (roughly 3,700-4,900 recruits per class), so dereferencing every recruit would be thousands of HTTP calls. ESPN exposes no pre-expanded recruiting endpoint – the site.web.api.espn.com recruiting paths all 404 – so this wrapper caps the walk at max_results recruits (default 100). Raise max_results (e.g. to several hundred or higher) to pull more of the class, at the cost of one extra HTTP call per recruit.

The index is returned by ESPN in athlete-name (alphabetical) order, not ranking order, and the sort query parameter is ignored upstream. The default max_results = 100 therefore returns the alphabetically-first 100 recruits, not the top-100 ranked recruits. To rank the class, pull a larger slice and sort the result on overall_rank (lower is better); note ESPN only publishes an overall_rank for the highly-rated portion of each class, so most recruits carry NA there. position_rank, state_rank, and region_rank are populated more widely. grade is ESPN's 0-100 recruit grade (0 / gradeDisplayValue = "NR" means not rated).

committed_team_id / committed_team_ref are resolved from the recruit's schools array by matching a school whose commitment status equals the recruit's top-level status (e.g. Signed); recruits still uncommitted at fetch time leave both columns NA.

Value

A data frame with one row per recruit:

col_name types description
recruit_id character ESPN recruit id.
recruiting_class integer Recruiting class / signing year.
athlete_id character ESPN athlete id.
alternate_athlete_id character ESPN alternate athlete id (recruiting feed id).
first_name character Recruit first name.
last_name character Recruit last name.
full_name character Recruit full name.
display_name character Recruit display name.
short_name character Recruit short name.
position_id character ESPN position id.
position_abbreviation character Position abbreviation (e.g. OT, WR).
weight numeric Listed weight (lbs).
height numeric Listed height (inches).
grade numeric ESPN recruit grade (0-100; 0 = not rated).
grade_display_value character Display-formatted grade (NR when not rated).
overall_rank integer Overall recruit ranking (top recruits only; may be NA).
position_rank integer Position ranking.
state_rank integer State ranking.
region_rank integer Region ranking.
status_id character ESPN commitment status id.
status character Commitment status description (e.g. Signed).
committed_team_id character ESPN team id of the committed school (may be NA).
hometown_city character Recruit hometown city.
hometown_state character Recruit hometown state.
hometown_state_abbreviation character Recruit hometown state abbreviation.
high_school_id character ESPN high-school id.
high_school_name character Recruit high-school name.
recruit_ref character ⁠$ref⁠ URL to the recruit resource.
athlete_ref character Player-card URL for the recruit.
committed_team_ref character ⁠$ref⁠ URL to the committed team-in-season resource.

See Also

Other ESPN CFB Functions: espn_cfb_award(), espn_cfb_awards(), espn_cfb_clear_cache(), espn_cfb_coach(), espn_cfb_coach_record(), espn_cfb_coaches(), espn_cfb_franchise(), espn_cfb_franchises(), espn_cfb_futures(), espn_cfb_game_broadcasts(), espn_cfb_game_drive_plays(), espn_cfb_game_drives(), espn_cfb_game_leaders(), espn_cfb_game_odds(), espn_cfb_game_pbp(), espn_cfb_game_play(), espn_cfb_game_player_box(), espn_cfb_game_player_statistics(), espn_cfb_game_powerindex(), espn_cfb_game_predictor(), espn_cfb_game_probabilities(), espn_cfb_game_situation(), espn_cfb_game_status(), espn_cfb_game_team_leaders(), espn_cfb_game_team_linescores(), espn_cfb_game_team_records(), espn_cfb_game_team_roster(), espn_cfb_game_team_statistics(), espn_cfb_game_teams(), espn_cfb_groups(), espn_cfb_pbp_v2(), espn_cfb_player(), espn_cfb_player_career_stats(), espn_cfb_player_eventlog(), espn_cfb_player_gamelog(), espn_cfb_player_overview(), espn_cfb_player_seasons(), espn_cfb_player_splits(), espn_cfb_player_stats_v3(), espn_cfb_players(), espn_cfb_position(), espn_cfb_positions(), espn_cfb_powerindex(), espn_cfb_qbr(), espn_cfb_rankings(), espn_cfb_season_info(), espn_cfb_season_types(), espn_cfb_season_weeks(), espn_cfb_seasons(), espn_cfb_standings(), espn_cfb_team(), espn_cfb_team_ats(), espn_cfb_team_awards(), espn_cfb_team_coaches(), espn_cfb_team_events(), espn_cfb_team_leaders(), espn_cfb_team_powerindex(), espn_cfb_team_ranks(), espn_cfb_team_record(), espn_cfb_team_roster(), espn_cfb_team_schedule(), espn_cfb_teams(), espn_cfb_unnest_plays(), espn_cfb_venue(), espn_cfb_venues(), espn_cfb_week_rankings()

Examples


  try(espn_cfb_recruits(year = 2024, max_results = 25))

ESPN Scoreboard

Description

ESPN Scoreboard

Get live scoreboard data from ESPN or look up the college football schedule for a given season

ESPN Schedule

Usage

espn_cfb_scoreboard(date = NULL)

espn_cfb_schedule(
  year = NULL,
  week = NULL,
  season_type = NULL,
  groups = NULL,
  limit = 500
)

Arguments

date

(Integer required - YYYYMMDD): Date to pull

year

(int): Used to define different seasons.
Minimum value accepted: 1877

week

(int): Week of the schedule.

season_type

(string): "regular", "postseason", "off-season", or "both".

groups

(string): Used to define different divisions. FBS or FCS.

limit

(int): number of records to return, default: 500.

Value

espn_cfb_scoreboard() & espn_cfb_schedule() - A data frame with 33 or 54 variables depending on if there are completed games: shared variables

Unique variables when there are completed games

espn_cfb_schedule() - A data frame with 8 variables:

Examples


  try(espn_cfb_scoreboard())



  try(espn_cfb_schedule(2021, week = 8))

ESPN College Football Season Endpoint Overview

Description

Details

Get ESPN College Football Groups & Conferences

espn_cfb_groups(year = 2024)

Get ESPN College Football Ranking Sources

espn_cfb_rankings(year = 2024)

Get ESPN College Football Season Detail

espn_cfb_season_info(year = 2024)

Get ESPN College Football Season Types

espn_cfb_season_types(year = 2024)

Get ESPN College Football Season Weeks

espn_cfb_season_weeks(year = 2024)

Get ESPN College Football Seasons Index

espn_cfb_seasons()

Get ESPN College Football Standings (Long Format)

espn_cfb_standings(year = 2024)

espn_cfb_standings(year = 2024, team_detail = FALSE)

Get ESPN College Football Weekly Rankings

espn_cfb_week_rankings(year = 2024, week = 8)

espn_cfb_week_rankings(year = 2024, week = 8, team_detail = FALSE)

ESPN College Football Season Detail

Description

Get the ESPN core-v2 detail record for a single college football season – start / end dates, the active season type, and the ⁠$ref⁠ links to that season's types, rankings, athletes, awards, and futures sub-resources.

Usage

espn_cfb_season_info(year = NULL)

Arguments

year

(Integer required): Season, 4 digit format (YYYY).
Minimum value accepted: 1872

Details

Wraps the ESPN core-v2 endpoint sports.core.api.espn.com/v2/sports/football/leagues/college-football/seasons/{year}. Returns a single-row tibble. The ⁠*_ref⁠ columns are the season-scoped sub-resource entry points – feed types_ref to espn_cfb_season_types(), rankings_ref to espn_cfb_rankings(), and so on. ⁠active_type_*⁠ describes the season type ESPN currently considers "live" for the year (preseason / regular / postseason / off-season).

Value

A single-row data frame:

col_name types description
season integer Season (4-digit year).
display_name character ESPN display name for the season.
start_date character Season start timestamp (ISO 8601, UTC).
end_date character Season end timestamp (ISO 8601, UTC).
active_type_id integer ESPN id of the currently active season type.
active_type integer Active season type code (1 pre, 2 reg, 3 post).
active_type_name character Active season type name (e.g. ⁠Regular Season⁠).
types_ref character ⁠$ref⁠ URL to the season types index.
rankings_ref character ⁠$ref⁠ URL to the season rankings index.
athletes_ref character ⁠$ref⁠ URL to the season athletes index.
awards_ref character ⁠$ref⁠ URL to the season awards index.
futures_ref character ⁠$ref⁠ URL to the season betting-futures index.
leaders_ref character ⁠$ref⁠ URL to the season leaders resource.

See Also

Other ESPN CFB Functions: espn_cfb_award(), espn_cfb_awards(), espn_cfb_clear_cache(), espn_cfb_coach(), espn_cfb_coach_record(), espn_cfb_coaches(), espn_cfb_franchise(), espn_cfb_franchises(), espn_cfb_futures(), espn_cfb_game_broadcasts(), espn_cfb_game_drive_plays(), espn_cfb_game_drives(), espn_cfb_game_leaders(), espn_cfb_game_odds(), espn_cfb_game_pbp(), espn_cfb_game_play(), espn_cfb_game_player_box(), espn_cfb_game_player_statistics(), espn_cfb_game_powerindex(), espn_cfb_game_predictor(), espn_cfb_game_probabilities(), espn_cfb_game_situation(), espn_cfb_game_status(), espn_cfb_game_team_leaders(), espn_cfb_game_team_linescores(), espn_cfb_game_team_records(), espn_cfb_game_team_roster(), espn_cfb_game_team_statistics(), espn_cfb_game_teams(), espn_cfb_groups(), espn_cfb_pbp_v2(), espn_cfb_player(), espn_cfb_player_career_stats(), espn_cfb_player_eventlog(), espn_cfb_player_gamelog(), espn_cfb_player_overview(), espn_cfb_player_seasons(), espn_cfb_player_splits(), espn_cfb_player_stats_v3(), espn_cfb_players(), espn_cfb_position(), espn_cfb_positions(), espn_cfb_powerindex(), espn_cfb_qbr(), espn_cfb_rankings(), espn_cfb_recruits(), espn_cfb_season_types(), espn_cfb_season_weeks(), espn_cfb_seasons(), espn_cfb_standings(), espn_cfb_team(), espn_cfb_team_ats(), espn_cfb_team_awards(), espn_cfb_team_coaches(), espn_cfb_team_events(), espn_cfb_team_leaders(), espn_cfb_team_powerindex(), espn_cfb_team_ranks(), espn_cfb_team_record(), espn_cfb_team_roster(), espn_cfb_team_schedule(), espn_cfb_teams(), espn_cfb_unnest_plays(), espn_cfb_venue(), espn_cfb_venues(), espn_cfb_week_rankings()

Examples


  try(espn_cfb_season_info(year = 2024))

ESPN College Football Season Types

Description

Get the set of season types (preseason, regular season, postseason, off-season) ESPN tracks for a college football season, including each type's date window and capability flags.

Usage

espn_cfb_season_types(year = NULL)

Arguments

year

(Integer required): Season, 4 digit format (YYYY).
Minimum value accepted: 1872

Details

Wraps the ESPN core-v2 endpoint sports.core.api.espn.com/v2/sports/football/leagues/college-football/seasons/{year}/types. The index returns one ⁠$ref⁠ per season type; this wrapper dereferences each and returns one row per type (typically four: 1 preseason, 2 regular season, 3 postseason, 4 off-season). The season_type ids returned here are the values other Batch 5 wrappers (espn_cfb_season_weeks(), espn_cfb_groups(), espn_cfb_standings(), espn_cfb_week_rankings()) accept as their season_type argument.

Value

A data frame with one row per season type:

col_name types description
season integer Season (4-digit year).
season_type integer ESPN season type id (1 pre, 2 reg, 3 post, 4 off).
type integer Season type code (mirrors season_type).
name character Season type name (e.g. ⁠Regular Season⁠).
abbreviation character Season type abbreviation (e.g. reg).
slug character Season type slug (e.g. regular-season).
start_date character Season type start timestamp (ISO 8601, UTC).
end_date character Season type end timestamp (ISO 8601, UTC).
has_groups logical Whether the season type exposes a groups resource.
has_standings logical Whether the season type exposes standings.
type_ref character ⁠$ref⁠ URL to the season type resource.

See Also

Other ESPN CFB Functions: espn_cfb_award(), espn_cfb_awards(), espn_cfb_clear_cache(), espn_cfb_coach(), espn_cfb_coach_record(), espn_cfb_coaches(), espn_cfb_franchise(), espn_cfb_franchises(), espn_cfb_futures(), espn_cfb_game_broadcasts(), espn_cfb_game_drive_plays(), espn_cfb_game_drives(), espn_cfb_game_leaders(), espn_cfb_game_odds(), espn_cfb_game_pbp(), espn_cfb_game_play(), espn_cfb_game_player_box(), espn_cfb_game_player_statistics(), espn_cfb_game_powerindex(), espn_cfb_game_predictor(), espn_cfb_game_probabilities(), espn_cfb_game_situation(), espn_cfb_game_status(), espn_cfb_game_team_leaders(), espn_cfb_game_team_linescores(), espn_cfb_game_team_records(), espn_cfb_game_team_roster(), espn_cfb_game_team_statistics(), espn_cfb_game_teams(), espn_cfb_groups(), espn_cfb_pbp_v2(), espn_cfb_player(), espn_cfb_player_career_stats(), espn_cfb_player_eventlog(), espn_cfb_player_gamelog(), espn_cfb_player_overview(), espn_cfb_player_seasons(), espn_cfb_player_splits(), espn_cfb_player_stats_v3(), espn_cfb_players(), espn_cfb_position(), espn_cfb_positions(), espn_cfb_powerindex(), espn_cfb_qbr(), espn_cfb_rankings(), espn_cfb_recruits(), espn_cfb_season_info(), espn_cfb_season_weeks(), espn_cfb_seasons(), espn_cfb_standings(), espn_cfb_team(), espn_cfb_team_ats(), espn_cfb_team_awards(), espn_cfb_team_coaches(), espn_cfb_team_events(), espn_cfb_team_leaders(), espn_cfb_team_powerindex(), espn_cfb_team_ranks(), espn_cfb_team_record(), espn_cfb_team_roster(), espn_cfb_team_schedule(), espn_cfb_teams(), espn_cfb_unnest_plays(), espn_cfb_venue(), espn_cfb_venues(), espn_cfb_week_rankings()

Examples


  try(espn_cfb_season_types(year = 2024))

ESPN College Football Season Weeks

Description

Get the calendar of weeks ESPN tracks for a college football season type – each week's number, label, and start / end dates.

Usage

espn_cfb_season_weeks(year = NULL, season_type = 2)

Arguments

year

(Integer required): Season, 4 digit format (YYYY).
Minimum value accepted: 1999

season_type

(Integer default 2): ESPN season type id. 2 = regular season (the only type with a meaningful week calendar), 3 = postseason, 1 = preseason.

Details

Wraps the ESPN core-v2 endpoint sports.core.api.espn.com/v2/sports/football/leagues/college-football/seasons/{year}/types/{season_type}/weeks. The index returns one ⁠$ref⁠ per week; this wrapper dereferences each and returns one row per week (~15-16 for a regular season). The week numbers returned here are the values espn_cfb_week_rankings() accepts.

Value

A data frame with one row per week:

col_name types description
season integer Season (4-digit year).
season_type integer ESPN season type id queried.
week integer Week number.
text character Week label (e.g. ⁠Week 1⁠, Bowls).
start_date character Week start timestamp (ISO 8601, UTC).
end_date character Week end timestamp (ISO 8601, UTC).
week_ref character ⁠$ref⁠ URL to the week resource.

See Also

Other ESPN CFB Functions: espn_cfb_award(), espn_cfb_awards(), espn_cfb_clear_cache(), espn_cfb_coach(), espn_cfb_coach_record(), espn_cfb_coaches(), espn_cfb_franchise(), espn_cfb_franchises(), espn_cfb_futures(), espn_cfb_game_broadcasts(), espn_cfb_game_drive_plays(), espn_cfb_game_drives(), espn_cfb_game_leaders(), espn_cfb_game_odds(), espn_cfb_game_pbp(), espn_cfb_game_play(), espn_cfb_game_player_box(), espn_cfb_game_player_statistics(), espn_cfb_game_powerindex(), espn_cfb_game_predictor(), espn_cfb_game_probabilities(), espn_cfb_game_situation(), espn_cfb_game_status(), espn_cfb_game_team_leaders(), espn_cfb_game_team_linescores(), espn_cfb_game_team_records(), espn_cfb_game_team_roster(), espn_cfb_game_team_statistics(), espn_cfb_game_teams(), espn_cfb_groups(), espn_cfb_pbp_v2(), espn_cfb_player(), espn_cfb_player_career_stats(), espn_cfb_player_eventlog(), espn_cfb_player_gamelog(), espn_cfb_player_overview(), espn_cfb_player_seasons(), espn_cfb_player_splits(), espn_cfb_player_stats_v3(), espn_cfb_players(), espn_cfb_position(), espn_cfb_positions(), espn_cfb_powerindex(), espn_cfb_qbr(), espn_cfb_rankings(), espn_cfb_recruits(), espn_cfb_season_info(), espn_cfb_season_types(), espn_cfb_seasons(), espn_cfb_standings(), espn_cfb_team(), espn_cfb_team_ats(), espn_cfb_team_awards(), espn_cfb_team_coaches(), espn_cfb_team_events(), espn_cfb_team_leaders(), espn_cfb_team_powerindex(), espn_cfb_team_ranks(), espn_cfb_team_record(), espn_cfb_team_roster(), espn_cfb_team_schedule(), espn_cfb_teams(), espn_cfb_unnest_plays(), espn_cfb_venue(), espn_cfb_venues(), espn_cfb_week_rankings()

Examples


  try(espn_cfb_season_weeks(year = 2024))

ESPN College Football Seasons Index

Description

Get the index of every college football season ESPN tracks in its core-v2 API, with each season's start and end dates.

Usage

espn_cfb_seasons()

Details

Wraps the ESPN core-v2 endpoint sports.core.api.espn.com/v2/sports/football/leagues/college-football/seasons. The index is ⁠$ref⁠-paginated; this wrapper walks every page, dereferences each season ⁠$ref⁠, and returns one row per season. ESPN's CFB season coverage runs back to the early 1900s, so the table is long – filter on season for the years you need. Use espn_cfb_season_info() for the full per-season detail (season types, rankings, awards, futures refs).

Value

A data frame with one row per season:

col_name types description
season integer Season (4-digit year).
display_name character ESPN display name for the season.
start_date character Season start timestamp (ISO 8601, UTC).
end_date character Season end timestamp (ISO 8601, UTC).
season_ref character ⁠$ref⁠ URL to the season resource.

See Also

Other ESPN CFB Functions: espn_cfb_award(), espn_cfb_awards(), espn_cfb_clear_cache(), espn_cfb_coach(), espn_cfb_coach_record(), espn_cfb_coaches(), espn_cfb_franchise(), espn_cfb_franchises(), espn_cfb_futures(), espn_cfb_game_broadcasts(), espn_cfb_game_drive_plays(), espn_cfb_game_drives(), espn_cfb_game_leaders(), espn_cfb_game_odds(), espn_cfb_game_pbp(), espn_cfb_game_play(), espn_cfb_game_player_box(), espn_cfb_game_player_statistics(), espn_cfb_game_powerindex(), espn_cfb_game_predictor(), espn_cfb_game_probabilities(), espn_cfb_game_situation(), espn_cfb_game_status(), espn_cfb_game_team_leaders(), espn_cfb_game_team_linescores(), espn_cfb_game_team_records(), espn_cfb_game_team_roster(), espn_cfb_game_team_statistics(), espn_cfb_game_teams(), espn_cfb_groups(), espn_cfb_pbp_v2(), espn_cfb_player(), espn_cfb_player_career_stats(), espn_cfb_player_eventlog(), espn_cfb_player_gamelog(), espn_cfb_player_overview(), espn_cfb_player_seasons(), espn_cfb_player_splits(), espn_cfb_player_stats_v3(), espn_cfb_players(), espn_cfb_position(), espn_cfb_positions(), espn_cfb_powerindex(), espn_cfb_qbr(), espn_cfb_rankings(), espn_cfb_recruits(), espn_cfb_season_info(), espn_cfb_season_types(), espn_cfb_season_weeks(), espn_cfb_standings(), espn_cfb_team(), espn_cfb_team_ats(), espn_cfb_team_awards(), espn_cfb_team_coaches(), espn_cfb_team_events(), espn_cfb_team_leaders(), espn_cfb_team_powerindex(), espn_cfb_team_ranks(), espn_cfb_team_record(), espn_cfb_team_roster(), espn_cfb_team_schedule(), espn_cfb_teams(), espn_cfb_unnest_plays(), espn_cfb_venue(), espn_cfb_venues(), espn_cfb_week_rankings()

Examples


  try(espn_cfb_seasons())

ESPN College Football Standings (Long Format)

Description

Get ESPN's standings for a college football group – the full set of record splits (overall, home, away, conference, ...) and every standings statistic (wins, losses, point differential, streak, ...) for every team in the group.

Usage

espn_cfb_standings(
  year = NULL,
  group_id = 90,
  season_type = 2,
  team_detail = TRUE
)

Arguments

year

(Integer required): Season, 4 digit format (YYYY).
Minimum value accepted: 2001

group_id

(Integer default 90): ESPN group id. 90 = NCAA Division I (all D-I teams). Conference group ids also work.

season_type

(Integer default 2): ESPN season type id. 2 = regular season.

team_detail

(Logical): when TRUE (default), fetch the ESPN team catalog once and join friendly team fields next to the team_id column (see Details). Set FALSE to skip the catalog fetch and the join.

Details

Wraps the ESPN core-v2 endpoint sports.core.api.espn.com/v2/sports/football/leagues/college-football/seasons/{year}/types/{season_type}/groups/{group_id}/standings. The standings resource nests three levels deep – team -> record split -> statistic – so this wrapper returns long format: one row per (team x record split x statistic). The long shape absorbs ESPN's habit of adding standings stats across seasons. Pivot wider keyed on stat_name (within a record_type) when a wide table is wanted.

group_id = 90 (NCAA Division I) is the sensible default and yields every D-I team in one call. Conference-level group_ids – enumerate them with espn_cfb_groups() – restrict the table to that conference.

When team_detail = TRUE (the default) the ESPN team catalog (espn_cfb_teams()) is fetched once and friendly team fields are joined in next to the team_id column – team_name, team_abbreviation, team_location, team_display_name, team_short_display_name, team_nickname, team_color, team_alternate_color, team_logo_href, and team_logo_dark_href, inserted immediately after team_id. A catalog failure degrades to NA rather than erroring the wrapper. Set team_detail = FALSE to skip the catalog fetch and the join.

Value

A data frame with one row per team-record-statistic:

col_name types description
season integer Season (4-digit year).
season_type integer ESPN season type id queried.
group_id character ESPN group id queried.
team_id character ESPN team id (parsed from team_ref).
team_name character Team nickname; team_detail = TRUE only.
team_abbreviation character Team abbreviation; team_detail = TRUE only.
team_location character Team location / school name; team_detail = TRUE only.
team_display_name character Full team display name; team_detail = TRUE only.
team_short_display_name character Short team display name; team_detail = TRUE only.
team_nickname character Team nickname label; team_detail = TRUE only.
team_color character Primary team color; team_detail = TRUE only.
team_alternate_color character Alternate team color; team_detail = TRUE only.
team_logo_href character Default team logo URL; team_detail = TRUE only.
team_logo_dark_href character Dark-variant team logo URL; team_detail = TRUE only.
record_type character Record split type code (e.g. total, homerecord).
record_name character Record split name (e.g. Overall, Home).
record_summary character Record split summary (e.g. 14-0).
stat_name character Standings statistic key (e.g. wins, streak).
abbreviation character Statistic abbreviation.
display_name character Human-readable statistic name.
value numeric Statistic value.
display_value character Display-formatted statistic value.
team_ref character ⁠$ref⁠ URL to the per-season team resource.

See Also

Other ESPN CFB Functions: espn_cfb_award(), espn_cfb_awards(), espn_cfb_clear_cache(), espn_cfb_coach(), espn_cfb_coach_record(), espn_cfb_coaches(), espn_cfb_franchise(), espn_cfb_franchises(), espn_cfb_futures(), espn_cfb_game_broadcasts(), espn_cfb_game_drive_plays(), espn_cfb_game_drives(), espn_cfb_game_leaders(), espn_cfb_game_odds(), espn_cfb_game_pbp(), espn_cfb_game_play(), espn_cfb_game_player_box(), espn_cfb_game_player_statistics(), espn_cfb_game_powerindex(), espn_cfb_game_predictor(), espn_cfb_game_probabilities(), espn_cfb_game_situation(), espn_cfb_game_status(), espn_cfb_game_team_leaders(), espn_cfb_game_team_linescores(), espn_cfb_game_team_records(), espn_cfb_game_team_roster(), espn_cfb_game_team_statistics(), espn_cfb_game_teams(), espn_cfb_groups(), espn_cfb_pbp_v2(), espn_cfb_player(), espn_cfb_player_career_stats(), espn_cfb_player_eventlog(), espn_cfb_player_gamelog(), espn_cfb_player_overview(), espn_cfb_player_seasons(), espn_cfb_player_splits(), espn_cfb_player_stats_v3(), espn_cfb_players(), espn_cfb_position(), espn_cfb_positions(), espn_cfb_powerindex(), espn_cfb_qbr(), espn_cfb_rankings(), espn_cfb_recruits(), espn_cfb_season_info(), espn_cfb_season_types(), espn_cfb_season_weeks(), espn_cfb_seasons(), espn_cfb_team(), espn_cfb_team_ats(), espn_cfb_team_awards(), espn_cfb_team_coaches(), espn_cfb_team_events(), espn_cfb_team_leaders(), espn_cfb_team_powerindex(), espn_cfb_team_ranks(), espn_cfb_team_record(), espn_cfb_team_roster(), espn_cfb_team_schedule(), espn_cfb_teams(), espn_cfb_unnest_plays(), espn_cfb_venue(), espn_cfb_venues(), espn_cfb_week_rankings()

Examples


  try(espn_cfb_standings(year = 2024))
  try(espn_cfb_standings(year = 2024, team_detail = FALSE))

ESPN College Football Team Endpoint Overview

Description

Get ESPN's detailed record for a single college football team in a given season – identifiers, branding, conference grouping, and home venue.

Usage

espn_cfb_team(team_id = NULL, year = NULL, team_detail = TRUE)

Arguments

team_id

(Integer required): ESPN team id.

year

(Integer required): Season, 4 digit format (YYYY).
Minimum value accepted: 1869

team_detail

(Logical): when TRUE (default), fetch the ESPN team catalog once and join friendly team fields next to the team_id column (see Details). Set FALSE to skip the catalog fetch and the join.

Details

ESPN College Football Team Detail (Season-Scoped)

espn_cfb_team(team_id = 61, year = 2024)

ESPN College Football Teams Index

espn_cfb_teams()

ESPN College Football Team Against-the-Spread Records

espn_cfb_team_ats(team_id = 61, year = 2024)

ESPN College Football Team Awards

espn_cfb_team_awards(team_id = 61, year = 2023)

ESPN College Football Team Coaches

espn_cfb_team_coaches(team_id = 61, year = 2024)

ESPN College Football Team Season Event Log

espn_cfb_team_events(team_id = 61, year = 2024)

ESPN College Football Team Statistical Leaders

espn_cfb_team_leaders(team_id = 61, year = 2024)

ESPN College Football Single-Team Power Index (Long Format)

espn_cfb_team_powerindex(team_id = 61, year = 2024)

ESPN College Football Team Poll Rank History

espn_cfb_team_ranks(team_id = 61, year = 2024)

ESPN College Football Team Record (Long Format)

espn_cfb_team_record(team_id = 61, year = 2024)

ESPN College Football Team Roster (Season-Scoped)

espn_cfb_team_roster(team_id = 61, year = 2024)

ESPN College Football Team Schedule

espn_cfb_team_schedule(team_id = 61, year = 2024)

Get ESPN college football team stats data

espn_cfb_team_stats(team_id = 52, year = 2020)

Wraps the ESPN core-v2 team-in-season endpoint sports.core.api.espn.com/v2/sports/football/leagues/college-football/seasons/{year}/teams/{team_id}. Unlike the site-v2 team payload, the core-v2 resource is season-scoped, so a team's conference grouping is resolved for the requested year. The result is a single-row data frame. Team ids are ESPN team identifiers – enumerate them with espn_cfb_teams().

When team_detail = TRUE (the default) the ESPN team catalog (espn_cfb_teams()) is fetched once and friendly team fields are joined in next to the team_id column – team_name, team_abbreviation, team_location, team_display_name, team_short_display_name, team_nickname, team_color, team_alternate_color, team_logo_href, and team_logo_dark_href, inserted immediately after team_id. A catalog failure degrades to NA rather than erroring the wrapper. Set team_detail = FALSE to skip the catalog fetch and the join.

Value

A one-row data frame:

col_name types description
season integer Season (4-digit year).
team_id character ESPN team id.
team_name character Team nickname; team_detail = TRUE only.
team_abbreviation character Team abbreviation; team_detail = TRUE only.
team_location character Team location / school name; team_detail = TRUE only.
team_display_name character Full team display name; team_detail = TRUE only.
team_short_display_name character Short team display name; team_detail = TRUE only.
team_nickname character Team nickname label; team_detail = TRUE only.
team_color character Primary team color; team_detail = TRUE only.
team_alternate_color character Alternate team color; team_detail = TRUE only.
team_logo_href character Default team logo URL; team_detail = TRUE only.
team_logo_dark_href character Dark-variant team logo URL; team_detail = TRUE only.
guid character ESPN team GUID.
uid character ESPN global unique identifier.
slug character URL slug for the team.
abbreviation character Team abbreviation.
display_name character Full team display name.
short_display_name character Short team display name.
name character Team nickname (e.g. Bulldogs).
nickname character Team nickname / location label.
location character Team location / school name.
color character Primary team color (hex, no ⁠#⁠).
alternate_color character Alternate team color (hex, no ⁠#⁠).
is_active logical Whether the team is currently active.
is_all_star logical Whether the team is an all-star team.
group_id character ESPN group (conference) id for the season.
venue_id character ESPN id of the team's home venue.
venue_name character Name of the team's home venue.
venue_city character Home venue city.
venue_state character Home venue state.
venue_indoor logical Whether the home venue is indoors.
venue_grass logical Whether the home venue has a grass surface.

See Also

Other ESPN CFB Functions: espn_cfb_award(), espn_cfb_awards(), espn_cfb_clear_cache(), espn_cfb_coach(), espn_cfb_coach_record(), espn_cfb_coaches(), espn_cfb_franchise(), espn_cfb_franchises(), espn_cfb_futures(), espn_cfb_game_broadcasts(), espn_cfb_game_drive_plays(), espn_cfb_game_drives(), espn_cfb_game_leaders(), espn_cfb_game_odds(), espn_cfb_game_pbp(), espn_cfb_game_play(), espn_cfb_game_player_box(), espn_cfb_game_player_statistics(), espn_cfb_game_powerindex(), espn_cfb_game_predictor(), espn_cfb_game_probabilities(), espn_cfb_game_situation(), espn_cfb_game_status(), espn_cfb_game_team_leaders(), espn_cfb_game_team_linescores(), espn_cfb_game_team_records(), espn_cfb_game_team_roster(), espn_cfb_game_team_statistics(), espn_cfb_game_teams(), espn_cfb_groups(), espn_cfb_pbp_v2(), espn_cfb_player(), espn_cfb_player_career_stats(), espn_cfb_player_eventlog(), espn_cfb_player_gamelog(), espn_cfb_player_overview(), espn_cfb_player_seasons(), espn_cfb_player_splits(), espn_cfb_player_stats_v3(), espn_cfb_players(), espn_cfb_position(), espn_cfb_positions(), espn_cfb_powerindex(), espn_cfb_qbr(), espn_cfb_rankings(), espn_cfb_recruits(), espn_cfb_season_info(), espn_cfb_season_types(), espn_cfb_season_weeks(), espn_cfb_seasons(), espn_cfb_standings(), espn_cfb_team_ats(), espn_cfb_team_awards(), espn_cfb_team_coaches(), espn_cfb_team_events(), espn_cfb_team_leaders(), espn_cfb_team_powerindex(), espn_cfb_team_ranks(), espn_cfb_team_record(), espn_cfb_team_roster(), espn_cfb_team_schedule(), espn_cfb_teams(), espn_cfb_unnest_plays(), espn_cfb_venue(), espn_cfb_venues(), espn_cfb_week_rankings()

Examples


  try(espn_cfb_team(team_id = 61, year = 2024))
  try(espn_cfb_team(team_id = 61, year = 2024, team_detail = FALSE))

ESPN College Football Team Against-the-Spread Records

Description

Get a college football team's against-the-spread (ATS) records for a season – the 6-7 betting split rows ESPN tracks (overall, as favorite, as underdog, home, away, ...).

Usage

espn_cfb_team_ats(
  team_id = NULL,
  year = NULL,
  season_type = 2,
  team_detail = TRUE
)

Arguments

team_id

(Integer required): ESPN team id.

year

(Integer required): Season, 4 digit format (YYYY).
Minimum value accepted: 2007

season_type

(Integer default 2): ESPN season type. 2 = regular season, 3 = postseason.

team_detail

(Logical): when TRUE (default), fetch the ESPN team catalog once and join friendly team fields next to the team_id column (see Details). Set FALSE to skip the catalog fetch and the join.

Details

Wraps the ESPN core-v2 team ATS endpoint sports.core.api.espn.com/v2/sports/football/leagues/college-football/seasons/{year}/types/{season_type}/teams/{team_id}/ats. ESPN returns one item per ATS split, each carrying a wins/losses/ pushes triple and a type block (id, name, description). This wrapper returns one row per split. The ATS records are populated only for completed games, so an in-progress or future season may return an empty frame.

When team_detail = TRUE (the default) the ESPN team catalog (espn_cfb_teams()) is fetched once and friendly team fields are joined in next to the team_id column – team_name, team_abbreviation, team_location, team_display_name, team_short_display_name, team_nickname, team_color, team_alternate_color, team_logo_href, and team_logo_dark_href, inserted immediately after team_id. A catalog failure degrades to NA rather than erroring the wrapper. Set team_detail = FALSE to skip the catalog fetch and the join.

Value

A data frame with one row per ATS split:

col_name types description
season integer Season (4-digit year).
season_type integer ESPN season type (2 = regular, 3 = postseason).
team_id character ESPN team id.
team_name character Team nickname; team_detail = TRUE only.
team_abbreviation character Team abbreviation; team_detail = TRUE only.
team_location character Team location / school name; team_detail = TRUE only.
team_display_name character Full team display name; team_detail = TRUE only.
team_short_display_name character Short team display name; team_detail = TRUE only.
team_nickname character Team nickname label; team_detail = TRUE only.
team_color character Primary team color; team_detail = TRUE only.
team_alternate_color character Alternate team color; team_detail = TRUE only.
team_logo_href character Default team logo URL; team_detail = TRUE only.
team_logo_dark_href character Dark-variant team logo URL; team_detail = TRUE only.
ats_type_id character ATS split type id (e.g. 0, 1, 2).
ats_type_name character ATS split type key (e.g. atsOverall, atsFavorite).
ats_description character ESPN's description of the ATS split.
wins integer Wins against the spread in the split.
losses integer Losses against the spread in the split.
pushes integer Pushes (no cover, no loss) in the split.

See Also

Other ESPN CFB Functions: espn_cfb_award(), espn_cfb_awards(), espn_cfb_clear_cache(), espn_cfb_coach(), espn_cfb_coach_record(), espn_cfb_coaches(), espn_cfb_franchise(), espn_cfb_franchises(), espn_cfb_futures(), espn_cfb_game_broadcasts(), espn_cfb_game_drive_plays(), espn_cfb_game_drives(), espn_cfb_game_leaders(), espn_cfb_game_odds(), espn_cfb_game_pbp(), espn_cfb_game_play(), espn_cfb_game_player_box(), espn_cfb_game_player_statistics(), espn_cfb_game_powerindex(), espn_cfb_game_predictor(), espn_cfb_game_probabilities(), espn_cfb_game_situation(), espn_cfb_game_status(), espn_cfb_game_team_leaders(), espn_cfb_game_team_linescores(), espn_cfb_game_team_records(), espn_cfb_game_team_roster(), espn_cfb_game_team_statistics(), espn_cfb_game_teams(), espn_cfb_groups(), espn_cfb_pbp_v2(), espn_cfb_player(), espn_cfb_player_career_stats(), espn_cfb_player_eventlog(), espn_cfb_player_gamelog(), espn_cfb_player_overview(), espn_cfb_player_seasons(), espn_cfb_player_splits(), espn_cfb_player_stats_v3(), espn_cfb_players(), espn_cfb_position(), espn_cfb_positions(), espn_cfb_powerindex(), espn_cfb_qbr(), espn_cfb_rankings(), espn_cfb_recruits(), espn_cfb_season_info(), espn_cfb_season_types(), espn_cfb_season_weeks(), espn_cfb_seasons(), espn_cfb_standings(), espn_cfb_team(), espn_cfb_team_awards(), espn_cfb_team_coaches(), espn_cfb_team_events(), espn_cfb_team_leaders(), espn_cfb_team_powerindex(), espn_cfb_team_ranks(), espn_cfb_team_record(), espn_cfb_team_roster(), espn_cfb_team_schedule(), espn_cfb_teams(), espn_cfb_unnest_plays(), espn_cfb_venue(), espn_cfb_venues(), espn_cfb_week_rankings()

Examples


  try(espn_cfb_team_ats(team_id = 61, year = 2024))
  try(espn_cfb_team_ats(team_id = 61, year = 2024, team_detail = FALSE))

ESPN College Football Team Awards

Description

Get the awards won by a college football team's players in a season – one row per (award x winning athlete).

Usage

espn_cfb_team_awards(team_id = NULL, year = NULL, team_detail = TRUE)

Arguments

team_id

(Integer required): ESPN team id.

year

(Integer required): Season, 4 digit format (YYYY).
Minimum value accepted: 1935

team_detail

(Logical): when TRUE (default), fetch the ESPN team catalog once and join friendly team fields next to every team-id column (team_id, winner_team_id) in the output (see Details). Set FALSE to skip the catalog fetch and the join.

Details

Wraps the ESPN core-v2 team awards endpoint sports.core.api.espn.com/v2/sports/football/leagues/college-football/seasons/{year}/teams/{team_id}/awards. The index endpoint returns a ⁠$ref⁠ list of award resources; this wrapper dereferences each one and returns a row per winning athlete for the award. Athletes are returned as ESPN athlete ids (parsed from athlete_ref); join to another athlete source for names. Most teams have only one or two award items in a season.

When team_detail = TRUE (the default) the ESPN team catalog (espn_cfb_teams()) is fetched once and friendly team fields are joined onto every team-id column the output carries – team_id and winner_team_id. For each id column X_id the friendly siblings X_name, X_abbreviation, X_location, X_display_name, X_short_display_name, X_nickname, X_color, X_alternate_color, X_logo_href, and X_logo_dark_href are inserted immediately after it. A catalog failure degrades to NA rather than erroring the wrapper. Set team_detail = FALSE to skip the catalog fetch and the join.

Value

A data frame with one row per award-winner:

col_name types description
season integer Season (4-digit year).
team_id character ESPN team id.
team_name character Team nickname; team_detail = TRUE only.
team_abbreviation character Team abbreviation; team_detail = TRUE only.
team_location character Team location / school name; team_detail = TRUE only.
team_display_name character Full team display name; team_detail = TRUE only.
team_short_display_name character Short team display name; team_detail = TRUE only.
team_nickname character Team nickname label; team_detail = TRUE only.
team_color character Primary team color; team_detail = TRUE only.
team_alternate_color character Alternate team color; team_detail = TRUE only.
team_logo_href character Default team logo URL; team_detail = TRUE only.
team_logo_dark_href character Dark-variant team logo URL; team_detail = TRUE only.
award_id character ESPN award id.
award_name character Award display name (e.g. ⁠John Mackey Award⁠).
award_description character Short description of the award.
athlete_id character ESPN athlete id of the winner (parsed from athlete_ref).
winner_team_id character ESPN team id credited with the win (parsed from winner_team_ref).
winner_team_name character Winner team nickname; team_detail = TRUE only.
winner_team_abbreviation character Winner team abbreviation; team_detail = TRUE only.
winner_team_location character Winner team location / school; team_detail = TRUE only.
winner_team_display_name character Winner team full display name; team_detail = TRUE only.
winner_team_short_display_name character Winner team short display name; team_detail = TRUE only.
winner_team_nickname character Winner team nickname label; team_detail = TRUE only.
winner_team_color character Winner team primary color; team_detail = TRUE only.
winner_team_alternate_color character Winner team alternate color; team_detail = TRUE only.
winner_team_logo_href character Winner team default logo URL; team_detail = TRUE only.
winner_team_logo_dark_href character Winner team dark logo URL; team_detail = TRUE only.
award_ref character ⁠$ref⁠ URL to the core-v2 award resource.
athlete_ref character ⁠$ref⁠ URL to the winning athlete-in-season resource.
winner_team_ref character ⁠$ref⁠ URL to the winner's team-in-season resource.

See Also

Other ESPN CFB Functions: espn_cfb_award(), espn_cfb_awards(), espn_cfb_clear_cache(), espn_cfb_coach(), espn_cfb_coach_record(), espn_cfb_coaches(), espn_cfb_franchise(), espn_cfb_franchises(), espn_cfb_futures(), espn_cfb_game_broadcasts(), espn_cfb_game_drive_plays(), espn_cfb_game_drives(), espn_cfb_game_leaders(), espn_cfb_game_odds(), espn_cfb_game_pbp(), espn_cfb_game_play(), espn_cfb_game_player_box(), espn_cfb_game_player_statistics(), espn_cfb_game_powerindex(), espn_cfb_game_predictor(), espn_cfb_game_probabilities(), espn_cfb_game_situation(), espn_cfb_game_status(), espn_cfb_game_team_leaders(), espn_cfb_game_team_linescores(), espn_cfb_game_team_records(), espn_cfb_game_team_roster(), espn_cfb_game_team_statistics(), espn_cfb_game_teams(), espn_cfb_groups(), espn_cfb_pbp_v2(), espn_cfb_player(), espn_cfb_player_career_stats(), espn_cfb_player_eventlog(), espn_cfb_player_gamelog(), espn_cfb_player_overview(), espn_cfb_player_seasons(), espn_cfb_player_splits(), espn_cfb_player_stats_v3(), espn_cfb_players(), espn_cfb_position(), espn_cfb_positions(), espn_cfb_powerindex(), espn_cfb_qbr(), espn_cfb_rankings(), espn_cfb_recruits(), espn_cfb_season_info(), espn_cfb_season_types(), espn_cfb_season_weeks(), espn_cfb_seasons(), espn_cfb_standings(), espn_cfb_team(), espn_cfb_team_ats(), espn_cfb_team_coaches(), espn_cfb_team_events(), espn_cfb_team_leaders(), espn_cfb_team_powerindex(), espn_cfb_team_ranks(), espn_cfb_team_record(), espn_cfb_team_roster(), espn_cfb_team_schedule(), espn_cfb_teams(), espn_cfb_unnest_plays(), espn_cfb_venue(), espn_cfb_venues(), espn_cfb_week_rankings()

Examples


  try(espn_cfb_team_awards(team_id = 61, year = 2023))
  try(espn_cfb_team_awards(team_id = 61, year = 2023,
                           team_detail = FALSE))

ESPN College Football Team Coaches

Description

Get the coach associated with a college football team for the current season – one row per coach, with name, birth detail, and experience.

Usage

espn_cfb_team_coaches(
  team_id = NULL,
  year = most_recent_cfb_season(),
  team_detail = TRUE
)

Arguments

team_id

(Integer required): ESPN team id.

year

DEPRECATED. (Integer): Season, 4 digit format (YYYY). Defaults to most recent CFB season.

team_detail

(Logical): when TRUE (default), fetch the ESPN team catalog once and join friendly team fields next to the team_id column (see Details). Set FALSE to skip the catalog fetch and the join.

Details

Wraps the ESPN core-v2 team coaches endpoint sports.core.api.espn.com/v2/sports/football/leagues/college-football/seasons/{year}/teams/{team_id}/coaches. The index endpoint returns a ⁠$ref⁠ list of coach resources; this wrapper dereferences each one and returns a row per coach with the coach detail flattened. Most teams list a single head coach per season.

When team_detail = TRUE (the default) the ESPN team catalog (espn_cfb_teams()) is fetched once and friendly team fields are joined in next to the team_id column – team_name, team_abbreviation, team_location, team_display_name, team_short_display_name, team_nickname, team_color, team_alternate_color, team_logo_href, and team_logo_dark_href, inserted immediately after team_id. A catalog failure degrades to NA rather than erroring the wrapper. Set team_detail = FALSE to skip the catalog fetch and the join.

Value

A data frame with one row per coach:

col_name types description
season integer Season (4-digit year).
team_id character ESPN team id.
team_name character Team nickname; team_detail = TRUE only.
team_abbreviation character Team abbreviation; team_detail = TRUE only.
team_location character Team location / school name; team_detail = TRUE only.
team_display_name character Full team display name; team_detail = TRUE only.
team_short_display_name character Short team display name; team_detail = TRUE only.
team_nickname character Team nickname label; team_detail = TRUE only.
team_color character Primary team color; team_detail = TRUE only.
team_alternate_color character Alternate team color; team_detail = TRUE only.
team_logo_href character Default team logo URL; team_detail = TRUE only.
team_logo_dark_href character Dark-variant team logo URL; team_detail = TRUE only.
coach_id character ESPN coach id.
first_name character Coach's first name.
last_name character Coach's last name.
date_of_birth character Coach's date of birth.
birth_city character City of birth.
birth_state character State of birth.
birth_country character Country of birth.
experience integer Years of experience ESPN credits the coach.
coach_ref character ⁠$ref⁠ URL to the core-v2 coach-in-season resource.

See Also

Other ESPN CFB Functions: espn_cfb_award(), espn_cfb_awards(), espn_cfb_clear_cache(), espn_cfb_coach(), espn_cfb_coach_record(), espn_cfb_coaches(), espn_cfb_franchise(), espn_cfb_franchises(), espn_cfb_futures(), espn_cfb_game_broadcasts(), espn_cfb_game_drive_plays(), espn_cfb_game_drives(), espn_cfb_game_leaders(), espn_cfb_game_odds(), espn_cfb_game_pbp(), espn_cfb_game_play(), espn_cfb_game_player_box(), espn_cfb_game_player_statistics(), espn_cfb_game_powerindex(), espn_cfb_game_predictor(), espn_cfb_game_probabilities(), espn_cfb_game_situation(), espn_cfb_game_status(), espn_cfb_game_team_leaders(), espn_cfb_game_team_linescores(), espn_cfb_game_team_records(), espn_cfb_game_team_roster(), espn_cfb_game_team_statistics(), espn_cfb_game_teams(), espn_cfb_groups(), espn_cfb_pbp_v2(), espn_cfb_player(), espn_cfb_player_career_stats(), espn_cfb_player_eventlog(), espn_cfb_player_gamelog(), espn_cfb_player_overview(), espn_cfb_player_seasons(), espn_cfb_player_splits(), espn_cfb_player_stats_v3(), espn_cfb_players(), espn_cfb_position(), espn_cfb_positions(), espn_cfb_powerindex(), espn_cfb_qbr(), espn_cfb_rankings(), espn_cfb_recruits(), espn_cfb_season_info(), espn_cfb_season_types(), espn_cfb_season_weeks(), espn_cfb_seasons(), espn_cfb_standings(), espn_cfb_team(), espn_cfb_team_ats(), espn_cfb_team_awards(), espn_cfb_team_events(), espn_cfb_team_leaders(), espn_cfb_team_powerindex(), espn_cfb_team_ranks(), espn_cfb_team_record(), espn_cfb_team_roster(), espn_cfb_team_schedule(), espn_cfb_teams(), espn_cfb_unnest_plays(), espn_cfb_venue(), espn_cfb_venues(), espn_cfb_week_rankings()

Examples


  try(espn_cfb_team_coaches(team_id = 61))
  try(espn_cfb_team_coaches(team_id = 61, team_detail = FALSE))

ESPN College Football Team Season Event Log

Description

Get a college football team's full season event log – every game (regular season and postseason) ESPN lists for the team-season.

Usage

espn_cfb_team_events(team_id = NULL, year = NULL, team_detail = TRUE)

Arguments

team_id

(Integer required): ESPN team id.

year

(Integer required): Season, 4 digit format (YYYY).
Minimum value accepted: 1999

team_detail

(Logical): when TRUE (default), fetch the ESPN team catalog once and join friendly team fields next to the team_id column (see Details). Set FALSE to skip the catalog fetch and the join.

Details

Wraps the ESPN core-v2 team events endpoint sports.core.api.espn.com/v2/sports/football/leagues/college-football/seasons/{year}/teams/{team_id}/events. ESPN returns a ⁠$ref⁠ list – one reference per game – in core-v2's id space, complementing the site-v2 espn_cfb_team_schedule(). This wrapper returns one row per game with game_id parsed from each ⁠$ref⁠; it does not dereference each game (feed the game_id values to espn_cfb_game_teams(), espn_cfb_game_pbp(), or the other ⁠espn_cfb_game_*()⁠ wrappers for hydrated game detail). The event_order column preserves the order ESPN returns the games.

When team_detail = TRUE (the default) the ESPN team catalog (espn_cfb_teams()) is fetched once and friendly team fields are joined in next to the team_id column – team_name, team_abbreviation, team_location, team_display_name, team_short_display_name, team_nickname, team_color, team_alternate_color, team_logo_href, and team_logo_dark_href, inserted immediately after team_id. A catalog failure degrades to NA rather than erroring the wrapper. Set team_detail = FALSE to skip the catalog fetch and the join.

Value

A data frame with one row per game:

col_name types description
season integer Season (4-digit year).
team_id character ESPN team id.
team_name character Team nickname; team_detail = TRUE only.
team_abbreviation character Team abbreviation; team_detail = TRUE only.
team_location character Team location / school name; team_detail = TRUE only.
team_display_name character Full team display name; team_detail = TRUE only.
team_short_display_name character Short team display name; team_detail = TRUE only.
team_nickname character Team nickname label; team_detail = TRUE only.
team_color character Primary team color; team_detail = TRUE only.
team_alternate_color character Alternate team color; team_detail = TRUE only.
team_logo_href character Default team logo URL; team_detail = TRUE only.
team_logo_dark_href character Dark-variant team logo URL; team_detail = TRUE only.
event_order integer Order of the game within the team's season event log.
game_id character ESPN game (event) id, parsed from event_ref.
event_ref character ⁠$ref⁠ URL to the core-v2 event resource.

See Also

Other ESPN CFB Functions: espn_cfb_award(), espn_cfb_awards(), espn_cfb_clear_cache(), espn_cfb_coach(), espn_cfb_coach_record(), espn_cfb_coaches(), espn_cfb_franchise(), espn_cfb_franchises(), espn_cfb_futures(), espn_cfb_game_broadcasts(), espn_cfb_game_drive_plays(), espn_cfb_game_drives(), espn_cfb_game_leaders(), espn_cfb_game_odds(), espn_cfb_game_pbp(), espn_cfb_game_play(), espn_cfb_game_player_box(), espn_cfb_game_player_statistics(), espn_cfb_game_powerindex(), espn_cfb_game_predictor(), espn_cfb_game_probabilities(), espn_cfb_game_situation(), espn_cfb_game_status(), espn_cfb_game_team_leaders(), espn_cfb_game_team_linescores(), espn_cfb_game_team_records(), espn_cfb_game_team_roster(), espn_cfb_game_team_statistics(), espn_cfb_game_teams(), espn_cfb_groups(), espn_cfb_pbp_v2(), espn_cfb_player(), espn_cfb_player_career_stats(), espn_cfb_player_eventlog(), espn_cfb_player_gamelog(), espn_cfb_player_overview(), espn_cfb_player_seasons(), espn_cfb_player_splits(), espn_cfb_player_stats_v3(), espn_cfb_players(), espn_cfb_position(), espn_cfb_positions(), espn_cfb_powerindex(), espn_cfb_qbr(), espn_cfb_rankings(), espn_cfb_recruits(), espn_cfb_season_info(), espn_cfb_season_types(), espn_cfb_season_weeks(), espn_cfb_seasons(), espn_cfb_standings(), espn_cfb_team(), espn_cfb_team_ats(), espn_cfb_team_awards(), espn_cfb_team_coaches(), espn_cfb_team_leaders(), espn_cfb_team_powerindex(), espn_cfb_team_ranks(), espn_cfb_team_record(), espn_cfb_team_roster(), espn_cfb_team_schedule(), espn_cfb_teams(), espn_cfb_unnest_plays(), espn_cfb_venue(), espn_cfb_venues(), espn_cfb_week_rankings()

Examples


  try(espn_cfb_team_events(team_id = 61, year = 2024))
  try(espn_cfb_team_events(team_id = 61, year = 2024,
                           team_detail = FALSE))

ESPN College Football Team Statistical Leaders

Description

Get a college football team's season statistical leaders – the top athletes in each ESPN leader category (passing, rushing, receiving, tackles, ...).

Usage

espn_cfb_team_leaders(
  team_id = NULL,
  year = NULL,
  season_type = 2,
  team_detail = TRUE
)

Arguments

team_id

(Integer required): ESPN team id.

year

(Integer required): Season, 4 digit format (YYYY).
Minimum value accepted: 2004

season_type

(Integer default 2): ESPN season type. 2 = regular season, 3 = postseason.

team_detail

(Logical): when TRUE (default), fetch the ESPN team catalog once and join friendly team fields next to the team_id column (see Details). Set FALSE to skip the catalog fetch and the join.

Details

Wraps the ESPN core-v2 team leaders endpoint sports.core.api.espn.com/v2/sports/football/leagues/college-football/seasons/{year}/types/{season_type}/teams/{team_id}/leaders. ESPN groups leaders into categories and ranks several athletes within each. This wrapper flattens that to long format: one row per (category x ranked athlete), with leader_rank preserving the order ESPN returns. Athletes are returned as ESPN athlete ids; join to espn_cfb_team_roster() for names.

When team_detail = TRUE (the default) the ESPN team catalog (espn_cfb_teams()) is fetched once and friendly team fields are joined in next to the team_id column – team_name, team_abbreviation, team_location, team_display_name, team_short_display_name, team_nickname, team_color, team_alternate_color, team_logo_href, and team_logo_dark_href, inserted immediately after team_id. A catalog failure degrades to NA rather than erroring the wrapper. Set team_detail = FALSE to skip the catalog fetch and the join.

Value

A data frame with one row per category-leader:

col_name types description
season integer Season (4-digit year).
season_type integer ESPN season type (2 = regular, 3 = postseason).
team_id character ESPN team id.
team_name character Team nickname; team_detail = TRUE only.
team_abbreviation character Team abbreviation; team_detail = TRUE only.
team_location character Team location / school name; team_detail = TRUE only.
team_display_name character Full team display name; team_detail = TRUE only.
team_short_display_name character Short team display name; team_detail = TRUE only.
team_nickname character Team nickname label; team_detail = TRUE only.
team_color character Primary team color; team_detail = TRUE only.
team_alternate_color character Alternate team color; team_detail = TRUE only.
team_logo_href character Default team logo URL; team_detail = TRUE only.
team_logo_dark_href character Dark-variant team logo URL; team_detail = TRUE only.
category_name character Leader category key (e.g. passingLeader).
category_display character Leader category display name.
leader_rank integer Rank of the athlete within the category (1 = top).
athlete_id character ESPN athlete id (parsed from athlete_ref).
value numeric Leading stat value.
display_value character Display-formatted stat line.
athlete_ref character ⁠$ref⁠ URL to the athlete-in-season resource.

See Also

Other ESPN CFB Functions: espn_cfb_award(), espn_cfb_awards(), espn_cfb_clear_cache(), espn_cfb_coach(), espn_cfb_coach_record(), espn_cfb_coaches(), espn_cfb_franchise(), espn_cfb_franchises(), espn_cfb_futures(), espn_cfb_game_broadcasts(), espn_cfb_game_drive_plays(), espn_cfb_game_drives(), espn_cfb_game_leaders(), espn_cfb_game_odds(), espn_cfb_game_pbp(), espn_cfb_game_play(), espn_cfb_game_player_box(), espn_cfb_game_player_statistics(), espn_cfb_game_powerindex(), espn_cfb_game_predictor(), espn_cfb_game_probabilities(), espn_cfb_game_situation(), espn_cfb_game_status(), espn_cfb_game_team_leaders(), espn_cfb_game_team_linescores(), espn_cfb_game_team_records(), espn_cfb_game_team_roster(), espn_cfb_game_team_statistics(), espn_cfb_game_teams(), espn_cfb_groups(), espn_cfb_pbp_v2(), espn_cfb_player(), espn_cfb_player_career_stats(), espn_cfb_player_eventlog(), espn_cfb_player_gamelog(), espn_cfb_player_overview(), espn_cfb_player_seasons(), espn_cfb_player_splits(), espn_cfb_player_stats_v3(), espn_cfb_players(), espn_cfb_position(), espn_cfb_positions(), espn_cfb_powerindex(), espn_cfb_qbr(), espn_cfb_rankings(), espn_cfb_recruits(), espn_cfb_season_info(), espn_cfb_season_types(), espn_cfb_season_weeks(), espn_cfb_seasons(), espn_cfb_standings(), espn_cfb_team(), espn_cfb_team_ats(), espn_cfb_team_awards(), espn_cfb_team_coaches(), espn_cfb_team_events(), espn_cfb_team_powerindex(), espn_cfb_team_ranks(), espn_cfb_team_record(), espn_cfb_team_roster(), espn_cfb_team_schedule(), espn_cfb_teams(), espn_cfb_unnest_plays(), espn_cfb_venue(), espn_cfb_venues(), espn_cfb_week_rankings()

Examples


  try(espn_cfb_team_leaders(team_id = 61, year = 2024))
  try(espn_cfb_team_leaders(team_id = 61, year = 2024,
                            team_detail = FALSE))

ESPN College Football Single-Team Power Index (Long Format)

Description

Get ESPN's College Football Power Index (FPI) detail for a single team-season – the full set of predictive metrics and efficiency components ESPN attaches to one team.

Usage

espn_cfb_team_powerindex(team_id = NULL, year = NULL, team_detail = TRUE)

Arguments

team_id

(Integer required): ESPN team id.

year

(Integer required): Season, 4 digit format (YYYY).
Minimum value accepted: 2005

team_detail

(Logical): when TRUE (default), fetch the ESPN team catalog once and join friendly team fields next to the team_id column (see Details). Set FALSE to skip the catalog fetch and the join.

Details

Wraps the ESPN core-v2 single-team power-index endpoint sports.core.api.espn.com/v2/sports/football/leagues/college-football/seasons/{year}/powerindex/{team_id}. Where espn_cfb_powerindex() returns the league-wide index, this wrapper drills into one team and returns one row per metric in long format: every predictive metric (FPI, projected wins, strength of record, ...) and every efficiency component (offensive, defensive, special-teams efficiency, ...). The long shape is deliberate – ESPN adds and retires metrics across seasons, and a long frame absorbs that drift. Pivot wider with tidyr::pivot_wider() keyed on stat_name for a wide table.

When team_detail = TRUE (the default) the ESPN team catalog (espn_cfb_teams()) is fetched once and friendly team fields are joined in next to the team_id column – team_name, team_abbreviation, team_location, team_display_name, team_short_display_name, team_nickname, team_color, team_alternate_color, team_logo_href, and team_logo_dark_href, inserted immediately after team_id. A catalog failure degrades to NA rather than erroring the wrapper. Set team_detail = FALSE to skip the catalog fetch and the join.

Value

A data frame with one row per metric:

col_name types description
season integer Season (4-digit year).
team_id character ESPN team id.
team_name character Team nickname; team_detail = TRUE only.
team_abbreviation character Team abbreviation; team_detail = TRUE only.
team_location character Team location / school name; team_detail = TRUE only.
team_display_name character Full team display name; team_detail = TRUE only.
team_short_display_name character Short team display name; team_detail = TRUE only.
team_nickname character Team nickname label; team_detail = TRUE only.
team_color character Primary team color; team_detail = TRUE only.
team_alternate_color character Alternate team color; team_detail = TRUE only.
team_logo_href character Default team logo URL; team_detail = TRUE only.
team_logo_dark_href character Dark-variant team logo URL; team_detail = TRUE only.
team_ref character ⁠$ref⁠ URL to the team-in-season resource.
last_updated character Timestamp ESPN last refreshed the power index.
metric_group character predictive or efficiency.
stat_name character Internal metric key (e.g. fpi, offefficiency).
abbreviation character Metric abbreviation.
display_name character Human-readable metric name.
value numeric Metric value.
display_value character Display-formatted metric value as shown on ESPN.
description character ESPN's description of the metric.

See Also

Other ESPN CFB Functions: espn_cfb_award(), espn_cfb_awards(), espn_cfb_clear_cache(), espn_cfb_coach(), espn_cfb_coach_record(), espn_cfb_coaches(), espn_cfb_franchise(), espn_cfb_franchises(), espn_cfb_futures(), espn_cfb_game_broadcasts(), espn_cfb_game_drive_plays(), espn_cfb_game_drives(), espn_cfb_game_leaders(), espn_cfb_game_odds(), espn_cfb_game_pbp(), espn_cfb_game_play(), espn_cfb_game_player_box(), espn_cfb_game_player_statistics(), espn_cfb_game_powerindex(), espn_cfb_game_predictor(), espn_cfb_game_probabilities(), espn_cfb_game_situation(), espn_cfb_game_status(), espn_cfb_game_team_leaders(), espn_cfb_game_team_linescores(), espn_cfb_game_team_records(), espn_cfb_game_team_roster(), espn_cfb_game_team_statistics(), espn_cfb_game_teams(), espn_cfb_groups(), espn_cfb_pbp_v2(), espn_cfb_player(), espn_cfb_player_career_stats(), espn_cfb_player_eventlog(), espn_cfb_player_gamelog(), espn_cfb_player_overview(), espn_cfb_player_seasons(), espn_cfb_player_splits(), espn_cfb_player_stats_v3(), espn_cfb_players(), espn_cfb_position(), espn_cfb_positions(), espn_cfb_powerindex(), espn_cfb_qbr(), espn_cfb_rankings(), espn_cfb_recruits(), espn_cfb_season_info(), espn_cfb_season_types(), espn_cfb_season_weeks(), espn_cfb_seasons(), espn_cfb_standings(), espn_cfb_team(), espn_cfb_team_ats(), espn_cfb_team_awards(), espn_cfb_team_coaches(), espn_cfb_team_events(), espn_cfb_team_leaders(), espn_cfb_team_ranks(), espn_cfb_team_record(), espn_cfb_team_roster(), espn_cfb_team_schedule(), espn_cfb_teams(), espn_cfb_unnest_plays(), espn_cfb_venue(), espn_cfb_venues(), espn_cfb_week_rankings()

Examples


  try(espn_cfb_team_powerindex(team_id = 61, year = 2024))
  try(espn_cfb_team_powerindex(team_id = 61, year = 2024,
                               team_detail = FALSE))

ESPN College Football Team Poll Rank History

Description

Get a college football team's poll-rank history for a season – one row per poll (AP, Coaches, CFP Committee, ...) the team appeared in, with current/previous rank, trend, and record.

Usage

espn_cfb_team_ranks(
  team_id = NULL,
  year = NULL,
  week = NULL,
  team_detail = TRUE
)

Arguments

team_id

(Integer required): ESPN team id.

year

(Integer required): Season, 4 digit format (YYYY).
Minimum value accepted: 2000

week

(Integer optional): Regular-season week. When supplied, the team's rank at that specific week is returned.

team_detail

(Logical): when TRUE (default), fetch the ESPN team catalog once and join friendly team fields next to the team_id column (see Details). Set FALSE to skip the catalog fetch and the join.

Details

Wraps the ESPN core-v2 team ranks endpoint sports.core.api.espn.com/v2/sports/football/leagues/college-football/seasons/{year}/teams/{team_id}/ranks. When a week is supplied the week-resolved variant is used instead: sports.core.api.espn.com/v2/sports/football/leagues/college-football/seasons/{year}/types/2/weeks/{week}/teams/{team_id}/ranks. The index endpoint returns a ⁠$ref⁠ list of poll-rank resources; this wrapper dereferences each one and returns a single row per poll with the rank detail flattened. Without a week, ESPN returns the season's final poll positions (one row per poll, plus postseason polls).

When team_detail = TRUE (the default) the ESPN team catalog (espn_cfb_teams()) is fetched once and friendly team fields are joined in next to the team_id column – team_name, team_abbreviation, team_location, team_display_name, team_short_display_name, team_nickname, team_color, team_alternate_color, team_logo_href, and team_logo_dark_href, inserted immediately after team_id. A catalog failure degrades to NA rather than erroring the wrapper. Set team_detail = FALSE to skip the catalog fetch and the join.

Value

A data frame with one row per poll-rank:

col_name types description
season integer Season (4-digit year).
team_id character ESPN team id.
team_name character Team nickname; team_detail = TRUE only.
team_abbreviation character Team abbreviation; team_detail = TRUE only.
team_location character Team location / school name; team_detail = TRUE only.
team_display_name character Full team display name; team_detail = TRUE only.
team_short_display_name character Short team display name; team_detail = TRUE only.
team_nickname character Team nickname label; team_detail = TRUE only.
team_color character Primary team color; team_detail = TRUE only.
team_alternate_color character Alternate team color; team_detail = TRUE only.
team_logo_href character Default team logo URL; team_detail = TRUE only.
team_logo_dark_href character Dark-variant team logo URL; team_detail = TRUE only.
week integer Week of the rank occurrence.
poll_id character ESPN poll id (e.g. 21 = CFP Committee Rankings).
poll_name character Poll display name.
poll_short_name character Poll short name.
poll_type character Poll type code (e.g. cfp, ap, usa).
headline character Headline ESPN attaches to the poll release.
date character Date of the poll release.
current_rank integer Team's rank in this poll.
previous_rank integer Team's rank in the prior release of this poll.
trend character Rank movement string (e.g. +3, -1).
points numeric Voting points the team received.
first_place_votes integer First-place votes the team received.
record_summary character Team's win-loss record at the time of the poll.

See Also

Other ESPN CFB Functions: espn_cfb_award(), espn_cfb_awards(), espn_cfb_clear_cache(), espn_cfb_coach(), espn_cfb_coach_record(), espn_cfb_coaches(), espn_cfb_franchise(), espn_cfb_franchises(), espn_cfb_futures(), espn_cfb_game_broadcasts(), espn_cfb_game_drive_plays(), espn_cfb_game_drives(), espn_cfb_game_leaders(), espn_cfb_game_odds(), espn_cfb_game_pbp(), espn_cfb_game_play(), espn_cfb_game_player_box(), espn_cfb_game_player_statistics(), espn_cfb_game_powerindex(), espn_cfb_game_predictor(), espn_cfb_game_probabilities(), espn_cfb_game_situation(), espn_cfb_game_status(), espn_cfb_game_team_leaders(), espn_cfb_game_team_linescores(), espn_cfb_game_team_records(), espn_cfb_game_team_roster(), espn_cfb_game_team_statistics(), espn_cfb_game_teams(), espn_cfb_groups(), espn_cfb_pbp_v2(), espn_cfb_player(), espn_cfb_player_career_stats(), espn_cfb_player_eventlog(), espn_cfb_player_gamelog(), espn_cfb_player_overview(), espn_cfb_player_seasons(), espn_cfb_player_splits(), espn_cfb_player_stats_v3(), espn_cfb_players(), espn_cfb_position(), espn_cfb_positions(), espn_cfb_powerindex(), espn_cfb_qbr(), espn_cfb_rankings(), espn_cfb_recruits(), espn_cfb_season_info(), espn_cfb_season_types(), espn_cfb_season_weeks(), espn_cfb_seasons(), espn_cfb_standings(), espn_cfb_team(), espn_cfb_team_ats(), espn_cfb_team_awards(), espn_cfb_team_coaches(), espn_cfb_team_events(), espn_cfb_team_leaders(), espn_cfb_team_powerindex(), espn_cfb_team_record(), espn_cfb_team_roster(), espn_cfb_team_schedule(), espn_cfb_teams(), espn_cfb_unnest_plays(), espn_cfb_venue(), espn_cfb_venues(), espn_cfb_week_rankings()

Examples


  try(espn_cfb_team_ranks(team_id = 61, year = 2024))
  try(espn_cfb_team_ranks(team_id = 61, year = 2024,
                          team_detail = FALSE))

ESPN College Football Team Record (Long Format)

Description

Get a college football team's season records – overall, home, away, and conference splits – with the full set of summary stats ESPN attaches to each.

Usage

espn_cfb_team_record(
  team_id = NULL,
  year = NULL,
  season_type = 2,
  team_detail = TRUE
)

Arguments

team_id

(Integer required): ESPN team id.

year

(Integer required): Season, 4 digit format (YYYY).
Minimum value accepted: 2000

season_type

(Integer default 2): ESPN season type. 2 = regular season, 3 = postseason.

team_detail

(Logical): when TRUE (default), fetch the ESPN team catalog once and join friendly team fields next to the team_id column (see Details). Set FALSE to skip the catalog fetch and the join.

Details

Wraps the ESPN core-v2 team record endpoint sports.core.api.espn.com/v2/sports/football/leagues/college-football/seasons/{year}/types/{season_type}/teams/{team_id}/record. ESPN returns several record items per team (overall, home record, away record, vs. conference), each carrying ~20 summary stats. This wrapper flattens that to long format: one row per (record-item x stat). The long shape absorbs ESPN adding or retiring stat keys across seasons. Pivot wider with tidyr::pivot_wider() keyed on stat_name for a wide table.

When team_detail = TRUE (the default) the ESPN team catalog (espn_cfb_teams()) is fetched once and friendly team fields are joined in next to the team_id column – team_name, team_abbreviation, team_location, team_display_name, team_short_display_name, team_nickname, team_color, team_alternate_color, team_logo_href, and team_logo_dark_href, inserted immediately after team_id. A catalog failure degrades to NA rather than erroring the wrapper. Set team_detail = FALSE to skip the catalog fetch and the join.

Value

A data frame with one row per record-stat:

col_name types description
season integer Season (4-digit year).
season_type integer ESPN season type (2 = regular, 3 = postseason).
team_id character ESPN team id.
team_name character Team nickname; team_detail = TRUE only.
team_abbreviation character Team abbreviation; team_detail = TRUE only.
team_location character Team location / school name; team_detail = TRUE only.
team_display_name character Full team display name; team_detail = TRUE only.
team_short_display_name character Short team display name; team_detail = TRUE only.
team_nickname character Team nickname label; team_detail = TRUE only.
team_color character Primary team color; team_detail = TRUE only.
team_alternate_color character Alternate team color; team_detail = TRUE only.
team_logo_href character Default team logo URL; team_detail = TRUE only.
team_logo_dark_href character Dark-variant team logo URL; team_detail = TRUE only.
record_type character Record type code (e.g. total, homerecord).
record_name character Record display name (e.g. overall, Home).
record_summary character Win-loss summary string (e.g. 13-1).
stat_name character Stat key (e.g. wins, avgPointsFor).
stat_value numeric Numeric stat value.
stat_display character Display-formatted stat value.

See Also

Other ESPN CFB Functions: espn_cfb_award(), espn_cfb_awards(), espn_cfb_clear_cache(), espn_cfb_coach(), espn_cfb_coach_record(), espn_cfb_coaches(), espn_cfb_franchise(), espn_cfb_franchises(), espn_cfb_futures(), espn_cfb_game_broadcasts(), espn_cfb_game_drive_plays(), espn_cfb_game_drives(), espn_cfb_game_leaders(), espn_cfb_game_odds(), espn_cfb_game_pbp(), espn_cfb_game_play(), espn_cfb_game_player_box(), espn_cfb_game_player_statistics(), espn_cfb_game_powerindex(), espn_cfb_game_predictor(), espn_cfb_game_probabilities(), espn_cfb_game_situation(), espn_cfb_game_status(), espn_cfb_game_team_leaders(), espn_cfb_game_team_linescores(), espn_cfb_game_team_records(), espn_cfb_game_team_roster(), espn_cfb_game_team_statistics(), espn_cfb_game_teams(), espn_cfb_groups(), espn_cfb_pbp_v2(), espn_cfb_player(), espn_cfb_player_career_stats(), espn_cfb_player_eventlog(), espn_cfb_player_gamelog(), espn_cfb_player_overview(), espn_cfb_player_seasons(), espn_cfb_player_splits(), espn_cfb_player_stats_v3(), espn_cfb_players(), espn_cfb_position(), espn_cfb_positions(), espn_cfb_powerindex(), espn_cfb_qbr(), espn_cfb_rankings(), espn_cfb_recruits(), espn_cfb_season_info(), espn_cfb_season_types(), espn_cfb_season_weeks(), espn_cfb_seasons(), espn_cfb_standings(), espn_cfb_team(), espn_cfb_team_ats(), espn_cfb_team_awards(), espn_cfb_team_coaches(), espn_cfb_team_events(), espn_cfb_team_leaders(), espn_cfb_team_powerindex(), espn_cfb_team_ranks(), espn_cfb_team_roster(), espn_cfb_team_schedule(), espn_cfb_teams(), espn_cfb_unnest_plays(), espn_cfb_venue(), espn_cfb_venues(), espn_cfb_week_rankings()

Examples


  try(espn_cfb_team_record(team_id = 61, year = 2024))
  try(espn_cfb_team_record(team_id = 61, year = 2024,
                           team_detail = FALSE))

ESPN College Football Team Roster (Season-Scoped)

Description

Get the season roster for a single college football team – one row per athlete with biographical detail, position, jersey number, and class/experience.

Usage

espn_cfb_team_roster(
  team_id = NULL,
  year = NULL,
  position_detail = TRUE,
  team_detail = TRUE
)

Arguments

team_id

(Integer required): ESPN team id.

year

(Integer required): Season, 4 digit format (YYYY).
Minimum value accepted: 2004

position_detail

(Logical): when TRUE (default), fetch the ESPN position catalog once and join it onto position_id, appending the five ⁠position_*⁠ detail columns shown in the Value table. A catalog failure degrades to NA rather than erroring the wrapper. Set FALSE to skip the extra fetch and the join.

team_detail

(Logical): when TRUE (default), fetch the ESPN team catalog once and join friendly team fields next to the team_id column (see Details). Set FALSE to skip the catalog fetch and the join.

Details

Wraps the ESPN core-v2 season athlete index sports.core.api.espn.com/v2/sports/football/leagues/college-football/seasons/{year}/teams/{team_id}/athletes. The index returns one ⁠$ref⁠ per athlete; this wrapper dereferences each athlete resource and flattens it into a row. The site-v2 roster endpoint is deliberately not used: it returns only the team's current roster and silently ignores a season query parameter, so it cannot deliver historical rosters. The core-v2 path used here is genuinely season-scoped.

Because each athlete is dereferenced individually, a full roster is roughly 150-220 HTTP requests; allow a few seconds per call.

When team_detail = TRUE (the default) the ESPN team catalog (espn_cfb_teams()) is fetched once and friendly team fields are joined in next to the team_id column – team_name, team_abbreviation, team_location, team_display_name, team_short_display_name, team_nickname, team_color, team_alternate_color, team_logo_href, and team_logo_dark_href, inserted immediately after team_id. A catalog failure degrades to NA rather than erroring the wrapper. Set team_detail = FALSE to skip the catalog fetch and the join.

When position_detail = TRUE (the default) the ESPN position catalog (espn_cfb_positions()) is fetched once and joined onto the position_id column, appending the five ⁠position_*⁠ detail columns (position_name, position_display_name, position_abbreviation, position_leaf, position_parent_id). A catalog failure degrades to NA rather than erroring the wrapper. Set position_detail = FALSE to skip the extra fetch and the join.

Value

A data frame with one row per athlete:

col_name types description
season integer Season (4-digit year).
team_id character ESPN team id.
team_name character Team nickname; team_detail = TRUE only.
team_abbreviation character Team abbreviation; team_detail = TRUE only.
team_location character Team location / school name; team_detail = TRUE only.
team_display_name character Full team display name; team_detail = TRUE only.
team_short_display_name character Short team display name; team_detail = TRUE only.
team_nickname character Team nickname label; team_detail = TRUE only.
team_color character Primary team color; team_detail = TRUE only.
team_alternate_color character Alternate team color; team_detail = TRUE only.
team_logo_href character Default team logo URL; team_detail = TRUE only.
team_logo_dark_href character Dark-variant team logo URL; team_detail = TRUE only.
athlete_id character ESPN athlete id.
first_name character Athlete first name.
last_name character Athlete last name.
full_name character Athlete full name.
display_name character Athlete display name.
jersey character Jersey number.
position character Position display name.
position_abbr character Position abbreviation.
height numeric Height in inches.
display_height character Human-readable height (e.g. ⁠6' 1"⁠).
weight numeric Weight in pounds.
display_weight character Human-readable weight (e.g. ⁠205 lbs⁠).
experience integer Years of experience.
class character Class / experience label (e.g. Junior).
birth_city character Birth city.
birth_state character Birth state.
birth_country character Birth country.
status character Athlete status (e.g. Active).
active logical Whether the athlete is active.
headshot_href character URL of the athlete headshot image.
position_id character ESPN position id; position_detail = TRUE only.
position_name character Position name (e.g. Quarterback); position_detail = TRUE only.
position_display_name character Human-readable position name; position_detail = TRUE only.
position_abbreviation character Position abbreviation (e.g. QB); position_detail = TRUE only.
position_leaf logical TRUE for a most-specific (leaf) position; position_detail = TRUE only.
position_parent_id character ESPN id of the parent position; position_detail = TRUE only.

See Also

Other ESPN CFB Functions: espn_cfb_award(), espn_cfb_awards(), espn_cfb_clear_cache(), espn_cfb_coach(), espn_cfb_coach_record(), espn_cfb_coaches(), espn_cfb_franchise(), espn_cfb_franchises(), espn_cfb_futures(), espn_cfb_game_broadcasts(), espn_cfb_game_drive_plays(), espn_cfb_game_drives(), espn_cfb_game_leaders(), espn_cfb_game_odds(), espn_cfb_game_pbp(), espn_cfb_game_play(), espn_cfb_game_player_box(), espn_cfb_game_player_statistics(), espn_cfb_game_powerindex(), espn_cfb_game_predictor(), espn_cfb_game_probabilities(), espn_cfb_game_situation(), espn_cfb_game_status(), espn_cfb_game_team_leaders(), espn_cfb_game_team_linescores(), espn_cfb_game_team_records(), espn_cfb_game_team_roster(), espn_cfb_game_team_statistics(), espn_cfb_game_teams(), espn_cfb_groups(), espn_cfb_pbp_v2(), espn_cfb_player(), espn_cfb_player_career_stats(), espn_cfb_player_eventlog(), espn_cfb_player_gamelog(), espn_cfb_player_overview(), espn_cfb_player_seasons(), espn_cfb_player_splits(), espn_cfb_player_stats_v3(), espn_cfb_players(), espn_cfb_position(), espn_cfb_positions(), espn_cfb_powerindex(), espn_cfb_qbr(), espn_cfb_rankings(), espn_cfb_recruits(), espn_cfb_season_info(), espn_cfb_season_types(), espn_cfb_season_weeks(), espn_cfb_seasons(), espn_cfb_standings(), espn_cfb_team(), espn_cfb_team_ats(), espn_cfb_team_awards(), espn_cfb_team_coaches(), espn_cfb_team_events(), espn_cfb_team_leaders(), espn_cfb_team_powerindex(), espn_cfb_team_ranks(), espn_cfb_team_record(), espn_cfb_team_schedule(), espn_cfb_teams(), espn_cfb_unnest_plays(), espn_cfb_venue(), espn_cfb_venues(), espn_cfb_week_rankings()

Examples


  try(espn_cfb_team_roster(team_id = 61, year = 2024))
  try(espn_cfb_team_roster(team_id = 61, year = 2024,
                           position_detail = FALSE))
  try(espn_cfb_team_roster(team_id = 61, year = 2024,
                           team_detail = FALSE))

ESPN College Football Team Schedule

Description

Get a single college football team's full-season schedule – one row per game with opponent, venue, broadcast, score, and result.

Usage

espn_cfb_team_schedule(team_id = NULL, year = NULL, team_detail = TRUE)

Arguments

team_id

(Integer required): ESPN team id.

year

(Integer required): Season, 4 digit format (YYYY).
Minimum value accepted: 1999

team_detail

(Logical): when TRUE (default), fetch the ESPN team catalog once and join friendly team fields next to every team-id column (team_id, opponent_id) in the output (see Details). Set FALSE to skip the catalog fetch and the join.

Details

Wraps the ESPN site-v2 team schedule endpoint site.api.espn.com/apis/site/v2/sports/football/college-football/teams/{team_id}/schedule. Each row is one scheduled game from the requested team's perspective: the ⁠opponent_*⁠ columns describe the other team, and team_score / opponent_score / team_winner describe the outcome (scores are NA for games that have not been played). Team ids are ESPN team identifiers – enumerate them with espn_cfb_teams().

When team_detail = TRUE (the default) the ESPN team catalog (espn_cfb_teams()) is fetched once and friendly team fields are joined onto every team-id column the output carries – team_id and opponent_id. For each id column X_id the friendly siblings X_name, X_abbreviation, X_location, X_display_name, X_short_display_name, X_nickname, X_color, X_alternate_color, X_logo_href, and X_logo_dark_href are inserted immediately after it. A catalog failure degrades to NA rather than erroring the wrapper. Set team_detail = FALSE to skip the catalog fetch and the join.

Value

A data frame with one row per scheduled game:

col_name types description
season integer Season (4-digit year).
team_id character ESPN team id queried.
team_name character Team nickname; team_detail = TRUE only.
team_abbreviation character Team abbreviation; team_detail = TRUE only.
team_location character Team location / school name; team_detail = TRUE only.
team_display_name character Full team display name; team_detail = TRUE only.
team_short_display_name character Short team display name; team_detail = TRUE only.
team_nickname character Team nickname label; team_detail = TRUE only.
team_color character Primary team color; team_detail = TRUE only.
team_alternate_color character Alternate team color; team_detail = TRUE only.
team_logo_href character Default team logo URL; team_detail = TRUE only.
team_logo_dark_href character Dark-variant team logo URL; team_detail = TRUE only.
game_id character ESPN event id.
game_date character Kickoff date-time (ISO 8601, UTC).
game_name character Full event name.
game_short_name character Short event name (e.g. UTM @ UGA).
season_type integer ESPN season type (2 = regular, 3 = postseason).
week integer Week number.
home_away character Whether the queried team is home or away.
team_score numeric Points scored by the queried team.
team_winner logical Whether the queried team won.
opponent_id character ESPN team id of the opponent.
opponent_team_name character Opponent team nickname; team_detail = TRUE only.
opponent_team_abbreviation character Opponent team abbreviation; team_detail = TRUE only.
opponent_team_location character Opponent team location / school; team_detail = TRUE only.
opponent_team_display_name character Opponent team full display name; team_detail = TRUE only.
opponent_team_short_display_name character Opponent team short display name; team_detail = TRUE only.
opponent_team_nickname character Opponent team nickname label; team_detail = TRUE only.
opponent_team_color character Opponent team primary color; team_detail = TRUE only.
opponent_team_alternate_color character Opponent team alternate color; team_detail = TRUE only.
opponent_team_logo_href character Opponent team default logo URL; team_detail = TRUE only.
opponent_team_logo_dark_href character Opponent team dark logo URL; team_detail = TRUE only.
opponent_name character Opponent display name.
opponent_abbr character Opponent abbreviation.
opponent_score numeric Points scored by the opponent.
neutral_site logical Whether the game is at a neutral site.
venue_name character Venue name.
venue_city character Venue city.
venue_state character Venue state.
attendance integer Reported attendance.
broadcast character Broadcast network short name.
status character Game status detail (e.g. Final).
completed logical Whether the game is completed.

See Also

Other ESPN CFB Functions: espn_cfb_award(), espn_cfb_awards(), espn_cfb_clear_cache(), espn_cfb_coach(), espn_cfb_coach_record(), espn_cfb_coaches(), espn_cfb_franchise(), espn_cfb_franchises(), espn_cfb_futures(), espn_cfb_game_broadcasts(), espn_cfb_game_drive_plays(), espn_cfb_game_drives(), espn_cfb_game_leaders(), espn_cfb_game_odds(), espn_cfb_game_pbp(), espn_cfb_game_play(), espn_cfb_game_player_box(), espn_cfb_game_player_statistics(), espn_cfb_game_powerindex(), espn_cfb_game_predictor(), espn_cfb_game_probabilities(), espn_cfb_game_situation(), espn_cfb_game_status(), espn_cfb_game_team_leaders(), espn_cfb_game_team_linescores(), espn_cfb_game_team_records(), espn_cfb_game_team_roster(), espn_cfb_game_team_statistics(), espn_cfb_game_teams(), espn_cfb_groups(), espn_cfb_pbp_v2(), espn_cfb_player(), espn_cfb_player_career_stats(), espn_cfb_player_eventlog(), espn_cfb_player_gamelog(), espn_cfb_player_overview(), espn_cfb_player_seasons(), espn_cfb_player_splits(), espn_cfb_player_stats_v3(), espn_cfb_players(), espn_cfb_position(), espn_cfb_positions(), espn_cfb_powerindex(), espn_cfb_qbr(), espn_cfb_rankings(), espn_cfb_recruits(), espn_cfb_season_info(), espn_cfb_season_types(), espn_cfb_season_weeks(), espn_cfb_seasons(), espn_cfb_standings(), espn_cfb_team(), espn_cfb_team_ats(), espn_cfb_team_awards(), espn_cfb_team_coaches(), espn_cfb_team_events(), espn_cfb_team_leaders(), espn_cfb_team_powerindex(), espn_cfb_team_ranks(), espn_cfb_team_record(), espn_cfb_team_roster(), espn_cfb_teams(), espn_cfb_unnest_plays(), espn_cfb_venue(), espn_cfb_venues(), espn_cfb_week_rankings()

Examples


  try(espn_cfb_team_schedule(team_id = 61, year = 2024))
  try(espn_cfb_team_schedule(team_id = 61, year = 2024,
                             team_detail = FALSE))

Get ESPN college football team stats data

Description

Get ESPN college football team stats data

Usage

espn_cfb_team_stats(team_id, year, season_type = "regular", total = FALSE)

Arguments

team_id

Team ID

year

Year
Minimum value accepted: 2004

season_type

(character, default: regular): Season type - regular or postseason

total

(boolean, default: FALSE): Totals

Value

Returns a tibble with the following columns:

col_name types
team_id character
team_guid character
team_uid character
team_sdr character
team_slug character
team_location character
team_name character
team_nickname character
team_abbreviation character
team_display_name character
team_short_display_name character
team_color character
team_alternate_color character
is_active logical
is_all_star logical
logo_href character
logo_dark_href character
general_fumbles numeric
general_fumbles_lost numeric
general_fumbles_forced numeric
general_fumbles_recovered numeric
general_fumbles_touchdowns numeric
general_games_played numeric
general_offensive_two_pt_returns numeric
general_offensive_fumbles_touchdowns numeric
general_defensive_fumbles_touchdowns numeric
passing_avg_gain numeric
passing_completion_pct numeric
passing_completions numeric
passing_espnqb_rating numeric
passing_interception_pct numeric
passing_interceptions numeric
passing_long_passing numeric
passing_misc_yards numeric
passing_net_passing_yards numeric
passing_net_passing_yards_per_game numeric
passing_net_total_yards numeric
passing_net_yards_per_game numeric
passing_passing_attempts numeric
passing_passing_big_plays numeric
passing_passing_first_downs numeric
passing_passing_fumbles numeric
passing_passing_fumbles_lost numeric
passing_passing_touchdown_pct numeric
passing_passing_touchdowns numeric
passing_passing_yards numeric
passing_passing_yards_after_catch numeric
passing_passing_yards_at_catch numeric
passing_passing_yards_per_game numeric
passing_qb_rating numeric
passing_sacks numeric
passing_sack_yards_lost numeric
passing_team_games_played numeric
passing_total_offensive_plays numeric
passing_total_points numeric
passing_total_points_per_game numeric
passing_total_touchdowns numeric
passing_total_yards numeric
passing_total_yards_from_scrimmage numeric
passing_two_point_pass_convs numeric
passing_two_pt_pass numeric
passing_two_pt_pass_attempts numeric
passing_yards_from_scrimmage_per_game numeric
passing_yards_per_completion numeric
passing_yards_per_game numeric
passing_yards_per_pass_attempt numeric
passing_net_yards_per_pass_attempt numeric
passing_quarterback_rating numeric
rushing_avg_gain numeric
rushing_espnrb_rating numeric
rushing_long_rushing numeric
rushing_misc_yards numeric
rushing_net_total_yards numeric
rushing_net_yards_per_game numeric
rushing_rushing_attempts numeric
rushing_rushing_big_plays numeric
rushing_rushing_first_downs numeric
rushing_rushing_fumbles numeric
rushing_rushing_fumbles_lost numeric
rushing_rushing_touchdowns numeric
rushing_rushing_yards numeric
rushing_rushing_yards_per_game numeric
rushing_stuffs numeric
rushing_stuff_yards_lost numeric
rushing_team_games_played numeric
rushing_total_offensive_plays numeric
rushing_total_points numeric
rushing_total_points_per_game numeric
rushing_total_touchdowns numeric
rushing_total_yards numeric
rushing_total_yards_from_scrimmage numeric
rushing_two_point_rush_convs numeric
rushing_two_pt_rush numeric
rushing_two_pt_rush_attempts numeric
rushing_yards_from_scrimmage_per_game numeric
rushing_yards_per_game numeric
rushing_yards_per_rush_attempt numeric
receiving_avg_gain numeric
receiving_espnwr_rating numeric
receiving_long_reception numeric
receiving_misc_yards numeric
receiving_net_total_yards numeric
receiving_net_yards_per_game numeric
receiving_receiving_big_plays numeric
receiving_receiving_first_downs numeric
receiving_receiving_fumbles numeric
receiving_receiving_fumbles_lost numeric
receiving_receiving_targets numeric
receiving_receiving_touchdowns numeric
receiving_receiving_yards numeric
receiving_receiving_yards_after_catch numeric
receiving_receiving_yards_at_catch numeric
receiving_receiving_yards_per_game numeric
receiving_receptions numeric
receiving_team_games_played numeric
receiving_total_offensive_plays numeric
receiving_total_points numeric
receiving_total_points_per_game numeric
receiving_total_touchdowns numeric
receiving_total_yards numeric
receiving_total_yards_from_scrimmage numeric
receiving_two_point_rec_convs numeric
receiving_two_pt_reception numeric
receiving_two_pt_reception_attempts numeric
receiving_yards_from_scrimmage_per_game numeric
receiving_yards_per_game numeric
receiving_yards_per_reception numeric
defensive_assist_tackles numeric
defensive_avg_interception_yards numeric
defensive_avg_sack_yards numeric
defensive_avg_stuff_yards numeric
defensive_blocked_field_goal_touchdowns numeric
defensive_blocked_punt_touchdowns numeric
defensive_defensive_touchdowns numeric
defensive_hurries numeric
defensive_kicks_blocked numeric
defensive_long_interception numeric
defensive_misc_touchdowns numeric
defensive_passes_batted_down numeric
defensive_passes_defended numeric
defensive_two_pt_returns numeric
defensive_sacks numeric
defensive_sack_yards numeric
defensive_safeties numeric
defensive_solo_tackles numeric
defensive_stuffs numeric
defensive_stuff_yards numeric
defensive_tackles_for_loss numeric
defensive_team_games_played numeric
defensive_total_tackles numeric
defensive_yards_allowed numeric
defensive_points_allowed numeric
defensive_one_pt_safeties_made numeric
defensive_interceptions_interceptions numeric
defensive_interceptions_interception_touchdowns numeric
defensive_interceptions_interception_yards numeric
kicking_avg_kickoff_return_yards numeric
kicking_avg_kickoff_yards numeric
kicking_extra_point_attempts numeric
kicking_extra_point_pct numeric
kicking_extra_points_blocked numeric
kicking_extra_points_blocked_pct numeric
kicking_extra_points_made numeric
kicking_fair_catches numeric
kicking_fair_catch_pct numeric
kicking_field_goal_attempts numeric
kicking_field_goal_attempts1_19 numeric
kicking_field_goal_attempts20_29 numeric
kicking_field_goal_attempts30_39 numeric
kicking_field_goal_attempts40_49 numeric
kicking_field_goal_attempts50_59 numeric
kicking_field_goal_attempts60_99 numeric
kicking_field_goal_attempts50 numeric
kicking_field_goal_attempt_yards numeric
kicking_field_goal_pct numeric
kicking_field_goals_blocked numeric
kicking_field_goals_blocked_pct numeric
kicking_field_goals_made numeric
kicking_field_goals_made1_19 numeric
kicking_field_goals_made20_29 numeric
kicking_field_goals_made30_39 numeric
kicking_field_goals_made40_49 numeric
kicking_field_goals_made50_59 numeric
kicking_field_goals_made60_99 numeric
kicking_field_goals_made50 numeric
kicking_field_goals_made_yards numeric
kicking_field_goals_missed_yards numeric
kicking_kickoff_returns numeric
kicking_kickoff_return_touchdowns numeric
kicking_kickoff_return_yards numeric
kicking_kickoffs numeric
kicking_kickoff_yards numeric
kicking_long_field_goal_attempt numeric
kicking_long_field_goal_made numeric
kicking_long_kickoff numeric
kicking_team_games_played numeric
kicking_total_kicking_points numeric
kicking_touchback_pct numeric
kicking_touchbacks numeric
returning_def_fumble_returns numeric
returning_def_fumble_return_yards numeric
returning_fumble_recoveries numeric
returning_fumble_recovery_yards numeric
returning_kick_return_fair_catches numeric
returning_kick_return_fair_catch_pct numeric
returning_kick_return_fumbles numeric
returning_kick_return_fumbles_lost numeric
returning_kick_returns numeric
returning_kick_return_touchdowns numeric
returning_kick_return_yards numeric
returning_long_kick_return numeric
returning_long_punt_return numeric
returning_misc_fumble_returns numeric
returning_misc_fumble_return_yards numeric
returning_opp_fumble_recoveries numeric
returning_opp_fumble_recovery_yards numeric
returning_opp_special_team_fumble_returns numeric
returning_opp_special_team_fumble_return_yards numeric
returning_punt_return_fair_catches numeric
returning_punt_return_fair_catch_pct numeric
returning_punt_return_fumbles numeric
returning_punt_return_fumbles_lost numeric
returning_punt_returns numeric
returning_punt_returns_started_inside_the10 numeric
returning_punt_returns_started_inside_the20 numeric
returning_punt_return_touchdowns numeric
returning_punt_return_yards numeric
returning_special_team_fumble_returns numeric
returning_special_team_fumble_return_yards numeric
returning_team_games_played numeric
returning_yards_per_kick_return numeric
returning_yards_per_punt_return numeric
returning_yards_per_return numeric
punting_avg_punt_return_yards numeric
punting_fair_catches numeric
punting_gross_avg_punt_yards numeric
punting_long_punt numeric
punting_net_avg_punt_yards numeric
punting_punt_returns numeric
punting_punt_return_yards numeric
punting_punts numeric
punting_punts_blocked numeric
punting_punts_blocked_pct numeric
punting_punts_inside10 numeric
punting_punts_inside10pct numeric
punting_punts_inside20 numeric
punting_punts_inside20pct numeric
punting_punt_yards numeric
punting_team_games_played numeric
punting_touchback_pct numeric
punting_touchbacks numeric
scoring_defensive_points numeric
scoring_field_goals numeric
scoring_kick_extra_points numeric
scoring_misc_points numeric
scoring_passing_touchdowns numeric
scoring_receiving_touchdowns numeric
scoring_return_touchdowns numeric
scoring_rushing_touchdowns numeric
scoring_total_points numeric
scoring_total_points_per_game numeric
scoring_total_touchdowns numeric
scoring_total_two_point_convs numeric
scoring_two_point_pass_convs numeric
scoring_two_point_rec_convs numeric
scoring_two_point_rush_convs numeric
scoring_one_pt_safeties_made numeric
miscellaneous_first_downs numeric
miscellaneous_first_downs_passing numeric
miscellaneous_first_downs_penalty numeric
miscellaneous_first_downs_per_game numeric
miscellaneous_first_downs_rushing numeric
miscellaneous_fourth_down_attempts numeric
miscellaneous_fourth_down_conv_pct numeric
miscellaneous_fourth_down_convs numeric
miscellaneous_fumbles_lost numeric
miscellaneous_possession_time_seconds numeric
miscellaneous_redzone_efficiency_pct numeric
miscellaneous_redzone_field_goal_pct numeric
miscellaneous_redzone_scoring_pct numeric
miscellaneous_redzone_touchdown_pct numeric
miscellaneous_third_down_attempts numeric
miscellaneous_third_down_conv_pct numeric
miscellaneous_third_down_convs numeric
miscellaneous_total_giveaways numeric
miscellaneous_total_penalties numeric
miscellaneous_total_penalty_yards numeric
miscellaneous_total_takeaways numeric
miscellaneous_total_drives numeric
miscellaneous_turn_over_differential numeric

Author(s)

Saiem Gilani

Examples


  try(espn_cfb_team_stats(team_id = 52, year = 2020))

ESPN College Football Teams Index

Description

Get the full ESPN directory of college football teams – one row per team with identifiers, branding, conference grouping, and logo URLs.

Usage

espn_cfb_teams()

Details

Wraps the ESPN site-v2 expanded teams endpoint site.api.espn.com/apis/site/v2/sports/football/college-football/teams. The expanded endpoint returns every team fully inlined in a single call (no ⁠$ref⁠ dereferencing), so one request produces the whole directory. The team_id column is the ESPN team identifier used as the team_id argument to the other ⁠espn_cfb_team_*()⁠ wrappers.

Value

A data frame with one row per team:

col_name types description
team_id character ESPN team id.
uid character ESPN global unique identifier.
slug character URL slug for the team.
abbreviation character Team abbreviation.
display_name character Full team display name.
short_display_name character Short team display name.
name character Team nickname (e.g. Bulldogs).
nickname character Team nickname / location label.
location character Team location / school name.
color character Primary team color (hex, no ⁠#⁠).
alternate_color character Alternate team color (hex, no ⁠#⁠).
is_active logical Whether the team is currently active.
is_all_star logical Whether the team is an all-star team.
logo_href character URL of the default team logo.
logo_dark_href character URL of the dark-variant team logo.

See Also

Other ESPN CFB Functions: espn_cfb_award(), espn_cfb_awards(), espn_cfb_clear_cache(), espn_cfb_coach(), espn_cfb_coach_record(), espn_cfb_coaches(), espn_cfb_franchise(), espn_cfb_franchises(), espn_cfb_futures(), espn_cfb_game_broadcasts(), espn_cfb_game_drive_plays(), espn_cfb_game_drives(), espn_cfb_game_leaders(), espn_cfb_game_odds(), espn_cfb_game_pbp(), espn_cfb_game_play(), espn_cfb_game_player_box(), espn_cfb_game_player_statistics(), espn_cfb_game_powerindex(), espn_cfb_game_predictor(), espn_cfb_game_probabilities(), espn_cfb_game_situation(), espn_cfb_game_status(), espn_cfb_game_team_leaders(), espn_cfb_game_team_linescores(), espn_cfb_game_team_records(), espn_cfb_game_team_roster(), espn_cfb_game_team_statistics(), espn_cfb_game_teams(), espn_cfb_groups(), espn_cfb_pbp_v2(), espn_cfb_player(), espn_cfb_player_career_stats(), espn_cfb_player_eventlog(), espn_cfb_player_gamelog(), espn_cfb_player_overview(), espn_cfb_player_seasons(), espn_cfb_player_splits(), espn_cfb_player_stats_v3(), espn_cfb_players(), espn_cfb_position(), espn_cfb_positions(), espn_cfb_powerindex(), espn_cfb_qbr(), espn_cfb_rankings(), espn_cfb_recruits(), espn_cfb_season_info(), espn_cfb_season_types(), espn_cfb_season_weeks(), espn_cfb_seasons(), espn_cfb_standings(), espn_cfb_team(), espn_cfb_team_ats(), espn_cfb_team_awards(), espn_cfb_team_coaches(), espn_cfb_team_events(), espn_cfb_team_leaders(), espn_cfb_team_powerindex(), espn_cfb_team_ranks(), espn_cfb_team_record(), espn_cfb_team_roster(), espn_cfb_team_schedule(), espn_cfb_unnest_plays(), espn_cfb_venue(), espn_cfb_venues(), espn_cfb_week_rankings()

Examples


  try(espn_cfb_teams())

Unnest ESPN CFB drive plays into a flat play-by-play table

Description

Turn a espn_cfb_game_drives() result carrying a plays list-column (produced with plays = "list") into the flat one-row-per-play table – every play in the full espn_cfb_game_pbp() schema with its drive-level columns carried alongside, prefixed drive_.

Usage

espn_cfb_unnest_plays(drives)

Arguments

drives

(data.frame required): a data frame produced by espn_cfb_game_drives(..., plays = "list") – i.e. carrying a plays list-column of full-schema play tibbles.

Details

Pure transform – no HTTP. espn_cfb_unnest_plays() unnests the plays list-column appended by espn_cfb_game_drives(..., plays = "list") and carries every drive-level column alongside each play, prefixed drive_ (e.g. drive_id, drive_result, drive_yards, drive_start_yard_line) so it never collides with the play's own columns. The result is identical in shape to espn_cfb_game_drives(..., plays = "expand") – the same flat table, one route via the plays argument, the other via this auxiliary function.

If drives does not carry a plays list-column the function aborts with a message telling the caller to run espn_cfb_game_drives(..., plays = "list") first.

Value

A data frame with one row per play:

col_name types description
drive_game_id character ESPN game identifier (drive-level column, drive_-prefixed).
drive_id character ESPN drive id the play belongs to (drive_-prefixed).
drive_result character Drive result code (drive_-prefixed; every drive-level column is carried with this prefix).
game_id character ESPN game identifier (play-level column).
play_id character ESPN play id.
... Every remaining espn_cfb_game_pbp() play column, plus any optional participant columns present in the embedded tibbles.

See Also

Other ESPN CFB Functions: espn_cfb_award(), espn_cfb_awards(), espn_cfb_clear_cache(), espn_cfb_coach(), espn_cfb_coach_record(), espn_cfb_coaches(), espn_cfb_franchise(), espn_cfb_franchises(), espn_cfb_futures(), espn_cfb_game_broadcasts(), espn_cfb_game_drive_plays(), espn_cfb_game_drives(), espn_cfb_game_leaders(), espn_cfb_game_odds(), espn_cfb_game_pbp(), espn_cfb_game_play(), espn_cfb_game_player_box(), espn_cfb_game_player_statistics(), espn_cfb_game_powerindex(), espn_cfb_game_predictor(), espn_cfb_game_probabilities(), espn_cfb_game_situation(), espn_cfb_game_status(), espn_cfb_game_team_leaders(), espn_cfb_game_team_linescores(), espn_cfb_game_team_records(), espn_cfb_game_team_roster(), espn_cfb_game_team_statistics(), espn_cfb_game_teams(), espn_cfb_groups(), espn_cfb_pbp_v2(), espn_cfb_player(), espn_cfb_player_career_stats(), espn_cfb_player_eventlog(), espn_cfb_player_gamelog(), espn_cfb_player_overview(), espn_cfb_player_seasons(), espn_cfb_player_splits(), espn_cfb_player_stats_v3(), espn_cfb_players(), espn_cfb_position(), espn_cfb_positions(), espn_cfb_powerindex(), espn_cfb_qbr(), espn_cfb_rankings(), espn_cfb_recruits(), espn_cfb_season_info(), espn_cfb_season_types(), espn_cfb_season_weeks(), espn_cfb_seasons(), espn_cfb_standings(), espn_cfb_team(), espn_cfb_team_ats(), espn_cfb_team_awards(), espn_cfb_team_coaches(), espn_cfb_team_events(), espn_cfb_team_leaders(), espn_cfb_team_powerindex(), espn_cfb_team_ranks(), espn_cfb_team_record(), espn_cfb_team_roster(), espn_cfb_team_schedule(), espn_cfb_teams(), espn_cfb_venue(), espn_cfb_venues(), espn_cfb_week_rankings()

Examples


  try(espn_cfb_unnest_plays(espn_cfb_game_drives(401628339,
                                                 plays = "list")))

ESPN College Football Venue Detail

Description

Get the ESPN core-v2 detail record for a single college football venue – full name, address, playing-surface and indoor flags.

Usage

espn_cfb_venue(venue_id = NULL)

Arguments

venue_id

(Integer required): ESPN venue id.

Details

Wraps the ESPN core-v2 endpoint sports.core.api.espn.com/v2/sports/football/leagues/college-football/venues/{venue_id}. espn_cfb_venues() returns the venue index; this wrapper returns the single-venue detail for one id. Returns a single-row tibble. Enumerate venue_ids with espn_cfb_venues().

Value

A single-row data frame:

col_name types description
venue_id character ESPN venue id.
full_name character Venue full name (e.g. ⁠Tenney Stadium⁠).
city character Venue city.
state character Venue state.
zip_code character Venue postal code.
country character Venue country.
grass logical TRUE if the playing surface is grass.
indoor logical TRUE if the venue is indoors.
venue_ref character ⁠$ref⁠ URL to the venue resource.

See Also

Other ESPN CFB Functions: espn_cfb_award(), espn_cfb_awards(), espn_cfb_clear_cache(), espn_cfb_coach(), espn_cfb_coach_record(), espn_cfb_coaches(), espn_cfb_franchise(), espn_cfb_franchises(), espn_cfb_futures(), espn_cfb_game_broadcasts(), espn_cfb_game_drive_plays(), espn_cfb_game_drives(), espn_cfb_game_leaders(), espn_cfb_game_odds(), espn_cfb_game_pbp(), espn_cfb_game_play(), espn_cfb_game_player_box(), espn_cfb_game_player_statistics(), espn_cfb_game_powerindex(), espn_cfb_game_predictor(), espn_cfb_game_probabilities(), espn_cfb_game_situation(), espn_cfb_game_status(), espn_cfb_game_team_leaders(), espn_cfb_game_team_linescores(), espn_cfb_game_team_records(), espn_cfb_game_team_roster(), espn_cfb_game_team_statistics(), espn_cfb_game_teams(), espn_cfb_groups(), espn_cfb_pbp_v2(), espn_cfb_player(), espn_cfb_player_career_stats(), espn_cfb_player_eventlog(), espn_cfb_player_gamelog(), espn_cfb_player_overview(), espn_cfb_player_seasons(), espn_cfb_player_splits(), espn_cfb_player_stats_v3(), espn_cfb_players(), espn_cfb_position(), espn_cfb_positions(), espn_cfb_powerindex(), espn_cfb_qbr(), espn_cfb_rankings(), espn_cfb_recruits(), espn_cfb_season_info(), espn_cfb_season_types(), espn_cfb_season_weeks(), espn_cfb_seasons(), espn_cfb_standings(), espn_cfb_team(), espn_cfb_team_ats(), espn_cfb_team_awards(), espn_cfb_team_coaches(), espn_cfb_team_events(), espn_cfb_team_leaders(), espn_cfb_team_powerindex(), espn_cfb_team_ranks(), espn_cfb_team_record(), espn_cfb_team_roster(), espn_cfb_team_schedule(), espn_cfb_teams(), espn_cfb_unnest_plays(), espn_cfb_venues(), espn_cfb_week_rankings()

Examples


  try(espn_cfb_venue(venue_id = 3785))

ESPN College Football Venues Index

Description

Get the catalog of stadiums and venues ESPN tracks for college football, with location, capacity-related flags, and addresses.

Usage

espn_cfb_venues(max_results = 200)

Arguments

max_results

(Integer default 200): Maximum number of venues to dereference and return.

Details

Wraps the ESPN core-v2 endpoint sports.core.api.espn.com/v2/sports/football/leagues/college-football/venues. The index is ⁠$ref⁠-paginated and large (~911 venues). Dereferencing every venue is hundreds of HTTP calls, so this wrapper caps the walk at max_results venues (default 200) – raise it to pull more, or set it high enough to harvest the whole catalog in one (slow) call. Pages are walked in id order, so the same max_results always returns the same prefix of the catalog.

Value

A data frame with one row per venue:

col_name types description
venue_id character ESPN venue id.
full_name character Venue full name (e.g. ⁠Tenney Stadium⁠).
city character Venue city.
state character Venue state.
zip_code character Venue postal code.
country character Venue country.
grass logical TRUE if the playing surface is grass.
indoor logical TRUE if the venue is indoors.
venue_ref character ⁠$ref⁠ URL to the venue resource.

See Also

Other ESPN CFB Functions: espn_cfb_award(), espn_cfb_awards(), espn_cfb_clear_cache(), espn_cfb_coach(), espn_cfb_coach_record(), espn_cfb_coaches(), espn_cfb_franchise(), espn_cfb_franchises(), espn_cfb_futures(), espn_cfb_game_broadcasts(), espn_cfb_game_drive_plays(), espn_cfb_game_drives(), espn_cfb_game_leaders(), espn_cfb_game_odds(), espn_cfb_game_pbp(), espn_cfb_game_play(), espn_cfb_game_player_box(), espn_cfb_game_player_statistics(), espn_cfb_game_powerindex(), espn_cfb_game_predictor(), espn_cfb_game_probabilities(), espn_cfb_game_situation(), espn_cfb_game_status(), espn_cfb_game_team_leaders(), espn_cfb_game_team_linescores(), espn_cfb_game_team_records(), espn_cfb_game_team_roster(), espn_cfb_game_team_statistics(), espn_cfb_game_teams(), espn_cfb_groups(), espn_cfb_pbp_v2(), espn_cfb_player(), espn_cfb_player_career_stats(), espn_cfb_player_eventlog(), espn_cfb_player_gamelog(), espn_cfb_player_overview(), espn_cfb_player_seasons(), espn_cfb_player_splits(), espn_cfb_player_stats_v3(), espn_cfb_players(), espn_cfb_position(), espn_cfb_positions(), espn_cfb_powerindex(), espn_cfb_qbr(), espn_cfb_rankings(), espn_cfb_recruits(), espn_cfb_season_info(), espn_cfb_season_types(), espn_cfb_season_weeks(), espn_cfb_seasons(), espn_cfb_standings(), espn_cfb_team(), espn_cfb_team_ats(), espn_cfb_team_awards(), espn_cfb_team_coaches(), espn_cfb_team_events(), espn_cfb_team_leaders(), espn_cfb_team_powerindex(), espn_cfb_team_ranks(), espn_cfb_team_record(), espn_cfb_team_roster(), espn_cfb_team_schedule(), espn_cfb_teams(), espn_cfb_unnest_plays(), espn_cfb_venue(), espn_cfb_week_rankings()

Examples


  try(espn_cfb_venues(max_results = 50))

ESPN College Football Weekly Rankings

Description

Get the ranked teams from every poll ESPN published in a single week of a college football season – the AP Top 25, the Coaches Poll, the CFP committee rankings, and the computer polls, with each team's rank, points, and first-place votes.

Usage

espn_cfb_week_rankings(
  year = NULL,
  week = NULL,
  season_type = 2,
  team_detail = TRUE
)

Arguments

year

(Integer required): Season, 4 digit format (YYYY).
Minimum value accepted: 2002

week

(Integer required): Week number within the season type.

season_type

(Integer default 2): ESPN season type id. 2 = regular season, 3 = postseason.

team_detail

(Logical): when TRUE (default), fetch the ESPN team catalog once and join friendly team fields next to the team_id column (see Details). Set FALSE to skip the catalog fetch and the join.

Details

Wraps the ESPN core-v2 endpoint sports.core.api.espn.com/v2/sports/football/leagues/college-football/seasons/{year}/types/{season_type}/weeks/{week}/rankings. The week index returns one ⁠$ref⁠ per poll; this wrapper dereferences each poll and returns one row per (poll x ranked team). Both the top-25 ranked teams (rank_type = "ranked") and the receiving-votes teams ESPN lists below the cutoff (rank_type = "others") are included.

When team_detail = TRUE (the default) the ESPN team catalog (espn_cfb_teams()) is fetched once and friendly team fields are joined in next to the team_id column – team_name, team_abbreviation, team_location, team_display_name, team_short_display_name, team_nickname, team_color, team_alternate_color, team_logo_href, and team_logo_dark_href, inserted immediately after team_id. A catalog failure degrades to NA rather than erroring the wrapper. Set team_detail = FALSE to skip the catalog fetch and the join; teams are then returned as ESPN team ids only.

Value

A data frame with one row per poll-team:

col_name types description
season integer Season (4-digit year).
season_type integer ESPN season type id queried.
week integer Week number queried.
ranking_id character ESPN poll id.
ranking_name character Poll name (e.g. ⁠AP Top 25⁠).
ranking_type character Poll type code (e.g. ap, coaches, cfp).
occurrence character Poll occurrence label (e.g. ⁠Week 8⁠, Preseason).
rank_type character ranked for ranked teams, others for receiving-votes teams.
current_rank integer Current rank (0 for receiving-votes teams).
previous_rank integer Rank in the previous poll (0 if unranked).
points numeric Poll points awarded to the team.
first_place_votes integer Number of first-place votes received.
trend character Movement vs the previous poll (e.g. -, +3).
record_summary character Team record at the time of the poll (e.g. 7-1).
team_id character ESPN team id (parsed from team_ref).
team_name character Team nickname; team_detail = TRUE only.
team_abbreviation character Team abbreviation; team_detail = TRUE only.
team_location character Team location / school name; team_detail = TRUE only.
team_display_name character Full team display name; team_detail = TRUE only.
team_short_display_name character Short team display name; team_detail = TRUE only.
team_nickname character Team nickname label; team_detail = TRUE only.
team_color character Primary team color; team_detail = TRUE only.
team_alternate_color character Alternate team color; team_detail = TRUE only.
team_logo_href character Default team logo URL; team_detail = TRUE only.
team_logo_dark_href character Dark-variant team logo URL; team_detail = TRUE only.
team_ref character ⁠$ref⁠ URL to the per-season team resource.

See Also

Other ESPN CFB Functions: espn_cfb_award(), espn_cfb_awards(), espn_cfb_clear_cache(), espn_cfb_coach(), espn_cfb_coach_record(), espn_cfb_coaches(), espn_cfb_franchise(), espn_cfb_franchises(), espn_cfb_futures(), espn_cfb_game_broadcasts(), espn_cfb_game_drive_plays(), espn_cfb_game_drives(), espn_cfb_game_leaders(), espn_cfb_game_odds(), espn_cfb_game_pbp(), espn_cfb_game_play(), espn_cfb_game_player_box(), espn_cfb_game_player_statistics(), espn_cfb_game_powerindex(), espn_cfb_game_predictor(), espn_cfb_game_probabilities(), espn_cfb_game_situation(), espn_cfb_game_status(), espn_cfb_game_team_leaders(), espn_cfb_game_team_linescores(), espn_cfb_game_team_records(), espn_cfb_game_team_roster(), espn_cfb_game_team_statistics(), espn_cfb_game_teams(), espn_cfb_groups(), espn_cfb_pbp_v2(), espn_cfb_player(), espn_cfb_player_career_stats(), espn_cfb_player_eventlog(), espn_cfb_player_gamelog(), espn_cfb_player_overview(), espn_cfb_player_seasons(), espn_cfb_player_splits(), espn_cfb_player_stats_v3(), espn_cfb_players(), espn_cfb_position(), espn_cfb_positions(), espn_cfb_powerindex(), espn_cfb_qbr(), espn_cfb_rankings(), espn_cfb_recruits(), espn_cfb_season_info(), espn_cfb_season_types(), espn_cfb_season_weeks(), espn_cfb_seasons(), espn_cfb_standings(), espn_cfb_team(), espn_cfb_team_ats(), espn_cfb_team_awards(), espn_cfb_team_coaches(), espn_cfb_team_events(), espn_cfb_team_leaders(), espn_cfb_team_powerindex(), espn_cfb_team_ranks(), espn_cfb_team_record(), espn_cfb_team_roster(), espn_cfb_team_schedule(), espn_cfb_teams(), espn_cfb_unnest_plays(), espn_cfb_venue(), espn_cfb_venues()

Examples


  try(espn_cfb_week_rankings(year = 2024, week = 8))
  try(espn_cfb_week_rankings(year = 2024, week = 8, team_detail = FALSE))

ESPN Metrics

Description

ESPN Metrics

Get win probability chart data from ESPN Graciously contributed by MrCaseB:

Usage

espn_metrics_wp(game_id)

Arguments

game_id

(Integer required): Game ID filter for querying a single game Can be found using the cfbd_game_info() function

Value

espn_metrics_wp() - A data frame with 5 variables:

Examples


  try(espn_metrics_wp(game_id = 401628369))

ESPN FPI Ratings

Description

Get FPI historical rating data (most recent of each year)

Usage

espn_ratings_fpi(year = 2019)

Arguments

year

Year
Minimum value accepted: 2004

Details

Adapted from sabinanalytic's fork of the cfbfastR repo

Value

A data frame with 20 variables:

Examples


  try(espn_ratings_fpi(year=2019))

Get Fox Sports college football boxscore

Description

Flattens the per-team stat tables embedded in Bifrost event/{id}/data (boxscore) into one tidy, long player-stat tibble.

Usage

fox_cfb_boxscore(game_id)

Arguments

game_id

(character/numeric, required): Fox Bifrost event id (e.g. "41616").

Value

A cfbfastR-tagged tibble with one row per (player, stat):

Examples


  try(fox_cfb_boxscore(game_id = "41616"))

Get Fox Sports college football statistical leaders

Description

Flattens a Bifrost league/stats-con/{who}/{category}/{page} leaderboard table.

Usage

fox_cfb_league_leaders(
  category = "passing",
  who = "player",
  page = 0,
  group_id = "2"
)

Arguments

category

(character): Stat category. One of passing, rushing, receiving, defense, kicking, returning, scoring, yardage (team adds downs, turnovers). Defaults to "passing".

who

(character): "player" or "team". Defaults to "player".

page

(integer): 0-based page index. Defaults to 0.

group_id

(character): Conference/group filter id. Defaults to "2" (FBS).

Value

A cfbfastR-tagged tibble with one row per player/team; columns are the leaderboard headers plus entity_id.

Examples


  try(fox_cfb_league_leaders(category = "passing"))

Get Fox Sports college football game odds

Description

Flattens the Bifrost event/{id}/odds matchup six-pack (spread / to win / total).

Usage

fox_cfb_odds(game_id)

Arguments

game_id

(character/numeric, required): Fox Bifrost event id (e.g. "41616").

Value

A cfbfastR-tagged tibble with one row per team:

Returns an empty tibble when no market is posted for the game.

Examples


  try(fox_cfb_odds(game_id = "41616"))

Get Fox Sports college football play-by-play

Description

Flattens the Bifrost event/{id}/data play-by-play layout (quarters -> drives -> plays) into one tidy play-level tibble.

Usage

fox_cfb_pbp(game_id)

Arguments

game_id

(character/numeric, required): Fox Bifrost event id (e.g. "41616"). This is the Fox event id, not the ESPN game id.

Value

A cfbfastR-tagged tibble with one row per play:

Examples


  try(fox_cfb_pbp(game_id = "41616"))

Get Fox Sports college football conference standings

Description

Flattens the Bifrost team/{id}/standings conference table (the standings of the given team's conference). Note: the league-wide league/standings endpoint returns header-only tables, so this is keyed by team.

Usage

fox_cfb_standings(team_id)

Arguments

team_id

(character/numeric, required): Fox Bifrost team id (e.g. "11").

Value

A cfbfastR-tagged tibble with one row per team in the conference; columns are the standings headers (rank, team, conf, w_l, home, away, pf, pa, ...) plus team_id, section (conference), and entity_id (Fox team id). Column set varies with the standings template.

Examples


  try(fox_cfb_standings(team_id = "11"))

Get Fox Sports college football team game log

Description

Flattens the Bifrost team/{id}/gamelog into one tidy, long row per (game, stat-category, stat). The endpoint groups team per-game stats by category (passing, rushing, defense, ...) and season-type split.

Usage

fox_cfb_team_gamelog(team_id)

Arguments

team_id

(character/numeric, required): Fox Bifrost team id (e.g. "11").

Value

A cfbfastR-tagged tibble with one row per (game, stat):

Examples


  try(fox_cfb_team_gamelog(team_id = "11"))

Get Fox Sports college football team roster

Description

Flattens the Bifrost team/{id}/roster position-group tables into one tidy player-level tibble.

Usage

fox_cfb_team_roster(team_id)

Arguments

team_id

(character/numeric, required): Fox Bifrost team id (e.g. "11" for Miami (FL)). Discover ids via the league team directory (league/teamnav).

Value

A cfbfastR-tagged tibble with one row per player:

Examples


  try(fox_cfb_team_roster(team_id = "11"))

Get Fox Sports college football team stat leaders

Description

Flattens the Bifrost team/{id}/stats leaders sections.

Usage

fox_cfb_team_stats(team_id)

Arguments

team_id

(character/numeric, required): Fox Bifrost team id (e.g. "11").

Value

A cfbfastR-tagged tibble with one row per (category, leader):

Examples


  try(fox_cfb_team_stats(team_id = "11"))

Series of functions to help clean the play-by-play data for analysis

Description

Cleans Play-by-Play data pulled from the API's raw game data

Usage

add_play_counts(play_df)

clean_drive_dat(play_df)

prep_epa_df_after(dat)

clean_drive_info(drive_df)

clean_play_text(play_df)

add_player_cols(pbp)

add_yardage(play_df)

clean_pbp_dat(play_df)

penalty_detection(raw_df)

Arguments

play_df

(data.frame required): Performs data cleansing on Play-by-Play DataFrame, as pulled from cfbd_pbp_data()

dat

(Data.Frame required) Clean Play-by-Play DataFrame pulled from cfbd_pbp_dat()

drive_df

(data.frame required) Drive dataframe pulled from API via the cfbd_drives() function

raw_df

(data.frame required): Performs data cleansing on Play-by-Play DataFrame, as pulled from cfbd_pbp_data()

Details

Requires the following columns to be present

Prep for EPA calculations at the end of the play. Requires the following columns be present:

Cleans CFB (D-I) Drive-By-Drive Data to create pts_drive column. Requires the following columns be present:

Cleans CFB play-by-play text to be compliant with existing play-by-play parsing. Generally not recommended for standalone use. This method exists due to ESPN PBP changes midway through the 2025 season.

Cleans CFB (D-I) player Data to create player name columns. Requires the following columns be present:

rush

.

pass

.

play_text

.

play_type

.

sack

.

fumble_vec

.

Cleans CFB (D-I) Drive-By-Drive Data to create yardage column. Requires the following columns be present:

play_text

.

play_type

.

rush

.

pass

.

int

.

int_td

.

kickoff_play

.

kickoff_tb

.

kickoff_downed

.

kickoff_fair_catch

.

fumble_vec

.

sack

.

punt

.

punt_tb

.

punt_downed

.

punt_fair_catch

.

punt_oob

.

punt_blocked

.

penalty_detail

.

Requires the following columns to be present

game_id

.

id_play

.

offense_play

.

defense_play

.

home

.

away

.

play_type

.

play_text

.

kickoff_play

.

down

.

distance

.

yards_gained

.

yards_to_goal

.

change_of_poss

.

penalty_1st_conv

.

off_timeouts_rem_before

.

def_timeouts_rem_before

.

Runs penalty detection on the play text and play types. Requires the following columns be present:

game_id

Referencing game id.

period

Game period (quarter).

down

Down of the play.

play_type

Categorical play type.

play_text

A description of the play.

Value

The original play_df with the following columns appended/redefined:

The original play_df with the following columns appended/redefined:

dat with the following columns appended/modified:

The original drive_df with the following columns appended to it:

The original play_df with the following columns appended to it:

The original pbp with the following columns appended to it:

rusher_player_name

.

receiver_player_name

.

passer_player_name

.

sack_player_name

.

sack_player_name2

.

pass_breakup_player_name

.

interception_player_name

.

fg_kicker_player_name

.

fg_block_player_name

.

fg_return_player_name

.

kickoff_player_name

.

kickoff_returner_player_name

.

punter_player_name

.

punt_block_player_name

.

punt_returner_player_name

.

punt_block_return_player_name

.

fumble_player_name

.

fumble_forced_player_name

.

fumble_recovered_player_name

.

The original play_df with the following columns appended to it:

yds_rushed

.

yds_receiving

.

yds_int_return

.

yds_kickoff

.

yds_kickoff_return

.

yds_punted

.

yds_fumble_return

.

yds_sacked

.

yds_penalty

.

The original play_df with the following columns appended/redefined:

scoring_play

.

td_play

.

touchdown

.

safety

.

fumble_vec

.

kickoff_play

.

kickoff_tb

.

kickoff_onside

.

kickoff_oob

.

kickoff_fair_catch

.

kickoff_downed

.

kick_play

.

kickoff_safety

.

punt

.

punt_play

.

punt_tb

.

punt_oob

.

punt_fair_catch

.

punt_downed

.

rush

.

pass

.

sack_vec

.

play_type

.

td_check

.

id_play

.

sack

.

int

.

int_td

.

completion

.

pass_attempt

.

target

.

pass_td

.

rush_td

.

turnover_vec

.

offense_score_play

.

defense_score_play

.

downs_turnover

.

scoring_play

.

fg_inds

.

yds_fg

.

yards_to_goal

.

lag_play_type3

.

lag_play_type2

.

lag_play_type

.

lead_play_type

.

lead_play_type2

.

lead_play_type3

.

The original raw_df with the following columns appended/redefined:

penalty_flag: TRUE/FALSE flag for penalty play types or penalty in play text plays.

.

penalty_declined: TRUE/FALSE flag for 'declined' in penalty play types or penalty in play text plays.

.

penalty_no_play: TRUE/FALSE flag for 'no play' in penalty play types or penalty in play text plays.

.

penalty_offset: TRUE/FALSE flag for 'off-setting' in penalty play types or penalty in play text plays.

.

penalty_1st_conv: TRUE/FALSE flag for 1st Down in penalty play types or penalty in play text plays.

.

penalty_text: TRUE/FALSE flag for penalty in text but not a penalty play type.

.

orig_play_type: Copy of original play_type label prior to any changes by the proceeding functions

.

down: Defines kickoff downs and penalties on kickoffs and converts them from 5 (as from the API) to 1.

.

play_type: Defines play_type, "Penalty (Kickoff)", penalties on kickoffs with a repeat kick.

.

half: Defines the half variable (1, 2).

.

Load college football weekly ESPN FPI ratings from the SportsDataverse data repo

Description

Loads weekly ESPN FPI snapshots – one row per team-week with FPI and its components as published that week. Published to the cfb_fpi_weekly release tag on the sportsdataverse-data repo.

Usage

load_cfb_fpi_weekly(
  seasons = most_recent_cfb_season(),
  ...,
  dbConnection = NULL,
  tablename = NULL
)

Arguments

seasons

A vector of 4-digit years associated with given college football seasons. Published coverage runs 2005 through the most recent season. Pass seasons = TRUE for every published season. (Min: 2005)

...

Additional arguments passed to an underlying function that writes the season data into a database.

dbConnection

A DBIConnection object, as returned by DBI::dbConnect()

tablename

The name of the data table within the database

Value

Returns a cfbfastR_data tibble.

col_name types description
season integer
season_type integer
week integer
team_id integer
last_updated character
run_date_time_key integer ESPN's run key for the snapshot, as an integer timestamp (e.g. 20241021040000). This is the AS-OF date the snapshot represents, which is not the same as last_updated (when ESPN computed it); the gap between the two is what snapshot_is_contemporaneous flags.
snapshot_out_of_sequence logical True when this snapshot was computed AFTER one belonging to a later week of the same season type -- so it cannot be read as an as-of-that-week rating. Almost always the week-1 slot, which ESPN overwrites with a late-season computation (2024 week 1 is stamped 2024-12-15). Filter these out for any point-in-time or backtest use.
fpi double Football Power Index that measures team's true strength on net points scale; expected point margin vs average opponent on neutral field.
fpirank double ESPN's FPI rank field. Agrees with rank on 99.4% of rows; on the ~0.6% where they differ it is stale -- it never matches the rank implied by the published fpi, while rank always does. Prefer rank.
projectedw double Projected overall W-L, accounting for results to date and FPI-based projections for remaining scheduled games (and potential conference championship games). May not sum to a whole number because of differing number of games played in each simulation.
projectedl double Projected overall Losses, accounting for results to date and FPI-based projections for remaining scheduled games (including potential conference championship games). May not sum to a whole number because of differing number of games played in each simulation.
projectedt character Projected ties. Always null -- college football abolished ties in 1996, and ESPN emits the key beside projectedw/projectedl without ever populating it. Retained so the column set matches the upstream payload.
projectedwpctrank double Rank among FBS teams by projected win percentage. ESPN publishes the rank without the underlying percentage; derive it from projectedw and projectedl.
probwinout double Percent of season simulations in which team won all remaining scheduled games as well as conference championship game (if applicable).
probwinconf double Percent of season simulations in which team won its conference, incorporating chance of getting to and winning conference championship game (if applicable). Accounts for shared conference titles in conferences that allow them.
sosremainingrank double Rank among all FBS teams of remaining schedule strength, from perspective of an average FBS team.
accomplishment double Reflects chance that an average Top 25 team would have team's record or better, given the schedule. On a 0 to 100 scale, where 100 is best.
accomplishmentrank double Strength of Record rank. Reflects chance that an average Top 25 team would have team's record or better, given the schedule.
adjwins double Team's Wins adjusted for chance an average FBS team would have team's record or better, given the schedule.
adjlosses double Team's Losses adjusted for chance an average FBS team would have team's record or better, given the schedule.
adjwinpctrank double Rank among FBS teams by adjusted win percentage. ESPN publishes the rank without the underlying percentage; derive it from adjwins and adjlosses. 0 is an unranked placeholder, not a rank -- it appears where the underlying value is null.
gamecontrol double Reflects chance that an average Top 25 team would control games from start to end the way this team did, given the schedule. On a 0 to 100 scale, where 100 is best.
gamecontrolrank double Game Control rank. Reflects chance that an average Top 25 team would control games from start to end the way this team did, given the schedule.
adjavgingamewp double Team's average in-game win probability adjusted for chance that an average FBS team would control games from start to end the way this team did, given the schedule.
adjavgingamewprank double Rank among FBS teams by adjavgingamewp (average in-game win probability adjusted for opponent). Null for most pre-2019 snapshots. 0 is an unranked placeholder, not a rank.
avgingamewp double Team's average in-game win probability across all plays of all games played, not adjusted for site or opponent.
avgingamewprank double Team's average in-game win probability rank adjusted for chance that an average FBS team would control games from start to end the way this team did, given the schedule.
avgsosrank double Rank among all FBS teams of games already played schedule strength, from perspective of an average Top 25 team.
topsosrank double Rank among all FBS teams of games already played schedule strength, from perspective of an top FBS team.
epaoffense double Offensive component of FPI. Offensive contribution to expected point margin vs average opponent on neutral field.
epadefense double Defensive component of FPI. Defensive contribution to expected point margin vs average opponent on neutral field.
epaspecialteams double Special teams component of FPI. Special teams contribution to expected point margin vs average opponent on neutral field.
probwindiv double Percent of season simulations in which team won its conference division, for those conferences that have divisions.
probmakeplayoffs double Chance to make the CFB Playoff, according to the Playoff Predictor.
probmaketitlegame double Chance to make the CFB Playoff National Championship game, according to the Playoff Predictor.
numwins double Actual wins to date at the time of the snapshot. Distinct from projectedw (full-season projection) and adjwins (opponent-adjusted).
numlosses double Actual losses to date at the time of the snapshot. Distinct from projectedl (full-season projection) and adjlosses (opponent-adjusted).
numties double Actual ties to date. Never nonzero -- college football abolished ties in 1996; the column is null or 0 in every published row.
probwintitle double Chance to win the CFB Playoff National Championship, according to the Playoff Predictor.
rankchange7days double FPI Rank change from previous week.
prob6wins double Percent of season simulations in which a team won at least 6 games (typically bowl-eligible).
rank double FPI rank among FBS teams for this snapshot (1 = best). Prefer this over fpirank: the two agree on 99.4% of rows, and on the ~0.6% where they differ, rank is always the one consistent with the published fpi value.
offefficiency double Offensive efficiency on 0-100 scale; based on offense's contribution to scoring margin on per-play basis, adjusted for strength of opposing defenses faced.
offefficiencyrank double Team's offensive efficiency rank among all FBS teams.
defefficiency double Defensive efficiency on 0-100 scale; based on defense's contribution to scoring margin on per-play basis, adjusted for strength of opposing offenses faced.
defefficiencyrank double Team's defensive efficiency rank among all FBS teams.
stefficiency double Special teams efficiency on 0-100 scale; based on special teams' contribution to scoring margin on per-play basis, adjusted for strength of opposing special teams faced.
stefficiencyrank double Team's special teams efficiency rank among all FBS teams.
totefficiency double Net efficiency on 0-100 scale; incorporates offense, defense and special teams efficiencies into a single schedule-adjusted measure of per-play efficiency.
totefficiencyrank double Team's overall efficiency rank among all FBS teams.
snapshot_is_contemporaneous logical True when the snapshot was computed inside its own season's window (August of the season year through February of the next), i.e. it is a live weekly run rather than a retrospective backfill. False for every row before 2015, which ESPN computed in one pass afterwards. A retrospective row is a reconstruction, not an as-of-week rating.

Author(s)

Saiem Gilani

Examples


  try(load_cfb_fpi_weekly(2005))

Load cleaned play-by-play from the data repo

Description

helper that loads multiple seasons from the data repo either into memory or writes it into a db using some forwarded arguments in the dots

This is the classic cfbfastR EPA/WPA play-by-play (FBS, 2014+). For the ESPN-derived pbp with deeper history (2004+) see load_espn_cfb_pbp(); for stats.ncaa.org pbp covering FCS and lower divisions (2013+) see load_ncaa_mfb_pbp().

Usage

load_cfb_pbp(
  seasons = most_recent_cfb_season(),
  ...,
  dbConnection = NULL,
  tablename = NULL
)

Arguments

seasons

A vector of 4-digit years associated with given College Football seasons.

...

Additional arguments passed to an underlying function that writes the season data into a database (used by update_cfb_db())

dbConnection

A DBIConnection object, as returned by DBI::dbConnect()

tablename

The name of the play by play data table within the database

Value

Returns a tibble with play-by-play data

Source

CFB Play-by-Play Data releases can be found here: https://github.com/sportsdataverse/sportsdataverse-data/releases/tag/cfbfastR_cfb_pbp

See Also

Issues with this data should be filed here: https://github.com/sportsdataverse/cfbfastR-data

update_cfb_db()

Other loaders: load_cfb_rosters(), load_cfb_schedules(), load_cfb_teams(), update_cfb_db()

Load college football season power ratings from the SportsDataverse data repo

Description

Loads season-end team power ratings from the cfbfastR modeling suite – one row per team with overall/offense/defense/special-teams ratings on the points scale. Published to the cfb_ratings release tag on the sportsdataverse-data repo.

Usage

load_cfb_ratings(
  seasons = most_recent_cfb_season(),
  ...,
  dbConnection = NULL,
  tablename = NULL
)

Arguments

seasons

A vector of 4-digit years associated with given college football seasons. Published coverage runs 2004 through the most recent season. Pass seasons = TRUE for every published season. (Min: 2004)

...

Additional arguments passed to an underlying function that writes the season data into a database.

dbConnection

A DBIConnection object, as returned by DBI::dbConnect()

tablename

The name of the data table within the database

Value

Returns a cfbfastR_data tibble.

col_name types description
season integer
team_id integer
adj_off_epa double Opponent-adjusted offensive EPA per play: the team's raw per-game EPA on pass and rush plays net of each opponent's ridge-fitted defensive strength, averaged over its games.
adj_def_epa double Opponent-adjusted EPA per play allowed, netted the same way as the offensive rating, so lower is better because it measures EPA surrendered.
adj_st_epa double Special-teams composite in EPA units: per-play mean EPA on field goals, punts, and kick returns, each centered on that unit's league mean and summed across the three units.
adj_net double adj_off_epa minus adj_def_epa, the team's overall efficiency rating in EPA per play; special teams is deliberately excluded.
fei_off double Drive-level offensive rating from a ridge fit on per-drive EPA, the Fremeau-style drive-efficiency counterpart to adj_off_epa.
fei_def double Drive-level defensive rating from the same per-drive ridge fit, on the same scale as fei_off.
fei_net double fei_off minus fei_def, the team's overall drive-efficiency rating, with the ridge's dropped reference team pinned at zero.
games integer
off_pace double Tempo measure: scrimmage plays (pass plus rush) per game, centering near 65 and used as the pace input to the totals model.
off_rank integer Dense rank of adj_off_epa in descending order, so rank 1 is the season's most efficient offense.
def_rank integer Dense rank of adj_def_epa in ascending order, so rank 1 is the season's stingiest defense.
net_rank integer Dense rank of adj_net in descending order, so rank 1 is the season's strongest overall team.
net_z double adj_net restated as a z-score against the mean and standard deviation of adj_net across the rated teams that season.

Author(s)

Saiem Gilani

Examples


  try(load_cfb_ratings(2004))

Load college football weekly power ratings from the SportsDataverse data repo

Description

Loads weekly team power ratings – one row per team-week, the as-of- week snapshots behind the season-end ratings. Published to the cfb_ratings_weekly release tag on the sportsdataverse-data repo.

Usage

load_cfb_ratings_weekly(
  seasons = most_recent_cfb_season(),
  ...,
  dbConnection = NULL,
  tablename = NULL
)

Arguments

seasons

A vector of 4-digit years associated with given college football seasons. Published coverage runs 2004 through the most recent season. Pass seasons = TRUE for every published season. (Min: 2004)

...

Additional arguments passed to an underlying function that writes the season data into a database.

dbConnection

A DBIConnection object, as returned by DBI::dbConnect()

tablename

The name of the data table within the database

Value

Returns a cfbfastR_data tibble.

col_name types description
season integer
team_id integer
adj_off_epa double Opponent-adjusted offensive EPA per play as of the snapshot week: raw per-game EPA on pass and rush plays net of each opponent's ridge-fitted defensive strength.
adj_def_epa double Opponent-adjusted EPA per play allowed as of the snapshot week, netted the same way as the offensive rating, so lower is better.
adj_st_epa double Special-teams composite in EPA units as of the snapshot week, summing the league-centered per-play EPA of the field goal, punt, and kick-return units.
adj_net double adj_off_epa minus adj_def_epa at the snapshot week, the team's overall efficiency rating in EPA per play with special teams excluded.
fei_off double Drive-level offensive rating at the snapshot week, from a ridge fit on per-drive EPA.
fei_def double Drive-level defensive rating at the snapshot week, from the same per-drive ridge fit and on the same scale as fei_off.
fei_net double fei_off minus fei_def at the snapshot week, the team's overall drive-efficiency rating.
games integer
off_pace double Scrimmage plays per game through the snapshot week, the tempo input consumed by the totals model.
off_rank integer Dense rank of adj_off_epa in descending order within the snapshot week, so rank 1 is the most efficient offense at that point.
def_rank integer Dense rank of adj_def_epa in ascending order within the snapshot week, so rank 1 is the stingiest defense at that point.
net_rank integer Dense rank of adj_net in descending order within the snapshot week, so rank 1 is the strongest overall team at that point.
net_z double adj_net restated as a z-score against the mean and standard deviation of adj_net across the teams rated in that snapshot week.
through_week integer Regular-season week the snapshot runs through; the ratings were refit using only games kicking off on or before that week's final kickoff date.

Author(s)

Saiem Gilani

Examples


  try(load_cfb_ratings_weekly(2004))

Load college football recruiting projections from the SportsDataverse data repo

Description

Loads recruiting-based team projections – one row per team-season with talent-derived projection inputs. Published to the cfb_recruiting_proj release tag on the sportsdataverse-data repo.

Usage

load_cfb_recruiting_proj(
  seasons = most_recent_cfb_season(),
  ...,
  dbConnection = NULL,
  tablename = NULL
)

Arguments

seasons

A vector of 4-digit years associated with given college football seasons. Published coverage runs 2016 through the most recent season. Pass seasons = TRUE for every published season. (Min: 2016)

...

Additional arguments passed to an underlying function that writes the season data into a database.

dbConnection

A DBIConnection object, as returned by DBI::dbConnect()

tablename

The name of the data table within the database

Value

Returns a cfbfastR_data tibble.

col_name types description
season integer
team_id integer
pred_wins double Ridge projection of the team's season win total, fit strictly on prior seasons from talent composite, blue-chip ratio, offensive and defensive returning production, and prior wins.
pred_margin double Ridge projection of the team's average per-game scoring margin, from the same preseason-known feature set as pred_wins.
pred_net_epa double Reserved slot for a projected adjusted net EPA; it ships all-null because the adjusted-EPA training target is not currently loadable.

Author(s)

Saiem Gilani

Examples


  try(load_cfb_recruiting_proj(2016))

Load college football recruiting rankings from the SportsDataverse data repo

Description

Loads player recruiting rankings – one row per recruit-season with stars, rating, position, and school commitment. Published to the cfb_recruits release tag on the sportsdataverse-data repo.

Usage

load_cfb_recruits(
  seasons = most_recent_cfb_season(),
  ...,
  dbConnection = NULL,
  tablename = NULL
)

Arguments

seasons

A vector of 4-digit years associated with given college football seasons. Published coverage runs 2002 through the most recent season. Pass seasons = TRUE for every published season. (Min: 2002)

...

Additional arguments passed to an underlying function that writes the season data into a database.

dbConnection

A DBIConnection object, as returned by DBI::dbConnect()

tablename

The name of the data table within the database

Value

Returns a cfbfastR_data tibble.

col_name types description
season integer
team_id integer
team_id_247 character
team character
recruit_id character
player_name character
stars integer
grade double
position character

Author(s)

Saiem Gilani

Examples


  try(load_cfb_recruits(2002))

Load college football returning production from the SportsDataverse data repo

Description

Loads returning production shares – one row per team-season with the share of prior-season production returning, overall and by unit. Published to the cfb_returning_production release tag on the sportsdataverse-data repo.

Usage

load_cfb_returning_production(
  seasons = most_recent_cfb_season(),
  ...,
  dbConnection = NULL,
  tablename = NULL
)

Arguments

seasons

A vector of 4-digit years associated with given college football seasons. Published coverage runs 2005 through the most recent season. Pass seasons = TRUE for every published season. (Min: 2005)

...

Additional arguments passed to an underlying function that writes the season data into a database.

dbConnection

A DBIConnection object, as returned by DBI::dbConnect()

tablename

The name of the data table within the database

Value

Returns a cfbfastR_data tibble.

col_name types description
season integer
team_id integer
off_returning double
def_returning double
overall_returning double
n_returning integer

Author(s)

Saiem Gilani

Examples


  try(load_cfb_returning_production(2005))

Load College Football Rosters

Description

Loads team rosters for specified seasons. This function wraps the cfbd_team_roster() function sourced from the College Football Data API.

Usage

load_cfb_rosters(seasons = most_recent_cfb_season())

Arguments

seasons

a numeric vector of seasons to return, defaults to returning this year's data if it is September or later. If set to TRUE, will return all available data.

Value

A tibble of season-level roster data.

See Also

cfbd_team_roster()

Issues with this data should be filed here: https://github.com/sportsdataverse/cfbfastR-data

Other loaders: load_cfb_pbp(), load_cfb_schedules(), load_cfb_teams(), update_cfb_db()

Examples


  try(load_cfb_rosters(2024))

Load college football roster id crosswalk from the SportsDataverse data repo

Description

Loads the roster-level id crosswalk linking CFBD athlete ids to ESPN athlete ids across seasons. Single cumulative file (not season- partitioned). Published to the cfb_crosswalk release tag on the sportsdataverse-data repo.

Usage

load_cfb_rosters_crosswalk(..., dbConnection = NULL, tablename = NULL)

Arguments

...

Additional arguments passed to an underlying function that writes the season data into a database.

dbConnection

A DBIConnection object, as returned by DBI::dbConnect()

tablename

The name of the data table within the database

Value

Returns a cfbfastR_data tibble.

col_name types description
espn_team_id integer
fox_team_id character
person_key character
espn_athlete_id integer
fox_athlete_id character
yahoo_athlete_id character
name character
espn_jersey character
fox_jersey character
espn_position character
fox_position character
yahoo_position character
match_method character
matched_sources character

Author(s)

Saiem Gilani

Examples


  try(load_cfb_rosters_crosswalk())

Load college football schedule id crosswalk from the SportsDataverse data repo

Description

Loads the game-level id crosswalk linking CFBD game ids to ESPN event ids – one row per game-season. Published to the cfb_crosswalk release tag on the sportsdataverse-data repo.

Usage

load_cfb_schedule_crosswalk(
  seasons = most_recent_cfb_season(),
  ...,
  dbConnection = NULL,
  tablename = NULL
)

Arguments

seasons

A vector of 4-digit years associated with given college football seasons. Published coverage runs 2014 through the most recent season. Pass seasons = TRUE for every published season. (Min: 2014)

...

Additional arguments passed to an underlying function that writes the season data into a database.

dbConnection

A DBIConnection object, as returned by DBI::dbConnect()

tablename

The name of the data table within the database

Value

Returns a cfbfastR_data tibble.

col_name types description
matchup_key character Order-independent key for the game: the two normalized team names sorted alphabetically and joined with a pipe.
espn_game_id integer ESPN game id for the crosswalk row.
fox_game_id character Fox Sports game id for the same game.
yahoo_game_id character Yahoo Sports game id for the same game.
yahoo_global_game_id character Yahoo's cross-season global game key in ncaaf.g.NNNN form, distinct from the date-encoded yahoo_game_id.
home_team character
away_team character
espn_date character Kickoff date as YYYY-MM-DD taken from ESPN's schedule, null on games that matched no ESPN row.
fox_date character Kickoff date as YYYY-MM-DD taken from the Fox Sports schedule, null on games that matched no Fox row.
yahoo_date character Kickoff date as YYYY-MM-DD, parsed from Yahoo's RFC-2822 start_time string.
matched_sources character Plus-joined provenance tag naming which of espn, fox, and yahoo actually supplied a row for this game.

Author(s)

Saiem Gilani

Examples


  try(load_cfb_schedule_crosswalk(2014))

Load CFB Game/Schedule Data from data repo

Description

This function returns game/schedule information for the specified season(s). This function wraps the cfbd_game_info() function sourced from the College Football Data API.

Usage

load_cfb_schedules(seasons = most_recent_cfb_season())

Arguments

seasons

a numeric vector of seasons to return, default TRUE returns all available data.

Value

A tibble of game information for past and/or future games.

See Also

cfbd_game_info()

Issues with this data should be filed here: https://github.com/sportsdataverse/cfbfastR-data

Other loaders: load_cfb_pbp(), load_cfb_rosters(), load_cfb_teams(), update_cfb_db()

Examples


  try(load_cfb_schedules(2024))

Load college football weekly team summaries from the SportsDataverse data repo

Description

Loads weekly team summaries – one row per team-week with cumulative- to-date EPA and success-rate profiles. Published to the cfb_team_summaries_weekly release tag on the sportsdataverse-data repo.

Usage

load_cfb_team_summaries_weekly(
  seasons = most_recent_cfb_season(),
  ...,
  dbConnection = NULL,
  tablename = NULL
)

Arguments

seasons

A vector of 4-digit years associated with given college football seasons. Published coverage runs 2004 through the most recent season. Pass seasons = TRUE for every published season. (Min: 2004)

...

Additional arguments passed to an underlying function that writes the season data into a database.

dbConnection

A DBIConnection object, as returned by DBI::dbConnect()

tablename

The name of the data table within the database

Value

Returns a cfbfastR_data tibble.

col_name types description
team_id integer
pos_team character
division character
conference character
season integer
plays_off integer Plays run, with the team on offense.
passrate_off double Share of plays that were pass plays, with the team on offense.
rushrate_off double Share of plays that were rush plays, with the team on offense.
havoc_off double Havoc rate -- the share of plays carrying the defensive-disruption flag, with the team on offense.
explosive_off double Explosive-play rate -- the share of plays carrying the explosive flag, with the team on offense.
TEPA_off double Total EPA summed over every play, with the team on offense.
EPAplay_off double EPA per play, with the team on offense.
yards_off integer Total yards gained, with the team on offense.
yardsplay_off double Yards gained per play, with the team on offense.
play_stuffed_off double Stuffed-play rate -- the share of plays carrying the stuffed flag, with the team on offense.
success_off double Success rate -- the share of plays flagged as successful by EPA, with the team on offense.
red_zone_success_off double Success rate on red-zone plays, with the team on offense.
third_down_success_off double Success rate on third-down plays, with the team on offense.
third_down_distance_off double Average yards to go on third down, with the team on offense.
late_down_success_off double Success rate on late-down plays, with the team on offense.
early_down_EPA_off double EPA per early-down play, with the team on offense.
start_position_off double Average drive start position, measured in yards from the opponent goal line, with the team on offense.
nonExplosiveEpaPerPlay_off double EPA per play with explosive plays excluded, with the team on offense.
line_yards_off double Average line yards credited to the offensive line on rushes, with the team on offense.
opportunity_rate_off double Opportunity rate -- the share of rushes carrying the opportunity flag, with the team on offense.
playsgame_off double Plays run per game, with the team on offense.
EPAdrive_off double EPA per drive (total EPA divided by drives), with the team on offense.
EPAgame_off double EPA per game (total EPA divided by games), with the team on offense.
yardsgame_off double Yards gained per game, with the team on offense.
drives_off integer Offensive drives, with the team on offense.
drivesgame_off double Drives per game, with the team on offense.
yardsdrive_off double Yards gained per drive, with the team on offense.
playsdrive_off double Plays run per drive, with the team on offense.
playsgame_off_rank double National rank of the team's plays run per game with the team on offense, where 1 is best.
TEPA_off_rank double National rank of the team's total EPA summed over every play with the team on offense, where 1 is best.
EPAgame_off_rank double National rank of the team's EPA per game (total EPA divided by games) with the team on offense, where 1 is best.
EPAplay_off_rank double National rank of the team's EPA per play with the team on offense, where 1 is best.
EPAdrive_off_rank double National rank of the team's EPA per drive (total EPA divided by drives) with the team on offense, where 1 is best.
early_down_EPA_off_rank double National rank of the team's EPA per early-down play with the team on offense, where 1 is best.
success_off_rank double National rank of the team's success rate -- the share of plays flagged as successful by EPA with the team on offense, where 1 is best.
yards_off_rank double National rank of the team's total yards gained with the team on offense, where 1 is best.
yardsplay_off_rank double National rank of the team's yards gained per play with the team on offense, where 1 is best.
yardsgame_off_rank double National rank of the team's yards gained per game with the team on offense, where 1 is best.
drivesgame_off_rank double National rank of the team's drives per game with the team on offense, where 1 is best.
yardsdrive_off_rank double National rank of the team's yards gained per drive with the team on offense, where 1 is best.
playsdrive_off_rank double National rank of the team's plays run per drive with the team on offense, where 1 is best.
play_stuffed_off_rank double National rank of the team's stuffed-play rate -- the share of plays carrying the stuffed flag with the team on offense, where 1 is best.
red_zone_success_off_rank double National rank of the team's success rate on red-zone plays with the team on offense, where 1 is best.
third_down_success_off_rank double National rank of the team's success rate on third-down plays with the team on offense, where 1 is best.
late_down_success_off_rank double National rank of the team's success rate on late-down plays with the team on offense, where 1 is best.
third_down_distance_off_rank double National rank of the team's average yards to go on third down with the team on offense, where 1 is best.
start_position_off_rank double National rank of the team's average drive start position, measured in yards from the opponent goal line with the team on offense, where 1 is best.
havoc_off_rank double National rank of the team's havoc rate -- the share of plays carrying the defensive-disruption flag with the team on offense, where 1 is best.
explosive_off_rank double National rank of the team's explosive-play rate -- the share of plays carrying the explosive flag with the team on offense, where 1 is best.
passrate_off_rank double National rank of the team's share of plays that were pass plays with the team on offense, where 1 is best.
rushrate_off_rank double National rank of the team's share of plays that were rush plays with the team on offense, where 1 is best.
nonExplosiveEpaPerPlay_off_rank double National rank of the team's EPA per play with explosive plays excluded with the team on offense, where 1 is best.
line_yards_off_rank double National rank of the team's average line yards credited to the offensive line on rushes with the team on offense, where 1 is best.
opportunity_rate_off_rank double National rank of the team's opportunity rate -- the share of rushes carrying the opportunity flag with the team on offense, where 1 is best.
plays_def integer Plays run, with the team on defense (i.e. allowed to opponents).
passrate_def double Share of plays that were pass plays, with the team on defense (i.e. allowed to opponents).
rushrate_def double Share of plays that were rush plays, with the team on defense (i.e. allowed to opponents).
havoc_def double Havoc rate -- the share of plays carrying the defensive-disruption flag, with the team on defense (i.e. allowed to opponents).
explosive_def double Explosive-play rate -- the share of plays carrying the explosive flag, with the team on defense (i.e. allowed to opponents).
TEPA_def double Total EPA summed over every play, with the team on defense (i.e. allowed to opponents).
EPAplay_def double EPA per play, with the team on defense (i.e. allowed to opponents).
yards_def integer Total yards gained, with the team on defense (i.e. allowed to opponents).
yardsplay_def double Yards gained per play, with the team on defense (i.e. allowed to opponents).
play_stuffed_def double Stuffed-play rate -- the share of plays carrying the stuffed flag, with the team on defense (i.e. allowed to opponents).
success_def double Success rate -- the share of plays flagged as successful by EPA, with the team on defense (i.e. allowed to opponents).
red_zone_success_def double Success rate on red-zone plays, with the team on defense (i.e. allowed to opponents).
third_down_success_def double Success rate on third-down plays, with the team on defense (i.e. allowed to opponents).
third_down_distance_def double Average yards to go on third down, with the team on defense (i.e. allowed to opponents).
late_down_success_def double Success rate on late-down plays, with the team on defense (i.e. allowed to opponents).
early_down_EPA_def double EPA per early-down play, with the team on defense (i.e. allowed to opponents).
start_position_def double Average drive start position, measured in yards from the opponent goal line, with the team on defense (i.e. allowed to opponents).
nonExplosiveEpaPerPlay_def double EPA per play with explosive plays excluded, with the team on defense (i.e. allowed to opponents).
line_yards_def double Average line yards credited to the offensive line on rushes, with the team on defense (i.e. allowed to opponents).
opportunity_rate_def double Opportunity rate -- the share of rushes carrying the opportunity flag, with the team on defense (i.e. allowed to opponents).
playsgame_def double Plays run per game, with the team on defense (i.e. allowed to opponents).
EPAdrive_def double EPA per drive (total EPA divided by drives), with the team on defense (i.e. allowed to opponents).
EPAgame_def double EPA per game (total EPA divided by games), with the team on defense (i.e. allowed to opponents).
yardsgame_def double Yards gained per game, with the team on defense (i.e. allowed to opponents).
drives_def integer Offensive drives, with the team on defense (i.e. allowed to opponents).
drivesgame_def double Drives per game, with the team on defense (i.e. allowed to opponents).
yardsdrive_def double Yards gained per drive, with the team on defense (i.e. allowed to opponents).
playsdrive_def double Plays run per drive, with the team on defense (i.e. allowed to opponents).
playsgame_def_rank double National rank of the team's plays run per game with the team on defense (i.e. allowed to opponents), where 1 is best.
TEPA_def_rank double National rank of the team's total EPA summed over every play with the team on defense (i.e. allowed to opponents), where 1 is best.
EPAgame_def_rank double National rank of the team's EPA per game (total EPA divided by games) with the team on defense (i.e. allowed to opponents), where 1 is best.
EPAplay_def_rank double National rank of the team's EPA per play with the team on defense (i.e. allowed to opponents), where 1 is best.
EPAdrive_def_rank double National rank of the team's EPA per drive (total EPA divided by drives) with the team on defense (i.e. allowed to opponents), where 1 is best.
early_down_EPA_def_rank double National rank of the team's EPA per early-down play with the team on defense (i.e. allowed to opponents), where 1 is best.
success_def_rank double National rank of the team's success rate -- the share of plays flagged as successful by EPA with the team on defense (i.e. allowed to opponents), where 1 is best.
yards_def_rank double National rank of the team's total yards gained with the team on defense (i.e. allowed to opponents), where 1 is best.
yardsplay_def_rank double National rank of the team's yards gained per play with the team on defense (i.e. allowed to opponents), where 1 is best.
yardsgame_def_rank double National rank of the team's yards gained per game with the team on defense (i.e. allowed to opponents), where 1 is best.
drivesgame_def_rank double National rank of the team's drives per game with the team on defense (i.e. allowed to opponents), where 1 is best.
yardsdrive_def_rank double National rank of the team's yards gained per drive with the team on defense (i.e. allowed to opponents), where 1 is best.
playsdrive_def_rank double National rank of the team's plays run per drive with the team on defense (i.e. allowed to opponents), where 1 is best.
play_stuffed_def_rank double National rank of the team's stuffed-play rate -- the share of plays carrying the stuffed flag with the team on defense (i.e. allowed to opponents), where 1 is best.
red_zone_success_def_rank double National rank of the team's success rate on red-zone plays with the team on defense (i.e. allowed to opponents), where 1 is best.
third_down_success_def_rank double National rank of the team's success rate on third-down plays with the team on defense (i.e. allowed to opponents), where 1 is best.
late_down_success_def_rank double National rank of the team's success rate on late-down plays with the team on defense (i.e. allowed to opponents), where 1 is best.
third_down_distance_def_rank double National rank of the team's average yards to go on third down with the team on defense (i.e. allowed to opponents), where 1 is best.
start_position_def_rank double National rank of the team's average drive start position, measured in yards from the opponent goal line with the team on defense (i.e. allowed to opponents), where 1 is best.
havoc_def_rank double National rank of the team's havoc rate -- the share of plays carrying the defensive-disruption flag with the team on defense (i.e. allowed to opponents), where 1 is best.
explosive_def_rank double National rank of the team's explosive-play rate -- the share of plays carrying the explosive flag with the team on defense (i.e. allowed to opponents), where 1 is best.
passrate_def_rank double National rank of the team's share of plays that were pass plays with the team on defense (i.e. allowed to opponents), where 1 is best.
rushrate_def_rank double National rank of the team's share of plays that were rush plays with the team on defense (i.e. allowed to opponents), where 1 is best.
nonExplosiveEpaPerPlay_def_rank double National rank of the team's EPA per play with explosive plays excluded with the team on defense (i.e. allowed to opponents), where 1 is best.
line_yards_def_rank double National rank of the team's average line yards credited to the offensive line on rushes with the team on defense (i.e. allowed to opponents), where 1 is best.
opportunity_rate_def_rank double National rank of the team's opportunity rate -- the share of rushes carrying the opportunity flag with the team on defense (i.e. allowed to opponents), where 1 is best.
TEPA_margin double Margin in total EPA summed over every play: the team's offensive value minus the value it allowed on defense.
EPAplay_margin double Margin in EPA per play: the team's offensive value minus the value it allowed on defense.
EPAdrive_margin double Margin in EPA per drive (total EPA divided by drives): the team's offensive value minus the value it allowed on defense.
EPAgame_margin double Margin in EPA per game (total EPA divided by games): the team's offensive value minus the value it allowed on defense.
success_margin double Margin in success rate -- the share of plays flagged as successful by EPA: the team's offensive value minus the value it allowed on defense.
yardsplay_margin double Margin in yards gained per play: the team's offensive value minus the value it allowed on defense.
TEPA_margin_rank double Margin in total EPA summed over every play: the team's offensive value minus the value it allowed on defense. National rank of that margin, 1 = largest.
EPAplay_margin_rank double Margin in EPA per play: the team's offensive value minus the value it allowed on defense. National rank of that margin, 1 = largest.
EPAdrive_margin_rank double Margin in EPA per drive (total EPA divided by drives): the team's offensive value minus the value it allowed on defense. National rank of that margin, 1 = largest.
EPAgame_margin_rank double Margin in EPA per game (total EPA divided by games): the team's offensive value minus the value it allowed on defense. National rank of that margin, 1 = largest.
success_margin_rank double Margin in success rate -- the share of plays flagged as successful by EPA: the team's offensive value minus the value it allowed on defense. National rank of that margin, 1 = largest.
yardsplay_margin_rank double Margin in yards gained per play: the team's offensive value minus the value it allowed on defense. National rank of that margin, 1 = largest.
start_position_margin double Field-position margin: the team's own average starting field position minus the average starting field position it allowed, both measured as yards gained from their own goal line. Positive means the team started closer to scoring than its opponents.
start_position_margin_rank double Field-position margin: the team's own average starting field position minus the average starting field position it allowed, both measured as yards gained from their own goal line. Positive means the team started closer to scoring than its opponents. National rank of that margin, 1 = largest.
total_available_yards_off double Available yards are the yards a drive could theoretically gain, summed from each drive's starting distance to the opponent goal line. Total available yards on the team's own drives.
total_gained_yards_off integer Total yards the team actually gained across its own drives.
available_yards_pct_off double Share of available yards the team's offense actually gained (total_gained_yards_off divided by total_available_yards_off). Higher is better.
available_yards_pct_off_rank double National rank of the team's offensive available-yards share, where 1 is best.
total_available_yards_def double Available yards are the yards a drive could theoretically gain, summed from each drive's starting distance to the opponent goal line. Total available yards on drives the team defended.
total_gained_yards_def integer Total yards the team allowed across the drives it defended.
available_yards_pct_def double Share of available yards the team's defense allowed opponents to gain. Lower is better.
available_yards_pct_def_rank double National rank of the team's defensive available-yards share, where 1 is best.
total_available_yards_margin double Available yards on the team's own drives minus available yards on drives it defended.
total_gained_yards_margin integer Yards the team gained minus yards it allowed.
available_yards_pct_margin double Available-yards share gained by the offense minus the share allowed by the defense. Higher is better.
total_available_yards_margin_rank double National rank of total_available_yards_margin, 1 = largest margin.
total_gained_yards_margin_rank double National rank of total_gained_yards_margin, 1 = largest margin.
available_yards_pct_margin_rank double National rank of available_yards_pct_margin, 1 = largest margin.
plays_off_pass integer Plays run on pass plays, with the team on offense.
passrate_off_pass double Share of plays that were pass plays on pass plays, with the team on offense.
rushrate_off_pass double Share of plays that were rush plays on pass plays, with the team on offense.
havoc_off_pass double Havoc rate -- the share of plays carrying the defensive-disruption flag on pass plays, with the team on offense.
explosive_off_pass double Explosive-play rate -- the share of plays carrying the explosive flag on pass plays, with the team on offense.
TEPA_off_pass double Total EPA summed over every play on pass plays, with the team on offense.
EPAplay_off_pass double EPA per play on pass plays, with the team on offense.
yards_off_pass integer Total yards gained on pass plays, with the team on offense.
yardsplay_off_pass double Yards gained per play on pass plays, with the team on offense.
play_stuffed_off_pass double Stuffed-play rate -- the share of plays carrying the stuffed flag on pass plays, with the team on offense.
success_off_pass double Success rate -- the share of plays flagged as successful by EPA on pass plays, with the team on offense.
red_zone_success_off_pass double Success rate on red-zone plays on pass plays, with the team on offense.
third_down_success_off_pass double Success rate on third-down plays on pass plays, with the team on offense.
third_down_distance_off_pass double Average yards to go on third down on pass plays, with the team on offense.
late_down_success_off_pass double Success rate on late-down plays on pass plays, with the team on offense.
early_down_EPA_off_pass double EPA per early-down play on pass plays, with the team on offense.
nonExplosiveEpaPerPlay_off_pass double EPA per play with explosive plays excluded on pass plays, with the team on offense.
line_yards_off_pass double Average line yards credited to the offensive line on rushes on pass plays, with the team on offense.
opportunity_rate_off_pass double Opportunity rate -- the share of rushes carrying the opportunity flag on pass plays, with the team on offense.
playsgame_off_pass double Plays run per game on pass plays, with the team on offense.
EPAdrive_off_pass double EPA per drive (total EPA divided by drives) on pass plays, with the team on offense.
EPAgame_off_pass double EPA per game (total EPA divided by games) on pass plays, with the team on offense.
yardsgame_off_pass double Yards gained per game on pass plays, with the team on offense.
drives_off_pass integer Offensive drives on pass plays, with the team on offense.
drivesgame_off_pass double Drives per game on pass plays, with the team on offense.
yardsdrive_off_pass double Yards gained per drive on pass plays, with the team on offense.
playsdrive_off_pass double Plays run per drive on pass plays, with the team on offense.
playsgame_off_pass_rank double National rank of the team's plays run per game on pass plays with the team on offense, where 1 is best.
TEPA_off_pass_rank double National rank of the team's total EPA summed over every play on pass plays with the team on offense, where 1 is best.
EPAgame_off_pass_rank double National rank of the team's EPA per game (total EPA divided by games) on pass plays with the team on offense, where 1 is best.
EPAplay_off_pass_rank double National rank of the team's EPA per play on pass plays with the team on offense, where 1 is best.
EPAdrive_off_pass_rank double National rank of the team's EPA per drive (total EPA divided by drives) on pass plays with the team on offense, where 1 is best.
early_down_EPA_off_pass_rank double National rank of the team's EPA per early-down play on pass plays with the team on offense, where 1 is best.
success_off_pass_rank double National rank of the team's success rate -- the share of plays flagged as successful by EPA on pass plays with the team on offense, where 1 is best.
yards_off_pass_rank double National rank of the team's total yards gained on pass plays with the team on offense, where 1 is best.
yardsplay_off_pass_rank double National rank of the team's yards gained per play on pass plays with the team on offense, where 1 is best.
yardsgame_off_pass_rank double National rank of the team's yards gained per game on pass plays with the team on offense, where 1 is best.
drivesgame_off_pass_rank double National rank of the team's drives per game on pass plays with the team on offense, where 1 is best.
yardsdrive_off_pass_rank double National rank of the team's yards gained per drive on pass plays with the team on offense, where 1 is best.
playsdrive_off_pass_rank double National rank of the team's plays run per drive on pass plays with the team on offense, where 1 is best.
play_stuffed_off_pass_rank double National rank of the team's stuffed-play rate -- the share of plays carrying the stuffed flag on pass plays with the team on offense, where 1 is best.
red_zone_success_off_pass_rank double National rank of the team's success rate on red-zone plays on pass plays with the team on offense, where 1 is best.
third_down_success_off_pass_rank double National rank of the team's success rate on third-down plays on pass plays with the team on offense, where 1 is best.
late_down_success_off_pass_rank double National rank of the team's success rate on late-down plays on pass plays with the team on offense, where 1 is best.
third_down_distance_off_pass_rank double National rank of the team's average yards to go on third down on pass plays with the team on offense, where 1 is best.
havoc_off_pass_rank double National rank of the team's havoc rate -- the share of plays carrying the defensive-disruption flag on pass plays with the team on offense, where 1 is best.
explosive_off_pass_rank double National rank of the team's explosive-play rate -- the share of plays carrying the explosive flag on pass plays with the team on offense, where 1 is best.
passrate_off_pass_rank double National rank of the team's share of plays that were pass plays on pass plays with the team on offense, where 1 is best.
rushrate_off_pass_rank double National rank of the team's share of plays that were rush plays on pass plays with the team on offense, where 1 is best.
nonExplosiveEpaPerPlay_off_pass_rank double National rank of the team's EPA per play with explosive plays excluded on pass plays with the team on offense, where 1 is best.
line_yards_off_pass_rank double National rank of the team's average line yards credited to the offensive line on rushes on pass plays with the team on offense, where 1 is best.
opportunity_rate_off_pass_rank double National rank of the team's opportunity rate -- the share of rushes carrying the opportunity flag on pass plays with the team on offense, where 1 is best.
plays_def_pass integer Plays run on pass plays, with the team on defense (i.e. allowed to opponents).
passrate_def_pass double Share of plays that were pass plays on pass plays, with the team on defense (i.e. allowed to opponents).
rushrate_def_pass double Share of plays that were rush plays on pass plays, with the team on defense (i.e. allowed to opponents).
havoc_def_pass double Havoc rate -- the share of plays carrying the defensive-disruption flag on pass plays, with the team on defense (i.e. allowed to opponents).
explosive_def_pass double Explosive-play rate -- the share of plays carrying the explosive flag on pass plays, with the team on defense (i.e. allowed to opponents).
TEPA_def_pass double Total EPA summed over every play on pass plays, with the team on defense (i.e. allowed to opponents).
EPAplay_def_pass double EPA per play on pass plays, with the team on defense (i.e. allowed to opponents).
yards_def_pass integer Total yards gained on pass plays, with the team on defense (i.e. allowed to opponents).
yardsplay_def_pass double Yards gained per play on pass plays, with the team on defense (i.e. allowed to opponents).
play_stuffed_def_pass double Stuffed-play rate -- the share of plays carrying the stuffed flag on pass plays, with the team on defense (i.e. allowed to opponents).
success_def_pass double Success rate -- the share of plays flagged as successful by EPA on pass plays, with the team on defense (i.e. allowed to opponents).
red_zone_success_def_pass double Success rate on red-zone plays on pass plays, with the team on defense (i.e. allowed to opponents).
third_down_success_def_pass double Success rate on third-down plays on pass plays, with the team on defense (i.e. allowed to opponents).
third_down_distance_def_pass double Average yards to go on third down on pass plays, with the team on defense (i.e. allowed to opponents).
late_down_success_def_pass double Success rate on late-down plays on pass plays, with the team on defense (i.e. allowed to opponents).
early_down_EPA_def_pass double EPA per early-down play on pass plays, with the team on defense (i.e. allowed to opponents).
nonExplosiveEpaPerPlay_def_pass double EPA per play with explosive plays excluded on pass plays, with the team on defense (i.e. allowed to opponents).
line_yards_def_pass double Average line yards credited to the offensive line on rushes on pass plays, with the team on defense (i.e. allowed to opponents).
opportunity_rate_def_pass double Opportunity rate -- the share of rushes carrying the opportunity flag on pass plays, with the team on defense (i.e. allowed to opponents).
playsgame_def_pass double Plays run per game on pass plays, with the team on defense (i.e. allowed to opponents).
EPAdrive_def_pass double EPA per drive (total EPA divided by drives) on pass plays, with the team on defense (i.e. allowed to opponents).
EPAgame_def_pass double EPA per game (total EPA divided by games) on pass plays, with the team on defense (i.e. allowed to opponents).
yardsgame_def_pass double Yards gained per game on pass plays, with the team on defense (i.e. allowed to opponents).
drives_def_pass integer Offensive drives on pass plays, with the team on defense (i.e. allowed to opponents).
drivesgame_def_pass double Drives per game on pass plays, with the team on defense (i.e. allowed to opponents).
yardsdrive_def_pass double Yards gained per drive on pass plays, with the team on defense (i.e. allowed to opponents).
playsdrive_def_pass double Plays run per drive on pass plays, with the team on defense (i.e. allowed to opponents).
playsgame_def_pass_rank double National rank of the team's plays run per game on pass plays with the team on defense (i.e. allowed to opponents), where 1 is best.
TEPA_def_pass_rank double National rank of the team's total EPA summed over every play on pass plays with the team on defense (i.e. allowed to opponents), where 1 is best.
EPAgame_def_pass_rank double National rank of the team's EPA per game (total EPA divided by games) on pass plays with the team on defense (i.e. allowed to opponents), where 1 is best.
EPAplay_def_pass_rank double National rank of the team's EPA per play on pass plays with the team on defense (i.e. allowed to opponents), where 1 is best.
EPAdrive_def_pass_rank double National rank of the team's EPA per drive (total EPA divided by drives) on pass plays with the team on defense (i.e. allowed to opponents), where 1 is best.
early_down_EPA_def_pass_rank double National rank of the team's EPA per early-down play on pass plays with the team on defense (i.e. allowed to opponents), where 1 is best.
success_def_pass_rank double National rank of the team's success rate -- the share of plays flagged as successful by EPA on pass plays with the team on defense (i.e. allowed to opponents), where 1 is best.
yards_def_pass_rank double National rank of the team's total yards gained on pass plays with the team on defense (i.e. allowed to opponents), where 1 is best.
yardsplay_def_pass_rank double National rank of the team's yards gained per play on pass plays with the team on defense (i.e. allowed to opponents), where 1 is best.
yardsgame_def_pass_rank double National rank of the team's yards gained per game on pass plays with the team on defense (i.e. allowed to opponents), where 1 is best.
drivesgame_def_pass_rank double National rank of the team's drives per game on pass plays with the team on defense (i.e. allowed to opponents), where 1 is best.
yardsdrive_def_pass_rank double National rank of the team's yards gained per drive on pass plays with the team on defense (i.e. allowed to opponents), where 1 is best.
playsdrive_def_pass_rank double National rank of the team's plays run per drive on pass plays with the team on defense (i.e. allowed to opponents), where 1 is best.
play_stuffed_def_pass_rank double National rank of the team's stuffed-play rate -- the share of plays carrying the stuffed flag on pass plays with the team on defense (i.e. allowed to opponents), where 1 is best.
red_zone_success_def_pass_rank double National rank of the team's success rate on red-zone plays on pass plays with the team on defense (i.e. allowed to opponents), where 1 is best.
third_down_success_def_pass_rank double National rank of the team's success rate on third-down plays on pass plays with the team on defense (i.e. allowed to opponents), where 1 is best.
late_down_success_def_pass_rank double National rank of the team's success rate on late-down plays on pass plays with the team on defense (i.e. allowed to opponents), where 1 is best.
third_down_distance_def_pass_rank double National rank of the team's average yards to go on third down on pass plays with the team on defense (i.e. allowed to opponents), where 1 is best.
havoc_def_pass_rank double National rank of the team's havoc rate -- the share of plays carrying the defensive-disruption flag on pass plays with the team on defense (i.e. allowed to opponents), where 1 is best.
explosive_def_pass_rank double National rank of the team's explosive-play rate -- the share of plays carrying the explosive flag on pass plays with the team on defense (i.e. allowed to opponents), where 1 is best.
passrate_def_pass_rank double National rank of the team's share of plays that were pass plays on pass plays with the team on defense (i.e. allowed to opponents), where 1 is best.
rushrate_def_pass_rank double National rank of the team's share of plays that were rush plays on pass plays with the team on defense (i.e. allowed to opponents), where 1 is best.
nonExplosiveEpaPerPlay_def_pass_rank double National rank of the team's EPA per play with explosive plays excluded on pass plays with the team on defense (i.e. allowed to opponents), where 1 is best.
line_yards_def_pass_rank double National rank of the team's average line yards credited to the offensive line on rushes on pass plays with the team on defense (i.e. allowed to opponents), where 1 is best.
opportunity_rate_def_pass_rank double National rank of the team's opportunity rate -- the share of rushes carrying the opportunity flag on pass plays with the team on defense (i.e. allowed to opponents), where 1 is best.
TEPA_margin_pass double Margin in total EPA summed over every play on pass plays: the team's offensive value minus the value it allowed on defense.
EPAplay_margin_pass double Margin in EPA per play on pass plays: the team's offensive value minus the value it allowed on defense.
EPAdrive_margin_pass double Margin in EPA per drive (total EPA divided by drives) on pass plays: the team's offensive value minus the value it allowed on defense.
EPAgame_margin_pass double Margin in EPA per game (total EPA divided by games) on pass plays: the team's offensive value minus the value it allowed on defense.
success_margin_pass double Margin in success rate -- the share of plays flagged as successful by EPA on pass plays: the team's offensive value minus the value it allowed on defense.
yardsplay_margin_pass double Margin in yards gained per play on pass plays: the team's offensive value minus the value it allowed on defense.
TEPA_margin_pass_rank double Margin in total EPA summed over every play on pass plays: the team's offensive value minus the value it allowed on defense. National rank of that margin, 1 = largest.
EPAplay_margin_pass_rank double Margin in EPA per play on pass plays: the team's offensive value minus the value it allowed on defense. National rank of that margin, 1 = largest.
EPAdrive_margin_pass_rank double Margin in EPA per drive (total EPA divided by drives) on pass plays: the team's offensive value minus the value it allowed on defense. National rank of that margin, 1 = largest.
EPAgame_margin_pass_rank double Margin in EPA per game (total EPA divided by games) on pass plays: the team's offensive value minus the value it allowed on defense. National rank of that margin, 1 = largest.
success_margin_pass_rank double Margin in success rate -- the share of plays flagged as successful by EPA on pass plays: the team's offensive value minus the value it allowed on defense. National rank of that margin, 1 = largest.
yardsplay_margin_pass_rank double Margin in yards gained per play on pass plays: the team's offensive value minus the value it allowed on defense. National rank of that margin, 1 = largest.
plays_off_rush integer Plays run on rush plays, with the team on offense.
passrate_off_rush double Share of plays that were pass plays on rush plays, with the team on offense.
rushrate_off_rush double Share of plays that were rush plays on rush plays, with the team on offense.
havoc_off_rush double Havoc rate -- the share of plays carrying the defensive-disruption flag on rush plays, with the team on offense.
explosive_off_rush double Explosive-play rate -- the share of plays carrying the explosive flag on rush plays, with the team on offense.
TEPA_off_rush double Total EPA summed over every play on rush plays, with the team on offense.
EPAplay_off_rush double EPA per play on rush plays, with the team on offense.
yards_off_rush integer Total yards gained on rush plays, with the team on offense.
yardsplay_off_rush double Yards gained per play on rush plays, with the team on offense.
play_stuffed_off_rush double Stuffed-play rate -- the share of plays carrying the stuffed flag on rush plays, with the team on offense.
success_off_rush double Success rate -- the share of plays flagged as successful by EPA on rush plays, with the team on offense.
red_zone_success_off_rush double Success rate on red-zone plays on rush plays, with the team on offense.
third_down_success_off_rush double Success rate on third-down plays on rush plays, with the team on offense.
third_down_distance_off_rush double Average yards to go on third down on rush plays, with the team on offense.
late_down_success_off_rush double Success rate on late-down plays on rush plays, with the team on offense.
early_down_EPA_off_rush double EPA per early-down play on rush plays, with the team on offense.
nonExplosiveEpaPerPlay_off_rush double EPA per play with explosive plays excluded on rush plays, with the team on offense.
line_yards_off_rush double Average line yards credited to the offensive line on rushes on rush plays, with the team on offense.
opportunity_rate_off_rush double Opportunity rate -- the share of rushes carrying the opportunity flag on rush plays, with the team on offense.
playsgame_off_rush double Plays run per game on rush plays, with the team on offense.
EPAdrive_off_rush double EPA per drive (total EPA divided by drives) on rush plays, with the team on offense.
EPAgame_off_rush double EPA per game (total EPA divided by games) on rush plays, with the team on offense.
yardsgame_off_rush double Yards gained per game on rush plays, with the team on offense.
drives_off_rush integer Offensive drives on rush plays, with the team on offense.
drivesgame_off_rush double Drives per game on rush plays, with the team on offense.
yardsdrive_off_rush double Yards gained per drive on rush plays, with the team on offense.
playsdrive_off_rush double Plays run per drive on rush plays, with the team on offense.
playsgame_off_rush_rank double National rank of the team's plays run per game on rush plays with the team on offense, where 1 is best.
TEPA_off_rush_rank double National rank of the team's total EPA summed over every play on rush plays with the team on offense, where 1 is best.
EPAgame_off_rush_rank double National rank of the team's EPA per game (total EPA divided by games) on rush plays with the team on offense, where 1 is best.
EPAplay_off_rush_rank double National rank of the team's EPA per play on rush plays with the team on offense, where 1 is best.
EPAdrive_off_rush_rank double National rank of the team's EPA per drive (total EPA divided by drives) on rush plays with the team on offense, where 1 is best.
early_down_EPA_off_rush_rank double National rank of the team's EPA per early-down play on rush plays with the team on offense, where 1 is best.
success_off_rush_rank double National rank of the team's success rate -- the share of plays flagged as successful by EPA on rush plays with the team on offense, where 1 is best.
yards_off_rush_rank double National rank of the team's total yards gained on rush plays with the team on offense, where 1 is best.
yardsplay_off_rush_rank double National rank of the team's yards gained per play on rush plays with the team on offense, where 1 is best.
yardsgame_off_rush_rank double National rank of the team's yards gained per game on rush plays with the team on offense, where 1 is best.
drivesgame_off_rush_rank double National rank of the team's drives per game on rush plays with the team on offense, where 1 is best.
yardsdrive_off_rush_rank double National rank of the team's yards gained per drive on rush plays with the team on offense, where 1 is best.
playsdrive_off_rush_rank double National rank of the team's plays run per drive on rush plays with the team on offense, where 1 is best.
play_stuffed_off_rush_rank double National rank of the team's stuffed-play rate -- the share of plays carrying the stuffed flag on rush plays with the team on offense, where 1 is best.
red_zone_success_off_rush_rank double National rank of the team's success rate on red-zone plays on rush plays with the team on offense, where 1 is best.
third_down_success_off_rush_rank double National rank of the team's success rate on third-down plays on rush plays with the team on offense, where 1 is best.
late_down_success_off_rush_rank double National rank of the team's success rate on late-down plays on rush plays with the team on offense, where 1 is best.
third_down_distance_off_rush_rank double National rank of the team's average yards to go on third down on rush plays with the team on offense, where 1 is best.
havoc_off_rush_rank double National rank of the team's havoc rate -- the share of plays carrying the defensive-disruption flag on rush plays with the team on offense, where 1 is best.
explosive_off_rush_rank double National rank of the team's explosive-play rate -- the share of plays carrying the explosive flag on rush plays with the team on offense, where 1 is best.
passrate_off_rush_rank double National rank of the team's share of plays that were pass plays on rush plays with the team on offense, where 1 is best.
rushrate_off_rush_rank double National rank of the team's share of plays that were rush plays on rush plays with the team on offense, where 1 is best.
nonExplosiveEpaPerPlay_off_rush_rank double National rank of the team's EPA per play with explosive plays excluded on rush plays with the team on offense, where 1 is best.
line_yards_off_rush_rank double National rank of the team's average line yards credited to the offensive line on rushes on rush plays with the team on offense, where 1 is best.
opportunity_rate_off_rush_rank double National rank of the team's opportunity rate -- the share of rushes carrying the opportunity flag on rush plays with the team on offense, where 1 is best.
plays_def_rush integer Plays run on rush plays, with the team on defense (i.e. allowed to opponents).
passrate_def_rush double Share of plays that were pass plays on rush plays, with the team on defense (i.e. allowed to opponents).
rushrate_def_rush double Share of plays that were rush plays on rush plays, with the team on defense (i.e. allowed to opponents).
havoc_def_rush double Havoc rate -- the share of plays carrying the defensive-disruption flag on rush plays, with the team on defense (i.e. allowed to opponents).
explosive_def_rush double Explosive-play rate -- the share of plays carrying the explosive flag on rush plays, with the team on defense (i.e. allowed to opponents).
TEPA_def_rush double Total EPA summed over every play on rush plays, with the team on defense (i.e. allowed to opponents).
EPAplay_def_rush double EPA per play on rush plays, with the team on defense (i.e. allowed to opponents).
yards_def_rush integer Total yards gained on rush plays, with the team on defense (i.e. allowed to opponents).
yardsplay_def_rush double Yards gained per play on rush plays, with the team on defense (i.e. allowed to opponents).
play_stuffed_def_rush double Stuffed-play rate -- the share of plays carrying the stuffed flag on rush plays, with the team on defense (i.e. allowed to opponents).
success_def_rush double Success rate -- the share of plays flagged as successful by EPA on rush plays, with the team on defense (i.e. allowed to opponents).
red_zone_success_def_rush double Success rate on red-zone plays on rush plays, with the team on defense (i.e. allowed to opponents).
third_down_success_def_rush double Success rate on third-down plays on rush plays, with the team on defense (i.e. allowed to opponents).
third_down_distance_def_rush double Average yards to go on third down on rush plays, with the team on defense (i.e. allowed to opponents).
late_down_success_def_rush double Success rate on late-down plays on rush plays, with the team on defense (i.e. allowed to opponents).
early_down_EPA_def_rush double EPA per early-down play on rush plays, with the team on defense (i.e. allowed to opponents).
nonExplosiveEpaPerPlay_def_rush double EPA per play with explosive plays excluded on rush plays, with the team on defense (i.e. allowed to opponents).
line_yards_def_rush double Average line yards credited to the offensive line on rushes on rush plays, with the team on defense (i.e. allowed to opponents).
opportunity_rate_def_rush double Opportunity rate -- the share of rushes carrying the opportunity flag on rush plays, with the team on defense (i.e. allowed to opponents).
playsgame_def_rush double Plays run per game on rush plays, with the team on defense (i.e. allowed to opponents).
EPAdrive_def_rush double EPA per drive (total EPA divided by drives) on rush plays, with the team on defense (i.e. allowed to opponents).
EPAgame_def_rush double EPA per game (total EPA divided by games) on rush plays, with the team on defense (i.e. allowed to opponents).
yardsgame_def_rush double Yards gained per game on rush plays, with the team on defense (i.e. allowed to opponents).
drives_def_rush integer Offensive drives on rush plays, with the team on defense (i.e. allowed to opponents).
drivesgame_def_rush double Drives per game on rush plays, with the team on defense (i.e. allowed to opponents).
yardsdrive_def_rush double Yards gained per drive on rush plays, with the team on defense (i.e. allowed to opponents).
playsdrive_def_rush double Plays run per drive on rush plays, with the team on defense (i.e. allowed to opponents).
playsgame_def_rush_rank double National rank of the team's plays run per game on rush plays with the team on defense (i.e. allowed to opponents), where 1 is best.
TEPA_def_rush_rank double National rank of the team's total EPA summed over every play on rush plays with the team on defense (i.e. allowed to opponents), where 1 is best.
EPAgame_def_rush_rank double National rank of the team's EPA per game (total EPA divided by games) on rush plays with the team on defense (i.e. allowed to opponents), where 1 is best.
EPAplay_def_rush_rank double National rank of the team's EPA per play on rush plays with the team on defense (i.e. allowed to opponents), where 1 is best.
EPAdrive_def_rush_rank double National rank of the team's EPA per drive (total EPA divided by drives) on rush plays with the team on defense (i.e. allowed to opponents), where 1 is best.
early_down_EPA_def_rush_rank double National rank of the team's EPA per early-down play on rush plays with the team on defense (i.e. allowed to opponents), where 1 is best.
success_def_rush_rank double National rank of the team's success rate -- the share of plays flagged as successful by EPA on rush plays with the team on defense (i.e. allowed to opponents), where 1 is best.
yards_def_rush_rank double National rank of the team's total yards gained on rush plays with the team on defense (i.e. allowed to opponents), where 1 is best.
yardsplay_def_rush_rank double National rank of the team's yards gained per play on rush plays with the team on defense (i.e. allowed to opponents), where 1 is best.
yardsgame_def_rush_rank double National rank of the team's yards gained per game on rush plays with the team on defense (i.e. allowed to opponents), where 1 is best.
drivesgame_def_rush_rank double National rank of the team's drives per game on rush plays with the team on defense (i.e. allowed to opponents), where 1 is best.
yardsdrive_def_rush_rank double National rank of the team's yards gained per drive on rush plays with the team on defense (i.e. allowed to opponents), where 1 is best.
playsdrive_def_rush_rank double National rank of the team's plays run per drive on rush plays with the team on defense (i.e. allowed to opponents), where 1 is best.
play_stuffed_def_rush_rank double National rank of the team's stuffed-play rate -- the share of plays carrying the stuffed flag on rush plays with the team on defense (i.e. allowed to opponents), where 1 is best.
red_zone_success_def_rush_rank double National rank of the team's success rate on red-zone plays on rush plays with the team on defense (i.e. allowed to opponents), where 1 is best.
third_down_success_def_rush_rank double National rank of the team's success rate on third-down plays on rush plays with the team on defense (i.e. allowed to opponents), where 1 is best.
late_down_success_def_rush_rank double National rank of the team's success rate on late-down plays on rush plays with the team on defense (i.e. allowed to opponents), where 1 is best.
third_down_distance_def_rush_rank double National rank of the team's average yards to go on third down on rush plays with the team on defense (i.e. allowed to opponents), where 1 is best.
havoc_def_rush_rank double National rank of the team's havoc rate -- the share of plays carrying the defensive-disruption flag on rush plays with the team on defense (i.e. allowed to opponents), where 1 is best.
explosive_def_rush_rank double National rank of the team's explosive-play rate -- the share of plays carrying the explosive flag on rush plays with the team on defense (i.e. allowed to opponents), where 1 is best.
passrate_def_rush_rank double National rank of the team's share of plays that were pass plays on rush plays with the team on defense (i.e. allowed to opponents), where 1 is best.
rushrate_def_rush_rank double National rank of the team's share of plays that were rush plays on rush plays with the team on defense (i.e. allowed to opponents), where 1 is best.
nonExplosiveEpaPerPlay_def_rush_rank double National rank of the team's EPA per play with explosive plays excluded on rush plays with the team on defense (i.e. allowed to opponents), where 1 is best.
line_yards_def_rush_rank double National rank of the team's average line yards credited to the offensive line on rushes on rush plays with the team on defense (i.e. allowed to opponents), where 1 is best.
opportunity_rate_def_rush_rank double National rank of the team's opportunity rate -- the share of rushes carrying the opportunity flag on rush plays with the team on defense (i.e. allowed to opponents), where 1 is best.
TEPA_margin_rush double Margin in total EPA summed over every play on rush plays: the team's offensive value minus the value it allowed on defense.
EPAplay_margin_rush double Margin in EPA per play on rush plays: the team's offensive value minus the value it allowed on defense.
EPAdrive_margin_rush double Margin in EPA per drive (total EPA divided by drives) on rush plays: the team's offensive value minus the value it allowed on defense.
EPAgame_margin_rush double Margin in EPA per game (total EPA divided by games) on rush plays: the team's offensive value minus the value it allowed on defense.
success_margin_rush double Margin in success rate -- the share of plays flagged as successful by EPA on rush plays: the team's offensive value minus the value it allowed on defense.
yardsplay_margin_rush double Margin in yards gained per play on rush plays: the team's offensive value minus the value it allowed on defense.
TEPA_margin_rush_rank double Margin in total EPA summed over every play on rush plays: the team's offensive value minus the value it allowed on defense. National rank of that margin, 1 = largest.
EPAplay_margin_rush_rank double Margin in EPA per play on rush plays: the team's offensive value minus the value it allowed on defense. National rank of that margin, 1 = largest.
EPAdrive_margin_rush_rank double Margin in EPA per drive (total EPA divided by drives) on rush plays: the team's offensive value minus the value it allowed on defense. National rank of that margin, 1 = largest.
EPAgame_margin_rush_rank double Margin in EPA per game (total EPA divided by games) on rush plays: the team's offensive value minus the value it allowed on defense. National rank of that margin, 1 = largest.
success_margin_rush_rank double Margin in success rate -- the share of plays flagged as successful by EPA on rush plays: the team's offensive value minus the value it allowed on defense. National rank of that margin, 1 = largest.
yardsplay_margin_rush_rank double Margin in yards gained per play on rush plays: the team's offensive value minus the value it allowed on defense. National rank of that margin, 1 = largest.
fbs_class character Power/Group classification for the season: P4 or G6 from 2024 on, P5 or G5 through 2023, derived from conference membership (Notre Dame is classified with the power group). Null for teams outside FBS.
valid_games integer Number of the team's games that produced both an offensive and a defensive adjusted-EPA value; teams below two valid games are dropped from the adjusted ratings.
adj_off_epa double Offensive opponent-adjusted EPA per play from the ridge (RAPM-style) regression on offense/defense team indicators plus home field -- cfbfastR's adjust_epa adjustment, fit in-sample across the season, so the value is descriptive of that window rather than predictive.
adj_def_epa double Defensive opponent-adjusted EPA per play from the ridge (RAPM-style) regression on offense/defense team indicators plus home field -- cfbfastR's adjust_epa adjustment, fit in-sample across the season, so the value is descriptive of that window rather than predictive. Lower is better -- it is EPA allowed.
off_strength_faced double Average opponent-defense strength the team's offense faced, taken as the mean of the ridge's defensive coefficients across its opponents. Higher means a tougher slate.
def_strength_faced double Average opponent-offense strength the team's defense faced, taken as the mean of the ridge's offensive coefficients across its opponents. Higher means a tougher slate.
net_adj_epa double Net opponent-adjusted EPA per play: adj_off_epa minus adj_def_epa. Higher is better.
adj_off_epa_rank double National rank of the team's adj_off_epa, where 1 is best.
adj_def_epa_rank double National rank of the team's adj_def_epa, where 1 is best (fewest EPA allowed).
net_adj_epa_rank double National rank of the team's net_adj_epa, 1 = largest net adjusted EPA.
through_week integer Regular-season week this cumulative snapshot covers -- the row reflects the team's state through the end of that week. One asset holds every week, so filter on this column.

Author(s)

Saiem Gilani

Examples


  try(load_cfb_team_summaries_weekly(2004))

Load college football team talent composite from the SportsDataverse data repo

Description

Loads the 247Sports team talent composite – one row per team-season. Published to the cfb_team_talent release tag on the sportsdataverse-data repo.

Usage

load_cfb_team_talent(
  seasons = most_recent_cfb_season(),
  ...,
  dbConnection = NULL,
  tablename = NULL
)

Arguments

seasons

A vector of 4-digit years associated with given college football seasons. Published coverage runs 2005 through the most recent season. Pass seasons = TRUE for every published season. (Min: 2005)

...

Additional arguments passed to an underlying function that writes the season data into a database.

dbConnection

A DBIConnection object, as returned by DBI::dbConnect()

tablename

The name of the data table within the database

Value

Returns a cfbfastR_data tibble.

col_name types description
season integer
team_id integer
team character
talent_composite double
talent_rank integer
blue_chip_ratio double
n_recruits integer

Author(s)

Saiem Gilani

Examples


  try(load_cfb_team_talent(2005))

Load CFB team info from the data repo

Description

Loads team information including colors and logos - useful for plots! This function wraps the cfbd_team_info() function sourced from the College Football Data API.

Usage

load_cfb_teams(fbs_only = TRUE)

Arguments

fbs_only

if TRUE, returns only FBS teams, otherwise returns all teams in the dataset

Value

A tibble of team-level image URLs and hex color codes.

See Also

cfbd_team_info()

Issues with this data should be filed here: https://github.com/sportsdataverse/cfbfastR-data

Other loaders: load_cfb_pbp(), load_cfb_rosters(), load_cfb_schedules(), update_cfb_db()

Examples


  try(load_cfb_teams())

Load college football team id crosswalk from the SportsDataverse data repo

Description

Loads the team-level id crosswalk linking CFBD team ids to ESPN team ids – one row per team-season. Published to the cfb_crosswalk release tag on the sportsdataverse-data repo.

Usage

load_cfb_teams_crosswalk(
  seasons = most_recent_cfb_season(),
  ...,
  dbConnection = NULL,
  tablename = NULL
)

Arguments

seasons

A vector of 4-digit years associated with given college football seasons. Published coverage runs 2014 through the most recent season. Pass seasons = TRUE for every published season. (Min: 2014)

...

Additional arguments passed to an underlying function that writes the season data into a database.

dbConnection

A DBIConnection object, as returned by DBI::dbConnect()

tablename

The name of the data table within the database

Value

Returns a cfbfastR_data tibble.

col_name types description
norm_key character Shared join key across providers: the team name lowercased, ASCII-folded, stripped of punctuation, whitespace-collapsed, and alias-mapped.
espn_team_id integer ESPN team id for the crosswalk row.
espn_team character ESPN's full team display name, school plus mascot, null when the row was anchored on a non-ESPN provider.
espn_abbreviation character
fox_team_id character Fox Sports team id for the same team.
fox_team character Fox Sports' team name, which that feed ships in all capitals.
fox_abbreviation character Fox Sports' short team code, which frequently differs from the ESPN abbreviation for the same school.
yahoo_team_id character Yahoo Sports team id for the same team.
yahoo_team character Yahoo Sports' team display name, school plus mascot.
yahoo_abbreviation character Yahoo Sports' short team code for the school.
matched_sources character Plus-joined provenance tag naming which of espn, fox, and yahoo contributed a directory row for this team.

Author(s)

Saiem Gilani

Examples


  try(load_cfb_teams_crosswalk(2014))

Load college football advanced defensive from the SportsDataverse data repo

Description

Loads season-level advanced defensive team stats – one row per defense with havoc, TFL, drive-stop, and pass-rush aggregates. Published to the espn_cfb_adv_defensive release tag on the sportsdataverse-data repo.

Usage

load_espn_cfb_adv_defensive(
  seasons = most_recent_cfb_season(),
  ...,
  dbConnection = NULL,
  tablename = NULL
)

Arguments

seasons

A vector of 4-digit years associated with given college football seasons. Published coverage runs 2004 through the most recent season. Pass seasons = TRUE for every published season. (Min: 2004)

...

Additional arguments passed to an underlying function that writes the season data into a database.

dbConnection

A DBIConnection object, as returned by DBI::dbConnect()

tablename

The name of the data table within the database

Value

Returns a cfbfastR_data tibble.

col_name types description
def_pos_team_id integer ESPN team id of the team on defense. Present for every season 2004+.
def_pos_team character
scrimmage_plays integer Number of plays from scrimmage (rushes plus passes), excluding special teams.
TFL integer Count of scrimmage plays the defense held to negative yardage (non-penalty, non-special-teams, ESPN statYardage below zero) plus every sack.
TFL_pass integer The TFL count restricted to plays classified as passes, so it covers sacks together with completions and laterals stopped behind the line.
TFL_rush integer The TFL count restricted to plays classified as rushes, that is rushing attempts the defense stopped for negative yardage.
havoc_total integer
havoc_total_rate double Share of the defense's scrimmage plays producing a havoc event, a 0-to-1 fraction equal to havoc_total divided by scrimmage_plays.
fumbles integer Fumbles the defense forced, counted from plays whose narrative contains the phrase forced by, not the total number of fumbles on the play.
def_int integer Interceptions the defense recorded, counted from plays ESPN types as Interception Return or Interception Return Touchdown.
drive_stopped_rate double Percentage from 0 to 100 of the defense's scrimmage plays that occurred on drives ending in a punt, fumble, interception, or turnover on downs; the denominator is plays, not drives.
num_pass_plays integer Number of pass scrimmage plays the defense faced, the denominator behind havoc_total_pass_rate and sacks_rate.
havoc_total_pass integer Havoc events (tackle for loss, sack, interception, forced fumble, or pass breakup) recorded on the pass plays the defense faced.
havoc_total_pass_rate double havoc_total_pass divided by num_pass_plays, the defense's havoc rate against the pass as a 0-to-1 fraction.
sacks integer
sacks_rate double Sacks divided by pass plays faced, the defense's per-pass-play sack rate as a 0-to-1 fraction.
pass_breakups integer Passes the defense broke up, counted from plays whose narrative contains the phrase broken up by.
havoc_total_rush integer Havoc events recorded on the rush plays the defense faced, in practice tackles for loss and forced fumbles.
havoc_total_rush_rate double Havoc events per rush play faced, the mean of the havoc flag over the defense's rush scrimmage plays.
game_id integer
season integer
week integer

Author(s)

Saiem Gilani

Examples


  try(load_espn_cfb_adv_defensive(2004))

Load college football advanced defensive players from the SportsDataverse data repo

Description

Loads season-level advanced defensive player stats – one row per player with tackles, TFL, sacks, pressures, and coverage counting stats. Published to the espn_cfb_adv_defensive_players release tag on the sportsdataverse-data repo.

Usage

load_espn_cfb_adv_defensive_players(
  seasons = most_recent_cfb_season(),
  ...,
  dbConnection = NULL,
  tablename = NULL
)

Arguments

seasons

A vector of 4-digit years associated with given college football seasons. Published coverage runs 2004 through the most recent season. Pass seasons = TRUE for every published season. (Min: 2004)

...

Additional arguments passed to an underlying function that writes the season data into a database.

dbConnection

A DBIConnection object, as returned by DBI::dbConnect()

tablename

The name of the data table within the database

Value

Returns a cfbfastR_data tibble.

col_name types description
def_pos_team_id integer ESPN team id of the team on defense. Present for every season 2004+.
def_pos_team character Display name of the team on defense (e.g. 'Ohio State Buckeyes'). Held an ESPN team id until the 2026-08 republish; the id now lives in def_pos_team_id.
player_name character Display name of the defender.
sacks integer Sacks recorded by the defender. Available from 2005 on; null for 2004.
sacks_yards integer Yards lost by the offense on the defender's sacks. Available from 2005 on; null for 2004.
fumble_recoveries integer Fumbles recovered by the defender. Available for every season 2004+.
fumble_recoveries_yards integer Yards returned on the defender's fumble recoveries. Available for every season 2004+.
game_id integer
season integer
week integer
pass_breakups integer Passes broken up by the defender. Available from 2005 on; null for 2004.
interceptions integer Passes intercepted by the defender. Available from 2014 on; null for 2004-2013, which ESPN ships without interception statistics in this block.
interceptions_yards integer Yards returned on the defender's interceptions. Available from 2014 on; null for 2004-2013.
forced_fumbles integer Fumbles forced by the defender. Available from 2005 on; null for 2004, which ESPN ships with only the fumble-recovery statistics.

Author(s)

Saiem Gilani

Examples


  try(load_espn_cfb_adv_defensive_players(2004))

Load college football advanced drives from the SportsDataverse data repo

Description

Loads season-level advanced drive aggregates – one row per team with drive-level scoring, efficiency, and field-position splits. Published to the espn_cfb_adv_drives release tag on the sportsdataverse-data repo.

Usage

load_espn_cfb_adv_drives(
  seasons = most_recent_cfb_season(),
  ...,
  dbConnection = NULL,
  tablename = NULL
)

Arguments

seasons

A vector of 4-digit years associated with given college football seasons. Published coverage runs 2004 through the most recent season. Pass seasons = TRUE for every published season. (Min: 2004)

...

Additional arguments passed to an underlying function that writes the season data into a database.

dbConnection

A DBIConnection object, as returned by DBI::dbConnect()

tablename

The name of the data table within the database

Value

Returns a cfbfastR_data tibble.

col_name types description
pos_team_id integer ESPN team id of the team on offense. Present for every season 2004+.
pos_team character
drive_total_available_yards double Sum of each drive's starting distance to the opponent end zone taken across every scrimmage play, so a drive contributes its available yards once per play rather than once per drive.
drive_total_gained_yards integer Sum of ESPN's per-drive yardage repeated across every scrimmage play of that drive, so a drive contributes its yardage once per play.
avg_field_position double Mean distance to the opponent end zone at drive start averaged over the team's scrimmage plays, exactly drive_total_available_yards divided by that play count.
plays_per_drive double Mean of ESPN's per-drive offensivePlays taken over plays rather than over drives, which weights every drive by its own length.
yards_per_drive double Mean of ESPN's per-drive yardage taken over plays rather than over drives, exactly drive_total_gained_yards divided by the team's scrimmage-play count.
drives integer Number of distinct ESPN drive ids on which the team ran at least one scrimmage play.
drive_total_gained_yards_rate double Available-yards conversion as a percentage, 100 times drive_total_gained_yards over drive_total_available_yards with both sums play-weighted.
game_id integer
season integer
week integer

Author(s)

Saiem Gilani

Examples


  try(load_espn_cfb_adv_drives(2004))

Load college football advanced passing from the SportsDataverse data repo

Description

Loads season-level advanced passing stats – one row per qualifying passer with EPA, CPOE, air-yards, and pressure splits. Published to the espn_cfb_adv_passing release tag on the sportsdataverse-data repo.

Usage

load_espn_cfb_adv_passing(
  seasons = most_recent_cfb_season(),
  ...,
  dbConnection = NULL,
  tablename = NULL
)

Arguments

seasons

A vector of 4-digit years associated with given college football seasons. Published coverage runs 2004 through the most recent season. Pass seasons = TRUE for every published season. (Min: 2004)

...

Additional arguments passed to an underlying function that writes the season data into a database.

dbConnection

A DBIConnection object, as returned by DBI::dbConnect()

tablename

The name of the data table within the database

Value

Returns a cfbfastR_data tibble.

col_name types description
pos_team_id integer ESPN team id of the team on offense. Present for every season 2004+.
pos_team character
passer_player_name character Display name of the passer -- the FIRST participant in that role on the play.
Comp integer Completed passes recorded in the advanced box score.
Att integer Pass attempts recorded in the advanced box score.
xComp double Expected completions, summed from the per-play completion model.
Yds double Passing yards from the advanced box score.
Pass_TD integer Passing touchdowns.
Int integer Interceptions thrown.
YPA double Yards per pass attempt.
EPA double
EPA_per_Play double EPA per play on the passer's plays.
WPA double
SR double Success rate on the passer's plays.
Sck integer Times the passer was sacked.
CompPct double Completion percentage from the advanced box score.
xCompPct double Expected completion percentage from the per-play completion model.
CPOE double Completion percentage over expected -- actual minus modelled completion rate.
qbr_epa double EPA variant used as an input to the QBR calculation.
sack_epa double EPA credited to the player's sacks taken.
pass_epa double EPA credited to the player's pass plays.
rush_epa double EPA credited to the player's rush plays.
pen_epa double EPA attributable to penalties on the player's plays.
spread double
era0 integer Rule-era indicator for the earliest modelled era.
era1 integer Rule-era indicator for the second modelled era.
era2 integer Rule-era indicator for the third modelled era.
era3 integer Rule-era indicator for the most recent modelled era.
exp_qbr double Expected QBR for the passer.
game_id integer
season integer
week integer

Author(s)

Saiem Gilani

Examples


  try(load_espn_cfb_adv_passing(2004))

Load college football advanced receiving from the SportsDataverse data repo

Description

Loads season-level advanced receiving stats – one row per qualifying receiver with target share, EPA per target, and YAC splits. Published to the espn_cfb_adv_receiving release tag on the sportsdataverse-data repo.

Usage

load_espn_cfb_adv_receiving(
  seasons = most_recent_cfb_season(),
  ...,
  dbConnection = NULL,
  tablename = NULL
)

Arguments

seasons

A vector of 4-digit years associated with given college football seasons. Published coverage runs 2004 through the most recent season. Pass seasons = TRUE for every published season. (Min: 2004)

...

Additional arguments passed to an underlying function that writes the season data into a database.

dbConnection

A DBIConnection object, as returned by DBI::dbConnect()

tablename

The name of the data table within the database

Value

Returns a cfbfastR_data tibble.

col_name types description
pos_team_id integer ESPN team id of the team on offense. Present for every season 2004+.
pos_team character
receiver_player_name character Display name of the targeted receiver -- the FIRST participant in that role on the play.
Rec integer Receptions credited to the receiver, the number of completions on plays where this player was the targeted receiver.
Tar integer Times the player was targeted on a pass attempt, the denominator behind YPT.
Yds double Passing yards from the advanced box score.
Rec_TD integer Receiving touchdowns, the count of the player's targeted plays that ended in a passing touchdown.
YPT double Receiving yards per target, the mean of receiving yardage over every target rather than over receptions only.
EPA double
EPA_per_Play double EPA per play on the passer's plays.
WPA double
SR double Success rate on the passer's plays.
Fum integer Count of the receiver's targeted pass plays whose text mentions a fumble; it is a play-level flag, not a fumble charged to this player.
Fum_Lost integer Count of the receiver's targeted plays on which a fumble was lost to the opponent.
game_id integer
season integer
week integer

Author(s)

Saiem Gilani

Examples


  try(load_espn_cfb_adv_receiving(2004))

Load college football advanced rushing from the SportsDataverse data repo

Description

Loads season-level advanced rushing stats – one row per qualifying rusher with EPA per rush, success rate, and yardage-band splits. Published to the espn_cfb_adv_rushing release tag on the sportsdataverse-data repo.

Usage

load_espn_cfb_adv_rushing(
  seasons = most_recent_cfb_season(),
  ...,
  dbConnection = NULL,
  tablename = NULL
)

Arguments

seasons

A vector of 4-digit years associated with given college football seasons. Published coverage runs 2004 through the most recent season. Pass seasons = TRUE for every published season. (Min: 2004)

...

Additional arguments passed to an underlying function that writes the season data into a database.

dbConnection

A DBIConnection object, as returned by DBI::dbConnect()

tablename

The name of the data table within the database

Value

Returns a cfbfastR_data tibble.

col_name types description
pos_team_id integer ESPN team id of the team on offense. Present for every season 2004+.
pos_team character
rusher_player_name character Display name of the ball carrier on a rush -- the FIRST participant in that role on the play.
Car integer Rushing attempts credited to this ball carrier in the game.
Yds double Passing yards from the advanced box score.
Rush_TD integer Rushing touchdowns scored by this ball carrier in the game.
YPC double Yards per carry, the mean rushing yardage across the player's attempts in the game.
EPA double
EPA_per_Play double EPA per play on the passer's plays.
WPA double
SR double Success rate on the passer's plays.
Fum integer Count of the carrier's rush attempts whose play text mentions a fumble; it is a play-level flag, not a fumble charged to this player.
Fum_Lost integer Count of the carrier's rush attempts on which a fumble was lost to the opponent.
game_id integer
season integer
week integer

Author(s)

Saiem Gilani

Examples


  try(load_espn_cfb_adv_rushing(2004))

Load college football advanced situational from the SportsDataverse data repo

Description

Loads season-level situational splits – one row per team-situation (down, distance band, field zone, game state) with EPA and success aggregates. Published to the espn_cfb_adv_situational release tag on the sportsdataverse-data repo.

Usage

load_espn_cfb_adv_situational(
  seasons = most_recent_cfb_season(),
  ...,
  dbConnection = NULL,
  tablename = NULL
)

Arguments

seasons

A vector of 4-digit years associated with given college football seasons. Published coverage runs 2004 through the most recent season. Pass seasons = TRUE for every published season. (Min: 2004)

...

Additional arguments passed to an underlying function that writes the season data into a database.

dbConnection

A DBIConnection object, as returned by DBI::dbConnect()

tablename

The name of the data table within the database

Value

Returns a cfbfastR_data tibble.

col_name types description
pos_team_id integer ESPN team id of the team on offense. Present for every season 2004+.
pos_team character Display name of the team on offense (e.g. 'Ohio State Buckeyes').
EPA_success integer Count of successful plays. Despite the EPA_ prefix this is a play COUNT, not an EPA total.
EPA_success_rate double Success rate -- the share of those plays ESPN scored as successful.
EPA_success_pass integer Count of successful plays on pass plays. Despite the EPA_ prefix this is a play COUNT, not an EPA total.
EPA_success_pass_rate double Success rate on pass plays -- the share of those plays ESPN scored as successful.
EPA_success_rush integer Count of successful plays on rush plays. Despite the EPA_ prefix this is a play COUNT, not an EPA total.
EPA_success_rush_rate double Success rate on rush plays -- the share of those plays ESPN scored as successful.
EPA_success_rz integer Count of successful plays on the red zone. Despite the EPA_ prefix this is a play COUNT, not an EPA total.
EPA_success_rate_rz double Success rate on the red zone -- the share of those plays ESPN scored as successful.
EPA_success_third integer Count of successful plays on third down. Despite the EPA_ prefix this is a play COUNT, not an EPA total.
EPA_success_rate_third double Success rate on third down -- the share of those plays ESPN scored as successful.
EPA_success_early_down integer Count of successful plays on early downs. Despite the EPA_ prefix this is a play COUNT, not an EPA total.
EPA_success_early_down_rate double Success rate on early downs -- the share of those plays ESPN scored as successful.
early_downs integer Number of plays the team ran on early downs.
early_down_pass_rate double Share of the team's plays on early downs that were pass plays.
early_down_rush_rate double Share of the team's plays on early downs that were rush plays.
EPA_early_down double Total EPA the team generated on early downs.
EPA_early_down_per_play double EPA per play on early downs.
early_down_first_down integer Number of early-down plays that produced a first down.
early_down_first_down_rate double Share of early-down plays that produced a first down.
early_down_pass integer Number of pass plays the team ran on early downs.
EPA_early_down_pass double Total EPA the team generated on early downs on pass plays.
EPA_early_down_pass_per_play double EPA per play on early downs on pass plays.
EPA_success_early_down_pass integer Count of successful plays on early downs on pass plays. Despite the EPA_ prefix this is a play COUNT, not an EPA total.
EPA_success_early_down_pass_rate double Success rate on early downs on pass plays -- the share of those plays ESPN scored as successful.
early_down_rush integer Number of rush plays the team ran on early downs.
EPA_early_down_rush double Total EPA the team generated on early downs on rush plays.
EPA_early_down_rush_per_play double EPA per play on early downs on rush plays.
EPA_success_early_down_rush integer Count of successful plays on early downs on rush plays. Despite the EPA_ prefix this is a play COUNT, not an EPA total.
EPA_success_early_down_rush_rate double Success rate on early downs on rush plays -- the share of those plays ESPN scored as successful.
middle_8 integer Number of plays the team ran in the middle eight -- the closing minutes of the first half and opening minutes of the second.
middle_8_pass_rate double Share of the team's plays on the middle eight -- the closing minutes of the first half and opening minutes of the second that were pass plays.
middle_8_rush_rate double Share of the team's plays on the middle eight -- the closing minutes of the first half and opening minutes of the second that were rush plays.
EPA_middle_8 double Total EPA the team generated on the middle eight -- the closing minutes of the first half and opening minutes of the second.
EPA_middle_8_per_play double EPA per play on the middle eight -- the closing minutes of the first half and opening minutes of the second.
EPA_middle_8_success integer Count of successful plays on the middle eight -- the closing minutes of the first half and opening minutes of the second. Despite the EPA_ prefix this is a play COUNT, not an EPA total.
EPA_middle_8_success_rate double Success rate on the middle eight -- the closing minutes of the first half and opening minutes of the second -- the share of those plays ESPN scored as successful.
middle_8_pass integer Number of pass plays the team ran on the middle eight -- the closing minutes of the first half and opening minutes of the second.
EPA_middle_8_pass double Total EPA the team generated on the middle eight -- the closing minutes of the first half and opening minutes of the second on pass plays.
EPA_middle_8_pass_per_play double EPA per play on the middle eight -- the closing minutes of the first half and opening minutes of the second on pass plays.
EPA_middle_8_success_pass integer Count of successful plays on the middle eight -- the closing minutes of the first half and opening minutes of the second on pass plays. Despite the EPA_ prefix this is a play COUNT, not an EPA total.
EPA_middle_8_success_pass_rate double Success rate on the middle eight -- the closing minutes of the first half and opening minutes of the second on pass plays -- the share of those plays ESPN scored as successful.
middle_8_rush integer Number of rush plays the team ran on the middle eight -- the closing minutes of the first half and opening minutes of the second.
EPA_middle_8_rush double Total EPA the team generated on the middle eight -- the closing minutes of the first half and opening minutes of the second on rush plays.
EPA_middle_8_rush_per_play double EPA per play on the middle eight -- the closing minutes of the first half and opening minutes of the second on rush plays.
EPA_middle_8_success_rush integer Count of successful plays on the middle eight -- the closing minutes of the first half and opening minutes of the second on rush plays. Despite the EPA_ prefix this is a play COUNT, not an EPA total.
EPA_middle_8_success_rush_rate double Success rate on the middle eight -- the closing minutes of the first half and opening minutes of the second on rush plays -- the share of those plays ESPN scored as successful.
EPA_success_late_down integer Count of successful plays on late downs. Despite the EPA_ prefix this is a play COUNT, not an EPA total.
EPA_success_late_down_pass integer Count of successful plays on late downs on pass plays. Despite the EPA_ prefix this is a play COUNT, not an EPA total.
EPA_success_late_down_rush integer Count of successful plays on late downs on rush plays. Despite the EPA_ prefix this is a play COUNT, not an EPA total.
late_downs integer Number of plays the team ran on late downs.
late_down_pass integer Number of pass plays the team ran on late downs.
late_down_rush integer Number of rush plays the team ran on late downs.
EPA_late_down double Total EPA the team generated on late downs.
EPA_late_down_per_play double EPA per play on late downs.
EPA_success_late_down_rate double Success rate on late downs -- the share of those plays ESPN scored as successful.
EPA_success_late_down_pass_rate double Success rate on late downs on pass plays -- the share of those plays ESPN scored as successful.
EPA_success_late_down_rush_rate double Success rate on late downs on rush plays -- the share of those plays ESPN scored as successful.
late_down_pass_rate double Share of the team's plays on late downs that were pass plays.
late_down_rush_rate double Share of the team's plays on late downs that were rush plays.
EPA_success_standard_down integer Count of successful plays on standard downs (the team ahead of schedule for the series). Despite the EPA_ prefix this is a play COUNT, not an EPA total.
EPA_success_standard_down_rate double Success rate on standard downs (the team ahead of schedule for the series) -- the share of those plays ESPN scored as successful.
EPA_standard_down double Total EPA the team generated on standard downs (the team ahead of schedule for the series).
EPA_standard_down_per_play double EPA per play on standard downs (the team ahead of schedule for the series).
standard_downs integer Number of plays the team ran on standard downs (the team ahead of schedule for the series).
EPA_success_passing_down integer Count of successful plays on passing downs (the team behind schedule for the series). Despite the EPA_ prefix this is a play COUNT, not an EPA total.
EPA_success_passing_down_rate double Success rate on passing downs (the team behind schedule for the series) -- the share of those plays ESPN scored as successful.
EPA_passing_down double Total EPA the team generated on passing downs (the team behind schedule for the series).
EPA_passing_down_per_play double EPA per play on passing downs (the team behind schedule for the series).
passing_downs integer Number of plays the team ran on passing downs (the team behind schedule for the series).
game_id integer
season integer
week integer

Author(s)

Saiem Gilani

Examples


  try(load_espn_cfb_adv_situational(2004))

Load college football advanced specialists from the SportsDataverse data repo

Description

Loads season-level specialist stats – one row per kicker/punter/returner with kicking EPA, field-goal profile, and return aggregates. Published to the espn_cfb_adv_specialists release tag on the sportsdataverse-data repo.

Usage

load_espn_cfb_adv_specialists(
  seasons = most_recent_cfb_season(),
  ...,
  dbConnection = NULL,
  tablename = NULL
)

Arguments

seasons

A vector of 4-digit years associated with given college football seasons. Published coverage runs 2004 through the most recent season. Pass seasons = TRUE for every published season. (Min: 2004)

...

Additional arguments passed to an underlying function that writes the season data into a database.

dbConnection

A DBIConnection object, as returned by DBI::dbConnect()

tablename

The name of the data table within the database

Value

Returns a cfbfastR_data tibble.

col_name types description
pos_team_id integer ESPN team id of the team on offense. Present for every season 2004+.
pos_team character
player_name character
field_goals integer Number of field-goal attempts.
field_goals_yards integer Sum of the field-goal attempt distances parsed out of the play text; it stays at zero when no distance could be parsed from the narrative.
punts integer Punts attempted.
punts_yards integer Total gross punt yardage parsed from the play text for this punter, working out to roughly 42 yards per punt league-wide.
kick_returns integer
kick_returns_yards integer Total yards the team gained returning kickoffs.
punt_returns integer
punt_returns_yards integer Total punt-return yardage credited to this returner, with fair catches, downed punts, and out-of-bounds punts scored as zero.
game_id integer
season integer
week integer

Author(s)

Saiem Gilani

Examples


  try(load_espn_cfb_adv_specialists(2004))

Load college football advanced team from the SportsDataverse data repo

Description

Loads season-level advanced team stats – one row per team with the offense/defense EPA, success, explosiveness, and havoc profile. Published to the espn_cfb_adv_team release tag on the sportsdataverse-data repo.

Usage

load_espn_cfb_adv_team(
  seasons = most_recent_cfb_season(),
  ...,
  dbConnection = NULL,
  tablename = NULL
)

Arguments

seasons

A vector of 4-digit years associated with given college football seasons. Published coverage runs 2004 through the most recent season. Pass seasons = TRUE for every published season. (Min: 2004)

...

Additional arguments passed to an underlying function that writes the season data into a database.

dbConnection

A DBIConnection object, as returned by DBI::dbConnect()

tablename

The name of the data table within the database

Value

Returns a cfbfastR_data tibble.

col_name types description
pos_team_id integer ESPN team id of the team on offense. Present for every season 2004+.
pos_team character
rushing_highlight_yards_per_opp double Highlight yards per rushing opportunity.
total_pen_yards integer Total penalty yards assessed.
EPA_penalty double Total EPA attributed to penalties.
penalty_first_downs_created integer Number of first downs the team gained via opponent penalty.
penalty_first_downs_created_rate double Share of the team's first downs that came via opponent penalty.
penalties integer Number of penalties assessed against the team.
penalty_yards integer Net penalty yardage assessed against the team; can be negative when enforcement moved the team forward on balance.
special_teams_plays integer Number of special-teams plays.
EPA_sp double Total special-teams EPA, ESPN's abbreviated field for the same phase.
EPA_special_teams double Total EPA generated on special-teams plays.
field_goals integer Number of field-goal attempts.
EPA_fg double Total EPA on field-goal attempts.
punt_plays integer Number of punt plays.
EPA_punt double Total EPA on punt plays.
kickoff_plays integer Number of kickoff plays.
EPA_kickoff double Total EPA on kickoff plays.
rushes integer Number of rushing attempts.
rush_yards double Total yards the team gained on rush plays.
yards_per_rush double Yards gained per rushing attempt.
rushing_power_rate double Share of carries that were power rushing attempts.
rushing_first_downs_created integer Number of first downs created on rush plays.
rushing_first_downs_created_rate double Share of rush plays that created a first down.
EPA_rushing_overall double Total EPA on rush plays.
EPA_rushing_per_play double EPA per rush play.
EPA_explosive_rushing integer Count of explosive rush plays. A play count, not an EPA total.
EPA_explosive_rushing_rate double Explosive-play rate on rush plays, over ESPN's qualifying-play denominator.
EPA_non_explosive_rushing double Total EPA on rush plays with explosive plays excluded.
EPA_non_explosive_rushing_per_play double EPA per rush play with explosive plays excluded.
passes integer Number of pass plays the team ran.
pass_yards double Total yards the team gained on pass plays.
yards_per_pass double
passing_first_downs_created integer Number of first downs created on pass plays.
passing_first_downs_created_rate double Share of pass plays that created a first down.
EPA_passing_overall double Total EPA on pass plays.
EPA_passing_per_play double EPA per pass play.
EPA_explosive_passing integer Count of explosive pass plays. A play count, not an EPA total.
EPA_explosive_passing_rate double Explosive-play rate on pass plays, over ESPN's qualifying-play denominator.
EPA_non_explosive_passing double Total EPA on pass plays with explosive plays excluded.
EPA_non_explosive_passing_per_play double EPA per pass play with explosive plays excluded.
scrimmage_plays integer Number of plays from scrimmage (rushes plus passes), excluding special teams.
EPA_overall_off double Total offensive EPA for the team. Duplicated exactly by EPA_overall_offense in every published season checked -- prefer one and ignore the other.
EPA_overall_offense double Total offensive EPA. An exact duplicate of EPA_overall_off.
EPA_per_play double Offensive EPA per play.
EPA_non_explosive double Total EPA with explosive plays excluded, isolating the team's routine-down production.
EPA_non_explosive_per_play double EPA per play with explosive plays excluded.
EPA_explosive integer Count of explosive plays, per ESPN's advanced box score. Despite the EPA_ prefix this is a play COUNT, not an EPA total.
EPA_explosive_rate double Explosive-play rate. Note this is NOT EPA_explosive divided by EPA_plays -- ESPN divides by its own smaller qualifying-play count, so deriving it yourself will not reproduce this value.
passes_rate double Share of the team's plays from scrimmage that were pass plays.
off_yards integer Offensive yards gained from scrimmage.
total_off_yards integer Total offensive yards across all plays.
yards_per_play double Yards gained per play.
EPA_plays integer Number of plays ESPN's advanced box score scored for the team.
total_yards integer Total yards the team gained across all plays.
EPA_overall_total double Total EPA across all phases, which is why it differs from the offense-only EPA_overall_off.
rushes_rate double Share of the team's plays from scrimmage that were rush plays.
first_downs_created integer Number of first downs the team created.
first_downs_created_rate double Share of the team's plays that created a first down.
EPA_rushing_power double Total EPA on power rushing situations, as classified by ESPN's advanced box score.
EPA_rushing_power_per_play double EPA per play on power rushing situations.
rushing_power_success integer Count of power rushing attempts that gained the yardage needed. An integer count, not a rate -- the rate is published separately as rushing_power_success_rate.
rushing_power_success_rate double Share of power rushing attempts that succeeded.
rushing_power integer Count of power rushing attempts, in short-yardage situations as classified by ESPN's advanced box score.
rushing_stuff integer Count of stuffed rushing attempts.
rushing_stuff_rate double Share of the team's carries that were stuffed at or behind the line of scrimmage.
rushing_stopped integer Count of rushing attempts stopped at or behind the line of scrimmage.
rushing_stopped_rate double Share of carries stopped at or behind the line of scrimmage.
rushing_opportunity integer Count of rushing opportunities -- carries that reached ESPN's opportunity threshold.
rushing_opportunity_rate double Share of carries that qualified as rushing opportunities.
rushing_highlight integer Highlight yards -- rushing yardage credited to the back rather than the offensive line.
rushing_highlight_rate double Share of rushing yardage that was highlight (back-credited) yardage.
rushing_highlight_yards double Total highlight yards the team accumulated -- the yardage credited to ball carriers rather than the line. The per-carry figure is rushing_highlight_yards_per_opp.
line_yards double Line yards -- the portion of rushing yardage credited to the offensive line under the standard rushing decomposition. ESPN applies its own qualifying threshold for the yardage split.
line_yards_per_carry double Line yards per rushing attempt.
second_level_yards double Second-level yards -- rushing yardage earned just beyond the line of scrimmage.
open_field_yards double Open-field yards -- rushing yardage earned well downfield, past the second level.
game_id integer
season integer
week integer

Author(s)

Saiem Gilani

Examples


  try(load_espn_cfb_adv_team(2004))

Load college football advanced team gamelog from the SportsDataverse data repo

Description

Loads season-level advanced team game logs – one row per team-game with the same advanced-stat profile at game grain. Published to the espn_cfb_adv_team_gamelog release tag on the sportsdataverse-data repo.

Usage

load_espn_cfb_adv_team_gamelog(
  seasons = most_recent_cfb_season(),
  ...,
  dbConnection = NULL,
  tablename = NULL
)

Arguments

seasons

A vector of 4-digit years associated with given college football seasons. Published coverage runs 2004 through the most recent season. Pass seasons = TRUE for every published season. (Min: 2004)

...

Additional arguments passed to an underlying function that writes the season data into a database.

dbConnection

A DBIConnection object, as returned by DBI::dbConnect()

tablename

The name of the data table within the database

Value

Returns a cfbfastR_data tibble.

col_name types description
season integer
week integer
season_type integer
game_id integer
start_date character
team_id integer
team character
opponent_id integer
opponent character
is_home logical
neutral_site logical
points_for integer
points_against integer
margin integer Final scoring margin from this team's perspective, exactly points_for minus points_against.
win logical
rushing_highlight_yards_per_opp double Highlight yards per rushing opportunity.
total_pen_yards integer Total penalty yards assessed.
EPA_penalty double Total EPA attributed to penalties.
penalty_first_downs_created integer Number of first downs the team gained via opponent penalty.
penalty_first_downs_created_rate double Share of the team's first downs that came via opponent penalty.
penalties integer Number of penalties assessed against the team.
penalty_yards integer Net penalty yardage assessed against the team; can be negative when enforcement moved the team forward on balance.
special_teams_plays integer Number of special-teams plays.
EPA_sp double Total special-teams EPA, ESPN's abbreviated field for the same phase.
EPA_special_teams double Total EPA generated on special-teams plays.
field_goals integer Number of field-goal attempts.
EPA_fg double Total EPA on field-goal attempts.
punt_plays integer Number of punt plays.
EPA_punt double Total EPA on punt plays.
kickoff_plays integer Number of kickoff plays.
EPA_kickoff double Total EPA on kickoff plays.
rushes integer Number of rushing attempts.
rush_yards double Total yards the team gained on rush plays.
yards_per_rush double Yards gained per rushing attempt.
rushing_power_rate double Share of carries that were power rushing attempts.
rushing_first_downs_created integer Number of first downs created on rush plays.
rushing_first_downs_created_rate double Share of rush plays that created a first down.
EPA_rushing_overall double Total EPA on rush plays.
EPA_rushing_per_play double EPA per rush play.
EPA_explosive_rushing integer Count of explosive rush plays. A play count, not an EPA total.
EPA_explosive_rushing_rate double Explosive-play rate on rush plays, over ESPN's qualifying-play denominator.
EPA_non_explosive_rushing double Total EPA on rush plays with explosive plays excluded.
EPA_non_explosive_rushing_per_play double EPA per rush play with explosive plays excluded.
passes integer Number of pass plays the team ran.
pass_yards double Total yards the team gained on pass plays.
yards_per_pass double
passing_first_downs_created integer Number of first downs created on pass plays.
passing_first_downs_created_rate double Share of pass plays that created a first down.
EPA_passing_overall double Total EPA on pass plays.
EPA_passing_per_play double EPA per pass play.
EPA_explosive_passing integer Count of explosive pass plays. A play count, not an EPA total.
EPA_explosive_passing_rate double Explosive-play rate on pass plays, over ESPN's qualifying-play denominator.
EPA_non_explosive_passing double Total EPA on pass plays with explosive plays excluded.
EPA_non_explosive_passing_per_play double EPA per pass play with explosive plays excluded.
scrimmage_plays integer Number of plays from scrimmage (rushes plus passes), excluding special teams.
EPA_overall_off double Total offensive EPA for the team. Duplicated exactly by EPA_overall_offense in every published season checked -- prefer one and ignore the other.
EPA_overall_offense double Total offensive EPA. An exact duplicate of EPA_overall_off.
EPA_per_play double Offensive EPA per play.
EPA_non_explosive double Total EPA with explosive plays excluded, isolating the team's routine-down production.
EPA_non_explosive_per_play double EPA per play with explosive plays excluded.
EPA_explosive integer Count of explosive plays, per ESPN's advanced box score. Despite the EPA_ prefix this is a play COUNT, not an EPA total.
EPA_explosive_rate double Explosive-play rate. Note this is NOT EPA_explosive divided by EPA_plays -- ESPN divides by its own smaller qualifying-play count, so deriving it yourself will not reproduce this value.
passes_rate double Share of the team's plays from scrimmage that were pass plays.
off_yards integer Offensive yards gained from scrimmage.
total_off_yards integer Total offensive yards across all plays.
yards_per_play double Yards gained per play.
EPA_plays integer Number of plays ESPN's advanced box score scored for the team.
total_yards integer Total yards the team gained across all plays.
EPA_overall_total double Total EPA across all phases, which is why it differs from the offense-only EPA_overall_off.
rushes_rate double Share of the team's plays from scrimmage that were rush plays.
first_downs_created integer Number of first downs the team created.
first_downs_created_rate double Share of the team's plays that created a first down.
EPA_rushing_power double Total EPA on power rushing situations, as classified by ESPN's advanced box score.
EPA_rushing_power_per_play double EPA per play on power rushing situations.
rushing_power_success integer Count of power rushing attempts that gained the yardage needed. An integer count, not a rate -- the rate is published separately as rushing_power_success_rate.
rushing_power_success_rate double Share of power rushing attempts that succeeded.
rushing_power integer Count of power rushing attempts, in short-yardage situations as classified by ESPN's advanced box score.
rushing_stuff integer Count of stuffed rushing attempts.
rushing_stuff_rate double Share of the team's carries that were stuffed at or behind the line of scrimmage.
rushing_stopped integer Count of rushing attempts stopped at or behind the line of scrimmage.
rushing_stopped_rate double Share of carries stopped at or behind the line of scrimmage.
rushing_opportunity integer Count of rushing opportunities -- carries that reached ESPN's opportunity threshold.
rushing_opportunity_rate double Share of carries that qualified as rushing opportunities.
rushing_highlight integer Highlight yards -- rushing yardage credited to the back rather than the offensive line.
rushing_highlight_rate double Share of rushing yardage that was highlight (back-credited) yardage.
rushing_highlight_yards double Total highlight yards the team accumulated -- the yardage credited to ball carriers rather than the line. The per-carry figure is rushing_highlight_yards_per_opp.
line_yards double Line yards -- the portion of rushing yardage credited to the offensive line under the standard rushing decomposition. ESPN applies its own qualifying threshold for the yardage split.
line_yards_per_carry double Line yards per rushing attempt.
second_level_yards double Second-level yards -- rushing yardage earned just beyond the line of scrimmage.
open_field_yards double Open-field yards -- rushing yardage earned well downfield, past the second level.

Author(s)

Saiem Gilani

Examples


  try(load_espn_cfb_adv_team_gamelog(2004))

Load college football advanced turnover from the SportsDataverse data repo

Description

Loads season-level turnover aggregates – one row per team with turnovers won/lost, expected turnovers, and turnover luck. Published to the espn_cfb_adv_turnover release tag on the sportsdataverse-data repo.

Usage

load_espn_cfb_adv_turnover(
  seasons = most_recent_cfb_season(),
  ...,
  dbConnection = NULL,
  tablename = NULL
)

Arguments

seasons

A vector of 4-digit years associated with given college football seasons. Published coverage runs 2004 through the most recent season. Pass seasons = TRUE for every published season. (Min: 2004)

...

Additional arguments passed to an underlying function that writes the season data into a database.

dbConnection

A DBIConnection object, as returned by DBI::dbConnect()

tablename

The name of the data table within the database

Value

Returns a cfbfastR_data tibble.

col_name types description
pos_team_id integer ESPN team id of the team on offense. Present for every season 2004+.
pos_team character
turnovers integer
st_turnovers_lost integer Turnovers the team lost on special-teams plays.
Int integer Interceptions thrown.
fumbles_lost integer
pass_breakups integer Passes thrown by this offense that the opposing defense broke up; it equals the opponent's row in the advanced defensive table exactly.
total_fumbles integer
fumbles_recovered integer
team_id integer
turnovers_pbp integer Turnover count derived from the play-by-play, retained unchanged so it can be reconciled against the ESPN-sourced turnovers total.
Int_pbp integer Interception count derived from the play-by-play, kept alongside the ESPN-sourced Int for reconciliation.
fumbles_lost_pbp integer Fumbles-lost count derived from the play-by-play, kept alongside the ESPN-sourced fumbles_lost for reconciliation.
espn_sourced logical CONSTANT: true on every published row. It records that the row was built from the ESPN feed rather than an alternate provider, and no other provider is currently used.
expected_turnovers double Turnover expectation for this team, computed as half its total fumbles plus 0.22 times the sum of its pass breakups and interceptions.
expected_turnover_margin double The opponent's expected_turnovers minus this team's, so positive means the team was expected to win the turnover battle.
turnover_margin integer The opponent's turnovers minus this team's turnovers, positive when the team gained more possessions than it gave away.
turnover_luck double Points of scoring luck attributed to turnovers, five points per turnover times the gap between turnover_margin and expected_turnover_margin.
takeaways integer
st_turnovers_gained integer Special-teams turnovers this team recovered, taken as the opponent's st_turnovers_lost.
fumble_recoveries_gained integer Opponent fumbles this team recovered, taken as the opponent's fumbles_lost.
game_id integer
season integer
week integer

Author(s)

Saiem Gilani

Examples


  try(load_espn_cfb_adv_turnover(2004))

Load ESPN college football betting lines from the SportsDataverse data repo

Description

Loads season-level betting lines – long format, one row per book per selection per market type (spread, moneyline, total), with open/close prices. Published to the espn_cfb_betting release tag on the sportsdataverse-data repo.

Usage

load_espn_cfb_betting(
  seasons = most_recent_cfb_season(),
  ...,
  dbConnection = NULL,
  tablename = NULL
)

Arguments

seasons

A vector of 4-digit years associated with given college football seasons. Published coverage runs 2004 through the most recent season. Pass seasons = TRUE for every published season. (Min: 2004)

...

Additional arguments passed to an underlying function that writes the season data into a database.

dbConnection

A DBIConnection object, as returned by DBI::dbConnect()

tablename

The name of the data table within the database

Value

Returns a cfbfastR_data tibble.

col_name types description
game_id integer
season integer
week integer
game_spread double
over_under double
home_favorite logical
home_team_spread double
game_spread_available logical
odds_source character

Author(s)

Saiem Gilani

Examples


  try(load_espn_cfb_betting(2004))

Load ESPN college football drives from the SportsDataverse data repo

Description

Loads season-level drive summaries – one row per drive with start/end field position, result, plays, yards, and clock. Published to the espn_cfb_drives release tag on the sportsdataverse-data repo.

Usage

load_espn_cfb_drives(
  seasons = most_recent_cfb_season(),
  ...,
  dbConnection = NULL,
  tablename = NULL
)

Arguments

seasons

A vector of 4-digit years associated with given college football seasons. Published coverage runs 2004 through the most recent season. Pass seasons = TRUE for every published season. (Min: 2004)

...

Additional arguments passed to an underlying function that writes the season data into a database.

dbConnection

A DBIConnection object, as returned by DBI::dbConnect()

tablename

The name of the data table within the database

Value

Returns a cfbfastR_data tibble.

col_name types description
drive_id character
team_id integer
result character
display_result character
short_display_result character
description character
yards integer
offensive_plays integer
is_score logical
start_period integer
start_yard_line integer
start_clock character
start_text character
end_period integer
end_yard_line integer
end_clock character
time_elapsed character
n_plays integer Number of entries in ESPN's raw plays array for the drive, which is generally at least offensive_plays because it also counts penalties and other non-offensive snaps.
game_id integer
season integer

Author(s)

Saiem Gilani

Examples


  try(load_espn_cfb_drives(2004))

Load ESPN college football game rosters from the SportsDataverse data repo

Description

Loads season-level game rosters – one row per player-game with team, position, and status, keyed by ESPN athlete id. Published to the espn_cfb_game_rosters release tag on the sportsdataverse-data repo.

Usage

load_espn_cfb_game_rosters(
  seasons = most_recent_cfb_season(),
  ...,
  dbConnection = NULL,
  tablename = NULL
)

Arguments

seasons

A vector of 4-digit years associated with given college football seasons. Published coverage runs 2004 through the most recent season. Pass seasons = TRUE for every published season. (Min: 2004)

...

Additional arguments passed to an underlying function that writes the season data into a database.

dbConnection

A DBIConnection object, as returned by DBI::dbConnect()

tablename

The name of the data table within the database

Value

Returns a cfbfastR_data tibble.

col_name types description
athlete_id integer
athlete_uid character
athlete_guid character
athlete_type character
first_name character
last_name character
full_name character
athlete_display_name character
short_name character
weight double
display_weight character
height double
display_height character
slug character
jersey character
linked logical
active logical
alternate_ids_sdr character
birth_place_city character
birth_place_state character
birth_place_country character
birth_country_alternate_id character ESPN's internal alternate identifier for the athlete's birth country, paired with birth_place_country and the flag fields.
birth_country_abbreviation character
headshot_href character
headshot_alt character
hand_type character
hand_abbreviation character
hand_display_value character
flag_href character URL of the birth-country flag image hosted on ESPN's CDN under teamlogos/countries.
flag_alt character Alt text ESPN attaches to the birth-country flag image, which is the country's name spelled out.
flag_rel character Stringified relationship list ESPN ships with the flag image; the only non-null value observed is a single country-flag entry.
experience_years double
experience_display_value character
experience_abbreviation character
status_id character
status_name character
status_type character
status_abbreviation character
middle_name character
starter logical
jersey_right character
valid logical
did_not_play logical
display_name character
athlete_href character ESPN Core v2 API reference URL for the athlete's season record, ending in the athlete id.
position_href character ESPN Core v2 API reference URL for the position resource ESPN lists the athlete at.
statistics_href character ESPN Core v2 API reference URL for this athlete's stat line in this game, null for the roughly 71 percent of listed players who recorded no stats.
team_id integer
order integer
home_away character
winner logical
team_guid character
team_uid character
team_slug character
team_location character
team_name character
team_nickname character
team_abbreviation character
team_display_name character
team_short_display_name character
team_color character
team_alternate_color character
is_active logical
is_all_star logical
team_alternate_ids_sdr character The team's Sportradar alternate identifier, which maps one-to-one with team_id.
logo_href character
logo_dark_href character
game_id integer
season integer
week integer
age double
date_of_birth character
citizenship character
draft_display_text character
draft_round double
draft_year double
draft_selection double
draft_team_href character API link to the team that drafted the player. Sparse: absent entirely from the 2023 and 2024 assets and populated on only a small share of 2025 rows.

Author(s)

Saiem Gilani

Examples


  try(load_espn_cfb_game_rosters(2004))

Load ESPN college football linescores from the SportsDataverse data repo

Description

Loads season-level period linescores – one row per team-period with points scored. Published to the espn_cfb_linescores release tag on the sportsdataverse-data repo.

Usage

load_espn_cfb_linescores(
  seasons = most_recent_cfb_season(),
  ...,
  dbConnection = NULL,
  tablename = NULL
)

Arguments

seasons

A vector of 4-digit years associated with given college football seasons. Published coverage runs 2004 through the most recent season. Pass seasons = TRUE for every published season. (Min: 2004)

...

Additional arguments passed to an underlying function that writes the season data into a database.

dbConnection

A DBIConnection object, as returned by DBI::dbConnect()

tablename

The name of the data table within the database

Value

Returns a cfbfastR_data tibble.

col_name types description
team_id integer
period integer
value character
game_id integer
season integer

Author(s)

Saiem Gilani

Examples


  try(load_espn_cfb_linescores(2004))

Load college football model-enriched play-by-play from the SportsDataverse data repo

Description

Loads season-level model-enriched play-by-play – the modeling-grade pbp frame with the engineered features the cfbfastR EP/WP model suite trains on. Published to the espn_cfb_model_pbp release tag on the sportsdataverse-data repo.

Usage

load_espn_cfb_model_pbp(
  seasons = most_recent_cfb_season(),
  ...,
  dbConnection = NULL,
  tablename = NULL
)

Arguments

seasons

A vector of 4-digit years associated with given college football seasons. Published coverage runs 2004 through the most recent season. Pass seasons = TRUE for every published season. (Min: 2004)

...

Additional arguments passed to an underlying function that writes the season data into a database.

dbConnection

A DBIConnection object, as returned by DBI::dbConnect()

tablename

The name of the data table within the database

Value

Returns a cfbfastR_data tibble.

col_name types description
game_id integer
id character
sequenceNumber character
game_play_number integer
drive.id character ESPN's drive identifier, formed as the game id followed by the drive's sequence number within that game.
season integer
week integer
period integer
pos_team integer
def_pos_team integer
start.pos_team.name character School name of the team with possession at the snap, taken from ESPN's team location field so it carries no mascot.
homeTeamId integer ESPN team id of the home team, read off the game header and stamped on every play.
awayTeamId integer ESPN team id of the away team, read off the game header and stamped on every play.
homeTeamName character Home team's school name from ESPN's team location field, without the mascot.
awayTeamName character Away team's school name from ESPN's team location field, without the mascot.
type.text character ESPN's play-type label, for example Rush, Pass Reception, Sack, Punt, Penalty, or Timeout.
text character
start.down integer Down at the snap as ESPN reports it; 0 marks the small share of rows ESPN leaves without a down, overwhelmingly timeouts and penalty administrations.
start.distance integer Yards the offense needs for a first down at the snap, carried through from ESPN without correction.
start.yardsToEndzone integer Distance in yards from the offense's spot at the snap to the opponent's end zone, ranging 0 to 100.
pos_score_diff_start integer
start.TimeSecsRem integer Seconds remaining in the half at the snap, so it tops out at 1800 rather than counting down from a full game.
start.is_home logical True when the team holding possession at the snap is the home team.
passing_down logical True on second and eight or longer, third and five or longer, or fourth and five or longer, the standard obvious-passing-situation flag.
pass logical
rush logical
completion logical
scoring_play logical
statYardage integer Yards gained on the play as ESPN reports it, negative on plays that lost yardage.
passer_player_name character Display name of the passer -- the FIRST participant in that role on the play.
ep_before double
ep_after double
epa double
wp_before double
wp_after double
wpa double
completion_prob double Modelled probability the pass is completed.
cpoe double
model_pbp_version character Version of the model-scored play-by-play build.
cp_model_version character Version of the completion-probability model that scored the play.
ep_model_version character Version of the expected-points model that scored the play.
wp_model_version character Version of the win-probability model that scored the play.
scored_date character Date on which the play was scored by the models.

Author(s)

Saiem Gilani

Examples


  try(load_espn_cfb_model_pbp(2004))

Load college football passing EPA splits from the SportsDataverse data repo

Description

Loads season-level passing EPA splits – one row per team (offense and defense views) with dropback EPA, success, and explosiveness aggregates. Published to the espn_cfb_passing release tag on the sportsdataverse-data repo.

Usage

load_espn_cfb_passing(
  seasons = most_recent_cfb_season(),
  ...,
  dbConnection = NULL,
  tablename = NULL
)

Arguments

seasons

A vector of 4-digit years associated with given college football seasons. Published coverage runs 2004 through the most recent season. Pass seasons = TRUE for every published season. (Min: 2004)

...

Additional arguments passed to an underlying function that writes the season data into a database.

dbConnection

A DBIConnection object, as returned by DBI::dbConnect()

tablename

The name of the data table within the database

Value

Returns a cfbfastR_data tibble.

col_name types description
team_id integer
pos_team character
division character
conference character
season integer
player_id integer
passer_player_name character Display name of the passer -- the FIRST participant in that role on the play.
plays integer
games integer
team_games integer Games the team played, used as the per-game denominator.
TEPA double Total EPA summed over every play.
EPAplay double EPA generated per play.
yards double
success double Success rate across the team plays.
comp double Completed passes.
att double Pass attempts thrown.
comppct double Completion percentage.
passing_td double
playsgame double Plays per game.
EPAgame double EPA generated per game.
yardsplay double Yards per play.
yardsgame double Yards per game.
sacked integer Times the passer was sacked.
sack_yds integer Yards lost to sacks.
sack_epa double EPA lost on the sacks the team's passers took -- the expected-points cost of those plays.
pass_int integer Interceptions thrown.
int_epa double EPA lost on the team's interceptions thrown -- the expected-points cost of the turnovers, not a count.
detmer double Detmer rating -- the composite passing-efficiency measure this pipeline publishes, named for the college passing-efficiency tradition.
detmergame double Detmer rating expressed per game.
dropbacks double Dropbacks taken by the passer.
sack_adj_yards double Passing yards adjusted for sack yardage lost.
yardsdropback double Yards per dropback.
TEPA_rank double National rank of the team's total EPA summed over every play, where 1 is best.
EPAgame_rank double National rank of the team's EPA generated per game, where 1 is best.
EPAplay_rank double National rank of the team's EPA generated per play, where 1 is best.
success_rank double National rank of the team's success rate across the team plays, where 1 is best.
comppct_rank double National rank of the team's completion percentage, where 1 is best.
yards_rank double National rank of the team's total yards, where 1 is best.
yardsplay_rank double National rank of the team's yards per play, where 1 is best.
yardsgame_rank double National rank of the team's yards per game, where 1 is best.
sack_adj_yards_rank double National rank of the team's passing yards adjusted for sack yardage lost, where 1 is best.
yardsdropback_rank double National rank of the team's yards per dropback, where 1 is best.
detmer_rank double National rank of the team's detmer rating -- the composite passing-efficiency measure this pipeline publishes, named for the college passing-efficiency tradition, where 1 is best.
detmergame_rank double National rank of the team's detmer rating expressed per game, where 1 is best.
fbs_class character Power/Group classification for the season: P4 or G6 from 2024 on, P5 or G5 through 2023, derived from conference membership. Null for teams outside FBS.

Author(s)

Saiem Gilani

Examples


  try(load_espn_cfb_passing(2004))

Load ESPN college football play-by-play from the SportsDataverse data repo

Description

Loads season-level ESPN-derived college football play-by-play – one row per play with the full EPA/WPA model columns and participant ids, covering 2004 to present. Published to the espn_cfb_pbp release tag on the sportsdataverse-data repo.

Delineation from the sibling pbp loaders: load_cfb_pbp() is the classic cfbfastR EPA/WPA pbp (FBS, 2014+, unchanged); load_espn_cfb_pbp() is this ESPN-derived build with deeper history; load_ncaa_mfb_pbp() is the stats.ncaa.org parse covering FCS and lower divisions (2013+).

Usage

load_espn_cfb_pbp(
  seasons = most_recent_cfb_season(),
  ...,
  dbConnection = NULL,
  tablename = NULL
)

Arguments

seasons

A vector of 4-digit years associated with given college football seasons. Published coverage runs 2004 through the most recent season. Pass seasons = TRUE for every published season. (Min: 2004)

...

Additional arguments passed to an underlying function that writes the season data into a database.

dbConnection

A DBIConnection object, as returned by DBI::dbConnect()

tablename

The name of the data table within the database

Value

Returns a cfbfastR_data tibble.

col_name types description
season integer
game_id integer
game_play_number integer
pos_team integer
def_pos_team integer
pos_team_score integer
def_pos_team_score integer
half integer
period integer
down integer
distance integer
EPA double
wpa double
wp_before double
wp_after double
def_wp_before double
def_wp_after double
penalty_detail character
yds_penalty character
penalty_1st_conv logical
def_EPA double
rz_play logical
scoring_opp logical
middle_8 logical
stuffed_run logical
change_of_pos_team logical
downs_turnover logical
pos_score_diff_start integer
pos_score_pts integer
home_wp_before double
away_wp_before double
home_wp_after double
away_wp_after double
end_of_half logical
lead_pos_team integer Value of pos_team on the next play, used for sequence-aware derivations.
lead_play_type character Value of play_type on the next play, used for sequence-aware derivations.
lag_pos_team integer Value of pos_team on the previous play, used for sequence-aware derivations.
orig_play_type character
offense_score_play logical
defense_score_play logical
pos_score_diff integer
change_of_poss logical
rusher_player_name character
yds_rushed integer
passer_player_name character
receiver_player_name character
yds_receiving integer
yds_sacked integer
sack_players character
sack_player_name character
sack_player_name2 character
pass_breakup_player_name character
interception_player_name character
yds_int_return integer
fumble_player_name character
fumble_forced_player_name character
fumble_recovered_player_name character
yds_fumble_return integer
punter_player_name character
yds_punted integer
yds_punt_return integer
yds_punt_gained integer
punt_block_player_name character
punt_block_return_player_name character
fg_kicker_player_name character
yds_fg integer
fg_block_player_name character
fg_return_player_name character
kickoff_player_name character
yds_kickoff integer
yds_kickoff_return integer
rush logical
rush_td logical
pass logical
pass_td logical
completion logical
pass_attempt logical
target logical
sack_vec logical
sack logical
int logical
int_td logical
turnover_vec logical
kickoff_play logical
scoring_play logical
td_play logical
touchdown logical
safety logical
fumble_vec logical
kickoff_tb logical
kickoff_onside logical
kickoff_oob logical
kickoff_fair_catch logical
kickoff_downed logical
kickoff_safety logical
kick_play logical
punt logical
punt_play logical
punt_tb logical
punt_oob logical
punt_fair_catch logical
punt_downed logical
punt_safety logical
punt_blocked logical
penalty_safety logical
fg_made logical
fg_make_prob double
penalty_flag logical
penalty_declined logical
penalty_no_play logical
penalty_offset logical
penalty_text character
lead_wp_before2 double Value of wp_before 2 plays ahead, used for sequence-aware derivations.
lead_wp_before double Value of wp_before on the next play, used for sequence-aware derivations.
lead_pos_team2 integer Value of pos_team 2 plays ahead, used for sequence-aware derivations.
lag_change_of_pos_team logical Value of change_of_pos_team on the previous play, used for sequence-aware derivations.
lag_pos_score_diff integer Value of pos_score_diff on the previous play, used for sequence-aware derivations.
id integer
sequenceNumber integer
text character
awayScore integer
homeScore integer
scoringPlay logical ESPN flag marking the play as a scoring play.
priority logical
modified character
wallclock character
teamParticipants character
isPenalty logical
statYardage integer Yardage ESPN credits to the play for statistical purposes.
isTurnover logical
type.id character ESPN's numeric identifier for the play type.
type.text character ESPN's text label for the play type.
type.abbreviation character ESPN's abbreviation for the play type.
period.number integer Period (quarter) number in which the play occurred.
clock.displayValue character Game clock at the play, as the displayed mm:ss string.
start.down integer ESPN's down value for the play state at the start of the play.
start.distance integer ESPN's distance value for the play state at the start of the play.
start.yardLine integer ESPN's yardLine value for the play state at the start of the play.
start.yardsToEndzone integer ESPN's yardsToEndzone value for the play state at the start of the play.
start.team.id integer ESPN's team.id value for the play state at the start of the play.
end.down integer ESPN's down value for the play state at the end of the play.
end.distance integer ESPN's distance value for the play state at the end of the play.
end.yardLine integer ESPN's yardLine value for the play state at the end of the play.
end.yardsToEndzone integer ESPN's yardsToEndzone value for the play state at the end of the play.
end.downDistanceText character ESPN's downDistanceText value for the play state at the end of the play.
end.shortDownDistanceText character ESPN's shortDownDistanceText value for the play state at the end of the play.
end.possessionText character ESPN's possessionText value for the play state at the end of the play.
end.team.id integer ESPN's team.id value for the play state at the end of the play.
start.downDistanceText character ESPN's downDistanceText value for the play state at the start of the play.
start.shortDownDistanceText character ESPN's shortDownDistanceText value for the play state at the start of the play.
start.possessionText character ESPN's possessionText value for the play state at the start of the play.
scoringType.name character ESPN's name for the scoring type (e.g. touchdown, field goal).
scoringType.displayName character ESPN's display label for the scoring type.
scoringType.abbreviation character ESPN's abbreviation for the scoring type.
pointAfterAttempt.id double
pointAfterAttempt.text character
pointAfterAttempt.abbreviation character
pointAfterAttempt.value double
drive.id character ESPN's id field for the drive containing this play.
drive.displayResult character ESPN's displayResult field for the drive containing this play.
drive.isScore logical ESPN's isScore field for the drive containing this play.
drive.team.shortDisplayName character ESPN's team.shortDisplayName field for the drive containing this play.
drive.team.displayName character ESPN's team.displayName field for the drive containing this play.
drive.team.name character ESPN's team.name field for the drive containing this play.
drive.team.abbreviation character ESPN's team.abbreviation field for the drive containing this play.
drive.yards integer ESPN's yards field for the drive containing this play.
drive.offensivePlays integer ESPN's offensivePlays field for the drive containing this play.
drive.result character ESPN's result field for the drive containing this play.
drive.description character ESPN's description field for the drive containing this play.
drive.shortDisplayResult character ESPN's shortDisplayResult field for the drive containing this play.
drive.timeElapsed.displayValue character ESPN's timeElapsed.displayValue field for the drive containing this play.
drive.start.period.number integer ESPN's start.period.number field for the drive containing this play.
drive.start.period.type character ESPN's start.period.type field for the drive containing this play.
drive.start.yardLine integer ESPN's start.yardLine field for the drive containing this play.
drive.start.clock.displayValue character ESPN's start.clock.displayValue field for the drive containing this play.
drive.start.text character ESPN's start.text field for the drive containing this play.
drive.end.period.number integer ESPN's end.period.number field for the drive containing this play.
drive.end.period.type character ESPN's end.period.type field for the drive containing this play.
drive.end.yardLine integer ESPN's end.yardLine field for the drive containing this play.
drive.end.clock.displayValue character ESPN's end.clock.displayValue field for the drive containing this play.
seasonType integer ESPN season type for the game (2 = regular season, 3 = postseason).
week integer
status_type_completed logical
homeTeamId integer ESPN's home-team Id for the game, stamped on every play.
awayTeamId integer ESPN's away-team Id for the game, stamped on every play.
homeTeamName character ESPN's home-team Name for the game, stamped on every play.
awayTeamName character ESPN's away-team Name for the game, stamped on every play.
homeTeamMascot character ESPN's home-team Mascot for the game, stamped on every play.
awayTeamMascot character ESPN's away-team Mascot for the game, stamped on every play.
homeTeamAbbrev character ESPN's home-team Abbrev for the game, stamped on every play.
awayTeamAbbrev character ESPN's away-team Abbrev for the game, stamped on every play.
homeTeamNameAlt character ESPN's home-team NameAlt for the game, stamped on every play.
awayTeamNameAlt character ESPN's away-team NameAlt for the game, stamped on every play.
gameSpread double Point spread used as an input to the win-probability model.
homeFavorite logical True when the home team was favoured by the spread.
gameSpreadAvailable logical True when a spread was available for the game.
overUnder double Over/under total used as a model input.
homeTeamSpread double ESPN's home-team Spread for the game, stamped on every play.
clock.minutes integer Minutes remaining on the game clock at the play.
clock.seconds integer Seconds component of the game clock at the play.
lag_half integer Value of half on the previous play, used for sequence-aware derivations.
lead_half integer Value of half on the next play, used for sequence-aware derivations.
start.TimeSecsRem integer ESPN's TimeSecsRem value for the play state at the start of the play.
start.adj_TimeSecsRem integer ESPN's adj_TimeSecsRem value for the play state at the start of the play.
lead_text character Value of text on the next play, used for sequence-aware derivations.
lead_start_team character Value of start_team on the next play, used for sequence-aware derivations.
lead_start_yardsToEndzone integer Value of start_yardsToEndzone on the next play, used for sequence-aware derivations.
lead_start_down integer Value of start_down on the next play, used for sequence-aware derivations.
lead_start_distance integer Value of start_distance on the next play, used for sequence-aware derivations.
lead_scoringPlay logical Value of scoringPlay on the next play, used for sequence-aware derivations.
text_dupe logical True when the play description duplicates the previous row's text.
end_state_missing logical
start.pos_team.id integer ESPN's pos_team.id value for the play state at the start of the play.
start.def_pos_team.id integer ESPN's def_pos_team.id value for the play state at the start of the play.
end.def_pos_team.id integer ESPN's def_pos_team.id value for the play state at the end of the play.
end.pos_team.id integer ESPN's pos_team.id value for the play state at the end of the play.
start.pos_team.name character ESPN's pos_team.name value for the play state at the start of the play.
start.def_pos_team.name character ESPN's def_pos_team.name value for the play state at the start of the play.
end.pos_team.name character ESPN's pos_team.name value for the play state at the end of the play.
end.def_pos_team.name character ESPN's def_pos_team.name value for the play state at the end of the play.
start.is_home logical ESPN's is_home value for the play state at the start of the play.
end.is_home logical ESPN's is_home value for the play state at the end of the play.
homeTimeoutCalled logical True when the home team called a timeout on the play.
awayTimeoutCalled logical True when the away team called a timeout on the play.
end.homeTeamTimeouts integer ESPN's homeTeamTimeouts value for the play state at the end of the play.
end.awayTeamTimeouts integer ESPN's awayTeamTimeouts value for the play state at the end of the play.
start.homeTeamTimeouts integer ESPN's homeTeamTimeouts value for the play state at the start of the play.
start.awayTeamTimeouts integer ESPN's awayTeamTimeouts value for the play state at the start of the play.
end.TimeSecsRem integer ESPN's TimeSecsRem value for the play state at the end of the play.
end.adj_TimeSecsRem integer ESPN's adj_TimeSecsRem value for the play state at the end of the play.
start.posTeamTimeouts integer ESPN's posTeamTimeouts value for the play state at the start of the play.
start.defPosTeamTimeouts integer ESPN's defPosTeamTimeouts value for the play state at the start of the play.
end.posTeamTimeouts integer ESPN's posTeamTimeouts value for the play state at the end of the play.
end.defPosTeamTimeouts integer ESPN's defPosTeamTimeouts value for the play state at the end of the play.
firstHalfKickoffTeamId integer ESPN id of the team that received the opening kickoff.
start.yard integer ESPN's yard value for the play state at the start of the play.
end.yard integer ESPN's yard value for the play state at the end of the play.
lag_scoringPlay logical Value of scoringPlay on the previous play, used for sequence-aware derivations.
down_1 logical True when it is 1st down at the start of the play.
down_2 logical True when it is 2nd down at the start of the play.
down_3 logical True when it is 3rd down at the start of the play.
down_4 logical True when it is 4th down at the start of the play.
down_1_end logical True when it is 1st down at the end of the play.
down_2_end logical True when it is 2nd down at the end of the play.
down_3_end logical True when it is 3rd down at the end of the play.
down_4_end logical True when it is 4th down at the end of the play.
td_check logical Internal flag used while reconciling whether the play produced a touchdown.
forced_fumble logical True when the defense forced a fumble on the play.
is_home logical
lag_HA_score_diff integer Value of HA_score_diff on the previous play, used for sequence-aware derivations.
HA_score_diff integer Home score minus away score for the play.
net_HA_score_pts integer Net points the play added to the home-minus-away score margin.
H_score_diff integer Home team's score minus the away team's, from the home perspective.
A_score_diff integer Away team's score minus the home team's, from the away perspective.
lag_homeScore integer Value of homeScore on the previous play, used for sequence-aware derivations.
lag_awayScore integer Value of awayScore on the previous play, used for sequence-aware derivations.
start.homeScore integer ESPN's homeScore value for the play state at the start of the play.
start.awayScore integer ESPN's awayScore value for the play state at the start of the play.
end.homeScore integer ESPN's homeScore value for the play state at the end of the play.
end.awayScore integer ESPN's awayScore value for the play state at the end of the play.
start.pos_team_score integer ESPN's pos_team_score value for the play state at the start of the play.
start.def_pos_team_score integer ESPN's def_pos_team_score value for the play state at the start of the play.
start.pos_score_diff integer ESPN's pos_score_diff value for the play state at the start of the play.
end.pos_team_score integer ESPN's pos_team_score value for the play state at the end of the play.
end.def_pos_team_score integer ESPN's def_pos_team_score value for the play state at the end of the play.
end.pos_score_diff integer ESPN's pos_score_diff value for the play state at the end of the play.
start.pos_team_receives_2H_kickoff logical ESPN's pos_team_receives_2H_kickoff value for the play state at the start of the play.
end.pos_team_receives_2H_kickoff logical ESPN's pos_team_receives_2H_kickoff value for the play state at the end of the play.
penalty_in_text logical True when the play description mentions a penalty.
pass_breakup logical True when a defender broke up the pass.
pass_depth character
pass_direction character
rush_direction character
qb_hurry logical
fg_attempt logical True when the play was a field-goal attempt.
pos_unit character
def_pos_unit character
sp logical
play logical
cleaned_text character
kneel_down logical
scrimmage_play logical True when the play is a play from scrimmage rather than a special-teams or administrative row.
pos_score_diff_end integer Score differential from the possessing team's perspective at the end of the play.
fumble_lost logical
fumble_recovered logical True when a fumble on the play was recovered.
field_goal_result character
extra_point_result character
two_point_conv_result character
air_yardsToEndzone integer
air_yards integer
yards_after_catch integer
kicking_team integer
return_team integer
fumble_or_muff logical
recovery_team integer
recovery_team_2 integer
fumbling_team integer
int_turnover logical
pos_fumble_lost logical
def_fumble_lost logical
is_pos_team_turnover logical
is_def_pos_team_turnover logical
is_turnover logical
turnover_team integer
is_st_turnover logical
is_blocked_punt_turnover logical
is_blocked_fg_turnover logical
sack_team integer
interception_team integer
pass_breakup_team integer
forced_fumble_team integer
fumble_recovery_team integer
punt_return_team integer
kick_return_team integer
fg_team integer
punt_team integer
penalized_team integer
penalty_yards_signed integer
new_down integer Down after the play, including any penalty enforcement.
new_distance integer Distance to go after the play, including any penalty enforcement.
under_2 logical
goal_to_go logical
stopped_run logical True when the rush was stopped at or behind the line of scrimmage.
opportunity_run logical True when a rush reached 4 yards -- the carries on which the blocking did its job. Matches cfbfastR's espn_cfb_15 definition. Assets published before the 2026-08 fix carry the inverted (4 yards or fewer) flag.
highlight_run logical True when the rush gained 8 or more yards.
adj_rush_yardage integer Rushing yards capped at 8, the input to the line-yards decomposition.
line_yards double Yards credited to the offensive line on a rush, using the standard sliding scale: 1.2x the capped yardage on a loss, all of it through 3 yards, half of each yard from 4 to 8, and a 5.5-yard ceiling beyond that.
second_level_yards double Rushing yards earned from 4 to 8, split evenly between line and carrier under the line-yards decomposition.
open_field_yards integer Rushing yards gained beyond 8, credited to the ball carrier rather than the line.
highlight_yards double Second-level plus open-field yards -- the yardage credited to the carrier.
opp_highlight_yards double Highlight yards earned on opportunity runs, isolating carrier production on carries where the blocking succeeded. Assets published before the 2026-08 fix are identically 0 here, because the inverted opportunity_run gate could never co-occur with non-zero highlight yards.
short_rush_success logical True when a short-yardage rush gained the yardage needed.
short_rush_attempt logical True when the play is a rush in a short-yardage situation.
power_rush_success logical True when a power rushing attempt gained the yardage needed.
power_rush_attempt logical True when the play is a short-yardage power rushing attempt.
early_down logical True when the play is a scrimmage play on first or second down.
late_down logical True when the play is a scrimmage play on third or fourth down.
early_down_pass logical True when the play is a pass on an early down.
early_down_rush logical True when the play is a rush on an early down.
late_down_pass logical True when the play is a pass on a late down.
late_down_rush logical True when the play is a rush on a late down.
standard_down logical True when the offense is on schedule for the series -- first down, second down needing fewer than 8, or third/fourth down needing fewer than 5.
passing_down logical True when the offense is behind schedule for the series -- second down needing 8 or more, or third/fourth down needing 5 or more.
TFL logical True when the play was a tackle for loss.
TFL_pass logical True when the play was a tackle for loss on a pass play (a sack).
TFL_rush logical True when the play was a tackle for loss on a rush play.
havoc logical True when the defense disrupted the play: a pass breakup, tackle for loss, interception or forced fumble.
start.pos_team_spread double ESPN's pos_team_spread value for the play state at the start of the play.
start.elapsed_share double ESPN's elapsed_share value for the play state at the start of the play.
start.spread_time double ESPN's spread_time value for the play state at the start of the play.
end.pos_team_spread double ESPN's pos_team_spread value for the play state at the end of the play.
end.elapsed_share double ESPN's elapsed_share value for the play state at the end of the play.
end.spread_time double ESPN's spread_time value for the play state at the end of the play.
penalty_assessed_on_kickoff logical
start.yardsToEndzone.touchback integer ESPN's yardsToEndzone.touchback value for the play state at the start of the play.
EP_start_touchback double Expected points the offense would have had from a touchback on this play.
EP_start double Expected points for the offense at the start of the play.
EP_end double Expected points for the offense at the end of the play.
lag_EP_end double Value of EP_end on the previous play, used for sequence-aware derivations.
EP_between double Change in expected points across the play, before penalty adjustment.
EPA_scrimmage double EPA credited to the play on plays from scrimmage.
EPA_rush double EPA credited to the play on rush plays.
EPA_pass double EPA credited to the play on pass plays.
EPA_explosive logical True when the play was explosive.
EPA_non_explosive double EPA credited to the play on non-explosive plays.
EPA_explosive_pass logical True when the pass play was explosive.
EPA_explosive_rush logical True when the rush play was explosive.
first_down_created logical True when the play produced a first down for the offense.
EPA_success logical True when the play was successful by EPA.
EPA_success_early_down logical True when the play on an early down was successful by EPA.
EPA_success_early_down_pass logical True when the pass play on an early down was successful by EPA.
EPA_success_early_down_rush logical True when the rush play on an early down was successful by EPA.
EPA_success_late_down logical True when the play on a late down was successful by EPA.
EPA_success_late_down_pass logical True when the pass play on a late down was successful by EPA.
EPA_success_late_down_rush logical True when the rush play on a late down was successful by EPA.
EPA_success_standard_down logical True when the play on a standard down was successful by EPA.
EPA_success_passing_down logical True when the play on a passing down was successful by EPA.
EPA_success_pass logical True when the pass play was successful by EPA.
EPA_success_rush logical True when the rush play was successful by EPA.
EPA_success_EPA double EPA on successful plays.
EPA_success_standard_down_EPA double EPA on successful plays on a standard down.
EPA_success_passing_down_EPA double EPA on successful plays on a passing down.
EPA_success_pass_EPA double EPA on successful pass plays.
EPA_success_rush_EPA double EPA on successful rush plays.
EPA_middle_8_success logical True when the play in the middle eight was successful by EPA.
EPA_middle_8_success_pass logical True when the pass play in the middle eight was successful by EPA.
EPA_middle_8_success_rush logical True when the rush play in the middle eight was successful by EPA.
EPA_penalty double EPA credited to the play attributable to penalties.
EPA_sp double EPA credited to the play on special-teams plays.
EPA_fg double EPA credited to the play on field-goal attempts.
EPA_punt double EPA credited to the play on punt plays.
EPA_kickoff double EPA credited to the play on kickoff plays.
start.ExpScoreDiff_touchback double ESPN's ExpScoreDiff_touchback value for the play state at the start of the play.
start.ExpScoreDiff double ESPN's ExpScoreDiff value for the play state at the start of the play.
start.ExpScoreDiff_Time_Ratio_touchback double ESPN's ExpScoreDiff_Time_Ratio_touchback value for the play state at the start of the play.
start.ExpScoreDiff_Time_Ratio double ESPN's ExpScoreDiff_Time_Ratio value for the play state at the start of the play.
end.ExpScoreDiff double ESPN's ExpScoreDiff value for the play state at the end of the play.
end.ExpScoreDiff_Time_Ratio double ESPN's ExpScoreDiff_Time_Ratio value for the play state at the end of the play.
wp_touchback double Win probability the offense would have had starting from a touchback.
wp_before_naive double
wp_touchback_naive double
wp_after_naive double
def_wp_before_naive double
home_wp_before_naive double
away_wp_before_naive double
lead_wp_before_naive double
lead_wp_before2_naive double
def_wp_after_naive double
home_wp_after_naive double
away_wp_after_naive double
wpa_naive double
cp double
cpoe double
era integer
xpass double
pass_oe double
drive_start double Yard line at which the drive began.
drive_stopped logical True when the play ended the drive.
drive_play_index integer Sequence number of the play within its drive.
drive_offense_plays integer Offensive plays run on the drive.
prog_drive_EPA double Cumulative EPA accrued by the drive up to and including this play.
prog_drive_WPA double Cumulative win-probability added by the drive up to and including this play.
drive_offense_yards integer Offensive yards gained on the drive.
drive_total_yards integer Total yards gained on the drive.
qbr_epa double EPA variant used as an input to the QBR calculation.
weight double
non_fumble_sack logical True when the play was a sack that did not produce a fumble.
sack_epa double EPA credited to the play when it is a sack.
pass_epa double EPA credited to the play when it is a pass.
rush_epa double EPA credited to the play when it is a rush.
pen_epa double EPA attributable to a penalty on the play.
sack_weight double Weighting applied to the sack component of the play.
pass_weight double Weighting applied to the pass component of the play.
rush_weight double Weighting applied to the rush component of the play.
pen_weight double Weighting applied to the penalty component of the play.
action_play logical True when the play advanced the game state -- excludes timeouts, end-of-period markers and other non-action rows.
athlete_name character
rusher_player_id integer
passer_player_id integer
receiver_player_id integer
fumble_player_id integer
sack_player_id integer
sack_player_id2 integer
interception_player_id integer
pass_breakup_player_id integer
fumble_forced_player_id integer
fumble_recovered_player_id integer
fg_kicker_player_id integer
punter_player_id integer
kickoff_player_id integer
kickoff_return_player_id integer
punt_return_player_id integer
fg_block_player_id integer
punt_block_player_id integer
fg_return_player_id integer
punt_block_return_player_id character
go_wp double
first_down_prob double
wp_succeed double
wp_fail double
make_fg_wp double
miss_fg_wp double
fg_wp double
punt_wp double
go_boost double
go_wp_diff double
fg_wp_diff double
punt_wp_diff double
fourth_down_recommendation character
two_pt_wp double
xp_wp double
prob_2pt double
two_pt_recommendation character
two_pt_wp_diff double

Author(s)

Saiem Gilani

Examples


  try(load_espn_cfb_pbp(2004))

Load college football team percentile profiles from the SportsDataverse data repo

Description

Loads season-level team percentile profiles – one row per team with league-percentile placements across the summary metrics. Published to the espn_cfb_percentiles release tag on the sportsdataverse-data repo.

Usage

load_espn_cfb_percentiles(
  seasons = most_recent_cfb_season(),
  ...,
  dbConnection = NULL,
  tablename = NULL
)

Arguments

seasons

A vector of 4-digit years associated with given college football seasons. Published coverage runs 2004 through the most recent season. Pass seasons = TRUE for every published season. (Min: 2004)

...

Additional arguments passed to an underlying function that writes the season data into a database.

dbConnection

A DBIConnection object, as returned by DBI::dbConnect()

tablename

The name of the data table within the database

Value

Returns a cfbfastR_data tibble.

col_name types description
pctile double Percentile bucket the row reports, from 0 to 100.
GEI double Value of game excitement index at the percentile this row reports.
EPAplay double Value of EPA generated per play at the percentile this row reports.
pass_success double Value of success rate on pass plays at the percentile this row reports.
rush_success double Value of success rate on rush plays at the percentile this row reports.
early_down_success double Value of success rate on early downs at the percentile this row reports.
early_down_EPA double Value of EPA per early-down play at the percentile this row reports.
late_down_success double Value of success rate on late downs at the percentile this row reports.
success double Value of success rate across the team plays at the percentile this row reports.
yardsplay double Value of yards per play at the percentile this row reports.
dropbacks double Value of dropbacks taken by the passer at the percentile this row reports.
rushes double Value of rushing attempts at the percentile this row reports.
EPAdropback double Value of EPA generated per dropback at the percentile this row reports.
EPArush double Value of EPA generated per rushing attempt at the percentile this row reports.
yardsdropback double Value of yards per dropback at the percentile this row reports.
pass_explosive double Value of explosive-play rate on pass plays at the percentile this row reports.
rush_explosive double Value of explosive-play rate on rush plays at the percentile this row reports.
explosive double Value of explosive-play rate at the percentile this row reports.
third_down_success double Value of success rate on third down at the percentile this row reports.
red_zone_success double Value of success rate in the red zone at the percentile this row reports.
play_stuffed double Value of stuffed-play rate at the percentile this row reports.
nonExplosiveEpaPerPlay double Value of EPA per play excluding explosive plays at the percentile this row reports.
havoc double Value of havoc rate at the percentile this row reports.
yardsrush double Value of yards per rush at the percentile this row reports.
lineyards double Value of line yards per rush at the percentile this row reports.
opportunity_run double Value of opportunity-run rate at the percentile this row reports.
third_down_distance double Value of average yards to go on third down at the percentile this row reports.

Author(s)

Saiem Gilani

Examples


  try(load_espn_cfb_percentiles(2004))

Load ESPN college football play participants from the SportsDataverse data repo

Description

Loads season-level per-play participants – one row per play- participant with role type and ESPN athlete id, the join partner for play-level attribution. Published to the espn_cfb_play_participants release tag on the sportsdataverse- data repo.

Usage

load_espn_cfb_play_participants(
  seasons = most_recent_cfb_season(),
  ...,
  dbConnection = NULL,
  tablename = NULL
)

Arguments

seasons

A vector of 4-digit years associated with given college football seasons. Published coverage runs 2014 through the most recent season. Pass seasons = TRUE for every published season. (Min: 2014)

...

Additional arguments passed to an underlying function that writes the season data into a database.

dbConnection

A DBIConnection object, as returned by DBI::dbConnect()

tablename

The name of the data table within the database

Value

Returns a cfbfastR_data tibble.

col_name types description
game_id integer
play_id integer
kicker_player_name character Display name of the kicker -- the FIRST participant in that role on the play.
tackler_player_name character Display name of a defender credited with the tackle -- the FIRST participant in that role on the play.
returner_player_name character Display name of the player returning the kick or punt -- the FIRST participant in that role on the play.
rusher_player_name character Display name of the ball carrier on a rush -- the FIRST participant in that role on the play.
passer_player_name character Display name of the passer -- the FIRST participant in that role on the play.
receiver_player_name character Display name of the targeted receiver -- the FIRST participant in that role on the play.
punter_player_name character Display name of the punter -- the FIRST participant in that role on the play.
assisted_by_player_name character Display name of a defender credited with an assisted tackle -- the FIRST participant in that role on the play.
penalized_player_name character Display name of the penalized player -- the FIRST participant in that role on the play.
scorer_player_name character Display name of the player credited with the score -- the FIRST participant in that role on the play.
pat_scorer_player_name character Display name of the player credited with the point-after score -- the FIRST participant in that role on the play.
sacked_by_player_name character Display name of a defender credited with the sack -- the FIRST participant in that role on the play.
kicker_player_id character ESPN athlete id of the kicker -- the FIRST participant in that role on the play.
tackler_player_id character ESPN athlete id of a defender credited with the tackle -- the FIRST participant in that role on the play.
returner_player_id character ESPN athlete id of the player returning the kick or punt -- the FIRST participant in that role on the play.
rusher_player_id character ESPN athlete id of the ball carrier on a rush -- the FIRST participant in that role on the play.
passer_player_id character ESPN athlete id of the passer -- the FIRST participant in that role on the play.
receiver_player_id character ESPN athlete id of the targeted receiver -- the FIRST participant in that role on the play.
punter_player_id character ESPN athlete id of the punter -- the FIRST participant in that role on the play.
assisted_by_player_id character ESPN athlete id of a defender credited with an assisted tackle -- the FIRST participant in that role on the play.
penalized_player_id character ESPN athlete id of the penalized player -- the FIRST participant in that role on the play.
scorer_player_id character ESPN athlete id of the player credited with the score -- the FIRST participant in that role on the play.
pat_scorer_player_id character ESPN athlete id of the player credited with the point-after score -- the FIRST participant in that role on the play.
sacked_by_player_id character ESPN athlete id of a defender credited with the sack -- the FIRST participant in that role on the play.
kicker_player_names character List of the display names of EVERY participant credited as the kicker on the play, so multi-entry roles such as split sacks or gang tackles are not collapsed to one.
tackler_player_names character List of the display names of EVERY participant credited as a defender credited with the tackle on the play, so multi-entry roles such as split sacks or gang tackles are not collapsed to one.
returner_player_names character List of the display names of EVERY participant credited as the player returning the kick or punt on the play, so multi-entry roles such as split sacks or gang tackles are not collapsed to one.
rusher_player_names character List of the display names of EVERY participant credited as the ball carrier on a rush on the play, so multi-entry roles such as split sacks or gang tackles are not collapsed to one.
passer_player_names character List of the display names of EVERY participant credited as the passer on the play, so multi-entry roles such as split sacks or gang tackles are not collapsed to one.
receiver_player_names character List of the display names of EVERY participant credited as the targeted receiver on the play, so multi-entry roles such as split sacks or gang tackles are not collapsed to one.
punter_player_names character List of the display names of EVERY participant credited as the punter on the play, so multi-entry roles such as split sacks or gang tackles are not collapsed to one.
assisted_by_player_names character List of the display names of EVERY participant credited as a defender credited with an assisted tackle on the play, so multi-entry roles such as split sacks or gang tackles are not collapsed to one.
penalized_player_names character List of the display names of EVERY participant credited as the penalized player on the play, so multi-entry roles such as split sacks or gang tackles are not collapsed to one.
scorer_player_names character List of the display names of EVERY participant credited as the player credited with the score on the play, so multi-entry roles such as split sacks or gang tackles are not collapsed to one.
pat_scorer_player_names character List of the display names of EVERY participant credited as the player credited with the point-after score on the play, so multi-entry roles such as split sacks or gang tackles are not collapsed to one.
sacked_by_player_names character List of the display names of EVERY participant credited as a defender credited with the sack on the play, so multi-entry roles such as split sacks or gang tackles are not collapsed to one.
kicker_player_ids character List of the athlete ids of EVERY participant credited as the kicker on the play, so multi-entry roles such as split sacks or gang tackles are not collapsed to one.
tackler_player_ids character List of the athlete ids of EVERY participant credited as a defender credited with the tackle on the play, so multi-entry roles such as split sacks or gang tackles are not collapsed to one.
returner_player_ids character List of the athlete ids of EVERY participant credited as the player returning the kick or punt on the play, so multi-entry roles such as split sacks or gang tackles are not collapsed to one.
rusher_player_ids character List of the athlete ids of EVERY participant credited as the ball carrier on a rush on the play, so multi-entry roles such as split sacks or gang tackles are not collapsed to one.
passer_player_ids character List of the athlete ids of EVERY participant credited as the passer on the play, so multi-entry roles such as split sacks or gang tackles are not collapsed to one.
receiver_player_ids character List of the athlete ids of EVERY participant credited as the targeted receiver on the play, so multi-entry roles such as split sacks or gang tackles are not collapsed to one.
punter_player_ids character List of the athlete ids of EVERY participant credited as the punter on the play, so multi-entry roles such as split sacks or gang tackles are not collapsed to one.
assisted_by_player_ids character List of the athlete ids of EVERY participant credited as a defender credited with an assisted tackle on the play, so multi-entry roles such as split sacks or gang tackles are not collapsed to one.
penalized_player_ids character List of the athlete ids of EVERY participant credited as the penalized player on the play, so multi-entry roles such as split sacks or gang tackles are not collapsed to one.
scorer_player_ids character List of the athlete ids of EVERY participant credited as the player credited with the score on the play, so multi-entry roles such as split sacks or gang tackles are not collapsed to one.
pat_scorer_player_ids character List of the athlete ids of EVERY participant credited as the player credited with the point-after score on the play, so multi-entry roles such as split sacks or gang tackles are not collapsed to one.
sacked_by_player_ids character List of the athlete ids of EVERY participant credited as a defender credited with the sack on the play, so multi-entry roles such as split sacks or gang tackles are not collapsed to one.
season integer
week integer
pass_defender_player_name character Display name of the defender credited with defending the pass -- the FIRST participant in that role on the play.
pass_defender_player_id character ESPN athlete id of the defender credited with defending the pass -- the FIRST participant in that role on the play.
pass_defender_player_names character List of the display names of EVERY participant credited as the defender credited with defending the pass on the play, so multi-entry roles such as split sacks or gang tackles are not collapsed to one.
pass_defender_player_ids character List of the athlete ids of EVERY participant credited as the defender credited with defending the pass on the play, so multi-entry roles such as split sacks or gang tackles are not collapsed to one.
recoverer_player_name character Display name of the player who recovered the fumble -- the FIRST participant in that role on the play.
fumbler_player_name character
recoverer_player_id character ESPN athlete id of the player who recovered the fumble -- the FIRST participant in that role on the play.
fumbler_player_id character
recoverer_player_names character List of the display names of EVERY participant credited as the player who recovered the fumble on the play, so multi-entry roles such as split sacks or gang tackles are not collapsed to one.
fumbler_player_names character
recoverer_player_ids character List of the athlete ids of EVERY participant credited as the player who recovered the fumble on the play, so multi-entry roles such as split sacks or gang tackles are not collapsed to one.
fumbler_player_ids character
forced_by_player_name character Display name of the defender who forced the fumble -- the FIRST participant in that role on the play.
forced_by_player_id character ESPN athlete id of the defender who forced the fumble -- the FIRST participant in that role on the play.
forced_by_player_names character List of the display names of EVERY participant credited as the defender who forced the fumble on the play, so multi-entry roles such as split sacks or gang tackles are not collapsed to one.
forced_by_player_ids character List of the athlete ids of EVERY participant credited as the defender who forced the fumble on the play, so multi-entry roles such as split sacks or gang tackles are not collapsed to one.
pat_passer_player_name character Display name of the passer on the point-after attempt -- the FIRST participant in that role on the play.
pat_passer_player_id character ESPN athlete id of the passer on the point-after attempt -- the FIRST participant in that role on the play.
pat_passer_player_names character List of the display names of EVERY participant credited as the passer on the point-after attempt on the play, so multi-entry roles such as split sacks or gang tackles are not collapsed to one.
pat_passer_player_ids character List of the athlete ids of EVERY participant credited as the passer on the point-after attempt on the play, so multi-entry roles such as split sacks or gang tackles are not collapsed to one.

Author(s)

Saiem Gilani

Examples


  try(load_espn_cfb_play_participants(2014))

Load ESPN college football player box scores from the SportsDataverse data repo

Description

Loads season-level player box scores – one row per player-game- category with the stat lines ESPN publishes per game. Published to the espn_cfb_player_box release tag on the sportsdataverse-data repo.

Usage

load_espn_cfb_player_box(
  seasons = most_recent_cfb_season(),
  ...,
  dbConnection = NULL,
  tablename = NULL
)

Arguments

seasons

A vector of 4-digit years associated with given college football seasons. Published coverage runs 2004 through the most recent season. Pass seasons = TRUE for every published season. (Min: 2004)

...

Additional arguments passed to an underlying function that writes the season data into a database.

dbConnection

A DBIConnection object, as returned by DBI::dbConnect()

tablename

The name of the data table within the database

Value

Returns a cfbfastR_data tibble.

col_name types description
stat_1 character First value of ESPN's raw athlete stats array, written only when the category's key list does not line up with the stats list; on those rows the named per-category columns are all null.
stat_2 character Second value of ESPN's raw athlete stats array, written only on rows where the category keys did not line up and the named columns could not be filled.
stat_3 character Third value of ESPN's raw athlete stats array, written only on rows where the category keys did not line up and the named columns could not be filled.
stat_4 character Fourth value of ESPN's raw athlete stats array, written only on rows where the category keys did not line up and the named columns could not be filled.
stat_5 character Fifth value of ESPN's raw athlete stats array, written only on rows where the category keys did not line up and the named columns could not be filled.
category character
athlete_id integer
athlete_name character
jersey character
team_id integer
rushingAttempts character Rushing attempts.
rushingYards character Net rushing yards gained.
yardsPerRushAttempt character Yards gained per rushing attempt.
rushingTouchdowns character Rushing touchdowns.
longRushing character Longest rush of the game, in yards.
receptions character
receivingYards character Receiving yards gained.
yardsPerReception character Yards gained per reception.
receivingTouchdowns character Receiving touchdowns.
longReception character Longest reception of the game, in yards.
fumbles character
fumblesLost character
fumblesRecovered character
kickReturns character
kickReturnYards character
yardsPerKickReturn character
longKickReturn character
kickReturnTouchdowns character
puntReturns character Punt returns attempted.
puntReturnYards character Yards gained on punt returns.
yardsPerPuntReturn character Yards gained per punt return.
longPuntReturn character Longest punt return of the game, in yards.
puntReturnTouchdowns character Touchdowns scored on punt returns.
fieldGoalsMade/fieldGoalAttempts character Field goals made and attempted, as ESPN's combined string.
fieldGoalPct character Field-goal percentage.
longFieldGoalMade character Longest field goal made, in yards.
extraPointsMade/extraPointAttempts character Extra points made and attempted, as ESPN's combined string.
totalKickingPoints character Total points scored by kicking.
punts character Punts attempted.
puntYards character Total punt yards.
grossAvgPuntYards character Gross average yards per punt, before return yardage.
touchbacks character Punts or kickoffs that resulted in a touchback.
puntsInside20 character Punts downed inside the opponent 20-yard line.
longPunt character Longest punt of the game, in yards.
game_id integer
season integer
interceptions character
interceptionYards character Yards returned on interceptions.
interceptionTouchdowns character Touchdowns scored on interception returns.
totalTackles character
soloTackles character
sacks character
tacklesForLoss character
passesDefended character
hurries character
defensiveTouchdowns character
completions/passingAttempts character Completions and pass attempts, as ESPN's combined string.
passingYards character Net passing yards gained.
yardsPerPassAttempt character Yards gained per pass attempt.
passingTouchdowns character Passing touchdowns.
adjQBR character Adjusted Total QBR for the quarterback.

Author(s)

Saiem Gilani

Examples


  try(load_espn_cfb_player_box(2004))

Load ESPN college football FPI power index from the SportsDataverse data repo

Description

Loads season-level ESPN FPI power-index snapshots – one row per team with FPI rating, projected wins, and efficiency components. Published to the espn_cfb_power_index release tag on the sportsdataverse-data repo.

Usage

load_espn_cfb_power_index(
  seasons = most_recent_cfb_season(),
  ...,
  dbConnection = NULL,
  tablename = NULL
)

Arguments

seasons

A vector of 4-digit years associated with given college football seasons. Published coverage runs 2015 through the most recent season. Pass seasons = TRUE for every published season. (Min: 2015)

...

Additional arguments passed to an underlying function that writes the season data into a database.

dbConnection

A DBIConnection object, as returned by DBI::dbConnect()

tablename

The name of the data table within the database

Value

Returns a cfbfastR_data tibble.

col_name types description
season integer
game_id integer
team_id integer
teampredptdiff double Expected margin of victory for the FPI favorite.
gameprojection double Team's predicted win percentage in this game at time of given BPI run.
matchupquality double A measure of projected competitiveness and excitement in the game, using a 0 to 100 scale, with 100 as the most exciting.
teamadjgamescore double A measure of how well a team performed compared to their expected performance and the expected performance of a typical top 25 team.

Author(s)

Saiem Gilani

Examples


  try(load_espn_cfb_power_index(2015))

Load college football receiving EPA splits from the SportsDataverse data repo

Description

Loads season-level receiving EPA splits – one row per team with target, catch, and yards-after-catch aggregates. Published to the espn_cfb_receiving release tag on the sportsdataverse-data repo.

Usage

load_espn_cfb_receiving(
  seasons = most_recent_cfb_season(),
  ...,
  dbConnection = NULL,
  tablename = NULL
)

Arguments

seasons

A vector of 4-digit years associated with given college football seasons. Published coverage runs 2004 through the most recent season. Pass seasons = TRUE for every published season. (Min: 2004)

...

Additional arguments passed to an underlying function that writes the season data into a database.

dbConnection

A DBIConnection object, as returned by DBI::dbConnect()

tablename

The name of the data table within the database

Value

Returns a cfbfastR_data tibble.

col_name types description
team_id integer
pos_team character
division character
conference character
season integer
player_id integer
receiver_player_name character Display name of the targeted receiver -- the FIRST participant in that role on the play.
plays integer
games integer
team_games integer Games the team played, used as the per-game denominator.
TEPA double Total EPA summed over every play.
EPAplay double EPA generated per play.
yards integer
success double Success rate across the team plays.
comp integer Completed passes.
targets integer
passing_td double
fumbles double Count of the receiver's targeted pass plays across the season whose play text mentions a fumble by either team.
playsgame double Plays per game.
EPAgame double EPA generated per game.
yardsplay double Yards per play.
yardsgame double Yards per game.
catchpct double Catch rate on a 0-to-1 scale, receptions divided by targets for the season.
TEPA_rank double National rank of the team's total EPA summed over every play, where 1 is best.
EPAgame_rank double National rank of the team's EPA generated per game, where 1 is best.
EPAplay_rank double National rank of the team's EPA generated per play, where 1 is best.
success_rank double National rank of the team's success rate across the team plays, where 1 is best.
catchpct_rank double Season rank of catchpct with the best catch rate first, computed only for receivers clearing the leaderboard minimum of 1.875 targets per team game and using averaged ranks for ties.
yards_rank double National rank of the team's total yards, where 1 is best.
yardsplay_rank double National rank of the team's yards per play, where 1 is best.
yardsgame_rank double National rank of the team's yards per game, where 1 is best.
fbs_class character Power/Group classification for the season: P4 or G6 from 2024 on, P5 or G5 through 2023, derived from conference membership. Null for teams outside FBS.

Author(s)

Saiem Gilani

Examples


  try(load_espn_cfb_receiving(2004))

Load college football rushing EPA splits from the SportsDataverse data repo

Description

Loads season-level rushing EPA splits – one row per team (offense and defense views) with rush EPA, success, line yards, and stuff-rate aggregates. Published to the espn_cfb_rushing release tag on the sportsdataverse-data repo.

Usage

load_espn_cfb_rushing(
  seasons = most_recent_cfb_season(),
  ...,
  dbConnection = NULL,
  tablename = NULL
)

Arguments

seasons

A vector of 4-digit years associated with given college football seasons. Published coverage runs 2004 through the most recent season. Pass seasons = TRUE for every published season. (Min: 2004)

...

Additional arguments passed to an underlying function that writes the season data into a database.

dbConnection

A DBIConnection object, as returned by DBI::dbConnect()

tablename

The name of the data table within the database

Value

Returns a cfbfastR_data tibble.

col_name types description
team_id integer
pos_team character
division character
conference character
season integer
player_id integer
rusher_player_name character Display name of the ball carrier on a rush -- the FIRST participant in that role on the play.
plays integer
games integer
team_games integer Games the team played, used as the per-game denominator.
TEPA double Total EPA summed over every play.
EPAplay double EPA generated per play.
yards integer
success double Success rate across the team plays.
rushing_td double
fumbles double Count of the ball carrier's rush attempts across the season whose play text mentions a fumble by either team.
playsgame double Plays per game.
EPAgame double EPA generated per game.
yardsplay double Yards per play.
yardsgame double Yards per game.
TEPA_rank double National rank of the team's total EPA summed over every play, where 1 is best.
EPAgame_rank double National rank of the team's EPA generated per game, where 1 is best.
EPAplay_rank double National rank of the team's EPA generated per play, where 1 is best.
success_rank double National rank of the team's success rate across the team plays, where 1 is best.
yards_rank double National rank of the team's total yards, where 1 is best.
yardsplay_rank double National rank of the team's yards per play, where 1 is best.
yardsgame_rank double National rank of the team's yards per game, where 1 is best.
fbs_class character Power/Group classification for the season: P4 or G6 from 2024 on, P5 or G5 through 2023, derived from conference membership. Null for teams outside FBS.

Author(s)

Saiem Gilani

Examples


  try(load_espn_cfb_rushing(2004))

Load ESPN college football schedules from the SportsDataverse data repo

Description

Loads season-level college football schedules built from the ESPN events API by the cfbfastR-cfb-data pipeline. One row per game with date/venue/broadcast metadata, team ids and names, scores, and status fields. Published to the espn_cfb_schedules release tag on the sportsdataverse-data repo.

Usage

load_espn_cfb_schedules(
  seasons = most_recent_cfb_season(),
  ...,
  dbConnection = NULL,
  tablename = NULL
)

Arguments

seasons

A vector of 4-digit years associated with given college football seasons. Published coverage runs 2004 through the most recent season. Pass seasons = TRUE for every published season. (Min: 2004)

...

Additional arguments passed to an underlying function that writes the season data into a database.

dbConnection

A DBIConnection object, as returned by DBI::dbConnect()

tablename

The name of the data table within the database

Value

Returns a cfbfastR_data tibble.

col_name types description
game_id integer
season integer
week integer
season_type integer
game_date character
neutral_site logical
conference_competition logical
home_id integer
away_id integer
home_team character
away_team character
home_abbreviation character
away_abbreviation character
home_score character
away_score character
home_winner logical
away_winner logical
venue character
attendance character
status character

Author(s)

Saiem Gilani

Examples


  try(load_espn_cfb_schedules(2004))

Load ESPN college football team box scores from the SportsDataverse data repo

Description

Loads season-level team box scores – one row per team-game with scoring, team statistics, and opponent context. Published to the espn_cfb_team_box release tag on the sportsdataverse-data repo.

Usage

load_espn_cfb_team_box(
  seasons = most_recent_cfb_season(),
  ...,
  dbConnection = NULL,
  tablename = NULL
)

Arguments

seasons

A vector of 4-digit years associated with given college football seasons. Published coverage runs 2004 through the most recent season. Pass seasons = TRUE for every published season. (Min: 2004)

...

Additional arguments passed to an underlying function that writes the season data into a database.

dbConnection

A DBIConnection object, as returned by DBI::dbConnect()

tablename

The name of the data table within the database

Value

Returns a cfbfastR_data tibble.

col_name types description
firstDowns character Total first downs ESPN credits the team, carried verbatim from the box score as a string.
thirdDownEff character Third-down efficiency as ESPN's conversions-attempts string, for example 5-15.
fourthDownEff character Fourth-down efficiency as a conversions-attempts string, for example 3-4.
totalYards character Total offensive yards for the team, matching rushingYards plus netPassingYards in about 99.8 percent of games.
netPassingYards character Passing yards after yardage lost to sacks is deducted, the numerator behind yardsPerPass.
completionAttempts character Completions and pass attempts as a slash-separated string, for example 23/41.
yardsPerPass character Net passing yards per pass attempt, netPassingYards divided by the attempt count in completionAttempts and rounded to one decimal.
rushingYards character Net rushing yards gained.
rushingAttempts character Rushing attempts.
yardsPerRushAttempt character Yards gained per rushing attempt.
totalPenaltiesYards character Penalties and penalty yards as a hyphen-separated string, for example 7-64.
turnovers character
fumblesLost character Number of fumbles the team lost to the opponent, carried as a string.
interceptions character
possessionTime character Time of possession as mm:ss; the two teams' values add up to 60 minutes in a regulation game.
team_id integer
team_abbreviation character
team_name character
home_away character
game_id integer
season integer

Author(s)

Saiem Gilani

Examples


  try(load_espn_cfb_team_box(2004))

Load college football team season summaries from the SportsDataverse data repo

Description

Loads season-level team summaries – one row per team with the full offense/defense/special-teams EPA and success-rate profile. Published to the espn_cfb_team_summaries release tag on the sportsdataverse-data repo.

Usage

load_espn_cfb_team_summaries(
  seasons = most_recent_cfb_season(),
  ...,
  dbConnection = NULL,
  tablename = NULL
)

Arguments

seasons

A vector of 4-digit years associated with given college football seasons. Published coverage runs 2004 through the most recent season. Pass seasons = TRUE for every published season. (Min: 2004)

...

Additional arguments passed to an underlying function that writes the season data into a database.

dbConnection

A DBIConnection object, as returned by DBI::dbConnect()

tablename

The name of the data table within the database

Value

Returns a cfbfastR_data tibble.

col_name types description
team_id integer
pos_team character
division character
conference character
season integer
plays_off integer Plays run, with the team on offense.
passrate_off double Share of plays that were pass plays, with the team on offense.
rushrate_off double Share of plays that were rush plays, with the team on offense.
havoc_off double Havoc rate -- the share of plays carrying the defensive-disruption flag, with the team on offense.
explosive_off double Explosive-play rate -- the share of plays carrying the explosive flag, with the team on offense.
TEPA_off double Total EPA summed over every play, with the team on offense.
EPAplay_off double EPA per play, with the team on offense.
yards_off integer Total yards gained, with the team on offense.
yardsplay_off double Yards gained per play, with the team on offense.
play_stuffed_off double Stuffed-play rate -- the share of plays carrying the stuffed flag, with the team on offense.
success_off double Success rate -- the share of plays flagged as successful by EPA, with the team on offense.
red_zone_success_off double Success rate on red-zone plays, with the team on offense.
third_down_success_off double Success rate on third-down plays, with the team on offense.
third_down_distance_off double Average yards to go on third down, with the team on offense.
late_down_success_off double Success rate on late-down plays, with the team on offense.
early_down_EPA_off double EPA per early-down play, with the team on offense.
start_position_off double Average drive start position, measured in yards from the opponent goal line, with the team on offense.
nonExplosiveEpaPerPlay_off double EPA per play with explosive plays excluded, with the team on offense.
line_yards_off double Average line yards credited to the offensive line on rushes, with the team on offense.
opportunity_rate_off double Opportunity rate -- the share of rushes carrying the opportunity flag, with the team on offense.
playsgame_off double Plays run per game, with the team on offense.
EPAdrive_off double EPA per drive (total EPA divided by drives), with the team on offense.
EPAgame_off double EPA per game (total EPA divided by games), with the team on offense.
yardsgame_off double Yards gained per game, with the team on offense.
drives_off integer Offensive drives, with the team on offense.
drivesgame_off double Drives per game, with the team on offense.
yardsdrive_off double Yards gained per drive, with the team on offense.
playsdrive_off double Plays run per drive, with the team on offense.
playsgame_off_rank double National rank of the team's plays run per game with the team on offense, where 1 is best.
TEPA_off_rank double National rank of the team's total EPA summed over every play with the team on offense, where 1 is best.
EPAgame_off_rank double National rank of the team's EPA per game (total EPA divided by games) with the team on offense, where 1 is best.
EPAplay_off_rank double National rank of the team's EPA per play with the team on offense, where 1 is best.
EPAdrive_off_rank double National rank of the team's EPA per drive (total EPA divided by drives) with the team on offense, where 1 is best.
early_down_EPA_off_rank double National rank of the team's EPA per early-down play with the team on offense, where 1 is best.
success_off_rank double National rank of the team's success rate -- the share of plays flagged as successful by EPA with the team on offense, where 1 is best.
yards_off_rank double National rank of the team's total yards gained with the team on offense, where 1 is best.
yardsplay_off_rank double National rank of the team's yards gained per play with the team on offense, where 1 is best.
yardsgame_off_rank double National rank of the team's yards gained per game with the team on offense, where 1 is best.
drivesgame_off_rank double National rank of the team's drives per game with the team on offense, where 1 is best.
yardsdrive_off_rank double National rank of the team's yards gained per drive with the team on offense, where 1 is best.
playsdrive_off_rank double National rank of the team's plays run per drive with the team on offense, where 1 is best.
play_stuffed_off_rank double National rank of the team's stuffed-play rate -- the share of plays carrying the stuffed flag with the team on offense, where 1 is best.
red_zone_success_off_rank double National rank of the team's success rate on red-zone plays with the team on offense, where 1 is best.
third_down_success_off_rank double National rank of the team's success rate on third-down plays with the team on offense, where 1 is best.
late_down_success_off_rank double National rank of the team's success rate on late-down plays with the team on offense, where 1 is best.
third_down_distance_off_rank double National rank of the team's average yards to go on third down with the team on offense, where 1 is best.
start_position_off_rank double National rank of the team's average drive start position, measured in yards from the opponent goal line with the team on offense, where 1 is best.
havoc_off_rank double National rank of the team's havoc rate -- the share of plays carrying the defensive-disruption flag with the team on offense, where 1 is best.
explosive_off_rank double National rank of the team's explosive-play rate -- the share of plays carrying the explosive flag with the team on offense, where 1 is best.
passrate_off_rank double National rank of the team's share of plays that were pass plays with the team on offense, where 1 is best.
rushrate_off_rank double National rank of the team's share of plays that were rush plays with the team on offense, where 1 is best.
nonExplosiveEpaPerPlay_off_rank double National rank of the team's EPA per play with explosive plays excluded with the team on offense, where 1 is best.
line_yards_off_rank double National rank of the team's average line yards credited to the offensive line on rushes with the team on offense, where 1 is best.
opportunity_rate_off_rank double National rank of the team's opportunity rate -- the share of rushes carrying the opportunity flag with the team on offense, where 1 is best.
plays_def integer Plays run, with the team on defense (i.e. allowed to opponents).
passrate_def double Share of plays that were pass plays, with the team on defense (i.e. allowed to opponents).
rushrate_def double Share of plays that were rush plays, with the team on defense (i.e. allowed to opponents).
havoc_def double Havoc rate -- the share of plays carrying the defensive-disruption flag, with the team on defense (i.e. allowed to opponents).
explosive_def double Explosive-play rate -- the share of plays carrying the explosive flag, with the team on defense (i.e. allowed to opponents).
TEPA_def double Total EPA summed over every play, with the team on defense (i.e. allowed to opponents).
EPAplay_def double EPA per play, with the team on defense (i.e. allowed to opponents).
yards_def integer Total yards gained, with the team on defense (i.e. allowed to opponents).
yardsplay_def double Yards gained per play, with the team on defense (i.e. allowed to opponents).
play_stuffed_def double Stuffed-play rate -- the share of plays carrying the stuffed flag, with the team on defense (i.e. allowed to opponents).
success_def double Success rate -- the share of plays flagged as successful by EPA, with the team on defense (i.e. allowed to opponents).
red_zone_success_def double Success rate on red-zone plays, with the team on defense (i.e. allowed to opponents).
third_down_success_def double Success rate on third-down plays, with the team on defense (i.e. allowed to opponents).
third_down_distance_def double Average yards to go on third down, with the team on defense (i.e. allowed to opponents).
late_down_success_def double Success rate on late-down plays, with the team on defense (i.e. allowed to opponents).
early_down_EPA_def double EPA per early-down play, with the team on defense (i.e. allowed to opponents).
start_position_def double Average drive start position, measured in yards from the opponent goal line, with the team on defense (i.e. allowed to opponents).
nonExplosiveEpaPerPlay_def double EPA per play with explosive plays excluded, with the team on defense (i.e. allowed to opponents).
line_yards_def double Average line yards credited to the offensive line on rushes, with the team on defense (i.e. allowed to opponents).
opportunity_rate_def double Opportunity rate -- the share of rushes carrying the opportunity flag, with the team on defense (i.e. allowed to opponents).
playsgame_def double Plays run per game, with the team on defense (i.e. allowed to opponents).
EPAdrive_def double EPA per drive (total EPA divided by drives), with the team on defense (i.e. allowed to opponents).
EPAgame_def double EPA per game (total EPA divided by games), with the team on defense (i.e. allowed to opponents).
yardsgame_def double Yards gained per game, with the team on defense (i.e. allowed to opponents).
drives_def integer Offensive drives, with the team on defense (i.e. allowed to opponents).
drivesgame_def double Drives per game, with the team on defense (i.e. allowed to opponents).
yardsdrive_def double Yards gained per drive, with the team on defense (i.e. allowed to opponents).
playsdrive_def double Plays run per drive, with the team on defense (i.e. allowed to opponents).
playsgame_def_rank double National rank of the team's plays run per game with the team on defense (i.e. allowed to opponents), where 1 is best.
TEPA_def_rank double National rank of the team's total EPA summed over every play with the team on defense (i.e. allowed to opponents), where 1 is best.
EPAgame_def_rank double National rank of the team's EPA per game (total EPA divided by games) with the team on defense (i.e. allowed to opponents), where 1 is best.
EPAplay_def_rank double National rank of the team's EPA per play with the team on defense (i.e. allowed to opponents), where 1 is best.
EPAdrive_def_rank double National rank of the team's EPA per drive (total EPA divided by drives) with the team on defense (i.e. allowed to opponents), where 1 is best.
early_down_EPA_def_rank double National rank of the team's EPA per early-down play with the team on defense (i.e. allowed to opponents), where 1 is best.
success_def_rank double National rank of the team's success rate -- the share of plays flagged as successful by EPA with the team on defense (i.e. allowed to opponents), where 1 is best.
yards_def_rank double National rank of the team's total yards gained with the team on defense (i.e. allowed to opponents), where 1 is best.
yardsplay_def_rank double National rank of the team's yards gained per play with the team on defense (i.e. allowed to opponents), where 1 is best.
yardsgame_def_rank double National rank of the team's yards gained per game with the team on defense (i.e. allowed to opponents), where 1 is best.
drivesgame_def_rank double National rank of the team's drives per game with the team on defense (i.e. allowed to opponents), where 1 is best.
yardsdrive_def_rank double National rank of the team's yards gained per drive with the team on defense (i.e. allowed to opponents), where 1 is best.
playsdrive_def_rank double National rank of the team's plays run per drive with the team on defense (i.e. allowed to opponents), where 1 is best.
play_stuffed_def_rank double National rank of the team's stuffed-play rate -- the share of plays carrying the stuffed flag with the team on defense (i.e. allowed to opponents), where 1 is best.
red_zone_success_def_rank double National rank of the team's success rate on red-zone plays with the team on defense (i.e. allowed to opponents), where 1 is best.
third_down_success_def_rank double National rank of the team's success rate on third-down plays with the team on defense (i.e. allowed to opponents), where 1 is best.
late_down_success_def_rank double National rank of the team's success rate on late-down plays with the team on defense (i.e. allowed to opponents), where 1 is best.
third_down_distance_def_rank double National rank of the team's average yards to go on third down with the team on defense (i.e. allowed to opponents), where 1 is best.
start_position_def_rank double National rank of the team's average drive start position, measured in yards from the opponent goal line with the team on defense (i.e. allowed to opponents), where 1 is best.
havoc_def_rank double National rank of the team's havoc rate -- the share of plays carrying the defensive-disruption flag with the team on defense (i.e. allowed to opponents), where 1 is best.
explosive_def_rank double National rank of the team's explosive-play rate -- the share of plays carrying the explosive flag with the team on defense (i.e. allowed to opponents), where 1 is best.
passrate_def_rank double National rank of the team's share of plays that were pass plays with the team on defense (i.e. allowed to opponents), where 1 is best.
rushrate_def_rank double National rank of the team's share of plays that were rush plays with the team on defense (i.e. allowed to opponents), where 1 is best.
nonExplosiveEpaPerPlay_def_rank double National rank of the team's EPA per play with explosive plays excluded with the team on defense (i.e. allowed to opponents), where 1 is best.
line_yards_def_rank double National rank of the team's average line yards credited to the offensive line on rushes with the team on defense (i.e. allowed to opponents), where 1 is best.
opportunity_rate_def_rank double National rank of the team's opportunity rate -- the share of rushes carrying the opportunity flag with the team on defense (i.e. allowed to opponents), where 1 is best.
TEPA_margin double Margin in total EPA summed over every play: the team's offensive value minus the value it allowed on defense.
EPAplay_margin double Margin in EPA per play: the team's offensive value minus the value it allowed on defense.
EPAdrive_margin double Margin in EPA per drive (total EPA divided by drives): the team's offensive value minus the value it allowed on defense.
EPAgame_margin double Margin in EPA per game (total EPA divided by games): the team's offensive value minus the value it allowed on defense.
success_margin double Margin in success rate -- the share of plays flagged as successful by EPA: the team's offensive value minus the value it allowed on defense.
yardsplay_margin double Margin in yards gained per play: the team's offensive value minus the value it allowed on defense.
TEPA_margin_rank double Margin in total EPA summed over every play: the team's offensive value minus the value it allowed on defense. National rank of that margin, 1 = largest.
EPAplay_margin_rank double Margin in EPA per play: the team's offensive value minus the value it allowed on defense. National rank of that margin, 1 = largest.
EPAdrive_margin_rank double Margin in EPA per drive (total EPA divided by drives): the team's offensive value minus the value it allowed on defense. National rank of that margin, 1 = largest.
EPAgame_margin_rank double Margin in EPA per game (total EPA divided by games): the team's offensive value minus the value it allowed on defense. National rank of that margin, 1 = largest.
success_margin_rank double Margin in success rate -- the share of plays flagged as successful by EPA: the team's offensive value minus the value it allowed on defense. National rank of that margin, 1 = largest.
yardsplay_margin_rank double Margin in yards gained per play: the team's offensive value minus the value it allowed on defense. National rank of that margin, 1 = largest.
start_position_margin double Field-position margin: the team's own average starting field position minus the average starting field position it allowed, both measured as yards gained from their own goal line. Positive means the team started closer to scoring than its opponents.
start_position_margin_rank double Field-position margin: the team's own average starting field position minus the average starting field position it allowed, both measured as yards gained from their own goal line. Positive means the team started closer to scoring than its opponents. National rank of that margin, 1 = largest.
total_available_yards_off double Available yards are the yards a drive could theoretically gain, summed from each drive's starting distance to the opponent goal line. Total available yards on the team's own drives.
total_gained_yards_off integer Total yards the team actually gained across its own drives.
available_yards_pct_off double Share of available yards the team's offense actually gained (total_gained_yards_off divided by total_available_yards_off). Higher is better.
available_yards_pct_off_rank double National rank of the team's offensive available-yards share, where 1 is best.
total_available_yards_def double Available yards are the yards a drive could theoretically gain, summed from each drive's starting distance to the opponent goal line. Total available yards on drives the team defended.
total_gained_yards_def integer Total yards the team allowed across the drives it defended.
available_yards_pct_def double Share of available yards the team's defense allowed opponents to gain. Lower is better.
available_yards_pct_def_rank double National rank of the team's defensive available-yards share, where 1 is best.
total_available_yards_margin double Available yards on the team's own drives minus available yards on drives it defended.
total_gained_yards_margin integer Yards the team gained minus yards it allowed.
available_yards_pct_margin double Available-yards share gained by the offense minus the share allowed by the defense. Higher is better.
total_available_yards_margin_rank double National rank of total_available_yards_margin, 1 = largest margin.
total_gained_yards_margin_rank double National rank of total_gained_yards_margin, 1 = largest margin.
available_yards_pct_margin_rank double National rank of available_yards_pct_margin, 1 = largest margin.
plays_off_pass integer Plays run on pass plays, with the team on offense.
passrate_off_pass double Share of plays that were pass plays on pass plays, with the team on offense.
rushrate_off_pass double Share of plays that were rush plays on pass plays, with the team on offense.
havoc_off_pass double Havoc rate -- the share of plays carrying the defensive-disruption flag on pass plays, with the team on offense.
explosive_off_pass double Explosive-play rate -- the share of plays carrying the explosive flag on pass plays, with the team on offense.
TEPA_off_pass double Total EPA summed over every play on pass plays, with the team on offense.
EPAplay_off_pass double EPA per play on pass plays, with the team on offense.
yards_off_pass integer Total yards gained on pass plays, with the team on offense.
yardsplay_off_pass double Yards gained per play on pass plays, with the team on offense.
play_stuffed_off_pass double Stuffed-play rate -- the share of plays carrying the stuffed flag on pass plays, with the team on offense.
success_off_pass double Success rate -- the share of plays flagged as successful by EPA on pass plays, with the team on offense.
red_zone_success_off_pass double Success rate on red-zone plays on pass plays, with the team on offense.
third_down_success_off_pass double Success rate on third-down plays on pass plays, with the team on offense.
third_down_distance_off_pass double Average yards to go on third down on pass plays, with the team on offense.
late_down_success_off_pass double Success rate on late-down plays on pass plays, with the team on offense.
early_down_EPA_off_pass double EPA per early-down play on pass plays, with the team on offense.
nonExplosiveEpaPerPlay_off_pass double EPA per play with explosive plays excluded on pass plays, with the team on offense.
line_yards_off_pass double Average line yards credited to the offensive line on rushes on pass plays, with the team on offense.
opportunity_rate_off_pass double Opportunity rate -- the share of rushes carrying the opportunity flag on pass plays, with the team on offense.
playsgame_off_pass double Plays run per game on pass plays, with the team on offense.
EPAdrive_off_pass double EPA per drive (total EPA divided by drives) on pass plays, with the team on offense.
EPAgame_off_pass double EPA per game (total EPA divided by games) on pass plays, with the team on offense.
yardsgame_off_pass double Yards gained per game on pass plays, with the team on offense.
drives_off_pass integer Offensive drives on pass plays, with the team on offense.
drivesgame_off_pass double Drives per game on pass plays, with the team on offense.
yardsdrive_off_pass double Yards gained per drive on pass plays, with the team on offense.
playsdrive_off_pass double Plays run per drive on pass plays, with the team on offense.
playsgame_off_pass_rank double National rank of the team's plays run per game on pass plays with the team on offense, where 1 is best.
TEPA_off_pass_rank double National rank of the team's total EPA summed over every play on pass plays with the team on offense, where 1 is best.
EPAgame_off_pass_rank double National rank of the team's EPA per game (total EPA divided by games) on pass plays with the team on offense, where 1 is best.
EPAplay_off_pass_rank double National rank of the team's EPA per play on pass plays with the team on offense, where 1 is best.
EPAdrive_off_pass_rank double National rank of the team's EPA per drive (total EPA divided by drives) on pass plays with the team on offense, where 1 is best.
early_down_EPA_off_pass_rank double National rank of the team's EPA per early-down play on pass plays with the team on offense, where 1 is best.
success_off_pass_rank double National rank of the team's success rate -- the share of plays flagged as successful by EPA on pass plays with the team on offense, where 1 is best.
yards_off_pass_rank double National rank of the team's total yards gained on pass plays with the team on offense, where 1 is best.
yardsplay_off_pass_rank double National rank of the team's yards gained per play on pass plays with the team on offense, where 1 is best.
yardsgame_off_pass_rank double National rank of the team's yards gained per game on pass plays with the team on offense, where 1 is best.
drivesgame_off_pass_rank double National rank of the team's drives per game on pass plays with the team on offense, where 1 is best.
yardsdrive_off_pass_rank double National rank of the team's yards gained per drive on pass plays with the team on offense, where 1 is best.
playsdrive_off_pass_rank double National rank of the team's plays run per drive on pass plays with the team on offense, where 1 is best.
play_stuffed_off_pass_rank double National rank of the team's stuffed-play rate -- the share of plays carrying the stuffed flag on pass plays with the team on offense, where 1 is best.
red_zone_success_off_pass_rank double National rank of the team's success rate on red-zone plays on pass plays with the team on offense, where 1 is best.
third_down_success_off_pass_rank double National rank of the team's success rate on third-down plays on pass plays with the team on offense, where 1 is best.
late_down_success_off_pass_rank double National rank of the team's success rate on late-down plays on pass plays with the team on offense, where 1 is best.
third_down_distance_off_pass_rank double National rank of the team's average yards to go on third down on pass plays with the team on offense, where 1 is best.
havoc_off_pass_rank double National rank of the team's havoc rate -- the share of plays carrying the defensive-disruption flag on pass plays with the team on offense, where 1 is best.
explosive_off_pass_rank double National rank of the team's explosive-play rate -- the share of plays carrying the explosive flag on pass plays with the team on offense, where 1 is best.
passrate_off_pass_rank double National rank of the team's share of plays that were pass plays on pass plays with the team on offense, where 1 is best.
rushrate_off_pass_rank double National rank of the team's share of plays that were rush plays on pass plays with the team on offense, where 1 is best.
nonExplosiveEpaPerPlay_off_pass_rank double National rank of the team's EPA per play with explosive plays excluded on pass plays with the team on offense, where 1 is best.
line_yards_off_pass_rank double National rank of the team's average line yards credited to the offensive line on rushes on pass plays with the team on offense, where 1 is best.
opportunity_rate_off_pass_rank double National rank of the team's opportunity rate -- the share of rushes carrying the opportunity flag on pass plays with the team on offense, where 1 is best.
plays_def_pass integer Plays run on pass plays, with the team on defense (i.e. allowed to opponents).
passrate_def_pass double Share of plays that were pass plays on pass plays, with the team on defense (i.e. allowed to opponents).
rushrate_def_pass double Share of plays that were rush plays on pass plays, with the team on defense (i.e. allowed to opponents).
havoc_def_pass double Havoc rate -- the share of plays carrying the defensive-disruption flag on pass plays, with the team on defense (i.e. allowed to opponents).
explosive_def_pass double Explosive-play rate -- the share of plays carrying the explosive flag on pass plays, with the team on defense (i.e. allowed to opponents).
TEPA_def_pass double Total EPA summed over every play on pass plays, with the team on defense (i.e. allowed to opponents).
EPAplay_def_pass double EPA per play on pass plays, with the team on defense (i.e. allowed to opponents).
yards_def_pass integer Total yards gained on pass plays, with the team on defense (i.e. allowed to opponents).
yardsplay_def_pass double Yards gained per play on pass plays, with the team on defense (i.e. allowed to opponents).
play_stuffed_def_pass double Stuffed-play rate -- the share of plays carrying the stuffed flag on pass plays, with the team on defense (i.e. allowed to opponents).
success_def_pass double Success rate -- the share of plays flagged as successful by EPA on pass plays, with the team on defense (i.e. allowed to opponents).
red_zone_success_def_pass double Success rate on red-zone plays on pass plays, with the team on defense (i.e. allowed to opponents).
third_down_success_def_pass double Success rate on third-down plays on pass plays, with the team on defense (i.e. allowed to opponents).
third_down_distance_def_pass double Average yards to go on third down on pass plays, with the team on defense (i.e. allowed to opponents).
late_down_success_def_pass double Success rate on late-down plays on pass plays, with the team on defense (i.e. allowed to opponents).
early_down_EPA_def_pass double EPA per early-down play on pass plays, with the team on defense (i.e. allowed to opponents).
nonExplosiveEpaPerPlay_def_pass double EPA per play with explosive plays excluded on pass plays, with the team on defense (i.e. allowed to opponents).
line_yards_def_pass double Average line yards credited to the offensive line on rushes on pass plays, with the team on defense (i.e. allowed to opponents).
opportunity_rate_def_pass double Opportunity rate -- the share of rushes carrying the opportunity flag on pass plays, with the team on defense (i.e. allowed to opponents).
playsgame_def_pass double Plays run per game on pass plays, with the team on defense (i.e. allowed to opponents).
EPAdrive_def_pass double EPA per drive (total EPA divided by drives) on pass plays, with the team on defense (i.e. allowed to opponents).
EPAgame_def_pass double EPA per game (total EPA divided by games) on pass plays, with the team on defense (i.e. allowed to opponents).
yardsgame_def_pass double Yards gained per game on pass plays, with the team on defense (i.e. allowed to opponents).
drives_def_pass integer Offensive drives on pass plays, with the team on defense (i.e. allowed to opponents).
drivesgame_def_pass double Drives per game on pass plays, with the team on defense (i.e. allowed to opponents).
yardsdrive_def_pass double Yards gained per drive on pass plays, with the team on defense (i.e. allowed to opponents).
playsdrive_def_pass double Plays run per drive on pass plays, with the team on defense (i.e. allowed to opponents).
playsgame_def_pass_rank double National rank of the team's plays run per game on pass plays with the team on defense (i.e. allowed to opponents), where 1 is best.
TEPA_def_pass_rank double National rank of the team's total EPA summed over every play on pass plays with the team on defense (i.e. allowed to opponents), where 1 is best.
EPAgame_def_pass_rank double National rank of the team's EPA per game (total EPA divided by games) on pass plays with the team on defense (i.e. allowed to opponents), where 1 is best.
EPAplay_def_pass_rank double National rank of the team's EPA per play on pass plays with the team on defense (i.e. allowed to opponents), where 1 is best.
EPAdrive_def_pass_rank double National rank of the team's EPA per drive (total EPA divided by drives) on pass plays with the team on defense (i.e. allowed to opponents), where 1 is best.
early_down_EPA_def_pass_rank double National rank of the team's EPA per early-down play on pass plays with the team on defense (i.e. allowed to opponents), where 1 is best.
success_def_pass_rank double National rank of the team's success rate -- the share of plays flagged as successful by EPA on pass plays with the team on defense (i.e. allowed to opponents), where 1 is best.
yards_def_pass_rank double National rank of the team's total yards gained on pass plays with the team on defense (i.e. allowed to opponents), where 1 is best.
yardsplay_def_pass_rank double National rank of the team's yards gained per play on pass plays with the team on defense (i.e. allowed to opponents), where 1 is best.
yardsgame_def_pass_rank double National rank of the team's yards gained per game on pass plays with the team on defense (i.e. allowed to opponents), where 1 is best.
drivesgame_def_pass_rank double National rank of the team's drives per game on pass plays with the team on defense (i.e. allowed to opponents), where 1 is best.
yardsdrive_def_pass_rank double National rank of the team's yards gained per drive on pass plays with the team on defense (i.e. allowed to opponents), where 1 is best.
playsdrive_def_pass_rank double National rank of the team's plays run per drive on pass plays with the team on defense (i.e. allowed to opponents), where 1 is best.
play_stuffed_def_pass_rank double National rank of the team's stuffed-play rate -- the share of plays carrying the stuffed flag on pass plays with the team on defense (i.e. allowed to opponents), where 1 is best.
red_zone_success_def_pass_rank double National rank of the team's success rate on red-zone plays on pass plays with the team on defense (i.e. allowed to opponents), where 1 is best.
third_down_success_def_pass_rank double National rank of the team's success rate on third-down plays on pass plays with the team on defense (i.e. allowed to opponents), where 1 is best.
late_down_success_def_pass_rank double National rank of the team's success rate on late-down plays on pass plays with the team on defense (i.e. allowed to opponents), where 1 is best.
third_down_distance_def_pass_rank double National rank of the team's average yards to go on third down on pass plays with the team on defense (i.e. allowed to opponents), where 1 is best.
havoc_def_pass_rank double National rank of the team's havoc rate -- the share of plays carrying the defensive-disruption flag on pass plays with the team on defense (i.e. allowed to opponents), where 1 is best.
explosive_def_pass_rank double National rank of the team's explosive-play rate -- the share of plays carrying the explosive flag on pass plays with the team on defense (i.e. allowed to opponents), where 1 is best.
passrate_def_pass_rank double National rank of the team's share of plays that were pass plays on pass plays with the team on defense (i.e. allowed to opponents), where 1 is best.
rushrate_def_pass_rank double National rank of the team's share of plays that were rush plays on pass plays with the team on defense (i.e. allowed to opponents), where 1 is best.
nonExplosiveEpaPerPlay_def_pass_rank double National rank of the team's EPA per play with explosive plays excluded on pass plays with the team on defense (i.e. allowed to opponents), where 1 is best.
line_yards_def_pass_rank double National rank of the team's average line yards credited to the offensive line on rushes on pass plays with the team on defense (i.e. allowed to opponents), where 1 is best.
opportunity_rate_def_pass_rank double National rank of the team's opportunity rate -- the share of rushes carrying the opportunity flag on pass plays with the team on defense (i.e. allowed to opponents), where 1 is best.
TEPA_margin_pass double Margin in total EPA summed over every play on pass plays: the team's offensive value minus the value it allowed on defense.
EPAplay_margin_pass double Margin in EPA per play on pass plays: the team's offensive value minus the value it allowed on defense.
EPAdrive_margin_pass double Margin in EPA per drive (total EPA divided by drives) on pass plays: the team's offensive value minus the value it allowed on defense.
EPAgame_margin_pass double Margin in EPA per game (total EPA divided by games) on pass plays: the team's offensive value minus the value it allowed on defense.
success_margin_pass double Margin in success rate -- the share of plays flagged as successful by EPA on pass plays: the team's offensive value minus the value it allowed on defense.
yardsplay_margin_pass double Margin in yards gained per play on pass plays: the team's offensive value minus the value it allowed on defense.
TEPA_margin_pass_rank double Margin in total EPA summed over every play on pass plays: the team's offensive value minus the value it allowed on defense. National rank of that margin, 1 = largest.
EPAplay_margin_pass_rank double Margin in EPA per play on pass plays: the team's offensive value minus the value it allowed on defense. National rank of that margin, 1 = largest.
EPAdrive_margin_pass_rank double Margin in EPA per drive (total EPA divided by drives) on pass plays: the team's offensive value minus the value it allowed on defense. National rank of that margin, 1 = largest.
EPAgame_margin_pass_rank double Margin in EPA per game (total EPA divided by games) on pass plays: the team's offensive value minus the value it allowed on defense. National rank of that margin, 1 = largest.
success_margin_pass_rank double Margin in success rate -- the share of plays flagged as successful by EPA on pass plays: the team's offensive value minus the value it allowed on defense. National rank of that margin, 1 = largest.
yardsplay_margin_pass_rank double Margin in yards gained per play on pass plays: the team's offensive value minus the value it allowed on defense. National rank of that margin, 1 = largest.
plays_off_rush integer Plays run on rush plays, with the team on offense.
passrate_off_rush double Share of plays that were pass plays on rush plays, with the team on offense.
rushrate_off_rush double Share of plays that were rush plays on rush plays, with the team on offense.
havoc_off_rush double Havoc rate -- the share of plays carrying the defensive-disruption flag on rush plays, with the team on offense.
explosive_off_rush double Explosive-play rate -- the share of plays carrying the explosive flag on rush plays, with the team on offense.
TEPA_off_rush double Total EPA summed over every play on rush plays, with the team on offense.
EPAplay_off_rush double EPA per play on rush plays, with the team on offense.
yards_off_rush integer Total yards gained on rush plays, with the team on offense.
yardsplay_off_rush double Yards gained per play on rush plays, with the team on offense.
play_stuffed_off_rush double Stuffed-play rate -- the share of plays carrying the stuffed flag on rush plays, with the team on offense.
success_off_rush double Success rate -- the share of plays flagged as successful by EPA on rush plays, with the team on offense.
red_zone_success_off_rush double Success rate on red-zone plays on rush plays, with the team on offense.
third_down_success_off_rush double Success rate on third-down plays on rush plays, with the team on offense.
third_down_distance_off_rush double Average yards to go on third down on rush plays, with the team on offense.
late_down_success_off_rush double Success rate on late-down plays on rush plays, with the team on offense.
early_down_EPA_off_rush double EPA per early-down play on rush plays, with the team on offense.
nonExplosiveEpaPerPlay_off_rush double EPA per play with explosive plays excluded on rush plays, with the team on offense.
line_yards_off_rush double Average line yards credited to the offensive line on rushes on rush plays, with the team on offense.
opportunity_rate_off_rush double Opportunity rate -- the share of rushes carrying the opportunity flag on rush plays, with the team on offense.
playsgame_off_rush double Plays run per game on rush plays, with the team on offense.
EPAdrive_off_rush double EPA per drive (total EPA divided by drives) on rush plays, with the team on offense.
EPAgame_off_rush double EPA per game (total EPA divided by games) on rush plays, with the team on offense.
yardsgame_off_rush double Yards gained per game on rush plays, with the team on offense.
drives_off_rush integer Offensive drives on rush plays, with the team on offense.
drivesgame_off_rush double Drives per game on rush plays, with the team on offense.
yardsdrive_off_rush double Yards gained per drive on rush plays, with the team on offense.
playsdrive_off_rush double Plays run per drive on rush plays, with the team on offense.
playsgame_off_rush_rank double National rank of the team's plays run per game on rush plays with the team on offense, where 1 is best.
TEPA_off_rush_rank double National rank of the team's total EPA summed over every play on rush plays with the team on offense, where 1 is best.
EPAgame_off_rush_rank double National rank of the team's EPA per game (total EPA divided by games) on rush plays with the team on offense, where 1 is best.
EPAplay_off_rush_rank double National rank of the team's EPA per play on rush plays with the team on offense, where 1 is best.
EPAdrive_off_rush_rank double National rank of the team's EPA per drive (total EPA divided by drives) on rush plays with the team on offense, where 1 is best.
early_down_EPA_off_rush_rank double National rank of the team's EPA per early-down play on rush plays with the team on offense, where 1 is best.
success_off_rush_rank double National rank of the team's success rate -- the share of plays flagged as successful by EPA on rush plays with the team on offense, where 1 is best.
yards_off_rush_rank double National rank of the team's total yards gained on rush plays with the team on offense, where 1 is best.
yardsplay_off_rush_rank double National rank of the team's yards gained per play on rush plays with the team on offense, where 1 is best.
yardsgame_off_rush_rank double National rank of the team's yards gained per game on rush plays with the team on offense, where 1 is best.
drivesgame_off_rush_rank double National rank of the team's drives per game on rush plays with the team on offense, where 1 is best.
yardsdrive_off_rush_rank double National rank of the team's yards gained per drive on rush plays with the team on offense, where 1 is best.
playsdrive_off_rush_rank double National rank of the team's plays run per drive on rush plays with the team on offense, where 1 is best.
play_stuffed_off_rush_rank double National rank of the team's stuffed-play rate -- the share of plays carrying the stuffed flag on rush plays with the team on offense, where 1 is best.
red_zone_success_off_rush_rank double National rank of the team's success rate on red-zone plays on rush plays with the team on offense, where 1 is best.
third_down_success_off_rush_rank double National rank of the team's success rate on third-down plays on rush plays with the team on offense, where 1 is best.
late_down_success_off_rush_rank double National rank of the team's success rate on late-down plays on rush plays with the team on offense, where 1 is best.
third_down_distance_off_rush_rank double National rank of the team's average yards to go on third down on rush plays with the team on offense, where 1 is best.
havoc_off_rush_rank double National rank of the team's havoc rate -- the share of plays carrying the defensive-disruption flag on rush plays with the team on offense, where 1 is best.
explosive_off_rush_rank double National rank of the team's explosive-play rate -- the share of plays carrying the explosive flag on rush plays with the team on offense, where 1 is best.
passrate_off_rush_rank double National rank of the team's share of plays that were pass plays on rush plays with the team on offense, where 1 is best.
rushrate_off_rush_rank double National rank of the team's share of plays that were rush plays on rush plays with the team on offense, where 1 is best.
nonExplosiveEpaPerPlay_off_rush_rank double National rank of the team's EPA per play with explosive plays excluded on rush plays with the team on offense, where 1 is best.
line_yards_off_rush_rank double National rank of the team's average line yards credited to the offensive line on rushes on rush plays with the team on offense, where 1 is best.
opportunity_rate_off_rush_rank double National rank of the team's opportunity rate -- the share of rushes carrying the opportunity flag on rush plays with the team on offense, where 1 is best.
plays_def_rush integer Plays run on rush plays, with the team on defense (i.e. allowed to opponents).
passrate_def_rush double Share of plays that were pass plays on rush plays, with the team on defense (i.e. allowed to opponents).
rushrate_def_rush double Share of plays that were rush plays on rush plays, with the team on defense (i.e. allowed to opponents).
havoc_def_rush double Havoc rate -- the share of plays carrying the defensive-disruption flag on rush plays, with the team on defense (i.e. allowed to opponents).
explosive_def_rush double Explosive-play rate -- the share of plays carrying the explosive flag on rush plays, with the team on defense (i.e. allowed to opponents).
TEPA_def_rush double Total EPA summed over every play on rush plays, with the team on defense (i.e. allowed to opponents).
EPAplay_def_rush double EPA per play on rush plays, with the team on defense (i.e. allowed to opponents).
yards_def_rush integer Total yards gained on rush plays, with the team on defense (i.e. allowed to opponents).
yardsplay_def_rush double Yards gained per play on rush plays, with the team on defense (i.e. allowed to opponents).
play_stuffed_def_rush double Stuffed-play rate -- the share of plays carrying the stuffed flag on rush plays, with the team on defense (i.e. allowed to opponents).
success_def_rush double Success rate -- the share of plays flagged as successful by EPA on rush plays, with the team on defense (i.e. allowed to opponents).
red_zone_success_def_rush double Success rate on red-zone plays on rush plays, with the team on defense (i.e. allowed to opponents).
third_down_success_def_rush double Success rate on third-down plays on rush plays, with the team on defense (i.e. allowed to opponents).
third_down_distance_def_rush double Average yards to go on third down on rush plays, with the team on defense (i.e. allowed to opponents).
late_down_success_def_rush double Success rate on late-down plays on rush plays, with the team on defense (i.e. allowed to opponents).
early_down_EPA_def_rush double EPA per early-down play on rush plays, with the team on defense (i.e. allowed to opponents).
nonExplosiveEpaPerPlay_def_rush double EPA per play with explosive plays excluded on rush plays, with the team on defense (i.e. allowed to opponents).
line_yards_def_rush double Average line yards credited to the offensive line on rushes on rush plays, with the team on defense (i.e. allowed to opponents).
opportunity_rate_def_rush double Opportunity rate -- the share of rushes carrying the opportunity flag on rush plays, with the team on defense (i.e. allowed to opponents).
playsgame_def_rush double Plays run per game on rush plays, with the team on defense (i.e. allowed to opponents).
EPAdrive_def_rush double EPA per drive (total EPA divided by drives) on rush plays, with the team on defense (i.e. allowed to opponents).
EPAgame_def_rush double EPA per game (total EPA divided by games) on rush plays, with the team on defense (i.e. allowed to opponents).
yardsgame_def_rush double Yards gained per game on rush plays, with the team on defense (i.e. allowed to opponents).
drives_def_rush integer Offensive drives on rush plays, with the team on defense (i.e. allowed to opponents).
drivesgame_def_rush double Drives per game on rush plays, with the team on defense (i.e. allowed to opponents).
yardsdrive_def_rush double Yards gained per drive on rush plays, with the team on defense (i.e. allowed to opponents).
playsdrive_def_rush double Plays run per drive on rush plays, with the team on defense (i.e. allowed to opponents).
playsgame_def_rush_rank double National rank of the team's plays run per game on rush plays with the team on defense (i.e. allowed to opponents), where 1 is best.
TEPA_def_rush_rank double National rank of the team's total EPA summed over every play on rush plays with the team on defense (i.e. allowed to opponents), where 1 is best.
EPAgame_def_rush_rank double National rank of the team's EPA per game (total EPA divided by games) on rush plays with the team on defense (i.e. allowed to opponents), where 1 is best.
EPAplay_def_rush_rank double National rank of the team's EPA per play on rush plays with the team on defense (i.e. allowed to opponents), where 1 is best.
EPAdrive_def_rush_rank double National rank of the team's EPA per drive (total EPA divided by drives) on rush plays with the team on defense (i.e. allowed to opponents), where 1 is best.
early_down_EPA_def_rush_rank double National rank of the team's EPA per early-down play on rush plays with the team on defense (i.e. allowed to opponents), where 1 is best.
success_def_rush_rank double National rank of the team's success rate -- the share of plays flagged as successful by EPA on rush plays with the team on defense (i.e. allowed to opponents), where 1 is best.
yards_def_rush_rank double National rank of the team's total yards gained on rush plays with the team on defense (i.e. allowed to opponents), where 1 is best.
yardsplay_def_rush_rank double National rank of the team's yards gained per play on rush plays with the team on defense (i.e. allowed to opponents), where 1 is best.
yardsgame_def_rush_rank double National rank of the team's yards gained per game on rush plays with the team on defense (i.e. allowed to opponents), where 1 is best.
drivesgame_def_rush_rank double National rank of the team's drives per game on rush plays with the team on defense (i.e. allowed to opponents), where 1 is best.
yardsdrive_def_rush_rank double National rank of the team's yards gained per drive on rush plays with the team on defense (i.e. allowed to opponents), where 1 is best.
playsdrive_def_rush_rank double National rank of the team's plays run per drive on rush plays with the team on defense (i.e. allowed to opponents), where 1 is best.
play_stuffed_def_rush_rank double National rank of the team's stuffed-play rate -- the share of plays carrying the stuffed flag on rush plays with the team on defense (i.e. allowed to opponents), where 1 is best.
red_zone_success_def_rush_rank double National rank of the team's success rate on red-zone plays on rush plays with the team on defense (i.e. allowed to opponents), where 1 is best.
third_down_success_def_rush_rank double National rank of the team's success rate on third-down plays on rush plays with the team on defense (i.e. allowed to opponents), where 1 is best.
late_down_success_def_rush_rank double National rank of the team's success rate on late-down plays on rush plays with the team on defense (i.e. allowed to opponents), where 1 is best.
third_down_distance_def_rush_rank double National rank of the team's average yards to go on third down on rush plays with the team on defense (i.e. allowed to opponents), where 1 is best.
havoc_def_rush_rank double National rank of the team's havoc rate -- the share of plays carrying the defensive-disruption flag on rush plays with the team on defense (i.e. allowed to opponents), where 1 is best.
explosive_def_rush_rank double National rank of the team's explosive-play rate -- the share of plays carrying the explosive flag on rush plays with the team on defense (i.e. allowed to opponents), where 1 is best.
passrate_def_rush_rank double National rank of the team's share of plays that were pass plays on rush plays with the team on defense (i.e. allowed to opponents), where 1 is best.
rushrate_def_rush_rank double National rank of the team's share of plays that were rush plays on rush plays with the team on defense (i.e. allowed to opponents), where 1 is best.
nonExplosiveEpaPerPlay_def_rush_rank double National rank of the team's EPA per play with explosive plays excluded on rush plays with the team on defense (i.e. allowed to opponents), where 1 is best.
line_yards_def_rush_rank double National rank of the team's average line yards credited to the offensive line on rushes on rush plays with the team on defense (i.e. allowed to opponents), where 1 is best.
opportunity_rate_def_rush_rank double National rank of the team's opportunity rate -- the share of rushes carrying the opportunity flag on rush plays with the team on defense (i.e. allowed to opponents), where 1 is best.
TEPA_margin_rush double Margin in total EPA summed over every play on rush plays: the team's offensive value minus the value it allowed on defense.
EPAplay_margin_rush double Margin in EPA per play on rush plays: the team's offensive value minus the value it allowed on defense.
EPAdrive_margin_rush double Margin in EPA per drive (total EPA divided by drives) on rush plays: the team's offensive value minus the value it allowed on defense.
EPAgame_margin_rush double Margin in EPA per game (total EPA divided by games) on rush plays: the team's offensive value minus the value it allowed on defense.
success_margin_rush double Margin in success rate -- the share of plays flagged as successful by EPA on rush plays: the team's offensive value minus the value it allowed on defense.
yardsplay_margin_rush double Margin in yards gained per play on rush plays: the team's offensive value minus the value it allowed on defense.
TEPA_margin_rush_rank double Margin in total EPA summed over every play on rush plays: the team's offensive value minus the value it allowed on defense. National rank of that margin, 1 = largest.
EPAplay_margin_rush_rank double Margin in EPA per play on rush plays: the team's offensive value minus the value it allowed on defense. National rank of that margin, 1 = largest.
EPAdrive_margin_rush_rank double Margin in EPA per drive (total EPA divided by drives) on rush plays: the team's offensive value minus the value it allowed on defense. National rank of that margin, 1 = largest.
EPAgame_margin_rush_rank double Margin in EPA per game (total EPA divided by games) on rush plays: the team's offensive value minus the value it allowed on defense. National rank of that margin, 1 = largest.
success_margin_rush_rank double Margin in success rate -- the share of plays flagged as successful by EPA on rush plays: the team's offensive value minus the value it allowed on defense. National rank of that margin, 1 = largest.
yardsplay_margin_rush_rank double Margin in yards gained per play on rush plays: the team's offensive value minus the value it allowed on defense. National rank of that margin, 1 = largest.
fbs_class character Power/Group classification for the season: P4 or G6 from 2024 on, P5 or G5 through 2023, derived from conference membership (Notre Dame is classified with the power group). Null for teams outside FBS.
valid_games integer Number of the team's games that produced both an offensive and a defensive adjusted-EPA value; teams below two valid games are dropped from the adjusted ratings.
adj_off_epa double Offensive opponent-adjusted EPA per play from the ridge (RAPM-style) regression on offense/defense team indicators plus home field -- cfbfastR's adjust_epa adjustment, fit in-sample across the season, so the value is descriptive of that window rather than predictive.
adj_def_epa double Defensive opponent-adjusted EPA per play from the ridge (RAPM-style) regression on offense/defense team indicators plus home field -- cfbfastR's adjust_epa adjustment, fit in-sample across the season, so the value is descriptive of that window rather than predictive. Lower is better -- it is EPA allowed.
off_strength_faced double Average opponent-defense strength the team's offense faced, taken as the mean of the ridge's defensive coefficients across its opponents. Higher means a tougher slate.
def_strength_faced double Average opponent-offense strength the team's defense faced, taken as the mean of the ridge's offensive coefficients across its opponents. Higher means a tougher slate.
net_adj_epa double Net opponent-adjusted EPA per play: adj_off_epa minus adj_def_epa. Higher is better.
adj_off_epa_rank double National rank of the team's adj_off_epa, where 1 is best.
adj_def_epa_rank double National rank of the team's adj_def_epa, where 1 is best (fewest EPA allowed).
net_adj_epa_rank double National rank of the team's net_adj_epa, 1 = largest net adjusted EPA.

Author(s)

Saiem Gilani

Examples


  try(load_espn_cfb_team_summaries(2004))

Load NCAA men's football drives (stats.ncaa.org) from the SportsDataverse data repo

Description

Loads season-level NCAA men's football drive summaries parsed from stats.ncaa.org; one row per drive. Published to the ncaa_mfb_drives release tag on the sportsdataverse-data repo.

Usage

load_ncaa_mfb_drives(
  seasons = most_recent_cfb_season(),
  ...,
  dbConnection = NULL,
  tablename = NULL
)

Arguments

seasons

A vector of 4-digit years associated with given college football seasons. Published coverage runs 2013 through the most recent season. Pass seasons = TRUE for every published season. (Min: 2013)

...

Additional arguments passed to an underlying function that writes the season data into a database.

dbConnection

A DBIConnection object, as returned by DBI::dbConnect()

tablename

The name of the data table within the database

Value

Returns a cfbfastR_data tibble.

col_name types description
contest_id character
drive_number integer
quarter integer
period integer
team character
start_period integer
start_how character
start_clock character
start_yard_line character
end_period integer
end_how character
end_clock character
end_yard_line character
n_plays integer
yards integer
espn_game_id character
season integer

Author(s)

Saiem Gilani

Examples


  try(load_ncaa_mfb_drives(2013))

Load NCAA men's football linescores (stats.ncaa.org) from the SportsDataverse data repo

Description

Loads season-level NCAA men's football period linescores parsed from stats.ncaa.org; one row per team-period. Published to the ncaa_mfb_linescore release tag on the sportsdataverse-data repo.

Usage

load_ncaa_mfb_linescore(
  seasons = most_recent_cfb_season(),
  ...,
  dbConnection = NULL,
  tablename = NULL
)

Arguments

seasons

A vector of 4-digit years associated with given college football seasons. Published coverage runs 2013 through the most recent season. Pass seasons = TRUE for every published season. (Min: 2013)

...

Additional arguments passed to an underlying function that writes the season data into a database.

dbConnection

A DBIConnection object, as returned by DBI::dbConnect()

tablename

The name of the data table within the database

Value

Returns a cfbfastR_data tibble.

col_name types description
contest_id character
team character
home_away character
period character
points integer
final integer
game_date character
venue character
attendance integer
espn_game_id character
season integer

Author(s)

Saiem Gilani

Examples


  try(load_ncaa_mfb_linescore(2013))

Load NCAA men's football officials (stats.ncaa.org) from the SportsDataverse data repo

Description

Loads season-level NCAA men's football game officials parsed from stats.ncaa.org; one row per game-official. Published to the ncaa_mfb_officials release tag on the sportsdataverse-data repo.

Usage

load_ncaa_mfb_officials(
  seasons = most_recent_cfb_season(),
  ...,
  dbConnection = NULL,
  tablename = NULL
)

Arguments

seasons

A vector of 4-digit years associated with given college football seasons. Published coverage runs 2013 through the most recent season. Pass seasons = TRUE for every published season. (Min: 2013)

...

Additional arguments passed to an underlying function that writes the season data into a database.

dbConnection

A DBIConnection object, as returned by DBI::dbConnect()

tablename

The name of the data table within the database

Value

Returns a cfbfastR_data tibble.

col_name types description
contest_id character
role character
official character
espn_game_id character
season integer

Author(s)

Saiem Gilani

Examples


  try(load_ncaa_mfb_officials(2013))

Load NCAA men's football play-by-play (stats.ncaa.org) from the SportsDataverse data repo

Description

Loads season-level NCAA men's football play-by-play parsed from stats.ncaa.org by the sdv-py cfb_ncaa_pbp parser. Covers FCS and lower divisions that ESPN's feed misses; one row per play with drive and participant context. Published to the ncaa_mfb_pbp release tag on the sportsdataverse-data repo.

For the same plays reshaped onto cfbfastR pbp column conventions (for binding with load_cfb_pbp() / load_espn_cfb_pbp() output), use load_ncaa_mfb_pbp_cfbfastr().

Usage

load_ncaa_mfb_pbp(
  seasons = most_recent_cfb_season(),
  ...,
  dbConnection = NULL,
  tablename = NULL
)

Arguments

seasons

A vector of 4-digit years associated with given college football seasons. Published coverage runs 2013 through the most recent season. Pass seasons = TRUE for every published season. (Min: 2013)

...

Additional arguments passed to an underlying function that writes the season data into a database.

dbConnection

A DBIConnection object, as returned by DBI::dbConnect()

tablename

The name of the data table within the database

Value

Returns a cfbfastR_data tibble.

col_name types description
contest_id character
drive_number integer
play_number integer
offense character
drive_result character
drive_scored logical
down integer
distance integer
yard_line character
yard_line_side character
yard_line_number integer
play_type character
clock character
yards_gained integer
formation character
passer character
rusher character
receiver character
kicker character
punter character
returner character
run_direction character
qb_scramble logical
pass_complete logical
pass_depth character
pass_direction character
tackler_1 character
tackler_2 character
kick_yards integer
return_yards integer
punt_yards integer
fg_distance integer
fg_made logical
is_first_down logical
is_touchdown logical
is_safety logical
is_fumble logical
is_turnover logical
turnover_type character
out_of_bounds logical
no_play logical
fair_catch logical
penalty_flag logical
penalty_team character
penalty_type character
penalty_player character
penalty_yards integer
end_yard_line character
play_text character
espn_game_id character
season integer

Author(s)

Saiem Gilani

Examples


  try(load_ncaa_mfb_pbp(2013))

Load NCAA men's football play-by-play, cfbfastR-shaped from the SportsDataverse data repo

Description

Loads the cfbfastR-schema-shaped variant of the stats.ncaa.org men's football play-by-play – the same plays as load_ncaa_mfb_pbp() reshaped onto cfbfastR pbp column conventions for cross-source binds. Published to the ncaa_mfb_pbp_cfbfastr release tag on the sportsdataverse-data repo.

Usage

load_ncaa_mfb_pbp_cfbfastr(
  seasons = most_recent_cfb_season(),
  ...,
  dbConnection = NULL,
  tablename = NULL
)

Arguments

seasons

A vector of 4-digit years associated with given college football seasons. Published coverage runs 2013 through the most recent season. Pass seasons = TRUE for every published season. (Min: 2013)

...

Additional arguments passed to an underlying function that writes the season data into a database.

dbConnection

A DBIConnection object, as returned by DBI::dbConnect()

tablename

The name of the data table within the database

Value

Returns a cfbfastR_data tibble.

col_name types description
game_id integer
id_play integer
drive_id integer
game_play_number integer
half_play_number integer
drive_play_number integer
drive_number integer
season integer
year integer
week integer
period integer
half integer
clock.minutes integer
clock.seconds integer
TimeSecsRem integer
Under_two logical
pos_team character
def_pos_team character
offense_play character
defense_play character
home character
away character
pos_team_score integer
def_pos_team_score integer
offense_score integer
defense_score integer
pos_score_diff integer
score_pts integer
scoring_play logical
scoring logical
down integer
distance integer
yard_line character
yards_to_goal integer
yards_to_goal_end integer
Goal_To_Go logical
log_ydstogo double
yards_gained integer
play_type character
orig_play_type character
play_text character
rush logical
rush_td logical
pass logical
pass_td logical
pass_attempt logical
completion logical
target logical
sack logical
sack_vec logical
int logical
int_td logical
turnover_vec logical
downs_turnover logical
touchdown logical
td_play logical
safety logical
fumble_vec logical
punt logical
punt_play logical
kickoff_play logical
kick_play logical
fg_inds logical
fg_made logical
punt_blocked logical
punt_fair_catch logical
firstD_by_yards logical
firstD_by_penalty logical
penalty_flag logical
penalty_no_play logical
penalty_declined logical
penalty_offset logical
penalty_text character
yds_penalty integer
rusher_player_name character
passer_player_name character
receiver_player_name character
interception_player_name character
punter_player_name character
punt_returner_player_name character
fg_kicker_player_name character
kickoff_player_name character
kickoff_returner_player_name character
yds_rushed integer
yds_receiving integer
yds_sacked integer
yds_punted integer
yds_punt_return integer
yds_kickoff integer
yds_kickoff_return integer
yds_int_return integer
yds_fg integer
drive_result character
drive_scoring logical
ot_synthesized logical
lag_pos_team character
lead_pos_team character
lag_play_type character
lead_play_type character
lag_play_text character
lead_play_text character
change_of_pos_team logical
play_after_turnover logical
n_plays_in_game integer
espn_game_id character

Author(s)

Saiem Gilani

Examples


  try(load_ncaa_mfb_pbp_cfbfastr(2013))

Load NCAA men's football player stats (stats.ncaa.org) from the SportsDataverse data repo

Description

Loads season-level NCAA men's football player box statistics parsed from stats.ncaa.org; one row per player-game-category. Published to the ncaa_mfb_player_stats release tag on the sportsdataverse-data repo.

Usage

load_ncaa_mfb_player_stats(
  seasons = most_recent_cfb_season(),
  ...,
  dbConnection = NULL,
  tablename = NULL
)

Arguments

seasons

A vector of 4-digit years associated with given college football seasons. Published coverage runs 2013 through the most recent season. Pass seasons = TRUE for every published season. (Min: 2013)

...

Additional arguments passed to an underlying function that writes the season data into a database.

dbConnection

A DBIConnection object, as returned by DBI::dbConnect()

tablename

The name of the data table within the database

Value

Returns a cfbfastR_data tibble.

col_name types description
contest_id character
team_id character
number character
name character
position character
rush_attempts character
rush_yds_gained character
rush_yds_lost character
yds_rush character
rush_tds character
rush_long character
category character
espn_game_id character
pass_attempts character
completions character
pass_yards character
interceptions character
pass_tds character
pass_eff character
yds_per_completion character
pct character
long_pass character
rec character
receiving_yards character
yards_per_reception character
rec_td character
long_rec character
yds character
plays character
pbu character
int character
intyds character
int_ret_tds character
pdef character
ko_ret character
ko_ret_yds character
kick_ret_tds character
long_kor character
sacks character
solo_tack character
asst_tack character
tackles character
fgm character
fga character
fg_blocks_allowed character
punt_ret character
punt_ret_yds character
punt_ret_tds character
long_pr character
season integer

Author(s)

Saiem Gilani

Examples


  try(load_ncaa_mfb_player_stats(2013))

Load NCAA men's football rosters (stats.ncaa.org) from the SportsDataverse data repo

Description

Loads season-level NCAA men's football rosters from stats.ncaa.org; one row per player-team-season. Published to the ncaa_mfb_rosters release tag on the sportsdataverse-data repo.

Usage

load_ncaa_mfb_rosters(
  seasons = most_recent_cfb_season(),
  ...,
  dbConnection = NULL,
  tablename = NULL
)

Arguments

seasons

A vector of 4-digit years associated with given college football seasons. Published coverage runs 2013 through the most recent season. Pass seasons = TRUE for every published season. (Min: 2013)

...

Additional arguments passed to an underlying function that writes the season data into a database.

dbConnection

A DBIConnection object, as returned by DBI::dbConnect()

tablename

The name of the data table within the database

Value

Returns a cfbfastR_data tibble.

col_name types description
team_id character
team_name character
player_id character
player_name character
jersey character
statcrew_jersey character
player_class character
position character
height character
weight integer
hometown character
high_school character
games_played integer
games_started integer
academic_year integer
season integer

Author(s)

Saiem Gilani

Examples


  try(load_ncaa_mfb_rosters(2013))

Load NCAA men's football schedules (stats.ncaa.org) from the SportsDataverse data repo

Description

Loads season-level NCAA men's football schedules from stats.ncaa.org; one row per game. Published to the ncaa_mfb_schedule release tag on the sportsdataverse-data repo.

Usage

load_ncaa_mfb_schedule(
  seasons = most_recent_cfb_season(),
  ...,
  dbConnection = NULL,
  tablename = NULL
)

Arguments

seasons

A vector of 4-digit years associated with given college football seasons. Published coverage runs 2013 through the most recent season. Pass seasons = TRUE for every published season. (Min: 2013)

...

Additional arguments passed to an underlying function that writes the season data into a database.

dbConnection

A DBIConnection object, as returned by DBI::dbConnect()

tablename

The name of the data table within the database

Value

Returns a cfbfastR_data tibble.

col_name types description
team_id character
team_name character
date character
opponent_id character
opponent character
result character
outcome character
team_score integer
opponent_score integer
contest_id character
attendance integer
academic_year integer
espn_game_id character
season integer

Author(s)

Saiem Gilani

Examples


  try(load_ncaa_mfb_schedule(2013))

Load NCAA men's football team stats (stats.ncaa.org) from the SportsDataverse data repo

Description

Loads season-level NCAA men's football team box statistics parsed from stats.ncaa.org; one row per team-game-category. Published to the ncaa_mfb_team_stats release tag on the sportsdataverse-data repo.

Usage

load_ncaa_mfb_team_stats(
  seasons = most_recent_cfb_season(),
  ...,
  dbConnection = NULL,
  tablename = NULL
)

Arguments

seasons

A vector of 4-digit years associated with given college football seasons. Published coverage runs 2013 through the most recent season. Pass seasons = TRUE for every published season. (Min: 2013)

...

Additional arguments passed to an underlying function that writes the season data into a database.

dbConnection

A DBIConnection object, as returned by DBI::dbConnect()

tablename

The name of the data table within the database

Value

Returns a cfbfastR_data tibble.

col_name types description
contest_id character
category character
stat character
period character
away_team character
away_value character
home_team character
home_value character
espn_game_id character
season integer

Author(s)

Saiem Gilani

Examples


  try(load_ncaa_mfb_team_stats(2013))

Load NCAA men's football teams (stats.ncaa.org) from the SportsDataverse data repo

Description

Loads season-level NCAA men's football team directories from stats.ncaa.org, with division/conference alignment; one row per team- season. Published to the ncaa_mfb_teams release tag on the sportsdataverse-data repo.

Usage

load_ncaa_mfb_teams(
  seasons = most_recent_cfb_season(),
  ...,
  dbConnection = NULL,
  tablename = NULL
)

Arguments

seasons

A vector of 4-digit years associated with given college football seasons. Published coverage runs 2013 through the most recent season. Pass seasons = TRUE for every published season. (Min: 2013)

...

Additional arguments passed to an underlying function that writes the season data into a database.

dbConnection

A DBIConnection object, as returned by DBI::dbConnect()

tablename

The name of the data table within the database

Value

Returns a cfbfastR_data tibble.

col_name types description
team_id character
team_name character
academic_year integer
division integer
season integer

Author(s)

Saiem Gilani

Examples


  try(load_ncaa_mfb_teams(2013))

Load .parquet file from a remote connection

Description

Load .parquet file from a remote connection

Usage

parquet_from_url(url)

Arguments

url

a character url

Value

a dataframe as created by arrow::read_parquet(); a zero-row data.table when the download or read fails.

Load .rds file from a remote connection

Description

Load .rds file from a remote connection

Usage

rds_from_url(url)

Arguments

url

a character url

Value

a dataframe as created by readRDS()

CFBD API Key Registration

Description

Save your API Key as a system environment variable CFBD_API_KEY

Usage

cfbd_key()

has_cfbd_key()

cfbd_api_key_info()

Details

To get access to an API key, follow the instructions at https://collegefootballdata.com/key

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

Get information about your API key, including your Patreon level and usage limits.

Value

Returns a data frame with 2 variables:

col_name types description
patron_level integer CFBD Patreon tier associated with the API key (0 = free tier, higher = paid tier).
remaining_calls integer Number of API calls remaining in the current rate-limit window for this key.

Update or create a cfbfastR play-by-play database

Description

update_cfb_db() updates or creates a database with cfbfastR play by play data of all completed games since 2014.

Usage

update_cfb_db(
  dbdir = getOption("cfbfastR.dbdirectory", default = "."),
  dbname = "cfb_pbp_db",
  tblname = "cfbfastR_pbp",
  force_rebuild = FALSE,
  db_connection = NULL
)

Arguments

dbdir

Directory in which the database is or shall be located. Can also be set globally with options(cfbfastR.dbdirectory).

dbname

File name of an existing or desired SQLite database within dbdir

tblname

The name of the play by play data table within the database

force_rebuild

Hybrid parameter (logical or numeric) to rebuild parts of or the complete play by play data table within the database (please see details for further information)

db_connection

A DBIConnection object, as returned by DBI::dbConnect() (please see details for further information)

Details

This function creates and updates a data table with the name tblname within a SQLite database (other drivers via db_connection) located in dbdir and named dbname. The data table combines all play by play data for every available game back to the 2014 season and adds the most recent completed games as soon as they are available for cfbfastR.

The argument force_rebuild is of hybrid type. It can rebuild the play by play data table either for the whole cfbfastR era (with force_rebuild = TRUE) or just for specified seasons (e.g. force_rebuild = c(2019, 2020)). Please note the following behavior:

force_rebuild = TRUE

: The data table with the name tblname will be removed completely and rebuilt from scratch. This is helpful when new columns are added during the Off-Season.

force_rebuild = c(2019, 2020)

: The data table with the name tblname will be preserved and only rows from the 2019 and 2020 seasons will be deleted and re-added. This is intended to be used for ongoing seasons because ESPN's data provider can make changes to the underlying data during the week.

The parameter db_connection is intended for advanced users who want to use other DBI drivers, such as MariaDB, Postgres or odbc. Please note that the arguments dbdir and dbname are dropped in case a db_connection is provided but the argument tblname will still be used to write the data table into the database.

Value

Invisibly returns NULL. The function is called for its side effects.

See Also

Other loaders: load_cfb_pbp(), load_cfb_rosters(), load_cfb_schedules(), load_cfb_teams()

Get Yahoo Sports college football boxscore (SCAFFOLD)

Description

Returns the raw editorial boxscore/{game_id} JSON (as a nested list). The boxscore uses a normalized decoder-dictionary schema (player_stats[playerId][variation][stat_type] joined against stat_types / stat_categories); full decoding is a follow-up.

Usage

yahoo_cfb_boxscore(game_id)

Arguments

game_id

(character, required): Dotted game id (e.g. "ncaaf.g.202509200023").

Value

The raw parsed JSON list (service$boxscore). TODO: decode to tibbles.

See Also

Other Yahoo CFB Functions: yahoo_cfb_player_season_stats(), yahoo_cfb_player_season_stats_legacy(), yahoo_cfb_scoreboard(), yahoo_cfb_team_season_stats(), yahoo_cfb_team_season_stats_legacy()

Examples


  try(yahoo_cfb_boxscore(game_id = "ncaaf.g.202509200023"))

Get Yahoo Sports college football player season stats (modern)

Description

Flattens the shangrila leagueStatsIndividual response (all stat groups in one call) into one wide tibble with one row per player. NCAAF data is available 2013-present.

Usage

yahoo_cfb_player_season_stats(
  season = most_recent_cfb_season(),
  league_structure = "ncaaf.struct.div.1",
  count = 200,
  qualified = FALSE
)

Arguments

season

(integer): Season year (e.g. 2024). Defaults to most_recent_cfb_season().

league_structure

(character): Division filter. Defaults to "ncaaf.struct.div.1" (FBS).

count

(integer): Max players. Defaults to 200.

qualified

(logical): Restrict to qualified leaders. Defaults to FALSE.

Value

A cfbfastR-tagged tibble with one row per player. Core columns:

Remaining columns are one per statId (e.g. passing_yards, rushing_yards, receptions, ...), value as displayed (character). Column set grows over time.

See Also

Other Yahoo CFB Functions: yahoo_cfb_boxscore(), yahoo_cfb_player_season_stats_legacy(), yahoo_cfb_scoreboard(), yahoo_cfb_team_season_stats(), yahoo_cfb_team_season_stats_legacy()

Examples


  try(yahoo_cfb_player_season_stats(season = 2024))

Get Yahoo Sports CFB legacy per-category player leaders

Description

Flattens a legacy ⁠seasonStatsFootball{Category}Ncaaf⁠ query (one category per call) into a wide player tibble.

Usage

yahoo_cfb_player_season_stats_legacy(
  season = most_recent_cfb_season(),
  category = "Passing",
  sort_stat = "PASSING_YARDS",
  league_structure = "ncaaf.struct.div.1",
  count = 200
)

Arguments

season

(integer): Season year. Defaults to most_recent_cfb_season().

category

(character): One of Passing, Rushing, Receiving, Defense, Kicking, Punting, Returns. Defaults to "Passing".

sort_stat

(character): Required sort stat id (a FootballStatId, e.g. "PASSING_YARDS"). Defaults to "PASSING_YARDS".

league_structure

(character): Defaults to "ncaaf.struct.div.1".

count

(integer): Defaults to 200.

Value

A cfbfastR-tagged tibble: player_id, display_name, team, team_abbreviation, season, category, plus one column per statId.

See Also

Other Yahoo CFB Functions: yahoo_cfb_boxscore(), yahoo_cfb_player_season_stats(), yahoo_cfb_scoreboard(), yahoo_cfb_team_season_stats(), yahoo_cfb_team_season_stats_legacy()

Examples


  try(yahoo_cfb_player_season_stats_legacy(season = 2024, category = "Rushing",
                                           sort_stat = "RUSHING_YARDS"))

Get Yahoo Sports college football scoreboard

Description

Flattens the editorial scoreboard games map into one tibble (one row per game). The full payload also embeds teams/leagues/odds maps.

Usage

yahoo_cfb_scoreboard(season = most_recent_cfb_season(), week = 1, count = 500)

Arguments

season

(integer): Season year. Defaults to most_recent_cfb_season().

week

(integer): Schedule week. Defaults to 1.

count

(integer): Max games. Defaults to 500.

Value

A cfbfastR-tagged tibble with one row per game; columns are the Yahoo game fields (gameid, home_team_id, away_team_id, total_home_points, total_away_points, status_type, ...) plus season and week. Column set varies with game state.

See Also

Other Yahoo CFB Functions: yahoo_cfb_boxscore(), yahoo_cfb_player_season_stats(), yahoo_cfb_player_season_stats_legacy(), yahoo_cfb_team_season_stats(), yahoo_cfb_team_season_stats_legacy()

Examples


  try(yahoo_cfb_scoreboard(season = 2024, week = 1))

Get Yahoo Sports college football team season stats (modern)

Description

Flattens the shangrila leagueStatsByTeam response into one wide tibble with one row per team (all stat groups in one call).

Usage

yahoo_cfb_team_season_stats(
  season = most_recent_cfb_season(),
  league_structure = "ncaaf.struct.div.1",
  count = 200
)

Arguments

season

(integer): Season year. Defaults to most_recent_cfb_season().

league_structure

(character): Division filter. Defaults to "ncaaf.struct.div.1".

count

(integer): Max teams. Defaults to 200.

Value

A cfbfastR-tagged tibble with one row per team: team, team_abbreviation, season, plus one column per statId.

See Also

Other Yahoo CFB Functions: yahoo_cfb_boxscore(), yahoo_cfb_player_season_stats(), yahoo_cfb_player_season_stats_legacy(), yahoo_cfb_scoreboard(), yahoo_cfb_team_season_stats_legacy()

Examples


  try(yahoo_cfb_team_season_stats(season = 2024))

Get Yahoo Sports CFB legacy per-category team stats

Description

Flattens a legacy ⁠seasonTeamStatsFootball{Category}⁠ query into a wide team tibble.

Usage

yahoo_cfb_team_season_stats_legacy(
  season = most_recent_cfb_season(),
  category = "Passing",
  sort_stat = "PASSING_YARDS",
  league_structure = "ncaaf.struct.div.1",
  count = 200
)

Arguments

season

(integer): Season year. Defaults to most_recent_cfb_season().

category

(character): One of Passing, Rushing, Receiving, Defense, Kicking, Punting, Returns, Kickoffs, Offense. Defaults to "Passing".

sort_stat

(character): Required sort stat id. Defaults to "PASSING_YARDS".

league_structure

(character): Defaults to "ncaaf.struct.div.1".

count

(integer): Defaults to 200.

Value

A cfbfastR-tagged tibble: team, team_abbreviation, season, category, plus one column per statId.

See Also

Other Yahoo CFB Functions: yahoo_cfb_boxscore(), yahoo_cfb_player_season_stats(), yahoo_cfb_player_season_stats_legacy(), yahoo_cfb_scoreboard(), yahoo_cfb_team_season_stats()

Examples


  try(yahoo_cfb_team_season_stats_legacy(season = 2024, category = "Rushing",
                                         sort_stat = "RUSHING_YARDS"))