Package 'cfbfastR'

Title: Access College Football Play by Play Data
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).
Authors: Saiem Gilani [cre, aut] (ORCID: <https://orcid.org/0000-0002-7194-9067>), 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]
Maintainer: Saiem Gilani <[email protected]>
License: MIT + file LICENSE
Version: 2.3.0
Built: 2026-06-09 21:54:18 UTC
Source: https://github.com/sportsdataverse/cfbfastr

Help Index

CFBD API Key Endpoint Overview

Description

  • cfbd_api_key_info(): Get information about your API key, including your Patreon level and usage limits.

  • register_cfbd(): Save your API Key as a system environment variable CFBD_API_KEY.

  • cfbd_key(): Retrieve the CFBD API key from the CFBD_API_KEY environment variable.

  • has_cfbd_key(): Check whether a CFBD API key is registered in the current session.

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

  • cfbd_betting_lines(): Get betting lines information for games.

  • cfbd_betting_ats(): Get against-the-spread (ATS) summary records by team.

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

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

  • cfbd_coaches(): A coach search function which provides coaching records and school history for a given coach.

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

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.

Examples

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

CFBD Conferences Endpoint Overview

Description

  • cfbd_conferences(): Get college football conference information.

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

Usage

cfbd_conferences()

Details

Get college football conference information

cfbd_conferences()

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

Examples

try(cfbd_conferences())

CFBD NFL Draft Endpoint Overview

Description

  • cfbd_draft_teams(): Get list of NFL teams.

  • cfbd_draft_positions(): Get list of NFL positions for mapping to college positions.

  • cfbd_draft_picks(): Get list of NFL Draft picks.

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

  • cfbd_drives(): Get college football game drives.

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

Arguments

year

(Integer required): Year, 4 digit format(YYYY)
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.

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

Arguments

year

(Integer required): Year, 4 digit format(YYYY)
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

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

Arguments

year

(Integer required): Year, 4 digit format(YYYY)
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

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

  • cfbd_game_box_advanced(): Get game advanced box score information.

  • cfbd_game_player_stats(): Get results information from games.

  • cfbd_game_team_stats(): Get team statistics by game.

  • cfbd_game_info(): Get results information from games.

  • cfbd_live_scoreboard(): Get live scoreboard information.

  • cfbd_game_weather(): Get weather from games.

  • cfbd_game_records(): Get team records by year.

  • cfbd_calendar(): Get calendar of weeks by season.

  • cfbd_game_media(): Get game media information (TV, radio, etc).

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

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

  • cfbd_metrics_fg_ep(): Get field goal expected points values.

  • cfbd_metrics_wepa_team_season(): Get opponent-adjusted team season statistics for predicted points added (PPA).

  • cfbd_metrics_wepa_players_passing(): Get opponent-adjusted player passing statistics for predicted points added (PPA).

  • cfbd_metrics_wepa_players_rushing(): Get opponent-adjusted player rushing statistics for predicted points added (PPA).

  • cfbd_metrics_wepa_players_kicking(): Get Points Added Above Replacement (PAAR) ratings for kickers.

  • cfbd_metrics_ppa_games(): Get team game averages for predicted points added (PPA).

  • cfbd_metrics_ppa_players_games(): Get player game averages for predicted points added (PPA).

  • cfbd_metrics_ppa_players_season(): Get player season averages for predicted points added (PPA).

  • cfbd_metrics_ppa_predicted(): Calculate predicted points using Down and Distance.

  • cfbd_metrics_ppa_teams(): Get team averages for predicted points added (PPA).

  • cfbd_metrics_wp_pregame(): Get pre-game win probability data from CFBD API.

  • cfbd_metrics_wp(): Get win probability chart data from CFBD API.

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
)

Arguments

year

(Integer required): Year, 4 digit format (YYYY)
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)

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

Arguments

year

(Integer optional): Year, 4 digit format (YYYY). Required if team not provided
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)

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

  • cfbd_pbp_data(): Get college football play by play data with cfbfastR expected points/win probability added.

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,
  ...
)

Arguments

year

Select year, (example: 2018)
season_type

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

Select week, this is optional (also numeric)
team

Select team name (example: Texas, Texas A&M, Clemson)
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
...

