Skip to contents

ESPN College Football Game Player Box Score

Source: R/espn_cfb_game.R
espn_cfb_game_player_box.Rd

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.

Value

A data frame with one row per team-athlete-category-stat:

col_nametypesdescription
game_idcharacterESPN game identifier.
team_idcharacterESPN team id (competitor id) for the team.
team_namecharacterTeam nickname; team_detail = TRUE only.
team_abbreviationcharacterTeam abbreviation; team_detail = TRUE only.
team_locationcharacterTeam location / school name; team_detail = TRUE only.
team_display_namecharacterFull team display name; team_detail = TRUE only.
team_short_display_namecharacterShort team display name; team_detail = TRUE only.
team_nicknamecharacterTeam nickname label; team_detail = TRUE only.
team_colorcharacterPrimary team color; team_detail = TRUE only.
team_alternate_colorcharacterAlternate team color; team_detail = TRUE only.
team_logo_hrefcharacterDefault team logo URL; team_detail = TRUE only.
team_logo_dark_hrefcharacterDark-variant team logo URL; team_detail = TRUE only.
home_awaycharacterhome or away.
athlete_idcharacterESPN athlete id (parsed from the athlete $ref).
athlete_namecharacterAthlete display name (roster-joined).
position_idcharacterESPN position id (roster-joined; NA if unmatched).
category_namecharacterStat category key (e.g. passing, rushing).
category_displaycharacterHuman-readable category name.
category_short_displaycharacterShort human-readable category name.
category_summarycharacterESPN's summary string for the category.
stat_namecharacterInternal stat key (e.g. passingYards).
abbreviationcharacterStat abbreviation.
display_namecharacterHuman-readable stat name.
short_display_namecharacterShort human-readable stat name.
descriptioncharacterESPN's description of the stat.
valuenumericStat value.
display_valuecharacterDisplay-formatted stat value as shown on ESPN.
statistics_refcharacter$ref URL to the athlete's game-statistics resource.
position_namecharacterPosition name (e.g. Quarterback); position_detail = TRUE only.
position_display_namecharacterHuman-readable position name; position_detail = TRUE only.
position_abbreviationcharacterPosition abbreviation (e.g. QB); position_detail = TRUE only.
position_leaflogicalTRUE for a most-specific (leaf) position; position_detail = TRUE only.
position_parent_idcharacterESPN id of the parent position; position_detail = TRUE only.

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.

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

# \donttest{
  try(espn_cfb_game_player_box(game_id = 401628339))
#> ── Game player box score data from ESPN ────────────────────── cfbfastR 2.3.0 ──
#> ℹ Data updated: 2026-06-09 07:56:14 UTC
#> # A tibble: 5,863 × 33
#>    game_id   team_id team_name team_abbreviation team_location team_display_name
#>    <chr>     <chr>   <chr>     <chr>             <chr>         <chr>            
#>  1 401628339 61      Bulldogs  UGA               Georgia       Georgia Bulldogs 
#>  2 401628339 61      Bulldogs  UGA               Georgia       Georgia Bulldogs 
#>  3 401628339 61      Bulldogs  UGA               Georgia       Georgia Bulldogs 
#>  4 401628339 61      Bulldogs  UGA               Georgia       Georgia Bulldogs 
#>  5 401628339 61      Bulldogs  UGA               Georgia       Georgia Bulldogs 
#>  6 401628339 61      Bulldogs  UGA               Georgia       Georgia Bulldogs 
#>  7 401628339 61      Bulldogs  UGA               Georgia       Georgia Bulldogs 
#>  8 401628339 61      Bulldogs  UGA               Georgia       Georgia Bulldogs 
#>  9 401628339 61      Bulldogs  UGA               Georgia       Georgia Bulldogs 
#> 10 401628339 61      Bulldogs  UGA               Georgia       Georgia Bulldogs 
#> # ℹ 5,853 more rows
#> # ℹ 27 more variables: team_short_display_name <chr>, team_nickname <chr>,
#> #   team_color <chr>, team_alternate_color <chr>, team_logo_href <chr>,
#> #   team_logo_dark_href <chr>, home_away <chr>, athlete_id <chr>,
#> #   athlete_name <chr>, position_id <chr>, category_name <chr>,
#> #   category_display <chr>, category_short_display <chr>,
#> #   category_summary <chr>, stat_name <chr>, abbreviation <chr>, …
  try(espn_cfb_game_player_box(game_id = 401628339,
                               position_detail = FALSE))
