Skip to contents

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.

Value

A data frame with one row per rostered player:

col_nametypesdescription
game_idcharacterESPN game identifier.
team_idcharacterESPN team 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 athlete_ref).
player_idcharacterESPN player id from the roster entry.
display_namecharacterPlayer display name as shown by ESPN.
jerseycharacterJersey number.
position_idcharacterESPN position id (parsed from position_ref).
periodintegerPeriod the player entered the game (0 if none).
starterlogicalTRUE if the player started the game.
activelogicalTRUE if the player was active for the game.
did_not_playlogicalTRUE if the player did not play.
validlogicalTRUE if the roster entry is flagged valid by ESPN.
athlete_refcharacter$ref URL to the athlete-in-season resource.
position_refcharacter$ref URL to the position 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}/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.

See also

family_espn_cfb lists every function in this family.

Examples

# \donttest{
  # position_detail = FALSE skips the position catalog (about 75 requests).
  try(espn_cfb_game_team_roster(game_id = 401628339,
                                position_detail = FALSE))
#> ── Game team roster data from ESPN ─────────────────────────── cfbfastR 3.1.0 ──
#> ℹ Data updated: 2026-11-09 21:12:29 UTC
#> # A tibble: 242 × 25
#>    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 
#> # ℹ 232 more rows
#> # ℹ 19 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>,
#> #   player_id <chr>, display_name <chr>, jersey <chr>, position_id <chr>,
#> #   period <int>, starter <lgl>, active <lgl>, did_not_play <lgl>, valid <lgl>,
#> #   athlete_ref <chr>, position_ref <chr>
# }