Documentation

Everything you need to connect and query 15 hockey data endpoints.

Getting started

Authentication

Every request requires an API key. Pass it via header or query parameter:

bash

x-api-key: YOUR_API_KEY
# or
Authorization: Bearer YOUR_API_KEY
# or (MCP only)
?key=YOUR_API_KEY

Verify your email, then create an API key from the dashboard. Free accounts get 500 credits.

Base URL

text

https://mcp.puckapi.com

REST API — POST /v1/{tool} with JSON body. Works with cURL, Python, any HTTP client.

MCP — POST /mcp via Streamable HTTP. Works with Claude Desktop, Claude Code, Cursor, and any MCP client.

Rate limits

Credit balance	Rate limit
100 credits or more	60 req/min
Under 100 credits	10 req/min

The limit is the same on every plan. It is burst protection, not the spend boundary; credits are that, and they are enforced per request. Running low slows you down so you notice before the balance reaches zero.

Error handling

Code	Meaning	What to do
400	Invalid parameters	Check required fields and value types
401	Invalid or missing API key	Check your x-api-key header
402	Insufficient credits	Top up your wallet or upgrade your plan
429	Rate limit exceeded	Wait and retry (see limits above)
500	Server error	Retry with idempotency key. Credits auto-refund on server errors.

Pass x-idempotency-key or x-request-id headers to make retries duplicate-safe.

Data coverage

Data	Status	Coverage	Volume
Play-by-play Every event with rink coordinates, strength state, zone, shot type, and the players involved: goals, shots, misses, blocks, faceoffs, hits, giveaways, takeaways, penalties. get_plays get_shot_map 21,980 of 22,067 completed games. The 87 gaps are preseason games before 2018, for which the source publishes no play data. Coordinates are present on locatable events; stoppages and period markers carry none.	Available	2010-11 through current	6,800,000+ events
Games Game records and detail for supported regular season, playoff, and preseason matchups. get_games get_game_detail get_schedule Historical coverage depends on supported seasons and source availability.	Available	2010-11 through current	23,000+
Players Player search and player stat lookup across supported datasets. search_players get_player_stats	Available	Bio, roster, position, supported stats	4,800+
Goalies Goalie stat lookup including save percentage, GAA, wins, shutouts, and time on ice. Shot-quality metrics (GSAX, high-danger save%) are not yet computed. get_goalie_stats	Available	Supported goalie stat seasons	1,509
Teams Team metadata, abbreviations, divisions, conferences, and arenas. list_teams	Available	Active and historical franchises represented in PuckAPI	34
Standings + rankings Standings, rankings, and supported advanced team metrics. get_standings get_team_stats Do not treat standings as real-time unless freshness is shown separately.	Available	Supported seasons and current-season snapshots	494
Odds Odds for supported games, books, and markets where available. get_odds Coverage varies by sportsbook, game, market, and source availability.	Partial	2019-20 through current	107,000+
Line movement Line movement data where multiple odds snapshots exist for a supported game and market. get_line_movement Not every game, book, or market has line movement history.	Partial	Historical odds snapshots where available	Opening/current/closing snapshots
Head-to-head Historical matchup context for supported teams and games. get_head_to_head	Available	Supported teams and games	Matchup history

Coverage describes the datasets PuckAPI supports. Freshness and operational health are tracked separately.

Odds snapshot definitions

opening — Game-day morning lines, captured at ~12:00 UTC (~7-8am ET). Represents the odds available on the morning of the game.

closing — Final pre-game lines, captured at ~23:00 UTC. For evening games, this is the last available line before or shortly after puck drop.

Odds coverage currently documents DraftKings, FanDuel, BetMGM, and ESPN BET. Sportsbook availability varies by game, market, and source. Do not assume every book is available for every game. Games before the 2019-20 season return no odds data.

Response format

REST API

All successful REST responses wrap the result in a data key:

json

{ "data": { "teams": [...], "count": 32 } }

Error responses return:

json

{ "error": "Insufficient credits", "message": "This tool costs 5 credits, you have 2" }

MCP Protocol

MCP responses follow the standard MCP tool result format. The data is returned directly (no data wrapper). Both access methods return identical data, just different envelopes.

Conventions

Seasons — 8-digit season id, start year + end year (2024-25 and 2024-2025 also accepted). Example: 20242025.

Game IDs — Assigned by the league, e.g. 2025020887. Get them from get_games or get_schedule.

Team abbreviations — Standard codes (BUF, TOR, NYR, EDM). Use list_teams if unsure.

Pagination — Endpoints use a limit parameter. No cursor or offset. Narrow your filters to get different slices of data.

Credits — Deducted before the request executes. Automatically refunded on server errors. Monthly credits are used first, then wallet balance.

Setup

Claude Desktop

Add to your claude_desktop_config.json:

json

{
  "mcpServers": {
    "puckapi": {
      "url": "https://mcp.puckapi.com/mcp?key=YOUR_API_KEY"
    }
  }
}

Claude Code

One command:

bash

claude mcp add puckapi https://mcp.puckapi.com/mcp?key=YOUR_API_KEY --transport streamable-http

REST / cURL

POST to /v1/{tool_name} with your params as JSON body. No MCP client needed:

bash

curl -X POST https://mcp.puckapi.com/v1/list_teams \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY"

With parameters:

bash

curl -X POST https://mcp.puckapi.com/v1/get_standings \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"season": "20242025"}'

Which endpoint should I use?

Start from what you want to do, not the API path.

I want a list of all NHL teamslist_teams1cr I want to see upcoming games this weekget_schedule2cr I want to look up a player by namesearch_players2cr I want to see how teams rank in the leagueget_standings2cr I want historical game results for model trainingget_games5cr I want a full stat profile for a teamget_team_stats5cr I want bio info for a player (and goalie stats if goalie)get_player_stats5cr I want to rank goalies by advanced statsget_goalie_stats5cr I want to rank skaters by points, goals or shotsget_skater_season_stats5cr I want betting odds for a gameget_odds10cr I want everything about a single gameget_game_detail10cr I want rivalry history between two teamsget_head_to_head10cr I want every shot in a game with its locationget_shot_map10cr I want the play-by-play for a game or a playerget_plays10cr I want to see how betting lines moved over timeget_line_movement25cr

Endpoint reference

15 endpoints grouped by credit cost. Each includes parameters, example requests in three formats, and documented response fields.

Static reference

1 credit/call

POST

list_teams

1 credit

All 32 active NHL teams with divisions, conferences, and arenas.

When to use: You need a reference list of teams -- team abbreviations for other endpoints, arena names for travel planning, or division/conference groupings for analysis.

Parameters

Name	Type	Required	Description
conference	string	optional	"Eastern" or "Western"
division	string	optional	Division name (e.g. "Atlantic")

Example request

{
  "tool": "list_teams",
  "arguments": {
    "conference": "Eastern",
    "division": "Atlantic"
  }
}

Example response

json

{
  "teams": [
    {
      "abbrev": "BUF",
      "name": "Sabres",
      "city": "Buffalo",
      "conference": "Eastern",
      "division": "Atlantic",
      "arena": "KeyBank Center"
    },
    {
      "abbrev": "TOR",
      "name": "Maple Leafs",
      "city": "Toronto",
      "conference": "Eastern",
      "division": "Atlantic",
      "arena": "Scotiabank Arena"
    },
    {
      "abbrev": "FLA",
      "name": "Panthers",
      "city": "Florida",
      "conference": "Eastern",
      "division": "Atlantic",
      "arena": "Amerant Bank Arena"
    }
  ]
}

Response fields

Field	Type	Description
teams[].abbrev	string	3-letter team code (e.g. "BUF")
teams[].name	string	Team name (e.g. "Sabres")
teams[].city	string	City name
teams[].conference	string	Eastern or Western
teams[].division	string	Division name
teams[].arena	string	Home arena name

Basic lookup

2 credits/call

POST

get_schedule

2 credits

Upcoming games for the next N days. Defaults to 7 days.

When to use: You want to know what games are coming up this week -- for a specific team or across the league. Useful for building game-day alerts or planning which games to watch.

Parameters

Name	Type	Required	Description
team	string	optional	Team abbreviation (e.g. "BUF")
days	integer	optional	Days ahead (1-30, default 7)

Example request

{
  "tool": "get_schedule",
  "arguments": {
    "team": "BUF",
    "days": 7
  }
}

Example response

json

{
  "games": [
    {
      "id": "2025021143",
      "gameDate": "2026-04-10",
      "startTime": "19:00:00",
      "homeTeam": "BUF",
      "awayTeam": "TOR",
      "homeTeamName": "Buffalo Sabres",
      "awayTeamName": "Toronto Maple Leafs",
      "venue": "KeyBank Center",
      "gameType": "regular"
    },
    {
      "id": "2025021187",
      "gameDate": "2026-04-12",
      "startTime": "19:30:00",
      "homeTeam": "FLA",
      "awayTeam": "BUF",
      "homeTeamName": "Florida Panthers",
      "awayTeamName": "Buffalo Sabres",
      "venue": "Amerant Bank Arena",
      "gameType": "regular"
    }
  ]
}

Response fields

Field	Type	Description
games[].id	string	Unique game ID
games[].gameDate	string	Date (YYYY-MM-DD)
games[].startTime	string	Start time (HH:MM:SS)
games[].homeTeam	string	Home team abbreviation
games[].awayTeam	string	Away team abbreviation
games[].homeTeamName	string	Home team full name
games[].awayTeamName	string	Away team full name
games[].venue	string	Arena name
games[].gameType	string	regular, playoff, or preseason