Additional arguments passed to an underlying function.

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

  • cfbd_pbp_data_v2(): Get college football play-by-play data — modular EPA/WPA pipeline (v2). 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. Runs side-by-side with the legacy cfbd_pbp_data() entry point until the equivalence harness proves the new path matches.

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

  • cfbd_plays(): CFBD's college football play-by-play.

  • cfbd_play_stats_player(): Gets player info associated by play.

  • cfbd_play_stats_types(): Gets CFBD play stat types.

  • cfbd_play_types(): Gets CFBD play types.

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

Arguments

year

(Integer optional): Year, 4 digit format (YYYY)
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

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

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

  • cfbd_player_info(): Player information search.

  • cfbd_player_returning(): Player returning production.

  • cfbd_player_usage(): Player usage.

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

Arguments

year

(Integer required): Year, 4 digit format (YYYY)
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

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

  • cfbd_rankings(): Gets Historical CFB poll rankings at a specific week.

  • cfbd_ratings_sp(): Get SP historical rating data.

  • cfbd_ratings_sp_conference(): Get SP conference-level historical rating data.

  • cfbd_ratings_srs(): Get SRS historical rating data.

  • cfbd_ratings_elo(): Get Elo historical rating data.

  • cfbd_ratings_fpi(): Get FPI historical rating data.

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

Arguments

year

(Integer optional): Year, 4 digit format (YYYY)
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

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

CFB Recruiting Endpoint Overview

Description

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

  • cfbd_recruiting_position(): Get college football position group recruiting information .

  • cfbd_recruiting_team(): Get college football recruiting team rankings information.

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
)

Arguments

year

(Integer optional): Year, 4 digit format (YYYY) - Minimum: 2000. Required if team not provided
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'

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
)

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

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) - Minimum: 2000. Required if team not provided.
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).

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

  • cfbd_stats_categories(): Get college football mapping for stats categories.

  • cfbd_stats_season_team(): Get season statistics by team.

  • cfbd_stats_season_advanced(): Get season advanced statistics by team.

  • cfbd_stats_game_advanced(): Get game advanced stats.

  • cfbd_stats_season_player(): Get season statistics by player.

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

Arguments

year

(Integer required): Year, 4 digit format (YYYY)
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

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

Arguments

year

(Integer required): Year, 4 digit format (YYYY)
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

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.

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)

Arguments

year

(Integer required): Year, 4 digit format (YYYY)
team

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

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)

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

  • cfbd_team_info(): Team Info Lookup.

  • cfbd_team_roster(): Get a team's full roster by year.

  • cfbd_team_talent(): Get composite team talent rankings for all teams in a given year.

  • cfbd_team_matchup_records(): Get matchup history records between two teams.

  • cfbd_team_matchup(): Get matchup history between two teams.

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)

CFBD Venues Endpoint Overview

Description

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

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

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

Usage

cfbd_play_type_df

cfbd_conf_types_df

Format

A data frame with 45 rows and 3 variables:

  • id: Referencing play id

  • text: play type description

  • abbreviation: play type abbreviation used for function call

A data frame with 11 rows and 4 variables:

  • id: Referencing conference id

  • name: Conference name

  • short_name: Short name for Conference

  • abbreviation: Conference abbreviation

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).
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).
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. 2002 is the earliest available season.
groups

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

Value

espn_cfb_calendar() - A data frame with 8 variables:

  • season: character.: .

  • season_type: character.: .

  • label: character.: .

  • alternate_label: character.: .

  • detail: character.: .

  • week: character.: .

  • start_date: character.: .

  • end_date: character.: .

Examples

try(espn_cfb_calendar(2021))

ESPN College Football Catalog Endpoint Overview

