espn_cfb_game_drives: *ESPN College Football Game Drives*
In cfbfastR: Access College Football Play by Play Data
View source: R/espn_cfb_game.R
espn_cfb_game_drives R Documentation
ESPN College Football Game Drives
Description
Get the per-game drive log for a single college football game
– one row per drive, with start/end field position, yardage, play count,
result, and a $ref to that drive's plays. Optionally embed each drive's
full-schema play-by-play as a nested list-column or as a flat
one-row-per-play table.
Usage
espn_cfb_game_drives(
game_id = NULL,
plays = c("none", "list", "expand"),
participants = c("none", "wide", "long"),
participants_list = FALSE,
team_participants = c("none", "wide"),
team_participants_list = FALSE,
position_detail = TRUE,
team_detail = TRUE
)
Arguments
game_id
(Integer required): ESPN game identifier.
plays
(Character): controls whether each drive's plays are
embedded. One of "none" (default), "list", or "expand" – see
Details.
participants
(Character): participant-flattening mode for the
embedded plays – one of "none" (default), "wide", or "long".
Consulted only when plays != "none". See espn_cfb_game_pbp().
participants_list
(Logical): when TRUE, append the
participants list-column to each embedded play. Defaults to FALSE.
Consulted only when plays != "none".
team_participants
(Character): team-participant-flattening mode
for the embedded plays – one of "none" (default) or "wide".
Consulted only when plays != "none".
team_participants_list
(Logical): when TRUE, append the
team_participants list-column to each embedded play. Defaults to
FALSE. Consulted only when plays != "none".
position_detail
(Logical): when TRUE (default), the embedded
plays' participants = "wide" output carries position detail joined
from the ESPN position catalog. Consulted only when plays != "none"
and participants = "wide".
team_detail
(Logical): when TRUE (default), the ESPN team
catalog (espn_cfb_teams()) is fetched once and friendly team fields
are joined in next to the drive-level team-id columns – team_id and
end_team_id (which become drive_team_id / drive_end_team_id in
plays = "expand" mode). For each id column X_id the sibling columns
X_name, X_abbreviation, X_location, X_display_name,
X_short_display_name, X_nickname, X_color, X_alternate_color,
X_logo_href, X_logo_dark_href are inserted immediately
after it. The embedded play tibbles keep the base
espn_cfb_game_pbp() schema (not team-enriched), so a plays = "expand" result matches espn_cfb_unnest_plays() of a plays = "list"
result. 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}/drives. The competition id always
equals the game id. Returns one row per drive (typically 18-24 drives per
game). Each drive carries the offensive team, the start and end
period/clock/yard-line, total yards, offensive play count, the drive
result, and a scoring flag. The plays_ref column is the $ref URL to
that drive's plays – pass the drive_id to espn_cfb_game_drive_plays()
to fetch the play-by-play partitioned to a single drive. This is the
richest drive resource ESPN exposes; the site-v2 summary feed only carries
a flattened subset.
The plays argument controls whether each drive's plays are embedded:
-
"none" (default) – the drives output is returned unchanged,
one row per drive, with no embedded plays.
-
"list" – a plays list-column is appended; each cell is
that drive's plays as a tibble in the full
espn_cfb_game_pbp() schema (~54 base columns plus any optional
participant columns). A drive with no matched plays gets an empty
0-row tibble, never NULL.
-
"expand" – the flat one-row-per-play table is returned:
every play in the full espn_cfb_game_pbp() schema, with that
play's drive-level columns carried alongside, prefixed drive_
(e.g. drive_id, drive_result, drive_yards,
drive_start_yard_line) to avoid collision with the play's own
columns. This is the espn_cfb_game_pbp() expanded form enriched
with drive context.
The participants, participants_list, team_participants,
team_participants_list, and position_detail arguments shape the
embedded plays and are consulted only when plays != "none". They
have the same meaning as the identically named arguments on
espn_cfb_game_pbp() – e.g. participants = "wide" appends the
type-keyed {type}_player_* columns to every embedded play tibble. See
espn_cfb_game_pbp() for the full description of each.
To get the plays efficiently the wrapper first probes the drives
endpoint for inline plays (items[].plays.items[]); when ESPN embeds
them, no extra request is made. When only a plays.$ref is present, the
competition-level /plays feed is fetched once and the plays are
partitioned into drives by matching each play's drive id. Per-drive
plays_ref URLs are never dereferenced individually.
espn_cfb_unnest_plays() turns a plays = "list" result into the same
flat table as plays = "expand" without any further HTTP.
Value
A data frame with one row per drive:
col_name types description
game_id character ESPN game identifier.
drive_id character ESPN drive id.
sequence_number character Drive sequence number within the game.
description character Drive summary text (e.g. 9 plays, 75 yards, 4:12).
team_id character ESPN team id of the offensive team (parsed from team_ref).
end_team_id character ESPN team id of the team in possession at drive end.
start_period integer Period (quarter) at the start of the drive.
start_period_type character Period type at the start of the drive (e.g. quarter).
start_clock character Game clock display value at the start of the drive.
start_clock_seconds numeric Game clock value in seconds at the start of the drive.
start_yard_line integer Yard line at the start of the drive.
start_text character Field-position text at the start of the drive.
end_period integer Period (quarter) at the end of the drive.
end_period_type character Period type at the end of the drive (e.g. quarter).
end_clock character Game clock display value at the end of the drive.
end_clock_seconds numeric Game clock value in seconds at the end of the drive.
end_yard_line integer Yard line at the end of the drive.
end_text character Field-position text at the end of the drive.
time_elapsed character Elapsed game time for the drive (MM:SS).
time_elapsed_seconds numeric Elapsed game time for the drive, in seconds.
yards integer Total yards gained on the drive.
offensive_plays integer Number of offensive plays on the drive.
is_score logical TRUE if the drive resulted in a score.
result character Drive result code (e.g. PUNT, TD).
short_display_result character Short drive-result label.
display_result character Drive-result label (e.g. Punt, Touchdown).
source_id character ESPN data-source id for the drive.
source_description character ESPN data-source description (e.g. Feed).
drive_ref character $ref URL to the drive resource itself.
team_ref character $ref URL to the offensive team resource.
end_team_ref character $ref URL to the team in possession at drive end.
plays_ref character $ref URL to the drive's plays resource.
When plays = "list", an additional plays list-column is appended –
each cell a tibble in the full espn_cfb_game_pbp() schema. When
plays = "expand", the flat one-row-per-play table is returned instead:
every column of espn_cfb_game_pbp() plus the drive-level columns above
carried alongside each play with a drive_ prefix.
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_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_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_drives(game_id = 401628339))
try(espn_cfb_game_drives(game_id = 401628339, plays = "list"))
try(espn_cfb_game_drives(game_id = 401628339, plays = "expand"))
try(espn_cfb_game_drives(game_id = 401628339, team_detail = FALSE))
cfbfastR documentation built on Aug. 24, 2026, 5:13 p.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
View source: R/espn_cfb_game.R
| espn_cfb_game_drives | R Documentation |
ESPN College Football Game Drives
Description
Get the per-game drive log for a single college football game
– one row per drive, with start/end field position, yardage, play count,
result, and a $ref to that drive's plays. Optionally embed each drive's
full-schema play-by-play as a nested list-column or as a flat
one-row-per-play table.
Usage
espn_cfb_game_drives(
game_id = NULL,
plays = c("none", "list", "expand"),
participants = c("none", "wide", "long"),
participants_list = FALSE,
team_participants = c("none", "wide"),
team_participants_list = FALSE,
position_detail = TRUE,
team_detail = TRUE
)
Arguments
game_id |
(Integer required): ESPN game identifier. |
plays |
(Character): controls whether each drive's plays are
embedded. One of |
participants |
(Character): participant-flattening mode for the
embedded plays – one of |
participants_list |
(Logical): when |
team_participants |
(Character): team-participant-flattening mode
for the embedded plays – one of |
team_participants_list |
(Logical): when |
position_detail |
(Logical): when |
team_detail |
(Logical): when |
Details
Wraps the ESPN core-v2 endpoint
events/{game_id}/competitions/{game_id}/drives. The competition id always
equals the game id. Returns one row per drive (typically 18-24 drives per
game). Each drive carries the offensive team, the start and end
period/clock/yard-line, total yards, offensive play count, the drive
result, and a scoring flag. The plays_ref column is the $ref URL to
that drive's plays – pass the drive_id to espn_cfb_game_drive_plays()
to fetch the play-by-play partitioned to a single drive. This is the
richest drive resource ESPN exposes; the site-v2 summary feed only carries
a flattened subset.
The plays argument controls whether each drive's plays are embedded:
-
"none"(default) – the drives output is returned unchanged, one row per drive, with no embedded plays. -
"list"– aplayslist-column is appended; each cell is that drive's plays as a tibble in the fullespn_cfb_game_pbp()schema (~54 base columns plus any optional participant columns). A drive with no matched plays gets an empty 0-row tibble, neverNULL. -
"expand"– the flat one-row-per-play table is returned: every play in the fullespn_cfb_game_pbp()schema, with that play's drive-level columns carried alongside, prefixeddrive_(e.g.drive_id,drive_result,drive_yards,drive_start_yard_line) to avoid collision with the play's own columns. This is theespn_cfb_game_pbp()expanded form enriched with drive context.
The participants, participants_list, team_participants,
team_participants_list, and position_detail arguments shape the
embedded plays and are consulted only when plays != "none". They
have the same meaning as the identically named arguments on
espn_cfb_game_pbp() – e.g. participants = "wide" appends the
type-keyed {type}_player_* columns to every embedded play tibble. See
espn_cfb_game_pbp() for the full description of each.
To get the plays efficiently the wrapper first probes the drives
endpoint for inline plays (items[].plays.items[]); when ESPN embeds
them, no extra request is made. When only a plays.$ref is present, the
competition-level /plays feed is fetched once and the plays are
partitioned into drives by matching each play's drive id. Per-drive
plays_ref URLs are never dereferenced individually.
espn_cfb_unnest_plays() turns a plays = "list" result into the same
flat table as plays = "expand" without any further HTTP.
Value
A data frame with one row per drive:
| col_name | types | description |
| game_id | character | ESPN game identifier. |
| drive_id | character | ESPN drive id. |
| sequence_number | character | Drive sequence number within the game. |
| description | character | Drive summary text (e.g. 9 plays, 75 yards, 4:12). |
| team_id | character | ESPN team id of the offensive team (parsed from team_ref). |
| end_team_id | character | ESPN team id of the team in possession at drive end. |
| start_period | integer | Period (quarter) at the start of the drive. |
| start_period_type | character | Period type at the start of the drive (e.g. quarter). |
| start_clock | character | Game clock display value at the start of the drive. |
| start_clock_seconds | numeric | Game clock value in seconds at the start of the drive. |
| start_yard_line | integer | Yard line at the start of the drive. |
| start_text | character | Field-position text at the start of the drive. |
| end_period | integer | Period (quarter) at the end of the drive. |
| end_period_type | character | Period type at the end of the drive (e.g. quarter). |
| end_clock | character | Game clock display value at the end of the drive. |
| end_clock_seconds | numeric | Game clock value in seconds at the end of the drive. |
| end_yard_line | integer | Yard line at the end of the drive. |
| end_text | character | Field-position text at the end of the drive. |
| time_elapsed | character | Elapsed game time for the drive (MM:SS). |
| time_elapsed_seconds | numeric | Elapsed game time for the drive, in seconds. |
| yards | integer | Total yards gained on the drive. |
| offensive_plays | integer | Number of offensive plays on the drive. |
| is_score | logical | TRUE if the drive resulted in a score. |
| result | character | Drive result code (e.g. PUNT, TD). |
| short_display_result | character | Short drive-result label. |
| display_result | character | Drive-result label (e.g. Punt, Touchdown). |
| source_id | character | ESPN data-source id for the drive. |
| source_description | character | ESPN data-source description (e.g. Feed). |
| drive_ref | character | $ref URL to the drive resource itself. |
| team_ref | character | $ref URL to the offensive team resource. |
| end_team_ref | character | $ref URL to the team in possession at drive end. |
| plays_ref | character | $ref URL to the drive's plays resource. |
When plays = "list", an additional plays list-column is appended –
each cell a tibble in the full espn_cfb_game_pbp() schema. When
plays = "expand", the flat one-row-per-play table is returned instead:
every column of espn_cfb_game_pbp() plus the drive-level columns above
carried alongside each play with a drive_ prefix.
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_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_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_drives(game_id = 401628339))
try(espn_cfb_game_drives(game_id = 401628339, plays = "list"))
try(espn_cfb_game_drives(game_id = 401628339, plays = "expand"))
try(espn_cfb_game_drives(game_id = 401628339, team_detail = FALSE))
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.