POST

search_players

2 credits

Find players by name, team, or position.

When to use: You need a player's ID to look up their stats, or you want to search a roster by position. For example, "find all active centers on the Sabres" or "look up Tage Thompson's player ID."

Parameters

Name	Type	Required	Description
query	string	required	Search string (e.g. "Tage Thompson")
team	string	optional	Filter by team abbreviation
position	string	optional	G, D, C, LW, or RW
active	boolean	optional	Active players only (default true)
limit	integer	optional	Max results (1-50, default 10)

Example request

{
  "tool": "search_players",
  "arguments": {
    "query": "Thompson",
    "team": "BUF"
  }
}

Example response

json

{
  "players": [
    {
      "id": 8480208,
      "name": "Tage Thompson",
      "team": "BUF",
      "teamName": "Buffalo Sabres",
      "position": "C",
      "jerseyNumber": 72,
      "active": true
    }
  ]
}

Response fields

Field	Type	Description
players[].id	integer	Player ID (use in get_player_stats)
players[].name	string	Full name
players[].firstName	string	First name
players[].lastName	string	Last name
players[].team	string	Team abbreviation
players[].teamName	string	Full team name
players[].position	string	Position code
players[].positionType	string	Position type (F, D, or G)
players[].jerseyNumber	integer	Jersey number
players[].birthCountry	string	Birth country
players[].active	boolean	Currently active

POST

get_standings

2 credits

Current standings with points, point pace, goal differential and goals for/against per game.

When to use: You want to see how teams rank in the league right now -- points, win percentage, goal differential, and goals for and against per game. The possession columns (Corsi, Fenwick, expected goals) are in the response but are not yet computed and come back null.

Parameters

Name	Type	Required	Description
conference	string	optional	"Eastern" or "Western"
division	string	optional	Division name (e.g. "Atlantic")
season	string	optional	Season (e.g. "20252026", default current)

Example request

{
  "tool": "get_standings",
  "arguments": {
    "conference": "Eastern",
    "division": "Atlantic"
  }
}

Example response

json

{
  "standings": [
    {
      "rank": 1,
      "teamAbbrev": "FLA",
      "teamName": "Florida Panthers",
      "points": 112,
      "gamesPlayed": 80,
      "wins": 52,
      "losses": 20,
      "otLosses": 8,
      "pointPct": 0.683,
      "goalDiff": 48,
      "goalsForPerGame": 3.54,
      "goalsAgainstPerGame": 2.94,
      "corsiPct": null,
      "fenwickPct": null,
      "expectedGoalsFor": null,
      "expectedGoalsAgainst": null
    },
    {
      "rank": 2,
      "teamAbbrev": "TOR",
      "teamName": "Toronto Maple Leafs",
      "points": 106,
      "gamesPlayed": 80,
      "wins": 49,
      "losses": 23,
      "otLosses": 8,
      "pointPct": 0.65,
      "goalDiff": 31,
      "goalsForPerGame": 3.41,
      "goalsAgainstPerGame": 3.02,
      "corsiPct": null,
      "fenwickPct": null,
      "expectedGoalsFor": null,
      "expectedGoalsAgainst": null
    }
  ]
}

Response fields

Field	Type	Description
standings[].rank	integer	League or division rank
standings[].teamAbbrev	string	Team abbreviation
standings[].teamName	string	Full team name
standings[].points	integer	Total points
standings[].gamesPlayed	integer	Games played
standings[].wins	integer	Wins
standings[].losses	integer	Losses
standings[].otLosses	integer	Overtime losses
standings[].pointPct	number	Points percentage
standings[].goalDiff	integer	Goal differential
standings[].goalsForPerGame	number	Goals for per game
standings[].goalsAgainstPerGame	number	Goals against per game
standings[].corsiPct	number\|null	Corsi percentage (5v5 shot attempts). Not yet computed -- always null.
standings[].fenwickPct	number\|null	Fenwick percentage (unblocked shots). Not yet computed -- always null.
standings[].expectedGoalsFor	number	Expected goals for
standings[].expectedGoalsAgainst	number	Expected goals against

Stats + aggregation

5 credits/call

POST

get_games

5 credits

Query games by date range, team, season, game state, or type.

When to use: You're building a dataset for analysis -- pull all games from a date range, all playoff games for a team, or all final scores from last season. This is the workhorse endpoint for model training data.

Parameters

Name	Type	Required	Description
date_from	string	optional	Start date (YYYY-MM-DD)
date_to	string	optional	End date (YYYY-MM-DD)
team	string	optional	Team abbreviation
season	string	optional	Season (e.g. "20252026")
game_state	string	optional	FUT, LIVE, FINAL, or OFF
game_type	string	optional	regular, playoff, or preseason
limit	integer	optional	Max results (1-500, default 100)