Description

  • espn_cfb_award(): 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.

  • espn_cfb_awards(): 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.

  • espn_cfb_coach(): 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.

  • espn_cfb_coach_record(): 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.

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

  • espn_cfb_franchise(): 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.

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

  • espn_cfb_position(): 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.

  • espn_cfb_positions(): 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.

  • espn_cfb_venue(): Get the ESPN core-v2 detail record for a single college football venue – full name, address, playing-surface and indoor flags.

  • espn_cfb_venues(): Get the catalog of stadiums and venues ESPN tracks for college football, with location, capacity-related flags, and addresses.

  • espn_cfb_clear_cache(): Clear the cfbfastR ESPN catalog cache – forget the memoised team and position lookups so the next call re-fetches them from ESPN.

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():

  • cfbfastR.cache – cache backend. One of "memory" (default; in-memory cachem::cache_mem(), cleared when the session ends), "filesystem" (persistent on-disk cachem::cache_disk() under tools::R_user_dir()), or "off" (no memoisation – every catalog fetch hits ESPN).

  • cfbfastR.cache_duration – cache time-to-live in seconds. Defaults to 86400 (24 hours).

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

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

  • espn_cfb_pbp(): Get ESPN college football PBP data (legacy site-v2).

  • espn_cfb_pbp_v2(): Get ESPN College Football Play-by-Play (core-v2) – core-v2-sourced successor to espn_cfb_pbp() with optional EPA/WPA modeling.

  • espn_cfb_unnest_plays(): Turn an espn_cfb_game_drives() result with a plays list-column into a flat one-row-per-play table.

  • espn_cfb_game_broadcasts(): Get the broadcast / streaming outlets carrying a single college football game.

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

  • espn_cfb_game_drives(): Get the per-game drive log for a single college football game – one row per drive.

  • espn_cfb_game_leaders(): Get the per-game statistical leaders for a single college football game – one row per leader within each statistical category.

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

  • espn_cfb_game_pbp(): Get the full core-v2 play-by-play feed for a single college football game – one row per play.

  • espn_cfb_game_play(): Get the full detail object for a single play of a college football game.

  • espn_cfb_game_player_box(): Get the full per-player box score for both teams in a single college football game, in long format.

  • espn_cfb_game_player_statistics(): Get one athlete's box-score line for a single college football game – one row per stat, in long format.

  • espn_cfb_game_powerindex(): Get ESPN's Football Power Index (FPI) matchup projections for both teams in a single college football game.

  • espn_cfb_game_predictor(): Get ESPN's pre-game matchup predictor (FPI game projection) for a single college football game.

  • espn_cfb_game_probabilities(): Get ESPN's play-by-play win-probability series for a single college football game.

  • espn_cfb_game_situation(): Get the current (or final) game situation for a single college football game – down, distance, yard line, red-zone flag, timeouts.

  • espn_cfb_game_status(): Get the competition status for a single college football game – clock, period, and the status type/state.

  • espn_cfb_game_team_leaders(): Get each team's statistical leaders (passing, rushing, receiving, ...) for a single college football game.

  • espn_cfb_game_team_linescores(): Get the quarter-by-quarter linescores for both teams in a single college football game.

  • espn_cfb_game_team_records(): Get each team's win-loss records (overall, home, road, conference) as they stood at the time of a single college football game.

  • espn_cfb_game_team_roster(): Get the game-day roster for both teams in a single college football game.

  • espn_cfb_game_team_statistics(): Get the full team box-score statistics for both teams in a single college football game, in long format.

  • espn_cfb_game_teams(): Get the two teams (home and away) for a single college football game.

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:

  • ⁠{type}_player_id⁠ – scalar character, the first occurrence of that type on the play (NA if none).

  • ⁠{type}_player_name⁠ – scalar character, that athlete's roster-joined name (NA if none or unmatched).

  • ⁠{type}_player_position⁠ – scalar character, the first athlete's position abbreviation (joined from the ESPN position catalog; NA if unmatched).

  • ⁠{type}_player_position_name⁠ – scalar character, the first athlete's position name.

  • ⁠{type}_player_ids⁠ – a list-column: a character vector of every athlete id of that type on the play, in ESPN order. Plays with none carry character(0).

  • ⁠{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 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:

  • "none" (default) – the drives output is returned unchanged, one row per drive, with no embedded plays.

  • "list" – a plays list-column is appended; each cell is that drive's plays as a tibble in the full espn_cfb_game_pbp() schema (~54 base columns plus any optional participant columns). A drive with no matched plays gets an empty 0-row tibble, never NULL.

  • "expand" – the flat one-row-per-play table is returned: every play in the full espn_cfb_game_pbp() schema, with that play's drive-level columns carried alongside, prefixed drive_ (e.g. drive_id, drive_result, drive_yards, drive_start_yard_line) to avoid collision with the play's own columns. This is the espn_cfb_game_pbp() expanded form enriched with drive context.

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:

  • ⁠{type}_player_id⁠ – scalar character, the first occurrence of that type on the play (NA if none).

  • ⁠{type}_player_name⁠ – scalar character, that athlete's roster-joined name (NA if none or unmatched).

  • ⁠{type}_player_position⁠ – scalar character, the first athlete's position abbreviation (joined from the ESPN position catalog; NA if unmatched).

  • ⁠{type}_player_position_name⁠ – scalar character, the first athlete's position name.

  • ⁠{type}_player_ids⁠ – a list-column: a character vector of every athlete id of that type on the play, in ESPN order. Plays with none carry character(0).

  • ⁠{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 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:

  • "long" (default) – one row per competitor (two rows per game), with the home_away column, as shown in the Value table.

  • "wide" – one row per game: every per-competitor column is pivoted to a ⁠home_*⁠ / ⁠away_*⁠ column keyed off the home_away value (e.g. home_team_id, home_winner, home_curated_rank, away_team_id, away_winner, ...). game_id stays a single key column, so a "wide" result is directly joinable onto any one-row-per-game 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 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).
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)