#> ── Game player box score data from ESPN ────────────────────── cfbfastR 2.3.0 ──
#> ℹ Data updated: 2026-06-09 07:56:20 UTC
#> # A tibble: 5,863 × 28
#>    game_id   team_id team_name team_abbreviation team_location team_display_name
#>    <chr>     <chr>   <chr>     <chr>             <chr>         <chr>            
#>  1 401628339 61      Bulldogs  UGA               Georgia       Georgia Bulldogs 
#>  2 401628339 61      Bulldogs  UGA               Georgia       Georgia Bulldogs 
#>  3 401628339 61      Bulldogs  UGA               Georgia       Georgia Bulldogs 
#>  4 401628339 61      Bulldogs  UGA               Georgia       Georgia Bulldogs 
#>  5 401628339 61      Bulldogs  UGA               Georgia       Georgia Bulldogs 
#>  6 401628339 61      Bulldogs  UGA               Georgia       Georgia Bulldogs 
#>  7 401628339 61      Bulldogs  UGA               Georgia       Georgia Bulldogs 
#>  8 401628339 61      Bulldogs  UGA               Georgia       Georgia Bulldogs 
#>  9 401628339 61      Bulldogs  UGA               Georgia       Georgia Bulldogs 
#> 10 401628339 61      Bulldogs  UGA               Georgia       Georgia Bulldogs 
#> # ℹ 5,853 more rows
#> # ℹ 22 more variables: team_short_display_name <chr>, team_nickname <chr>,
#> #   team_color <chr>, team_alternate_color <chr>, team_logo_href <chr>,
#> #   team_logo_dark_href <chr>, home_away <chr>, athlete_id <chr>,
#> #   athlete_name <chr>, position_id <chr>, category_name <chr>,
#> #   category_display <chr>, category_short_display <chr>,
#> #   category_summary <chr>, stat_name <chr>, abbreviation <chr>, …
  try(espn_cfb_game_player_box(game_id = 401628339,
                               team_detail = FALSE))
#> ── Game player box score data from ESPN ────────────────────── cfbfastR 2.3.0 ──
#> ℹ Data updated: 2026-06-09 07:56:26 UTC
#> # A tibble: 5,863 × 23
#>    game_id   team_id home_away athlete_id athlete_name position_id category_name
#>    <chr>     <chr>   <chr>     <chr>      <chr>        <chr>       <chr>        
#>  1 401628339 61      home      4429105    A. Smith     1           general      
#>  2 401628339 61      home      4429105    A. Smith     1           general      
#>  3 401628339 61      home      4429105    A. Smith     1           general      
#>  4 401628339 61      home      4429105    A. Smith     1           general      
#>  5 401628339 61      home      4429105    A. Smith     1           general      
#>  6 401628339 61      home      4429105    A. Smith     1           general      
#>  7 401628339 61      home      4429105    A. Smith     1           general      
#>  8 401628339 61      home      4429105    A. Smith     1           passing      
#>  9 401628339 61      home      4429105    A. Smith     1           passing      
#> 10 401628339 61      home      4429105    A. Smith     1           passing      
#> # ℹ 5,853 more rows
#> # ℹ 16 more variables: category_display <chr>, category_short_display <chr>,
#> #   category_summary <chr>, stat_name <chr>, abbreviation <chr>,
#> #   display_name <chr>, short_display_name <chr>, description <chr>,
#> #   value <dbl>, display_value <chr>, statistics_ref <chr>,
#> #   position_name <chr>, position_display_name <chr>,
#> #   position_abbreviation <chr>, position_leaf <lgl>, …
# }