Example request

{
  "tool": "get_games",
  "arguments": {
    "team": "TOR",
    "date_from": "2026-03-01",
    "date_to": "2026-03-07",
    "game_state": "FINAL"
  }
}

Example response

json

{
  "games": [
    {
      "id": "2025020934",
      "season": "20252026",
      "gameDate": "2026-03-02",
      "startTime": "19:00:00",
      "homeTeam": "TOR",
      "awayTeam": "BOS",
      "homeScore": 4,
      "awayScore": 2,
      "gameState": "FINAL",
      "gameType": "regular",
      "venue": "Scotiabank Arena"
    },
    {
      "id": "2025020958",
      "season": "20252026",
      "gameDate": "2026-03-05",
      "startTime": "19:30:00",
      "homeTeam": "MTL",
      "awayTeam": "TOR",
      "homeScore": 1,
      "awayScore": 3,
      "gameState": "FINAL",
      "gameType": "regular",
      "venue": "Bell Centre"
    }
  ]
}

Response fields

Field	Type	Description
games[].id	string	Unique game ID
games[].season	string	Season code (e.g. "20252026")
games[].gameDate	string	Date (YYYY-MM-DD)
games[].startTime	string	Start time
games[].homeTeam	string	Home team abbreviation
games[].awayTeam	string	Away team abbreviation
games[].homeTeamName	string	Home team full name
games[].awayTeamName	string	Away team full name
games[].homeScore	integer	Home team score (FINAL only)
games[].awayScore	integer	Away team score (FINAL only)
games[].gameState	string	FUT, LIVE, FINAL, or OFF
games[].gameType	string	regular, playoff, or preseason
games[].venue	string	Arena name

POST

get_team_stats

5 credits

Detailed stats for a specific team including advanced metrics and league rankings.

When to use: You want a complete statistical profile of a team -- league rank, point pace, goal differential, and goals for and against. The Corsi, Fenwick and expected-goals columns are present but not yet computed.

Parameters

Name	Type	Required	Description
team	string	required	Team abbreviation (e.g. "BUF")
season	string	optional	Season (e.g. "20252026")

Example request

{
  "tool": "get_team_stats",
  "arguments": {
    "team": "BUF",
    "season": "20252026"
  }
}

Example response

json

{
  "team": {
    "abbrev": "BUF",
    "name": "Sabres",
    "fullName": "Buffalo Sabres",
    "city": "Buffalo",
    "conference": "Eastern",
    "division": "Atlantic",
    "arena": "KeyBank Center"
  },
  "current_stats": {
    "rank": 14,
    "gamesPlayed": 82,
    "wins": 44,
    "losses": 28,
    "otLosses": 10,
    "points": 98,
    "pointPct": 0.598,
    "goalDiff": 12,
    "goalsForPerGame": 3.27,
    "goalsAgainstPerGame": 3.12,
    "corsiPct": null,
    "fenwickPct": null,
    "expectedGoalsFor": null,
    "expectedGoalsAgainst": null
  },
  "season": "20252026"
}

Response fields

Field	Type	Description
team.abbrev	string	Team abbreviation
team.fullName	string	Full team name
team.conference	string	Conference
team.division	string	Division
current_stats.rank	integer	League rank
current_stats.gamesPlayed	integer	Games played
current_stats.wins	integer	Wins
current_stats.losses	integer	Losses
current_stats.points	integer	Total points
current_stats.pointPct	number	Points percentage
current_stats.goalDiff	integer	Goal differential
current_stats.goalsForPerGame	number	Goals for per game
current_stats.goalsAgainstPerGame	number	Goals against per game
current_stats.corsiPct	number\|null	Corsi percentage. Not yet computed -- always null.
current_stats.fenwickPct	number	Fenwick percentage
current_stats.expectedGoalsFor	number	Expected goals for
current_stats.expectedGoalsAgainst	number	Expected goals against

POST

get_player_stats

5 credits

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

When to use: You have a player ID (from search_players) and want their full profile -- bio, team, position, and for goalies, their complete stat line including GSAX and advanced metrics.

Parameters

Name	Type	Required	Description
player_id	integer	required	Player ID (from search_players)

Example request

{
  "tool": "get_player_stats",
  "arguments": {
    "player_id": 8480045
  }
}

Example response

json