Arguments

game_id

Game ID
epa_wpa

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

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

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.

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

  • espn_cfb_player(): Get the full ESPN record for a single college football player in a given season – bio, measurements, position, team, status, and ⁠$ref⁠ URLs to nested resources.

  • espn_cfb_players(): Get a paginated index of ESPN college football players for a season (id + ⁠$ref⁠ rows; dereference with espn_cfb_player()).

  • espn_cfb_player_eventlog(): Get the per-game event log for a single college football player in a season – one row per game, with ⁠$ref⁠ URLs to each game's event, competition, and per-game statistics.

  • espn_cfb_player_gamelog(): Get a single college football player's game-by-game statistical log for a season – stat line joined to opponent, score, and result metadata.

  • espn_cfb_player_overview(): Get the season-by-season statistics overview ESPN shows on a college football player's page – one row per season, with the headline stat line for each.

  • espn_cfb_player_seasons(): Get the list of seasons a single college football player has a statistical record for on ESPN, with ⁠$ref⁠ URLs to each season's statistics.

  • espn_cfb_player_splits(): Get a single college football player's statistical splits for a season – stat lines broken out by month, quarter, down, field position, and more.

  • espn_cfb_player_career_stats(): 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).

  • espn_cfb_player_stats(): Get ESPN college football player season stats (legacy wide-format wrapper covering all categories and athlete / team detail columns).

  • espn_cfb_recruits(): Get the ESPN recruiting-class catalog for a college football signing class – one row per recruit, with identity, position, measurements, grade, rankings, and committed school.

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

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).
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 .../weeks/{week}/qbr/... path returns the same season aggregate for every week – use espn_cfb_player_stats() for week-resolved passing production instead.

  • The home/away game-location split (.../qbr/1, .../qbr/2) responds 200 but is empty for college football; only the total (.../qbr/0) is populated.

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

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).
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. 2002 is the earliest available season.
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

  • matchup: character.: Long matchup description with full team names (Utah Utes at UCLA Bruins).

  • matchup_short: character.: Short matchup description with team abbreviations (UTAH @ UCLA).

  • season: integer.: Season of the game.

  • type: character.: Season type of the game in CFBD format.

  • slug: character.: Season type of the game in ESPN format.

  • game_id: character.: Referencing game ID.

  • game_uid: character.:

  • game_date: character.: Game date.

  • attendance: integer.: Reported attendance at the game.

  • play_by_play_available: logical:

  • home_team_name: character.: Home team mascot name (Sun Devils).

  • home_team_logo: character.: Home team logo url.

  • home_team_abb: character.: Home team abbreviation (ASU).

  • home_team_id: character.: Home team ID.

  • home_team_location: character.: Home team name (Arizona State).

  • home_team_full: character.: Home team full name (Arizona State Sun Devils).

  • home_team_color: character.: Home team color.

  • home_score: integer.: Home team points.

  • home_win: integer.: 1 if home team won, 0 if home team lost, NA if game is unfinished

  • home_record: character: Home team record.

  • away_team_name: character.: Away team mascot name (Sun Devils).

  • away_team_logo: character.: Away team logo url.

  • away_team_abb: character.: Away team abbreviation (ASU).

  • away_team_id: character.: Away team ID.

  • away_team_location: character.: Away team name (Arizona State).

  • away_team_full: character.: Away team full name (Arizona State Sun Devils).

  • away_team_color: character.: Away team color.

  • away_score: integer.: Away team points.

  • away_win: integer.: 1 if away team won, 0 if home team lost, NA if game is unfinished

  • away_record: character: Away team record.

  • status_name: character.: Status of the game

  • start_date: character.: Game date.

