Skip to contents

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

family_espn_cfb lists every function in this family.

Examples

# One request per player in the game, so this takes a while.
try(espn_cfb_game_player_box(game_id = 401628339,
                             position_detail = FALSE, team_detail = FALSE))
#> ── Game player box score data from ESPN ────────────────────── cfbfastR 3.1.0 ──
#> ℹ Data updated: 2026-11-09 21:12:21 UTC
#> # A tibble: 6,101 × 18
#>    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      
#> # ℹ 6,091 more rows
#> # ℹ 11 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>