{
  "player": {
    "id": 8480045,
    "name": "Ukko-Pekka Luukkonen",
    "team": "BUF",
    "teamName": "Buffalo Sabres",
    "position": "G",
    "jerseyNumber": 1,
    "birthDate": "1999-03-09",
    "birthCountry": "FIN",
    "heightInches": 77,
    "weightLbs": 220,
    "shootsCatches": "L"
  },
  "goalie_stats": {
    "gamesPlayed": 58,
    "gamesStarted": 55,
    "wins": 30,
    "losses": 20,
    "otLosses": 5,
    "savePct": 0.912,
    "gaa": 2.71,
    "gsax": null,
    "shutouts": 3,
    "highDangerSavePct": null,
    "rollingSavePct": null,
    "trend": null
  }
}

Response fields

Field	Type	Description
player.id	integer	Player ID
player.name	string	Full name
player.team	string	Team abbreviation
player.teamName	string	Full team name
player.position	string	Position code
player.jerseyNumber	integer	Jersey number
player.birthDate	string	Birth date
player.birthCountry	string	Birth country
player.heightInches	integer	Height in inches
player.weightLbs	integer	Weight in pounds
player.shootsCatches	string	Shoots/catches (L or R)
goalie_stats	object\|null	Goalie stats (null for skaters)
goalie_stats.savePct	number	Save percentage
goalie_stats.gaa	number	Goals against average
goalie_stats.gsax	number	Goals saved above expected

POST

get_goalie_stats

5 credits

Goalie leaderboard sorted by save%, GAA, GSAX, or wins.

When to use: You want to rank goalies across the league or within a team. GSAX (goals saved above expected) is the advanced metric that tells you who's actually good versus who plays behind a strong defense.

Parameters

Name	Type	Required	Description
team	string	optional	Filter by team abbreviation
season	string	optional	Season (e.g. "20252026")
min_games	integer	optional	Minimum games played (default 10)
sort_by	string	optional	save_pct, gaa, gsax, or wins
limit	integer	optional	Max results (1-50, default 20)

Example request

{
  "tool": "get_goalie_stats",
  "arguments": {
    "sort_by": "gsax",
    "limit": 3
  }
}

Example response

json

{
  "goalies": [
    {
      "playerId": 8479361,
      "playerName": "Connor Hellebuyck",
      "team": "WPG",
      "gamesPlayed": 64,
      "wins": 38,
      "losses": 18,
      "savePct": 0.924,
      "gaa": 2.31,
      "gsax": null,
      "shutouts": 5
    },
    {
      "playerId": 8477424,
      "playerName": "Sergei Bobrovsky",
      "team": "FLA",
      "gamesPlayed": 55,
      "wins": 34,
      "losses": 14,
      "savePct": 0.918,
      "gaa": 2.48,
      "gsax": null,
      "shutouts": 4
    },
    {
      "playerId": 8480045,
      "playerName": "Ukko-Pekka Luukkonen",
      "team": "BUF",
      "gamesPlayed": 58,
      "wins": 30,
      "losses": 20,
      "savePct": 0.912,
      "gaa": 2.71,
      "gsax": null,
      "shutouts": 3
    }
  ]
}

Response fields

Field	Type	Description
goalies[].playerId	integer	Player ID
goalies[].playerName	string	Goalie name
goalies[].team	string	Team abbreviation
goalies[].teamName	string	Full team name
goalies[].gamesPlayed	integer	Games played
goalies[].wins	integer	Wins
goalies[].losses	integer	Losses
goalies[].otLosses	integer	Overtime losses
goalies[].savePct	number	Save percentage
goalies[].gaa	number	Goals against average
goalies[].gsax	number	Goals saved above expected
goalies[].shutouts	integer	Shutouts
goalies[].highDangerSavePct	number	High-danger save percentage
goalies[].rollingSavePct	number	Rolling save percentage (recent trend)
goalies[].trend	string	Performance trend (hot, cold, stable)
goalies[].restDays	integer	Days since last start

POST

get_skater_season_stats

5 credits

Skater leaderboard sorted by points, goals, assists, plus/minus, or shots.

When to use: You want to rank skaters across the league or within a team, with special-teams production and usage alongside the counting stats. Use get_goalie_stats for goaltenders and get_player_stats for one player in depth.

Parameters

Name	Type	Required	Description
team	string	optional	Filter by team abbreviation
season	string	optional	Season (e.g. "20252026"). Defaults to current.
min_games	integer	optional	Minimum games played (default 10)
sort_by	string	optional	points, goals, assists, plus_minus, or shots (default points)
limit	integer	optional	Max results (1-50, default 20)

Example request

{
  "tool": "get_skater_season_stats",
  "arguments": {
    "season": "20242025",
    "sort_by": "points",
    "limit": 3
  }
}

Example response

json

{
  "skaters": [
    {
      "playerId": 8476453,
      "playerName": "Nikita Kucherov",
      "team": "TBL",
      "position": "RW",
      "gamesPlayed": 78,
      "goals": 37,
      "assists": 84,
      "points": 121,
      "plusMinus": 22,
      "shots": 265,
      "shootingPct": 0.1396,
      "avgToiPerGame": 1271
    }
  ],
  "count": 1
}