Unique variables when there are completed games

  • broadcast_market: character.: Broadcast market (typically "national" or NA)

  • broadcast_name: character.: Broadcast channel i.e. ESPN, ABC, FOX

  • passing_leader_yards: numeric.: Passing yards of game's passing leader

  • passing_leader_stat: character.: Stat line of game's passing leader

  • passing_leader_name: character.: Name of game's passing leader

  • passing_leader_shortname: character.: First initial and last name of game's passing leader

  • passing_leader_headshot: character.: Headshot url of game's passing leader

  • passing_leader_team_id: character.: Team ID of game's passing leader

  • passing_leader_pos: character.: Position of game's passing leader

  • rushing_leader_yards: numeric.: Passing yards of game's rushing leader

  • rushing_leader_stat: character.: Stat line of game's rushing leader

  • rushing_leader_name: character.: Name of game's rushing leader

  • rushing_leader_shortname: character.: First initial and last name of game's rushing leader

  • rushing_leader_headshot: character.: Headshot url of game's rushing leader

  • rushing_leader_team_id: character.: Team ID of game's rushing leader

  • rushing_leader_pos: character.: Position of game's rushing leader

  • receiving_leader_yards: numeric.: Passing yards of game's receiving leader

  • receiving_leader_stat: character.: Stat line of game's receiving leader

  • receiving_leader_name: character.: Name of game's receiving leader

  • receiving_leader_shortname: character.: First initial and last name of game's receiving leader

  • receiving_leader_headshot: character.: Headshot url of game's receiving leader

  • receiving_leader_team_id: character.: Team ID of game's receiving leader

  • receiving_leader_pos: character.: Position of game's receiving leader

espn_cfb_schedule() - A data frame with 8 variables:

  • matchup: character.: .

  • matchup_short: character.: .

  • season: integer.: .

  • type: character.: .

  • slug: character.: .

  • game_id: character.: .

  • game_uid: character.: .

  • game_date: Date.: .

  • attendance: integer.: .

  • date_valid: logical.: .

  • play_by_play_available: logical.: .

  • home_team_name: character.: .

  • home_team_logo: character.: .

  • home_team_abb: character.: .

  • home_team_id: character.: .

  • home_team_location: character.: .

  • home_team_full: character.: .

  • home_team_color: character.: .

  • home_score: integer.: .

  • home_win: integer.: .

  • home_record: character.: .

  • away_team_name: character.: .

  • away_team_logo: character.: .

  • away_team_abb: character.: .

  • away_team_id: character.: .

  • away_team_location: character.: .

  • away_team_full: character.: .

  • away_team_color: character.: .

  • away_score: integer.: .

  • away_win: integer.: .

  • away_record: character.: .

  • status_name: character.: .

  • start_date: character.: .

  • highlights: logical.: .

  • game_date_time: datetime.: .

Examples

try(espn_cfb_scoreboard())



  try(espn_cfb_schedule(2021, week = 8))

ESPN College Football Season Endpoint Overview

