Skip to content
PuckAPI

get_plays

10 creditsMulti-tablePOST /v1/get_plays

Play-by-play events with rink coordinates, strength state, and the players involved.

Use it when you are working at the event level: shot locations, what happened on a power play, every faceoff a centre took, or the sequence leading to a goal. Requires at least game_id, season, or player_id: an unfiltered scan of 7 million events is not offered.

Parameters

game_idstringoptional
NHL game ID (e.g. 2025020887)
seasonstringoptional
Season ID, 8-digit (e.g. 20242025)
teamstringoptional
Team abbreviation that owns the event
player_idnumberoptional
NHL player ID; matches any role on the event
typestringoptional
goal, shot-on-goal, missed-shot, blocked-shot, faceoff, hit, giveaway, takeaway, penalty, stoppage, ...
strengthstringoptional
Skater strength from the event owner's view: 5v5, 5v4, 4v5, ...
zonestringoptional
O offensive, N neutral, D defensive
periodnumberoptional
Period number (4+ is overtime)
shot_attempts_onlybooleanoptional
Only goals, shots, misses and blocks (Corsi events)
limitnumberoptional
Max events (default 200, max 1000)
offsetnumberoptional
Pagination offset
leagueenum: nhl | pwhl | ohl | whl | qmjhl | echl | ahl | ushloptional
League. Defaults to nhl. One of: nhl, pwhl, ohl, whl, qmjhl, echl, ahl, ushl.

Notes

  • Over MCP, ask for it in plain English and the client calls get_plays itself. Point any MCP client at https://mcp.puckapi.com/mcp?key=YOUR_API_KEY.
  • Each call costs 10 credits, taken before it runs and refunded if the server errors.
  • Not the call you need? Find the right call by what you are trying to answer.

Request

curl -X POST https://mcp.puckapi.com/v1/get_plays \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
  "game_id": "2024020601",
  "type": "goal"
}'

Response

json
{
  "plays": [
    {
      "game_id": "2024020601",
      "event_id": 111,
      "season": "20242025",
      "period": 1,
      "time_in_period": "01:08",
      "seconds_elapsed": 68,
      "type": "goal",
      "team": "PIT",
      "strength": "5v4",
      "x_coord": -80,
      "y_coord": -10,
      "zone": "O",
      "shot_type": "tip-in",
      "scoring_player_id": 8479344,
      "assist1_player_id": 8482758,
      "assist2_player_id": 8482698,
      "goalie_in_net_id": 8480045,
      "away_score": 1,
      "home_score": 0
    }
  ],
  "summary": {
    "returned": 1,
    "scope": "this page of results, not the full filter",
    "by_type": {
      "goal": 1
    },
    "shot_attempts": 1,
    "goals": 1
  },
  "count": 1,
  "next_offset": null
}

Response fields

plays[].typestring
Event type, the NHL's own key
plays[].teamstring
Abbreviation of the team that owns the event
plays[].strengthstring
Skater count from the owner's view, e.g. 5v4
plays[].x_coordnumber
Rink x, -100..100 along the length
plays[].y_coordnumber
Rink y, -42..42 across
plays[].zonestring
O, N or D
plays[].seconds_elapsednumber
Seconds from the opening faceoff, continuous across periods
plays[].scoring_player_idnumber
Scorer on a goal; see also shooting_player_id, winning_player_id, hitting_player_id
summary.by_typeobject
Counts per event type, for this page of results only
next_offsetnumber
Offset for the next page, or null when the page is the last

Related endpoints

get_player_stats5 cr

Takes the player_id this one returns.

Player bio and goalie stats (if goalie). For skaters, returns bio info and team context.

get_player_game_log5 cr

Takes the player_id this one returns.

A player's game-by-game stat lines for a season: date, opponent, home/away, and the box score for each game.

get_market_odds10 cr

Returns the game_id this one takes.

Opening and closing lines by sportsbook for the period and regulation-result markets (history from May 2023)

get_line_movement25 cr

Returns the game_id this one takes.

Time-series odds snapshots grouped by bookmaker. Shows how lines moved from open to close.

Try it

500 free credits every month: 50 calls to get_plays, and no card.

Get a free keyAll NHL endpoints