Response fields

Field	Type	Description
skaters[].playerId	integer	Player ID
skaters[].playerName	string	Skater name
skaters[].team	string	Team abbreviation
skaters[].teamName	string	Full team name
skaters[].position	string	Position (C, LW, RW, D)
skaters[].gamesPlayed	integer	Games played
skaters[].goals	integer	Goals
skaters[].assists	integer	Assists
skaters[].points	integer	Points
skaters[].plusMinus	integer	Plus/minus
skaters[].pim	integer	Penalty minutes
skaters[].powerPlayGoals	integer	Power play goals
skaters[].powerPlayPoints	integer	Power play points
skaters[].shorthandedGoals	integer	Shorthanded goals
skaters[].shorthandedPoints	integer	Shorthanded points
skaters[].gameWinningGoals	integer	Game-winning goals
skaters[].otGoals	integer	Overtime goals
skaters[].shots	integer	Shots on goal
skaters[].shootingPct	number	Shooting percentage, as a fraction
skaters[].faceoffPct	number	Faceoff win percentage, as a fraction
skaters[].avgToiPerGame	integer	Average time on ice per game, in SECONDS
skaters[].snapshotDate	string	Date the season snapshot was taken (YYYY-MM-DD)
count	integer	Number of skaters returned
filters	object	The filters applied, echoed back

Multi-table

10 credits/call

POST

get_odds

10 credits

Odds for a specific game with optional bookmaker and snapshot type filters.

When to use: You have a game ID and want the betting lines -- moneyline, spread, and total from specific bookmakers. Filter by opening or closing lines to see how the market priced the game.

Parameters

Name	Type	Required	Description
game_id	string	required	Game ID (e.g. "2025020887")
bookmaker	string	optional	Filter by bookmaker (e.g. "draftkings")
snapshot_type	string	optional	"opening" (game-day morning) or "closing" (final pre-game). Default returns both.

Example request

{
  "tool": "get_odds",
  "arguments": {
    "game_id": "2025020887",
    "bookmaker": "draftkings"
  }
}

Example response

json

{
  "game_id": "2025020887",
  "home_team": "BUF",
  "away_team": "TOR",
  "game_date": "2026-03-15",
  "odds": [
    {
      "bookmaker": "draftkings",
      "snapshotType": "opening",
      "mlHome": -115,
      "mlAway": -105,
      "mlHomeProb": 0.535,
      "mlAwayProb": 0.512,
      "spreadHome": -1.5,
      "spreadHomeOdds": 170,
      "spreadAway": 1.5,
      "spreadAwayOdds": -200,
      "total": 6,
      "totalOverOdds": -110,
      "totalUnderOdds": -110,
      "capturedAt": "2026-03-14T12:00:00Z"
    },
    {
      "bookmaker": "draftkings",
      "snapshotType": "closing",
      "mlHome": -125,
      "mlAway": 105,
      "mlHomeProb": 0.556,
      "mlAwayProb": 0.488,
      "spreadHome": -1.5,
      "spreadHomeOdds": 165,
      "spreadAway": 1.5,
      "spreadAwayOdds": -195,
      "total": 6.5,
      "totalOverOdds": -110,
      "totalUnderOdds": -110,
      "capturedAt": "2026-03-15T18:50:00Z"
    }
  ],
  "bookmaker_count": 1
}

Response fields

Field	Type	Description
game_id	string	Game ID
home_team	string	Home team abbreviation
away_team	string	Away team abbreviation
odds[].bookmaker	string	Bookmaker name
odds[].snapshotType	string	opening or closing
odds[].mlHome	integer	Home moneyline
odds[].mlAway	integer	Away moneyline
odds[].mlHomeProb	number	Implied home win probability
odds[].mlAwayProb	number	Implied away win probability
odds[].spreadHome	number	Home puck line
odds[].spreadHomeOdds	integer	Home spread price
odds[].spreadAway	number	Away puck line
odds[].spreadAwayOdds	integer	Away spread price
odds[].total	number	Over/under total
odds[].totalOverOdds	integer	Over price
odds[].totalUnderOdds	integer	Under price
odds[].capturedAt	string	Timestamp of snapshot
bookmaker_count	integer	Number of bookmakers returned

POST

get_game_detail

10 credits

Full game detail including odds snapshots and confirmed goalie starts.

When to use: You want everything about a single game in one call -- scores, odds from multiple bookmakers, and confirmed goalie starts. Saves you from making separate get_odds and search_players calls.

Parameters

Name	Type	Required	Description
game_id	string	required	Game ID (e.g. "2025020887")

Example request

{
  "tool": "get_game_detail",
  "arguments": {
    "game_id": "2025020887"
  }
}