Description

  • espn_cfb_groups(): Get the full ESPN group hierarchy for a college football season – division roll-ups and conferences flattened into one catalog table.

  • espn_cfb_rankings(): Get the index of poll / ranking sources ESPN publishes for a college football season.

  • espn_cfb_season_info(): Get the ESPN core-v2 detail record for a single college football season.

  • espn_cfb_season_types(): Get the set of season types (preseason, regular season, postseason, off-season) ESPN tracks for a college football season.

  • espn_cfb_season_weeks(): Get the calendar of weeks ESPN tracks for a college football season type.

  • espn_cfb_seasons(): Get the index of every college football season ESPN tracks in its core-v2 API.

  • espn_cfb_standings(): Get ESPN's standings for a college football group – full record splits and standings statistics for every team.

  • espn_cfb_week_rankings(): Get the ranked teams from every poll ESPN published in a single week of a college football season.

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

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

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

  • espn_cfb_team(): Get ESPN's detailed record for a single college football team in a given season – identifiers, branding, conference grouping, and home venue.

  • espn_cfb_teams(): Get the full ESPN directory of college football teams – one row per team with identifiers, branding, conference grouping, and logo URLs.

  • espn_cfb_team_ats(): 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, ...).

  • espn_cfb_team_awards(): Get the awards won by a college football team's players in a season – one row per (award x winning athlete).

  • espn_cfb_team_coaches(): Get the coaches associated with a college football team for a season – one row per coach, with name, birth detail, and experience.

  • espn_cfb_team_events(): Get a college football team's full season event log – every game (regular season and postseason) ESPN lists for the team-season.

  • espn_cfb_team_leaders(): Get a college football team's season statistical leaders – the top athletes in each ESPN leader category (passing, rushing, receiving, tackles, ...).

  • espn_cfb_team_powerindex(): 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.

  • espn_cfb_team_ranks(): Get a college football team's poll-rank history for a season – one row per poll (AP, Coaches, CFP Committee, ...) the team appeared in.

  • espn_cfb_team_record(): 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.

  • espn_cfb_team_roster(): Get the season roster for a single college football team – one row per athlete with biographical detail, position, jersey number, and class/experience.

  • espn_cfb_team_schedule(): Get a single college football team's full-season schedule – one row per game with opponent, venue, broadcast, score, and result.

  • espn_cfb_team_stats(): Get ESPN college football team season statistics – a wide tibble of team identifiers and per-category statistical totals.

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).
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).
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).
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 coaches associated with a college football team for a season – one row per coach, with name, birth detail, and experience.

Usage

espn_cfb_team_coaches(team_id = NULL, year = NULL, team_detail = TRUE)

Arguments

team_id

(Integer required): ESPN team id.
year

(Integer required): Season, 4 digit format (YYYY).
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, year = 2024))
  try(espn_cfb_team_coaches(team_id = 61, year = 2024,
                            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).
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).
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).
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).
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).
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).
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).
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
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).
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:

  • game_id: character. Referencing game ID (should be same as game_id from other functions).

  • play_id: character. Referencing play ID.

  • seconds_left: integer. DEPRECATED. Seconds left in the game.

  • home_win_percentage: double. The probability of the home team winning the game.

  • away_win_percentage: double. The probability of the away team winning the game (calculated as 1 - home_win_percentage - tie_percentage).

  • tie_percentage: double. The probability of the game ending the final period in a tie.

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

Details

Adapted from sabinanalytic's fork of the cfbfastR repo

Value

A data frame with 20 variables:

  • year: integer. Season of the Football Power Index (FPI) Rating.

  • team_id: integer. Unique ESPN team ID - team_id.

  • team_name: character. Team Name.

  • team_abbreviation: character. Team abbreviation.

  • fpi: character. Football Power Index (FPI) Rating.

  • fpi_rk: character. Football Power Index (FPI) Rank.

  • trend: character. Football Power Index (FPI) ranking trend.

  • projected_wins: character. Projected Win total for the season.

  • projected_losses: character. Projected Loss total for the season.

  • win_out_pct: double. Probability the team wins out.

  • win_6_pct: double. Probability the team wins at least six games.

  • win_division_pct: double. Probability the team wins at their division.

  • playoff_pct: double. Probability the team reaches the playoff.

  • nc_game_pct: double. Probability the team reaches the national championship game.

  • nc_win_pct: double. Probability the team wins the national championship game.

  • win_conference_pct: double. Probability the team wins their conference game.

  • w: integer. Wins on the season.

  • l: integer. Losses on the season.

  • t: character. Ties on the season.

Examples

try(espn_ratings_fpi(year=2019))

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

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 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 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 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 .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()