scrape_json_play_by_play: Scrape an individual game's JSON play-by-play data from...
In maksimhorowitz/nflscrapR: Compiling the NFL Play-by-Play API for easy use in R

Description Usage Arguments Value Examples

This function returns the play-by-play data available from NFL.com's JSON feed (for games starting in 2009).

1	scrape_json_play_by_play(game_id, check_url = 1)

`game_id`	Ten digit game id (either numeric or character) associated with a given NFL game.
`check_url`	Indicator for whether or not to check if the game's url exists (default is 1, meaning yes). This is used to work with the `scrape_season_play_by_play` function that will perform its own check prior to scraping individual games.

Data frame where each individual row represents a single play in the game containing the following detailed information:

play_id - Numeric play id that when used with game_id and drive provides the unique identifier for a single play.
game_id - Ten digit identifier for NFL game.
home_team - String abbreviation for the home team.
away_team - String abbreviation for the away team.
posteam - String abbreviation for the team with possession.
posteam_type - String indicating whether the posteam team is home or away.
defteam - String abbreviation for the team on defense.
side_of_field - String abbreviation for which team's side of the field the team with possession is currently on.
yardline_100 - Numeric distance in the number of yards from the opponent's endzone for the posteam.
game_date - Date of the game.
quarter_seconds_remaining - Numeric seconds remaining in the quarter.
half_seconds_remaining - Numeric seconds remaining in the half.
game_seconds_remaining - Numeric seconds remaining in the game.
game_half - String indicating which half the play is in, either Half1, Half2, or Overtime.
quarter_end - Binary indicator for whether or not the row of the data is marking the end of a quarter.
drive - Numeric drive number in the game.
sp - Binary indicator for whether or not a score occurred on the play.
qtr - Quarter of the game (5 is overtime).
down - The down for the given play.
goal_to_go - Binary indicator for whether or not the posteam is in a goal down situation.
time - Time at start of play provided in string format as minutes:seconds remaining in the quarter.
yrdln - String indicating the current field position for a given play.
ydstogo - Numeric yards in distance from either the first down marker or the endzone in goal down situations.
ydsnet - Numeric value for total yards gained on the given drive.
desc - Detailed string description for the given play.
play_type - String indicating the type of play: pass (includes sacks), run (includes scrambles), punt, field_goal, kickoff, extra_point, qb_kneel, qb_spike, no_play (timeouts and penalties), and missing for rows indicating end of play.
yards_gained - Numeric yards gained (or lost) for the given play.
shotgun - Binary indicator for whether or not the play was in shotgun formation.
no_huddle - Binary indicator for whether or not the play was in no_huddle formation.
qb_dropback - Binary indicator for whether or not the QB dropped back on the play (pass attempt, sack, or scrambled).
qb_kneel - Binary indicator for whether or not the QB took a knee.
qb_spike - Binary indicator for whether or not the QB spiked the ball.
qb_scramble - Binary indicator for whether or not the QB scrambled.
pass_length - String indicator for pass length: short or deep.
pass_location - String indicator for pass location: left, middle, or right.
air_yards - Numeric value for distance in yards perpendicular to the line of scrimmage at where the targeted receiver either caught or didn't catch the ball.
yards_after_catch - Numeric value for distance in yards perpendicular to the yard line where the receiver made the reception to where the play ended.
run_location - String indicator for location of run: left, middle, or right.
run_gap - String indicator for line gap of run: end, guard, or tackle
field_goal_result - String indicator for result of field goal attempt: made, missed, or blocked.
kick_distance - Numeric distance in yards for kickoffs, field goals, and punts.
extra_point_result - String indicator for the result of the extra point attempt: good, failed, blocked, safety (touchback in defensive endzone is 1 point apparently), or aborted.
two_point_conv_result - String indicator for result of two point conversion attempt: success, failure, safety (touchback in defensive endzone is 1 point apparently), or return.
home_timeouts_remaining - Numeric timeouts remaining in the half for the home team.
away_timeouts_remaining - Numeric timeouts remaining in the half for the away team.
timeout - Binary indicator for whether or not a timeout was called.
timeout_team - String abbreviation for which team called the timeout.
td_team - String abbreviation for which team scored the touchdown.
posteam_timeouts_remaining - Number of timeouts remaining for the possession team.
defteam_timeouts_remaining - Number of timeouts remaining for the team on defense.
total_home_score - Score for the home team at the start of the play.
total_away_score - Score for the away team at the start of the play.
posteam_score - Score the posteam at the start of the play.
defteam_score - Score the defteam at the start of the play.
score_differential - Score differential between the posteam and defteam at the start of the play.
posteam_score_post - Score for the posteam at the end of the play.
defteam_score_post - Score for the defteam at the end of the play.
score_differential_post - Score differential between the posteam and defteam at the end of the play.
no_score_prob - Predicted probability of no score occurring for the rest of the half based on the expected points model.
opp_fg_prob - Predicted probability of the defteam scoring a FG next.
opp_safety_prob - Predicted probability of the defteam scoring a safety next.
opp_td_prob - Predicted probability of the defteam scoring a TD next.
fg_prob - Predicted probability of the posteam scoring a FG next.
safety_prob - Predicted probability of the posteam scoring a safety next.
td_prob - Predicted probability of the posteam scoring a TD next.
extra_point_prob - Predicted probability of the posteam scoring an extra point.
two_point_conversion_prob - Predicted probability of the posteam scoring the two point conversion.
ep - Using the scoring event probabilities, the estimated expected points with respect to the possession team for the given play.
epa - Expected points added (EPA) by the posteam for the given play.
total_home_epa - Cumulative total EPA for the home team in the game so far.
total_away_epa - Cumulative total EPA for the away team in the game so far.
total_home_rush_epa - Cumulative total rushing EPA for the home team in the game so far.
total_away_rush_epa - Cumulative total rushing EPA for the away team in the game so far.
total_home_pass_epa - Cumulative total passing EPA for the home team in the game so far.
total_away_pass_epa - Cumulative total passing EPA for the away team in the game so far.
air_epa - EPA from the air yards alone. For completions this represents the actual value provided through the air. For incompletions this represents the hypothetical value that could've been added through the air if the pass was completed.
yac_epa - EPA from the yards after catch alone. For completions this represents the actual value provided after the catch. For incompletions this represents the difference between the hypothetical air_epa and the play's raw observed EPA (how much the incomplete pass cost the posteam).
comp_air_epa - EPA from the air yards alone only for completions.
comp_yac_epa - EPA from the yards after catch alone only for completions.
total_home_comp_air_epa - Cumulative total completions air EPA for the home team in the game so far.
total_away_comp_air_epa - Cumulative total completions air EPA for the away team in the game so far.
total_home_comp_yac_epa - Cumulative total completions yac EPA for the home team in the game so far.
total_away_comp_yac_epa - Cumulative total completions yac EPA for the away team in the game so far.
total_home_raw_air_epa - Cumulative total raw air EPA for the home team in the game so far.
total_away_raw_air_epa - Cumulative total raw air EPA for the away team in the game so far.
total_home_raw_yac_epa - Cumulative total raw yac EPA for the home team in the game so far.
total_away_raw_yac_epa - Cumulative total raw yac EPA for the away team in the game so far.
wp - Estimated win probabiity for the posteam given the current situation at the start of the given play.
def_wp - Estimated win probability for the defteam.
home_wp - Estimated win probability for the home team.
away_wp - Estimated win probability for the away team.
wpa - Win probability added (WPA) for the posteam.
home_wp_post - Estimated win probability for the home team at the start of the play.
away_wp_post - Estimated win probability for the away team at the start of the play.
total_home_rush_wpa - Cumulative total rushing WPA for the home team in the game so far.
total_away_rush_wpa - Cumulative total rushing WPA for the away team in the game so far.
total_home_pass_wpa - Cumulative total passing WPA for the home team in the game so far.
total_away_pass_wpa - Cumulative total passing WPA for the away team in the game so far.
air_wpa - WPA through the air (same logic as air_epa).
yac_wpa - WPA from yards after the catch (same logic as yac_epa).
comp_air_wpa - The air_wpa for completions only.
comp_yac_wpa - The yac_wpa for completions only.
total_home_comp_air_wpa - Cumulative total completions air WPA for the home team in the game so far.
total_away_comp_air_wpa - Cumulative total completions air WPA for the away team in the game so far.
total_home_comp_yac_wpa - Cumulative total completions yac WPA for the home team in the game so far.
total_away_comp_yac_wpa - Cumulative total completions yac WPA for the away team in the game so far.
total_home_raw_air_wpa - Cumulative total raw air WPA for the home team in the game so far.
total_away_raw_air_wpa - Cumulative total raw air WPA for the away team in the game so far.
total_home_raw_yac_wpa - Cumulative total raw yac WPA for the home team in the game so far.
total_away_raw_yac_wpa - Cumulative total raw yac WPA for the away team in the game so far.
punt_blocked - Binary indicator for if the punt was blocked.
first_down_rush - Binary indicator for if a running play converted the first down.
first_down_pass - Binary indicator for if a passing play converted the first down.
first_down_penalty - Binary indicator for if a penalty converted the first down.
third_down_converted - Binary indicator for if the first down was converted on third down.
third_down_failed - Binary indicator for if the posteam failed to convert first down on third down.
fourth_down_converted - Binary indicator for if the first down was converted on fourth down.
fourth_down_failed - Binary indicator for if the posteam failed to convert first down on fourth down.
incomplete_pass - Binary indicator for if the pass was incomplete.
interception - Binary indicator for if the pass was intercepted.
touchback - Binary indicator for if a touchback occurred on the play.
punt_inside_twenty - Binary indicator for if the punt ended inside the twenty yard line.
punt_in_endzone - Binary indicator for if the punt was in the endzone.
punt_out_of_bounds - Binary indicator for if the punt went out of bounds.
punt_downed - Binary indicator for if the punt was downed.
punt_fair_catch - Binary indicator for if the punt was caught with a fair catch.
kickoff_inside_twenty - Binary indicator for if the kickoff ended inside the twenty yard line.
kickoff_in_endzone - Binary indicator for if the kickoff was in the endzone.
kickoff_out_of_bounds - Binary indicator for if the kickoff went out of bounds.
kickoff_downed - Binary indicator for if the kickoff was downed.
kickoff_fair_catch - Binary indicator for if the kickoff was caught with a fair catch.
fumble_forced - Binary indicator for if the fumble was forced.
fumble_not_forced - Binary indicator for if the fumble was not forced.
fumble_out_of_bounds - Binary indicator for if the fumble went out of bounds.
solo_tackle - Binary indicator if the play had a solo tackle (could be multiple due to fumbles).
safety - Binary indicator for whether or not a safety occurred.
penalty - Binary indicator for whether or not a penalty occurred.
tackled_for_loss - Binary indicator for whether or not a tackle for loss occurred.
fumble_lost - Binary indicator for if the fumble was lost.
own_kickoff_recovery - Binary indicator for if the kicking team recovered the kickoff.
own_kickoff_recovery_td - Binary indicator for if the kicking team recovered the kickoff and scored a TD.
qb_hit - Binary indicator if the QB was hit on the play.
rush_attempt - Binary indicator for if the play was a run.
pass_attempt - Binary indicator for if the play was a pass attempt (includes sacks).
sack - Binary indicator for if the play ended in a sack.
touchdown - Binary indicator for if the play resulted in a TD.
pass_touchdown - Binary indicator for if the play resulted in a passing TD.
rush_touchdown - Binary indicator for if the play resulted in a rushing TD.
return_touchdown - Binary indicator for if the play resulted in a return TD.
extra_point_attempt - Binary indicator for extra point attempt.
two_point_attempt - Binary indicator for two point conversion attempt.
field_goal_attempt - Binary indicator for field goal attempt.
kickoff_attempt - Binary indicator for kickoff.
punt_attempt - Binary indicator for punts.
fumble - Binary indicator for if a fumble occurred.
complete_pass - Binary indicator for if the pass was completed.
assist_tackle - Binary indicator for if an assist tackle occurred.
lateral_reception - Binary indicator for if a lateral occurred on the reception.
lateral_rush - Binary indicator for if a lateral occurred on a run.
lateral_return - Binary indicator for if a lateral occurred on a return.
lateral_recovery - Binary indicator for if a lateral occurred on a fumble recovery.
passer_player_id - Unique identifier for the player that attempted the pass.
passer_player_name - String name for the player that attempted the pass.
receiver_player_id - Unique identifier for the receiver that was targeted on the pass.
receiver_player_name - String name for the targeted receiver.
rusher_player_id - Unique identifier for the player that attempted the run.
rusher_player_name - String name for the player that attempted the run.
lateral_receiver_player_id - Unique identifier for the player that received the lateral on a reception.
lateral_receiver_player_name - String name for the player that received the lateral on a reception.
lateral_rusher_player_id - Unique identifier for the player that received the lateral on a run.
lateral_rusher_player_name - String name for the player that received the lateral on a run.
lateral_sack_player_id - Unique identifier for the player that received the lateral on a sack.
lateral_sack_player_name - String name for the player that received the lateral on a sack.
interception_player_id - Unique identifier for the player that intercepted the pass.
interception_player_name - String name for the player that intercepted the pass.
lateral_interception_player_id - Unique indentifier for the player that received the lateral on an interception.
lateral_interception_player_name - String name for the player that received the lateral on an interception.
punt_returner_player_id - Unique identifier for the punt returner.
punt_returner_player_name - String name for the punt returner.
lateral_punt_returner_player_id - Unique identifier for the player that received the lateral on a punt return.
lateral_punt_returner_player_name - String name for the player that received the lateral on a punt return.
kickoff_returner_player_name - String name for the kickoff returner.
kickoff_returner_player_id - Unique identifier for the kickoff returner.
lateral_kickoff_returner_player_id - Unique identifier for the player that received the lateral on a kickoff return.
lateral_kickoff_returner_player_name - String name for the player that received the lateral on a kickoff return.
punter_player_id - Unique identifier for the punter.
punter_player_name - String name for the punter.
kicker_player_name - String name for the kicker on FG or kickoff.
kicker_player_id - Unique identifier for the kicker on FG or kickoff.
own_kickoff_recovery_player_id - Unique identifier for the player that recovered their own kickoff.
own_kickoff_recovery_player_name - String name for the player that recovered their own kickoff.
blocked_player_id - Unique identifier for the player that blocked the punt or FG.
blocked_player_name - String name for the player that blocked the punt or FG.
tackle_for_loss_1_player_id - Unique identifier for one of the potential players with the tackle for loss.
tackle_for_loss_1_player_name - String name for one of the potential players with the tackle for loss.
tackle_for_loss_2_player_id - Unique identifier for one of the potential players with the tackle for loss.
tackle_for_loss_2_player_name - String name for one of the potential players with the tackle for loss.
qb_hit_1_player_id - Unique identifier for one of the potential players that hit the QB.
qb_hit_1_player_name - String name for one of the potential players that hit the QB.
qb_hit_2_player_id - Unique identifier for one of the potential players that hit the QB.
qb_hit_2_player_name - String name for one of the potential players that hit the QB.
forced_fumble_player_1_team - Team of one of the players with a forced fumble.
forced_fumble_player_1_player_id - Unique identifier of one of the players with a forced fumble.
forced_fumble_player_1_player_name - String name of one of the players with a forced fumble.
forced_fumble_player_2_team - Team of one of the players with a forced fumble.
forced_fumble_player_2_player_id - Unique identifier of one of the players with a forced fumble.
forced_fumble_player_2_player_name - String name of one of the players with a forced fumble.
solo_tackle_1_team - Team of one of the players with a solo tackle.
solo_tackle_2_team - Team of one of the players with a solo tackle.
solo_tackle_1_player_id - Unique identifier of one of the players with a solo tackle.
solo_tackle_2_player_id - Unique identifier of one of the players with a solo tackle.
solo_tackle_1_player_name - String name of one of the players with a solo tackle.
solo_tackle_2_player_name - String name of one of the players with a solo tackle.
assist_tackle_1_player_id - Unique identifier of one of the players with a tackle assist.
assist_tackle_1_player_name - String name of one of the players with a tackle assist.
assist_tackle_1_team - Team of one of the players with a tackle assist.
assist_tackle_2_player_id - Unique identifier of one of the players with a tackle assist.
assist_tackle_2_player_name - String name of one of the players with a tackle assist.
assist_tackle_2_team - Team of one of the players with a tackle assist.
assist_tackle_3_player_id - Unique identifier of one of the players with a tackle assist.
assist_tackle_3_player_name - String name of one of the players with a tackle assist.
assist_tackle_3_team - Team of one of the players with a tackle assist.
assist_tackle_4_player_id - Unique identifier of one of the players with a tackle assist.
assist_tackle_4_player_name - String name of one of the players with a tackle assist.
assist_tackle_4_team - Team of one of the players with a tackle assist.
pass_defense_1_player_id - Unique identifier of one of the players with a pass defense.
pass_defense_1_player_name - String name of one of the players with a pass defense.
pass_defense_2_player_id - Unique identifier of one of the players with a pass defense.
pass_defense_2_player_name - String name of one of the players with a pass defense.
fumbled_1_team - Team of one of the players with a fumble.
fumbled_1_player_id - Unique identifier of one of the players with a fumble.
fumbled_1_player_name - String name of one of the players with a fumble.
fumbled_2_player_id - Unique identifier of one of the players with a fumble.
fumbled_2_player_name - String name of one of the players with a fumble.
fumbled_2_team - Team of one of the players with a fumble.
fumble_recovery_1_team - Team of one of the players with a fumble recovery.
fumble_recovery_1_yards - Yards gained by one of the players with a fumble recovery.
fumble_recovery_1_player_id - Unique identifier of one of the players with a fumble recovery.
fumble_recovery_1_player_name - String name of one of the players with a fumble recovery.
fumble_recovery_2_team - Team of one of the players with a fumble recovery.
fumble_recovery_2_yards - Yards gained by one of the players with a fumble recovery.
fumble_recovery_2_player_id - Unique identifier of one of the players with a fumble recovery.
fumble_recovery_2_player_name - String name of one of the players with a fumble recovery.
return_team - String abbreviation of the return team.
return_yards - Yards gained by the return team.
penalty_team - String abbreviation of the team with the penalty.
penalty_player_id - Unique identifier for the player with the penalty.
penalty_player_name - String name for the player with the penalty.
penalty_yards - Yards gained (or lost) by the posteam from the penalty.
replay_or_challenge - Binary indicator for whether or not a replay or challenge.
replay_or_challenge_result - String indicating the result of the replay or challenge.
penalty_type - String indicating the penalty type.
defensive_two_point_attempt - Binary indicator whether or not the defense was able to have an attempt on a two point conversion, this results following a turnover.
defensive_two_point_conv - Binary indicator whether or not the defense successfully scored on the two point conversion.
defensive_extra_point_attempt - Binary indicator whether or not the defense was able to have an attempt on an extra point attempt, this results following a blocked attempt that the defense recovers the ball.
defensive_extra_point_conv - Binary indicator whether or not the defense successfully scored on an extra point attempt.

# Scrape the play-by-play data for the 2017 Super Bowl by first getting all
# of the post-season game ids then use the required info to scrape the 
# play-by-play data (knowing that it's the last game):
playoff_game_ids_17 <- scrape_game_ids(2017, type = "post")
sb_17_id <- playoff_game_ids_17$game_id[nrow(playoff_game_ids_17)]
sb_17_pbp <- scrape_json_play_by_play(game_id = sb_17_id)