Example response

json

{
  "game": {
    "id": "2025020887",
    "season": "20252026",
    "gameDate": "2026-03-15",
    "startTime": "19:00:00",
    "homeTeam": "BUF",
    "awayTeam": "TOR",
    "homeScore": 5,
    "awayScore": 3,
    "gameState": "FINAL",
    "gameType": "regular",
    "venue": "KeyBank Center"
  },
  "home_team": {
    "abbrev": "BUF",
    "fullName": "Buffalo Sabres",
    "conference": "Eastern",
    "division": "Atlantic",
    "arena": "KeyBank Center"
  },
  "away_team": {
    "abbrev": "TOR",
    "fullName": "Toronto Maple Leafs",
    "conference": "Eastern",
    "division": "Atlantic",
    "arena": "Scotiabank Arena"
  },
  "odds": [
    {
      "bookmaker": "draftkings",
      "snapshotType": "closing",
      "mlHome": -125,
      "mlAway": 105,
      "mlHomeProb": 0.556,
      "mlAwayProb": 0.488,
      "spreadHome": -1.5,
      "total": 6.5,
      "totalOverOdds": -110,
      "totalUnderOdds": -110
    },
    {
      "bookmaker": "fanduel",
      "snapshotType": "closing",
      "mlHome": -130,
      "mlAway": 110,
      "mlHomeProb": 0.565,
      "mlAwayProb": 0.476,
      "spreadHome": -1.5,
      "total": 6.5,
      "totalOverOdds": -108,
      "totalUnderOdds": -112
    }
  ],
  "goalie_starts": null
}

Response fields

Field	Type	Description
game.id	string	Game ID
game.gameDate	string	Date
game.homeScore	integer	Home team score
game.awayScore	integer	Away team score
game.gameState	string	FUT, LIVE, FINAL, or OFF
home_team.abbrev	string	Home team abbreviation
home_team.fullName	string	Full team name
away_team.abbrev	string	Away team abbreviation
away_team.fullName	string	Full team name
odds[]	array	Odds snapshots from all bookmakers
goalie_starts	object\|null	Confirmed goalie starts. The table backing this is empty, so it is null for every game today
goalie_starts.homeGoalieName	string	Home starting goalie
goalie_starts.awayGoalieName	string	Away starting goalie

POST

get_head_to_head

10 credits

Matchup history between two teams with win/loss records.

When to use: You're previewing a matchup and want to know the rivalry history -- who has the edge, recent results, and head-to-head record for a specific season or all-time.

Parameters

Name	Type	Required	Description
team1	string	required	First team abbreviation
team2	string	required	Second team abbreviation
season	string	optional	Filter to specific season
limit	integer	optional	Max games (1-100, default 20)

Example request

{
  "tool": "get_head_to_head",
  "arguments": {
    "team1": "BUF",
    "team2": "TOR",
    "season": "20252026"
  }
}

Example response

json

{
  "team1": "BUF",
  "team2": "TOR",
  "record": {
    "BUF": 2,
    "TOR": 1
  },
  "total_games": 3,
  "games": [
    {
      "id": "2025020412",
      "season": "20252026",
      "gameDate": "2025-12-14",
      "homeTeam": "TOR",
      "awayTeam": "BUF",
      "homeScore": 3,
      "awayScore": 4,
      "gameState": "FINAL",
      "venue": "Scotiabank Arena"
    },
    {
      "id": "2025020623",
      "season": "20252026",
      "gameDate": "2026-01-28",
      "homeTeam": "BUF",
      "awayTeam": "TOR",
      "homeScore": 2,
      "awayScore": 5,
      "gameState": "FINAL",
      "venue": "KeyBank Center"
    }
  ]
}

Response fields

Field	Type	Description
team1	string	First team abbreviation
team2	string	Second team abbreviation
record	object	Win counts keyed by team abbreviation
record.[TEAM]	integer	Wins for that team
total_games	integer	Total games in range
games[].id	string	Game ID
games[].gameDate	string	Date
games[].homeTeam	string	Home team abbreviation
games[].awayTeam	string	Away team abbreviation
games[].homeScore	integer	Home team score
games[].awayScore	integer	Away team score

POST

get_plays

10 credits

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

When to use: 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

Name	Type	Required	Description
game_id	string	optional	NHL game ID (e.g. 2025020887)
season	string	optional	Season ID, 8-digit (e.g. 20242025)
team	string	optional	Team abbreviation that owns the event
player_id	number	optional	NHL player ID; matches any role on the event
type	string	optional	goal, shot-on-goal, missed-shot, blocked-shot, faceoff, hit, giveaway, takeaway, penalty, stoppage, ...
strength	string	optional	Skater strength from the event owner's view: 5v5, 5v4, 4v5, ...
zone	string	optional	O offensive, N neutral, D defensive
period	number	optional	Period number (4+ is overtime)
shot_attempts_only	boolean	optional	Only goals, shots, misses and blocks (Corsi events)
limit	number	optional	Max events (default 200, max 1000)
offset	number	optional	Pagination offset

