STAT-API

NHL play_by_plays API

play_by_playsnhl.play_by_plays
Every event in every NHL game since 2021-22 — faceoffs, shots on goal, missed and blocked shots, hits, giveaways, takeaways, goals, penalties and stoppages — with the period, the game clock, the rink coordinates, the players involved and the score and shots on goal after the event.
GET/api/v1/nhl/play_by_plays
Requires one of: game_id — requests satisfying none of these return 400.
Parameters
game_idquerybigintoptional
Filter to a single game.
period_numberqueryintegeroptional
Filter to a period (1-3; 4 and up for overtime or the shootout).
type_desc_keyquerystringoptional
Filter by event type. Values: blocked-shot, delayed-penalty, failed-shot-attempt, faceoff, game-end, giveaway, goal, hit, missed-shot, penalty, period-end, period-start, shootout-complete, shot-on-goal, stoppage, takeaway.
event_owner_team_idquerybigintoptional
Filter to the events of one team.
limitqueryintegeroptionaldefault 50
Page size. Defaults to 50; max 5000.
from_idquerybigintoptional
Return rows with id strictly greater than this value; page using the previous response's `next_from_id`. Omit on the first page.
Restores the documented defaults (trial keys only accept the unchanged defaults).
Request
curl -sS --compressed \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  'https://api.stat-api.com/api/v1/nhl/play_by_plays?game_id=1'
Responses
200play_by_plays rows matching the declared filter set, wrapped in { play_by_plays, limit, next_from_id, has_more }. has_more is true when another row follows this page. To walk every row, start with ?from_id=0 and pass each next_from_id back as from_id until it is null; the filters stay. A first page without from_id comes in the default order and gives next_from_id null.application/jsonshow example ▸
400No declared filter set was satisfied — response body matches MissingRequiredFiltersError; pick one combo from the accepted-sets hint and resend.application/json
Response Schema(39 fields)show schema ▸
FieldTypeReferencesDescription
idkey
bigint—Primary Key
assist1_player_id
bigintnullable—
e.g. 307
assist2_player_id
bigintnullable—
e.g. 7123
blocking_player_id
bigintnullable—
e.g. 15
committed_by_player_id
bigintnullablePlayer who took the penalty
e.g. 834
drawn_by_player_id
bigintnullablePlayer who drew the penalty
e.g. 308
event_id
integer—The league's event number, unique within the game
e.g. 58
event_owner_team_id
bigintnullableTeam credited with the event
e.g. 29
game_id
bigint—
e.g. 15003
goalie_in_net_id
bigintnullableGoaltender the shot was taken against
e.g. 531
hittee_player_id
bigintnullable—
e.g. 353
hitting_player_id
bigintnullable—
e.g. 7297
losing_player_id
bigintnullableFaceoff loser
e.g. 6627
player_id
bigintnullablePlayer of a giveaway or takeaway
e.g. 105
scoring_player_id
bigintnullable—
e.g. 858
served_by_player_id
bigintnullablePlayer who served the penalty (bench and goalie penalties)
e.g. 7393
shooting_player_id
bigintnullable—
e.g. 6757
winning_player_id
bigintnullableFaceoff winner
e.g. 6627
away_score
integernullable—Away goals after the event; empty on most event types
e.g. 1
away_sog
integernullable—Away shots on goal after the event; empty on most event types
e.g. 2
home_score
integernullable—Home goals after the event; empty on most event types
e.g. 1
home_sog
integernullable—Home shots on goal after the event; empty on most event types
e.g. 19
penalty_desc_key
stringnullable—The infraction (e.g. tripping, hooking, slashing)
e.g. hooking
penalty_minutes
integernullable——
e.g. 2
penalty_type_code
stringnullable—Penalty class (MIN minor, MAJ major, BEN bench minor, MIS misconduct, GAM game misconduct, MAT match, PS penalty shot)
Values:MINMAJMISBENGAM
period_number
integer——
e.g. 1
period_type
string—REG, OT or SO (shootout)
Values:REGOTSO
reason
stringnullable—Why a shot missed or play stopped (e.g. wide-of-net, icing, goalie-stopped-after-sog)
e.g. wide-of-net
secondary_reason
stringnullable——
Values:tv-timeouthome-timeoutvisitor-timeoutplayer-injuryice-problem
shot_type
stringnullable—wrist, snap, slap, tip-in, backhand, deflected, wrap-around, bat, poke
Values:wristslapsnapbackhandtip-indeflectedwrap-around
situation_code
stringnullable—Four digits: away goalie in net (1/0), away skaters, home skaters, home goalie in net (1/0); e.g. 1551 is five on five
e.g. 1551
sort_order
integernullable—Order of the event within the game
e.g. 8
time_in_period_seconds
integer—Seconds elapsed in the period when the event happened
e.g. 0
time_remaining_seconds
integer—Seconds left in the period when the event happened
e.g. 1200
type_code
integer—The league's numeric event type (e.g. 505 goal, 506 shot on goal, 502 faceoff)
e.g. 502
type_desc_key
string—Event type (e.g. goal, shot-on-goal, faceoff, hit, penalty)
Values:faceoffshot-on-goalhitstoppageblocked-shotmissed-shotgiveawaytakeawaypenaltygoalperiod-startperiod-enddelayed-penaltygame-endshootout-complete
x_coord
integernullable—Rink x coordinate in feet from center ice
e.g. 69
y_coord
integernullable—Rink y coordinate in feet from center ice
e.g. 22
zone_code
stringnullable—Zone of the event for the owning team (O offensive, D defensive, N neutral)
Values:ODN
GET/api/v1/nhl/play_by_plays/{id}
Parameters
idpathbigintrequired
Primary key (id) of the play_by_play row.
Restores the documented defaults (trial keys only accept the unchanged defaults).
Request
curl -sS --compressed \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  'https://api.stat-api.com/api/v1/nhl/play_by_plays/{pk_value}'
Responses
200Single play_by_play row.application/jsonshow example ▸
404Row not found.
Response Schema(39 fields)show schema ▸
FieldTypeReferencesDescription
idkey
bigint—Primary Key
assist1_player_id
bigintnullable—
e.g. 307
assist2_player_id
bigintnullable—
e.g. 7123
blocking_player_id
bigintnullable—
e.g. 15
committed_by_player_id
bigintnullablePlayer who took the penalty
e.g. 834
drawn_by_player_id
bigintnullablePlayer who drew the penalty
e.g. 308
event_id
integer—The league's event number, unique within the game
e.g. 58
event_owner_team_id
bigintnullableTeam credited with the event
e.g. 29
game_id
bigint—
e.g. 15003
goalie_in_net_id
bigintnullableGoaltender the shot was taken against
e.g. 531
hittee_player_id
bigintnullable—
e.g. 353
hitting_player_id
bigintnullable—
e.g. 7297
losing_player_id
bigintnullableFaceoff loser
e.g. 6627
player_id
bigintnullablePlayer of a giveaway or takeaway
e.g. 105
scoring_player_id
bigintnullable—
e.g. 858
served_by_player_id
bigintnullablePlayer who served the penalty (bench and goalie penalties)
e.g. 7393
shooting_player_id
bigintnullable—
e.g. 6757
winning_player_id
bigintnullableFaceoff winner
e.g. 6627
away_score
integernullable—Away goals after the event; empty on most event types
e.g. 1
away_sog
integernullable—Away shots on goal after the event; empty on most event types
e.g. 2
home_score
integernullable—Home goals after the event; empty on most event types
e.g. 1
home_sog
integernullable—Home shots on goal after the event; empty on most event types
e.g. 19
penalty_desc_key
stringnullable—The infraction (e.g. tripping, hooking, slashing)
e.g. hooking
penalty_minutes
integernullable——
e.g. 2
penalty_type_code
stringnullable—Penalty class (MIN minor, MAJ major, BEN bench minor, MIS misconduct, GAM game misconduct, MAT match, PS penalty shot)
Values:MINMAJMISBENGAM
period_number
integer——
e.g. 1
period_type
string—REG, OT or SO (shootout)
Values:REGOTSO
reason
stringnullable—Why a shot missed or play stopped (e.g. wide-of-net, icing, goalie-stopped-after-sog)
e.g. wide-of-net
secondary_reason
stringnullable——
Values:tv-timeouthome-timeoutvisitor-timeoutplayer-injuryice-problem
shot_type
stringnullable—wrist, snap, slap, tip-in, backhand, deflected, wrap-around, bat, poke
Values:wristslapsnapbackhandtip-indeflectedwrap-around
situation_code
stringnullable—Four digits: away goalie in net (1/0), away skaters, home skaters, home goalie in net (1/0); e.g. 1551 is five on five
e.g. 1551
sort_order
integernullable—Order of the event within the game
e.g. 8
time_in_period_seconds
integer—Seconds elapsed in the period when the event happened
e.g. 0
time_remaining_seconds
integer—Seconds left in the period when the event happened
e.g. 1200
type_code
integer—The league's numeric event type (e.g. 505 goal, 506 shot on goal, 502 faceoff)
e.g. 502
type_desc_key
string—Event type (e.g. goal, shot-on-goal, faceoff, hit, penalty)
Values:faceoffshot-on-goalhitstoppageblocked-shotmissed-shotgiveawaytakeawaypenaltygoalperiod-startperiod-enddelayed-penaltygame-endshootout-complete
x_coord
integernullable—Rink x coordinate in feet from center ice
e.g. 69
y_coord
integernullable—Rink y coordinate in feet from center ice
e.g. 22
zone_code
stringnullable—Zone of the event for the owning team (O offensive, D defensive, N neutral)
Values:ODN