ESPN College Football Players Index

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.

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.

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.

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

# \donttest{
  try(espn_cfb_players(year = 2024, page = 1, max_pages = 1))
#> ── Players index from ESPN ─────────────────────────────────── cfbfastR 2.3.0 ──
#> ℹ Data updated: 2026-06-09 07:56:52 UTC
#> # A tibble: 100 × 6
#>    season athlete_id athlete_ref                           page page_count count
#>     <int> <chr>      <chr>                                <int>      <int> <int>
#>  1   2024 2027901    http://sports.core.api.espn.com/v2/…     1        996 99524
#>  2   2024 2488274    http://sports.core.api.espn.com/v2/…     1        996 99524
#>  3   2024 2586732    http://sports.core.api.espn.com/v2/…     1        996 99524
#>  4   2024 2586749    http://sports.core.api.espn.com/v2/…     1        996 99524
#>  5   2024 2586765    http://sports.core.api.espn.com/v2/…     1        996 99524
#>  6   2024 2586812    http://sports.core.api.espn.com/v2/…     1        996 99524
#>  7   2024 2988219    http://sports.core.api.espn.com/v2/…     1        996 99524
#>  8   2024 2988246    http://sports.core.api.espn.com/v2/…     1        996 99524
#>  9   2024 539758     http://sports.core.api.espn.com/v2/…     1        996 99524
#> 10   2024 3145545    http://sports.core.api.espn.com/v2/…     1        996 99524
#> # ℹ 90 more rows
  try(espn_cfb_players(year = 2024, page = 1, max_pages = 1, limit = 5,
                       athlete_detail = TRUE))
#> ── Players index from ESPN ─────────────────────────────────── cfbfastR 2.3.0 ──
#> ℹ Data updated: 2026-06-09 07:56:52 UTC
#> # A tibble: 5 × 12
#>   season athlete_id athlete_ref       page page_count count athlete_display_name
#>    <int> <chr>      <chr>            <int>      <int> <int> <chr>               
#> 1   2024 2027901    http://sports.c…     1      19905 99524 NA                  
#> 2   2024 2488274    http://sports.c…     1      19905 99524 NA                  
#> 3   2024 2586732    http://sports.c…     1      19905 99524 NA                  
#> 4   2024 2586749    http://sports.c…     1      19905 99524 NA                  
#> 5   2024 2586765    http://sports.c…     1      19905 99524 NA                  
#> # ℹ 5 more variables: athlete_first_name <chr>, athlete_last_name <chr>,
#> #   athlete_jersey <chr>, athlete_position <chr>,
#> #   athlete_position_abbreviation <chr>
# }