espn_cfb_game_probabilities: *ESPN College Football Game Win Probabilities*

In cfbfastR: Access College Football Play by Play Data

ESPN College Football Game Win Probabilities

Description

Get ESPN's play-by-play win-probability series for a single college football game – one row per play.

Usage

espn_cfb_game_probabilities(game_id = NULL, team_detail = TRUE)

Arguments

game_id	(Integer required): ESPN game identifier for a completed game.
team_detail	(Logical): when TRUE (default), fetch the ESPN team catalog once and join friendly team fields next to the home_team_id / away_team_id columns (see Details). Set FALSE to skip the catalog fetch and the join.

Details

Wraps the paginated ESPN core-v2 endpoint events/{game_id}/competitions/{game_id}/probabilities. The endpoint is paginated; this wrapper loops every page and stacks the results into one frame – one row per play, each carrying the home / away / tie win percentages at that point in the game, plus spread-cover and total (over/under) probabilities. play_id is parsed from each row's play ⁠$ref⁠ so the series can be joined to espn_cfb_game_pbp().

This endpoint responds ⁠HTTP 400⁠ for future / not-yet-played games and is only populated for completed games. The ⁠@examples⁠ use a finished game; pass game_id values for completed games.

When team_detail = TRUE (the default) the ESPN team catalog (espn_cfb_teams()) is fetched once and friendly team fields are joined in next to both the home_team_id and away_team_id columns – e.g. home_team_name, home_team_abbreviation, ..., away_team_name, away_team_abbreviation, .... A catalog failure degrades to NA rather than erroring the wrapper. Set team_detail = FALSE to skip the catalog fetch and the join.

Value

A data frame with one row per play:

col_name	types	description
game_id	character	ESPN game identifier.
play_id	character	ESPN play id (parsed from the play ⁠$ref⁠).
sequence_number	character	Play sequence number within the game.
home_team_id	character	ESPN home team id (parsed from home_team_ref).
home_team_name	character	Home team nickname; team_detail = TRUE only.
home_team_abbreviation	character	Home team abbreviation; team_detail = TRUE only.
home_team_location	character	Home team location / school; team_detail = TRUE only.
home_team_display_name	character	Home team full display name; team_detail = TRUE only.
home_team_short_display_name	character	Home team short display name; team_detail = TRUE only.
home_team_nickname	character	Home team nickname label; team_detail = TRUE only.
home_team_color	character	Home team primary color; team_detail = TRUE only.
home_team_alternate_color	character	Home team alternate color; team_detail = TRUE only.
home_team_logo_href	character	Home team default logo URL; team_detail = TRUE only.
home_team_logo_dark_href	character	Home team dark logo URL; team_detail = TRUE only.
away_team_id	character	ESPN away team id (parsed from away_team_ref).
away_team_name	character	Away team nickname; team_detail = TRUE only.
away_team_abbreviation	character	Away team abbreviation; team_detail = TRUE only.
away_team_location	character	Away team location / school; team_detail = TRUE only.
away_team_display_name	character	Away team full display name; team_detail = TRUE only.
away_team_short_display_name	character	Away team short display name; team_detail = TRUE only.
away_team_nickname	character	Away team nickname label; team_detail = TRUE only.
away_team_color	character	Away team primary color; team_detail = TRUE only.
away_team_alternate_color	character	Away team alternate color; team_detail = TRUE only.
away_team_logo_href	character	Away team default logo URL; team_detail = TRUE only.
away_team_logo_dark_href	character	Away team dark logo URL; team_detail = TRUE only.
home_win_percentage	numeric	Home-team win probability after the play (0-1).
away_win_percentage	numeric	Away-team win probability after the play (0-1).
tie_percentage	numeric	Tie probability after the play (0-1).
seconds_left	integer	Seconds left in the game at the play.
spread_cover_prob_home	numeric	Probability the home team covers the spread.
spread_push_prob	numeric	Probability of a spread push.
total_over_prob	numeric	Probability the game total goes over.
total_push_prob	numeric	Probability of a total push.
source_id	character	ESPN data-source id for the probability row.
source_description	character	ESPN data-source description (e.g. feed).
source_state	character	ESPN data-source state (e.g. full).
last_modified	character	ISO timestamp the probability row was last modified.
play_ref	character	⁠$ref⁠ URL to the play resource for the row.
competition_ref	character	⁠$ref⁠ URL to the competition resource.
home_team_ref	character	⁠$ref⁠ URL to the home team resource.
away_team_ref	character	⁠$ref⁠ URL to the away team resource.

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_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_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_probabilities(game_id = 401628339))
  try(espn_cfb_game_probabilities(game_id = 401628339,
                                  team_detail = FALSE))

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