espn_cfb_players: *ESPN College Football Players Index*

In cfbfastR: Access College Football Play by Play Data

ESPN College Football Players Index

Description

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). Minimum value accepted: 1936
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.

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.

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.

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

  try(espn_cfb_players(year = 2024, page = 1, max_pages = 1))
  try(espn_cfb_players(year = 2024, page = 1, max_pages = 1, limit = 5,
                       athlete_detail = TRUE))

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