espn_cfb_game_team_roster: *ESPN College Football Game Team Roster*

In cfbfastR: Access College Football Play by Play Data

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

cfbfastR documentation built on Aug. 24, 2026, 5:13 p.m.