NHL play_by_plays API
play_by_plays
nhl.play_by_playsEvery 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_playsList play_by_plays for NHL
Requires one of:
game_id — requests satisfying none of these return 400.Parameters
game_idquerybigintoptionalFilter to a single game.
period_numberqueryintegeroptionalFilter to a period (1-3; 4 and up for overtime or the shootout).
type_desc_keyquerystringoptionalFilter 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_idquerybigintoptionalFilter to the events of one team.
limitqueryintegeroptionaldefault 50Page size. Defaults to 50; max 5000.
from_idquerybigintoptionalReturn 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/jsonResponse Schema(39 fields)show schema ▸
| Field | Type | References | Description |
|---|---|---|---|
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 | bigintnullable | Player who took the penalty e.g. 834 | |
drawn_by_player_id | bigintnullable | Player 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 | bigintnullable | Team credited with the event e.g. 29 | |
game_id | bigint | — e.g. 15003 | |
goalie_in_net_id | bigintnullable | Goaltender 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 | bigintnullable | Faceoff loser e.g. 6627 | |
player_id | bigintnullable | Player of a giveaway or takeaway e.g. 105 | |
scoring_player_id | bigintnullable | — e.g. 858 | |
served_by_player_id | bigintnullable | Player who served the penalty (bench and goalie penalties) e.g. 7393 | |
shooting_player_id | bigintnullable | — e.g. 6757 | |
winning_player_id | bigintnullable | Faceoff 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}Get a single play_by_play by id
Parameters
idpathbigintrequiredPrimary 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 ▸
| Field | Type | References | Description |
|---|---|---|---|
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 | bigintnullable | Player who took the penalty e.g. 834 | |
drawn_by_player_id | bigintnullable | Player 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 | bigintnullable | Team credited with the event e.g. 29 | |
game_id | bigint | — e.g. 15003 | |
goalie_in_net_id | bigintnullable | Goaltender 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 | bigintnullable | Faceoff loser e.g. 6627 | |
player_id | bigintnullable | Player of a giveaway or takeaway e.g. 105 | |
scoring_player_id | bigintnullable | — e.g. 858 | |
served_by_player_id | bigintnullable | Player who served the penalty (bench and goalie penalties) e.g. 7393 | |
shooting_player_id | bigintnullable | — e.g. 6757 | |
winning_player_id | bigintnullable | Faceoff 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 |