> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://statpad.dev/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://statpad.dev/docs/_mcp/server.

# Hockey

> How Statpad describes NHL games, including the hockey live state, overtime and shootout scoring, play types, strength and penalties on plays, and skater and goalie box score stat codes.

Statpad serves one hockey league, the NHL (`nhl`). A hockey game fills the same endpoints as every other sport, with its sport's details in the `hockey` blocks.

The examples come from a recorded game, the [Panthers at the Capitals](https://statpad.dev/samples/nhl-panthers-at-capitals/plays.json) on November 7, 2026, which Washington won 4 to 3.

## Live state

`live_state` on `GET /v1/nhl/games/{id}` carries the situation in its `hockey` block. The other sports' blocks are `null`.

| Field                                          | What it is                                                                                     |
| ---------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `period`                                       | The period. 1 to 3 are regulation, 4 is overtime, and in the regular season 5 is the shootout. |
| `clock_seconds`                                | Seconds left in the period. `null` in a shootout, which has no clock.                          |
| `clock_running`                                | Always `null`. The hockey feed doesn't say whether the clock is running.                       |
| `possession_team_id`                           | Always `null`. Hockey has no possession.                                                       |
| `hockey.home_shootout`, `hockey.away_shootout` | Goals each team scored in the shootout. `null` until a shootout starts.                        |

There's no live power-play state. Each play carries its team's manpower at the time as `strength`.

After the final, `period` and `clock_seconds` keep the end of the game, such as period 3 at `0`, and the `hockey` block stays.

## Periods, overtime and shootouts

The NHL has a `period_kind` of `period` and 3 `regulation_periods`:

| Period | Regular season               | Playoffs                                           |
| ------ | ---------------------------- | -------------------------------------------------- |
| 1 to 3 | 20-minute regulation periods | 20-minute regulation periods                       |
| 4      | A 5-minute overtime          | A 20-minute overtime                               |
| 5      | The shootout, with no clock  | Another 20-minute overtime, and so on until a goal |

[Build a scoreboard](/docs/scoreboard#the-period) labels these periods, `Shootout` included, and [the clock section](/docs/scoreboard#the-clock) formats `clock_seconds`.

A shootout changes the score only once. Each attempt is a `goal`, `shot_on_goal` or `missed_shot` play with `hockey.is_shootout` set. Attempts never score, so they keep the tied score from the end of overtime. The plays that end the shootout carry the final score, which gives the winner one goal more. The game's `home_score` and `away_score` include that goal. A player's shootout goals are in `shootout_goals` in the box score, not in `goals`.

## Plays

`GET /v1/nhl/games/{id}/plays` lists every event. It returns a page of events, 500 by default and up to 1,000 with `limit`, with a `next_cursor` for the rest. [Lists, pagination and dates](/docs/pagination) shows how to page. A play's `type` and its `hockey.play_type` are the same value, one of these:

| `play_type`                              | The event                                                |
| ---------------------------------------- | -------------------------------------------------------- |
| `goal`                                   | A goal, or a scored shootout attempt                     |
| `shot_on_goal`                           | A shot on goal that didn't score                         |
| `missed_shot`                            | A shot that missed the net, or a failed shootout attempt |
| `blocked_shot`                           | A shot an opponent blocked                               |
| `faceoff`, `hit`, `giveaway`, `takeaway` | What the name says                                       |
| `penalty`                                | A penalty, whatever the infraction                       |
| `stoppage`                               | A stoppage in play                                       |
| `period_start`, `period_end`, `game_end` | The start or end of a period, and the end of the game    |
| `other`                                  | Anything else                                            |

The `hockey` block on each play:

| Field              | What it is                                                                                                                                                                                                                                                            |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `shot_type`        | How a shot was taken: `wrist`, `snap`, `slap`, `backhand`, `tip_in`, `deflected`, `wrap_around`, `batted`, `poke`, `between_legs` or `cradle`. Set on goals and shots only, and `null` when the feed doesn't say.                                                     |
| `strength`         | The manpower of the play's team when it happened: `even`, `power_play` or `shorthanded`. `null` on a play without a team, such as the end of a period.                                                                                                                |
| `is_empty_net`     | A goal scored into an empty net.                                                                                                                                                                                                                                      |
| `is_shootout`      | A shootout attempt.                                                                                                                                                                                                                                                   |
| `penalty_minutes`  | The minutes a penalty assesses, 0 to 20. Penalties only.                                                                                                                                                                                                              |
| `penalty_severity` | `minor`, `double_minor`, `bench_minor`, `major`, `misconduct`, `game_misconduct` or `match`. Penalties only.                                                                                                                                                          |
| `rink_x`, `rink_y` | Where the play happened, in whole feet from center ice. `rink_x` runs along the rink between the end boards, -100 to 100, and `rink_y` across it, -43 to 43. Statpad passes them on as the feed reports them, without turning them to the team's direction of attack. |

`team_id` is the team the feed credits: the shooting team for a goal, a shot on goal or a miss, the blocking team for a blocked shot, the faceoff's winner, and the penalized team. `description` is the feed's play text.

Each play's `participants` lists the players in it with a `role`: `scorer`, `assist`, `shooter`, `goalie` (who faced the shot), `blocker`, `faceoff_winner`, `faceoff_loser`, `hitter`, `hittee`, `giver`, `taker`, `fouler` (the penalized player) and `fouled` (who drew the penalty), or `player` for any other part. Join each participant's `player_id` to `players[].id` in the game roster response, not to the box score, because a player in a play can have no stat line.

This is the Panthers' power-play goal in the 1st period, from `plays.json`, unedited:

```json
{
  "away_score": 2,
  "basketball": null,
  "clock_seconds": 600,
  "description": "Brady Tkachuk Goal (10) Snap Shot, assists: Matthew Tkachuk (20), Seth Jones (17)",
  "football": null,
  "game_id": "01a1e5f6-713e-7a47-b1d5-dbb74e828b61",
  "group_id": null,
  "hockey": {
    "is_empty_net": false,
    "is_shootout": false,
    "penalty_minutes": null,
    "penalty_severity": null,
    "play_type": "goal",
    "rink_x": 88,
    "rink_y": -4,
    "shot_type": "snap",
    "strength": "power_play"
  },
  "home_score": 1,
  "id": "01a1e5f6-713e-7bfc-b8b7-a1a44802e38e",
  "is_official": true,
  "is_scoring": true,
  "participants": [
    {
      "player_id": "01a1e5f6-713e-7a7c-9d19-62cfca700356",
      "role": "assist",
      "team_id": "01a1e5f6-713e-7a52-920b-26f20525ffbc"
    },
    {
      "player_id": "01a1e5f6-713e-7a98-a3f0-5befc2db1da5",
      "role": "assist",
      "team_id": "01a1e5f6-713e-7a52-920b-26f20525ffbc"
    },
    {
      "player_id": "01a1e5f6-713e-7a80-8ad5-9ba4f7e298d0",
      "role": "scorer",
      "team_id": "01a1e5f6-713e-7a52-920b-26f20525ffbc"
    }
  ],
  "period": 1,
  "period_half": null,
  "points": 1,
  "sequence": 10600000000063,
  "soccer": null,
  "team_id": "01a1e5f6-713e-7a52-920b-26f20525ffbc",
  "type": "goal",
  "updated_at": "2026-11-16T20:04:55.740953Z",
  "version": 1,
  "wall_clock": "2026-11-07T18:00:55Z"
}
```

Brady Tkachuk scored with 10:00 left in the 1st period to put Florida up 2 to 1, with two assists. The play has no `baseball` block because Statpad recorded the sample before it added baseball. Treat a missing block as `null`.

## Play groups

Hockey has no drives or possessions in the data. Every play's `group_id` is `null`, and `GET /v1/nhl/games/{id}/play-groups` returns an empty list.

## Box score

`GET /v1/nhl/games/{id}/boxscore` has one line per player with stats, in one of two categories. Forwards and defensemen are `skaters`:

| Code                                                                              | What it is                                                         |
| --------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| `goals`, `assists`                                                                | Goals and assists, without the shootout                            |
| `shots_on_goal`, `missed_shots`, `blocked_shots`                                  | Shots on goal and missed shots taken, and opponents' shots blocked |
| `shootout_goals`                                                                  | Goals in the shootout                                              |
| `plus_minus`                                                                      | The player's plus-minus                                            |
| `hits`, `takeaways`, `giveaways`                                                  | What the names say                                                 |
| `faceoffs_won`, `faceoffs_lost`, `faceoff_pct`                                    | Faceoffs. `faceoff_pct` is a percentage, such as `61.9`.           |
| `penalties`, `penalty_minutes`                                                    | Penalties taken and the minutes they assessed                      |
| `time_on_ice`                                                                     | Time on ice, in seconds                                            |
| `even_strength_time_on_ice`, `power_play_time_on_ice`, `short_handed_time_on_ice` | Time on ice at each strength, in seconds                           |
| `shifts`                                                                          | Shifts                                                             |

Goaltenders are `goalies`:

| Code                                                            | What it is                                     |
| --------------------------------------------------------------- | ---------------------------------------------- |
| `shots_against`, `goals_against`, `saves`                       | Shots faced, goals allowed and saves           |
| `save_pct`                                                      | Saves per shot, as a fraction, such as `0.871` |
| `even_strength_saves`, `power_play_saves`, `short_handed_saves` | Saves at each strength                         |
| `shootout_shots_against`, `shootout_saves`                      | Shootout attempts faced and saved              |
| `time_on_ice`                                                   | Time on ice, in seconds                        |
| `penalty_minutes`                                               | Penalty minutes                                |

Treat every code as optional, and ignore codes you don't use. [Build a scoreboard](/docs/scoreboard#build-a-box-score) joins the lines to player names.

## Rosters and injuries

`GET /v1/nhl/games/{id}/roster` lists every player in the box score, with their team, jersey and position (`C`, `LW`, `RW`, `D` or `G`). The hockey feed doesn't mark starters, so `starter` is `false`.

The NHL fills injuries. `GET /v1/nhl/injuries` and `league:nhl` carry the league's injury report, refreshed every 30 minutes, with statuses such as `day_to_day`, `out` and `injured_reserve`. [Coverage by league](/docs/coverage#field-notes) describes the injury fields.

## What isn't filled yet

| Data                              | What you get today                        |
| --------------------------------- | ----------------------------------------- |
| `clock_running` on the live state | `null`. Use `status` and `clock_seconds`. |
| `starter` on a game roster entry  | `false` for every player                  |

[Coverage by league](/docs/coverage#not-filled-yet) lists the gaps every sport shares, such as team totals and the score by period.