Example request

{
  "tool": "get_plays",
  "arguments": {
    "game_id": "2024020601",
    "type": "goal"
  }
}

Example 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

Field	Type	Description
plays[].type	string	Event type, the NHL's own key
plays[].team	string	Abbreviation of the team that owns the event
plays[].strength	string	Skater count from the owner's view, e.g. 5v4
plays[].x_coord	number	Rink x, -100..100 along the length
plays[].y_coord	number	Rink y, -42..42 across
plays[].zone	string	O, N or D
plays[].seconds_elapsed	number	Seconds from the opening faceoff, continuous across periods
plays[].scoring_player_id	number	Scorer on a goal; see also shooting_player_id, winning_player_id, hitting_player_id
summary.by_type	object	Counts per event type, for this page of results only
next_offset	number	Offset for the next page, or null when the page is the last

POST

get_shot_map

10 credits

Every shot attempt with rink coordinates, shot type, shooter and goalie.

When to use: You want to plot or model shot locations rather than read a list of events -- a shooter's season heat map, a team's attempts by zone, or the input to an expected-goals model. Filter by game, by player, or by season plus team.

Parameters

Name	Type	Required	Description
game_id	string	optional	NHL game ID
season	string	optional	Season ID, 8-digit; use with team
team	string	optional	Team abbreviation; use with season
player_id	number	optional	NHL player ID of the shooter
strength	string	optional	Strength filter, e.g. 5v5

Example request

{
  "tool": "get_shot_map",
  "arguments": {
    "game_id": "2024020601"
  }
}

Example response

json

{
  "shots": [
    {
      "type": "shot-on-goal",
      "x_coord": 62,
      "y_coord": -9,
      "shot_type": "wrist",
      "strength": "5v5",
      "team": "PIT",
      "shooter": 8471675,
      "goalie": 8480045,
      "game_id": "2024020601",
      "period": 1,
      "seconds_elapsed": 143
    }
  ],
  "summary": {
    "returned": 114,
    "capped_at": 2000,
    "by_type": {
      "shot-on-goal": 55,
      "missed-shot": 29,
      "blocked-shot": 20,
      "goal": 10
    }
  },
  "count": 114
}

Response fields

Field	Type	Description
shots[].x_coord	number	Rink x, -100..100
shots[].y_coord	number	Rink y, -42..42
shots[].type	string	goal, shot-on-goal, missed-shot or blocked-shot
shots[].shot_type	string	wrist, snap, slap, tip-in, backhand, deflected, wrap-around
shots[].shooter	number	Shooter's NHL player ID
shots[].goalie	number	Goalie in net at the time
summary.capped_at	number	Hard cap of 2,000 shots per call

Time-series

25 credits/call

POST

get_line_movement

25 credits

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

When to use: You're analyzing sharp money or building a betting model and need to see how odds changed over time. Opening vs. closing line differences reveal where the market moved, which is the strongest signal in sports betting.

Parameters

Name	Type	Required	Description
game_id	string	required	Game ID (e.g. "2025020887")
bookmaker	string	optional	Filter to one bookmaker

Example request

{
  "tool": "get_line_movement",
  "arguments": {
    "game_id": "2025020887",
    "bookmaker": "draftkings"
  }
}

Example response

json

{
  "game_id": "2025020887",
  "home_team": "BUF",
  "away_team": "TOR",
  "movement": {
    "draftkings": [
      {
        "bookmaker": "draftkings",
        "snapshotType": "opening",
        "mlHome": -115,
        "mlAway": -105,
        "spreadHome": -1.5,
        "total": 6,
        "capturedAt": "2026-03-15T12:00:00Z"
      },
      {
        "bookmaker": "draftkings",
        "snapshotType": "closing",
        "mlHome": -125,
        "mlAway": 105,
        "spreadHome": -1.5,
        "total": 6.5,
        "capturedAt": "2026-03-15T23:00:00Z"
      }
    ]
  }
}

Response fields

Field	Type	Description
game_id	string	Game ID
home_team	string	Home team abbreviation
away_team	string	Away team abbreviation
movement[book][]	array	Chronological snapshots per bookmaker
movement[book][].snapshotType	string	opening or closing
movement[book][].mlHome	integer	Home moneyline at this snapshot
movement[book][].mlAway	integer	Away moneyline at this snapshot
movement[book][].spreadHome	number	Home puck line
movement[book][].total	number	Over/under total
movement[book][].capturedAt	string	Timestamp

Ready to start?

500 free credits on signup. No credit card required.

Get a free key