# PuckAPI > The hockey data API. 22 hockey data tools for AI agents. REST API + MCP server. Full reference with response shapes: https://puckapi.com/llms-full.txt MCP server setup: https://puckapi.com/llms-install.md MCP server for AI agents (clients, prompts, every tool): https://puckapi.com/mcp Datasets with live coverage by season: https://puckapi.com/docs/atlas Tool catalogue with JSON Schema: https://mcp.puckapi.com/v1/tools OpenAPI 3.1 spec: https://mcp.puckapi.com/openapi.json ## Quick Start - API base URL: https://mcp.puckapi.com - Auth: `Authorization: Bearer YOUR_API_KEY` or `x-api-key: YOUR_API_KEY` - MCP server: `https://mcp.puckapi.com/mcp?key=YOUR_API_KEY` - Python client: `pip install puckapi` (https://pypi.org/project/puckapi/). Reads PUCKAPI_API_KEY. - 500 free credits every month, no credit card required - REST API responses include `X-Credits-Used` and `X-Credits-Remaining` headers - Seasons: 8-digit season id, start year + end year (2024-25 and 2024-2025 also accepted). Team codes like BUF, TOR, NYR, EDM. Game ids like 2025020887. ## Data timing and rights - Odds and props are pre-game only. captured_at is when a line was captured (the page says exactly what it means for each kind of row); where props are held, rows also carry scheduled_start and minutes_before_scheduled_start (negative when captured after the scheduled start). - Records are overwritten when sources correct them; no revision history is kept. - You may store the data, train models, backtest, and build commercial products that show your users what you derive. You may not redistribute the data, or odds as a raw feed, as a dataset or API of its own. After an account closes, stored data is for internal use only. - PuckAPI is independent, not an official league partner, and grants no league rights. - Full answers: https://puckapi.com/docs/timing-and-rights ## Which Tool Should I Use? ### Static reference - All 32 active NHL teams with divisions, conferences, and arenas. -> list_teams (1 cr) ### Basic lookup - Upcoming games for the next N days. Defaults to 7 days. -> get_schedule (2 cr) - Find players by name, team, or position. -> search_players (2 cr) - Current standings with points, point pace, goal differential, and 5v5 possession: Corsi%, Fenwick% and expected goals. -> get_standings (2 cr) ### Stats + aggregation - Query games by date range, team, season, game state, or type. -> get_games (5 cr) - The model's win probability and A/B/C grade for each NHL game on the current slate, with the model version and a backtest note. -> get_predictions (5 cr) - One team's record, league rank, and 5v5 possession: Corsi%, Fenwick% and expected goals for and against. -> get_team_stats (5 cr) - Player bio and goalie stats (if goalie). For skaters, returns bio info and team context. -> get_player_stats (5 cr) - Goalie leaderboard sorted by save%, GAA, GSAX or wins, with high-danger save%, recent form and rest days. -> get_goalie_stats (5 cr) - Skater leaderboard sorted by points, goals, assists, plus/minus, or shots. -> get_skater_season_stats (5 cr) - A player's game-by-game stat lines for a season: date, opponent, home/away, and the box score for each game. -> get_player_game_log (5 cr) ### Model projections - Paid plans only. The model's projected goals, assists, points and shots for each skater and saves for each goalie in tonight's NHL games, with a low-to-high range and over probabilities. -> get_prop_projections (25 cr) ### Multi-table - Odds for one game, or a whole season of closing lines in one call, billed per game returned (estimate_only prices it first), with bookmaker and snapshot filters. -> get_odds (10 cr) - Full game detail including odds snapshots and the goalies who started, with time on ice. -> get_game_detail (10 cr) - Matchup history between two teams with win/loss records. -> get_head_to_head (10 cr) - Play-by-play events with rink coordinates, strength state, and the players involved. -> get_plays (10 cr) - Every shot attempt with rink coordinates, shot type, shooter and goalie. -> get_shot_map (10 cr) - Every player's shifts in one NHL game, to the second, with the official boxscore time on ice and plus/minus. -> get_shifts (10 cr) - Exact seconds each team spent at 5v5, 5v4, 4v5, 6v5 and every other on-ice state in an NHL game, from the shift charts, with a completeness check. -> get_situation_time (10 cr) - Player prop lines by sportsbook, the closing line and the opening line where held: points, goals, assists, shots on goal, blocked shots, goalie saves and anytime goal scorer. -> get_player_props (10 cr) - A player's prop lines against the result, game by game, with the over rate. -> get_prop_history (10 cr) ### Time-series - Time-series odds snapshots grouped by bookmaker. Shows how lines moved from open to close. -> get_line_movement (25 cr) ## Intents - "I want a list of all NHL teams" -> list_teams - "I want to see upcoming games this week" -> get_schedule - "I want to look up a player by name" -> search_players - "I want to see how teams rank in the league" -> get_standings - "I want to know which teams control play (Corsi, Fenwick, expected goals)" -> get_standings - "I want historical game results for model training" -> get_games - "I want a full stat profile for a team" -> get_team_stats - "I want bio info for a player (and goalie stats if goalie)" -> get_player_stats - "I want to rank goalies by advanced stats" -> get_goalie_stats - "I want the goalies who saved the most goals above expected" -> get_goalie_stats - "I want to know which goalie is in form right now" -> get_goalie_stats - "I want to rank skaters by points, goals or shots" -> get_skater_season_stats - "I want a player's game-by-game stat lines for a season" -> get_player_game_log - "I want the model's win probability for each game tonight" -> get_predictions - "I want the model's projected stat lines for tonight's players (paid plans only)" -> get_prop_projections - "I want betting odds for a game" -> get_odds - "I want everything about a single game" -> get_game_detail - "I want to know which goalies started a game" -> get_game_detail - "I want rivalry history between two teams" -> get_head_to_head - "I want every shot in a game with its location" -> get_shot_map - "I want the play-by-play for a game or a player" -> get_plays - "I want every player's shifts in a game" -> get_shifts - "I want exact 5v5, power-play and shorthanded time for each team" -> get_situation_time - "I want to see how betting lines moved over time" -> get_line_movement - "I want the closing shots-on-goal or points line for a player, and which book had the best price" -> get_player_props - "I want to know how often a player goes over his prop line" -> get_prop_history ## Pages - [Docs](https://puckapi.com/docs): every endpoint, with parameters and a live example response. - [Data changelog](https://puckapi.com/changelog): when each dataset was last refreshed and what it runs through, read from the database. - [Status](https://puckapi.com/status): measured uptime for the website and MCP server over 24 hours, 7 days and 90 days, probed every five minutes from outside our own infrastructure, with incidents and data freshness. - [Data atlas](https://puckapi.com/docs/atlas): what exists, which endpoints expose it, and where coverage is partial. - [Teams](https://puckapi.com/teams): a page per club with its record, season figures and recent games. - [Players](https://puckapi.com/players): a page per NHL player with prop history: the over/under record against the closing line in each market (points, goals, assists, shots on goal, saves and more) and the last games. - [Data timing and rights](https://puckapi.com/docs/timing-and-rights): what timestamps mean, when each dataset updates, whether lines are pre-game, and what the terms allow. - [Pricing](https://puckapi.com/pricing): credits per call and what a plan includes. - [Sign up](https://puckapi.com/signup): 500 free credits every month, no card. ### Live odds - [NHL odds tonight](https://puckapi.com/odds): The next NHL slate's moneylines, puck lines and totals from tracked sportsbooks, refreshed hourly. - [NHL player props today](https://puckapi.com/props): Tonight's NHL player props: points, goals, assists, shots on goal, saves and anytime goal scorer, with the consensus line and the best over and under price across sportsbooks. ### Other leagues - [Every PWHL game, as an API.](https://puckapi.com/pwhl): Every PWHL game since 2024 as an API: results, standings, skater and goalie lines, and play-by-play with shot locations. REST and MCP, same key as the NHL data. MCP: https://mcp.puckapi.com/mcp/pwhl - [OHL data, as an API.](https://puckapi.com/ohl): Ontario Hockey League games since 2014-15 as an API: results, standings, skater and goalie lines, and play-by-play with shot locations from 2015-16. REST and MCP, same key as the NHL data. MCP: https://mcp.puckapi.com/mcp/ohl - [WHL data, as an API.](https://puckapi.com/whl): Western Hockey League games since 2014-15 as an API: results, standings, skater and goalie lines, and every goal and penalty. REST and MCP, same key as the NHL data. MCP: https://mcp.puckapi.com/mcp/whl - [QMJHL data, as an API.](https://puckapi.com/qmjhl): QMJHL games since 2014-15 as an API: results, standings, skater and goalie lines, and play-by-play with shot locations. REST and MCP, same key as the NHL data. MCP: https://mcp.puckapi.com/mcp/qmjhl - [ECHL data, as an API.](https://puckapi.com/echl): ECHL games since 2014-15 as an API: results, standings, skater and goalie lines, and play-by-play with shot locations. REST and MCP, same key as the NHL data. MCP: https://mcp.puckapi.com/mcp/echl - [AHL data, as an API.](https://puckapi.com/ahl): AHL games since 2004-05 as an API: results, standings, skater and goalie lines, and play-by-play with shot locations from 2017-18. REST and MCP, same key as the NHL data. MCP: https://mcp.puckapi.com/mcp/ahl - [USHL data, as an API.](https://puckapi.com/ushl): USHL games since 2002-03 as an API: results, standings, skater and goalie lines, and every goal and penalty. REST and MCP, same key as the NHL data. MCP: https://mcp.puckapi.com/mcp/ushl ### Datasets - [NHL historical odds and closing lines](https://puckapi.com/data/historical-odds): Moneyline, puck line and total for every NHL game since 2019-20, by sportsbook: 16 to 18 books a game to 2023-24, 8 since, 60+ on about 300 in 2025-26. REST or MCP. - [NHL play-by-play data](https://puckapi.com/data/play-by-play): Every NHL play-by-play event since 2010-11 with rink coordinates, strength state and the players involved. REST or MCP, 500 free credits every month. - [NHL expected goals: team xG, Corsi and goalie GSAX](https://puckapi.com/data/expected-goals): NHL expected goals since 2010-11: team 5-on-5 xGF and xGA with Corsi and Fenwick, and goalie GSAX, updated daily. REST or MCP, 500 free credits every month. - [NHL shot data with rink coordinates](https://puckapi.com/data/shot-data): Every NHL shot attempt since 2010-11 with rink coordinates, shot type, shooter and goalie, by game, team-season or player. REST or MCP, 500 free credits every month. - [NHL player props by sportsbook, from 2023](https://puckapi.com/data/player-props): NHL player prop lines by sportsbook since May 2023: the closing line, and the opening line where held, with each player's history against his line. REST or MCP. ### Compared with the alternatives - [The NHL API: free endpoints, community docs and PuckAPI](https://puckapi.com/compare/nhl-api): The NHL's api-web.nhle.com and api.nhle.com/stats are free but undocumented. Where each fits, what the community docs cover, and how PuckAPI differs. (checked 2026-10-14) - [PuckAPI vs SportsDataIO for NHL data](https://puckapi.com/compare/sportsdataio-alternative): SportsDataIO sells real-time NHL feeds with production pricing through sales. PuckAPI is self-serve NHL history, shot data and odds from $19/mo, with an MCP server. (checked 2026-10-07) - [PuckAPI vs Natural Stat Trick](https://puckapi.com/compare/natural-stat-trick-api): Natural Stat Trick is a stats site whose data subdomain allows rate-limited scraping with an approved key. PuckAPI is a JSON API and MCP server for NHL data. (checked 2026-10-07) - [PuckAPI vs the NHL's public web API](https://puckapi.com/compare/nhl-api-alternative): The NHL's web API is free but undocumented, with no published terms or rate limits and no odds. PuckAPI is documented, adds odds, xG and GSAX, and speaks MCP. (checked 2026-10-14) - [PuckAPI vs MoneyPuck's data](https://puckapi.com/compare/moneypuck-api): MoneyPuck publishes free CSV downloads and asks anyone scraping it to arrange a data license. PuckAPI is a queryable API with odds and an MCP server. (checked 2026-09-26) ### Endpoint pages - [list_teams](https://puckapi.com/docs/list-teams): All 32 active NHL teams with divisions, conferences, and arenas. - [get_schedule](https://puckapi.com/docs/get-schedule): Upcoming games for the next N days. Defaults to 7 days. - [search_players](https://puckapi.com/docs/search-players): Find players by name, team, or position. - [get_standings](https://puckapi.com/docs/get-standings): Current standings with points, point pace, goal differential, and 5v5 possession: Corsi%, Fenwick% and expected goals. - [get_games](https://puckapi.com/docs/get-games): Query games by date range, team, season, game state, or type. - [get_predictions](https://puckapi.com/docs/get-predictions): The model's win probability and A/B/C grade for each NHL game on the current slate, with the model version and a backtest note. - [get_prop_projections](https://puckapi.com/docs/get-prop-projections): Paid plans only. The model's projected goals, assists, points and shots for each skater and saves for each goalie in tonight's NHL games, with a low-to-high range and over probabilities. - [get_team_stats](https://puckapi.com/docs/get-team-stats): One team's record, league rank, and 5v5 possession: Corsi%, Fenwick% and expected goals for and against. - [get_player_stats](https://puckapi.com/docs/get-player-stats): Player bio and goalie stats (if goalie). For skaters, returns bio info and team context. - [get_goalie_stats](https://puckapi.com/docs/get-goalie-stats): Goalie leaderboard sorted by save%, GAA, GSAX or wins, with high-danger save%, recent form and rest days. - [get_skater_season_stats](https://puckapi.com/docs/get-skater-season-stats): Skater leaderboard sorted by points, goals, assists, plus/minus, or shots. - [get_player_game_log](https://puckapi.com/docs/get-player-game-log): A player's game-by-game stat lines for a season: date, opponent, home/away, and the box score for each game. - [get_odds](https://puckapi.com/docs/get-odds): Odds for one game, or a whole season of closing lines in one call, billed per game returned (estimate_only prices it first), with bookmaker and snapshot filters. - [get_game_detail](https://puckapi.com/docs/get-game-detail): Full game detail including odds snapshots and the goalies who started, with time on ice. - [get_head_to_head](https://puckapi.com/docs/get-head-to-head): Matchup history between two teams with win/loss records. - [get_plays](https://puckapi.com/docs/get-plays): Play-by-play events with rink coordinates, strength state, and the players involved. - [get_shot_map](https://puckapi.com/docs/get-shot-map): Every shot attempt with rink coordinates, shot type, shooter and goalie. - [get_shifts](https://puckapi.com/docs/get-shifts): Every player's shifts in one NHL game, to the second, with the official boxscore time on ice and plus/minus. - [get_situation_time](https://puckapi.com/docs/get-situation-time): Exact seconds each team spent at 5v5, 5v4, 4v5, 6v5 and every other on-ice state in an NHL game, from the shift charts, with a completeness check. - [get_line_movement](https://puckapi.com/docs/get-line-movement): Time-series odds snapshots grouped by bookmaker. Shows how lines moved from open to close. - [get_player_props](https://puckapi.com/docs/get-player-props): Player prop lines by sportsbook, the closing line and the opening line where held: points, goals, assists, shots on goal, blocked shots, goalie saves and anytime goal scorer. - [get_prop_history](https://puckapi.com/docs/get-prop-history): A player's prop lines against the result, game by game, with the over rate. ### Metric definitions - [Corsi%](https://puckapi.com/glossary/corsi): A team's share of all shot attempts while it is on the ice: the oldest and bluntest measure of who is controlling play. - [Fenwick%](https://puckapi.com/glossary/fenwick): Corsi with blocked shots removed: a slightly cleaner read on possession, and a better predictor of goals. - [Expected goals (xG)](https://puckapi.com/glossary/expected-goals): The sum of every shot's probability of becoming a goal, given where and how it was taken. - [GSAX](https://puckapi.com/glossary/gsax): Expected goals against minus goals actually allowed: how many goals a goalie saved that an average goalie would not have. - [High-danger chances (HDCF)](https://puckapi.com/glossary/high-danger): Shots from the slot: how teams count them (HDCF, HDCA) and how goalies stop them (HDSV%). About a quarter of all shots, and the ones that decide games. - [Save percentage](https://puckapi.com/glossary/save-percentage): Shots stopped as a share of shots faced. The oldest goalie stat, and the one most distorted by the team in front. - [PDO](https://puckapi.com/glossary/pdo): Shooting percentage plus save percentage. It regresses hard toward 100, which is the entire point of looking at it. - [Goals against average](https://puckapi.com/glossary/goals-against-average): Goals allowed per sixty minutes of play. The oldest goalie stat, and the one that tells you most about the team in front. - [Strength state](https://puckapi.com/glossary/strength-state): How many skaters each side has on the ice. Almost every number worth reading is filtered to one of these. - [Rink coordinates](https://puckapi.com/glossary/rink-coordinates): Where on the ice a play happened, in feet, already turned so every team attacks the same end. - [Plus/minus](https://puckapi.com/glossary/plus-minus): Goals for minus goals against while a skater was on the ice, at even strength and shorthanded. - [Shooting percentage](https://puckapi.com/glossary/shooting-percentage): Goals as a share of shots on goal. Half of PDO, and the half that regresses hardest. - [Point percentage](https://puckapi.com/glossary/point-percentage): Points won as a share of points available. The only fair way to compare teams that have played a different number of games. ### By what you are building - [Analysts and researchers](https://puckapi.com/for/analysts): Play-by-play with coordinates for every NHL game since 2010-11, queryable without building a scraper first. - [Bettors and modellers](https://puckapi.com/for/bettors): Moneyline, puck line and totals for every game from 2019-20, about 16 to 18 books a game from 2020-21 to 2023-24, eight a game since (Pinnacle included), all eight fetched hourly from October 2026, alongside the shot data to model against them. - [Developers](https://puckapi.com/for/developers): REST for code, MCP for Claude and Cursor: the same tools, the same credits, no scraping and no schema archaeology. - [Fantasy players](https://puckapi.com/for/fantasy): Skater and goalie form, rest days, matchup history and who is actually starting in net. ### Code guides Python, JavaScript and cURL for common questions, each run against the live API (code verified 2026-10-21). Index: https://puckapi.com/guides - [How do I get an NHL goalie's save percentage by game in Python?](https://puckapi.com/guides/nhl-goalie-save-percentage-by-game-python): A goalie's game log for a season with shots against, saves, goals against and the decision, ready for a rolling save percentage. Tool: get_player_game_log. - [How do I rank NHL goalies by goals saved above expected?](https://puckapi.com/guides/nhl-goalie-leaderboard-gsax-python): A goalie leaderboard for a season sorted by goals saved above expected, with save percentage, GAA, high-danger save percentage and a recent-form trend. Tool: get_goalie_stats. - [How do I get NHL play-by-play data in Python?](https://puckapi.com/guides/nhl-play-by-play-python): Every event in a game in order, with rink coordinates, strength state, zone and the players involved, loaded into pandas. Tool: get_plays. - [How do I get NHL shot locations for a shot map in Python?](https://puckapi.com/guides/nhl-shot-map-rink-coordinates-python): Every shot attempt in a game with rink x and y, shot type, strength, shooter and goalie, and a distance to the net computed in pandas. Tool: get_shot_map. - [How do I get NHL opening and closing odds by sportsbook in Python?](https://puckapi.com/guides/nhl-opening-and-closing-odds-python): Every sportsbook's opening and closing moneyline and puck line for a game, so you can measure how far the price moved. Tool: get_odds. - [How do I compare NHL player prop lines across sportsbooks?](https://puckapi.com/guides/nhl-player-prop-lines-by-sportsbook-python): Every sportsbook's line and over and under price on shots on goal for one game, so you can find the books that disagree and the best price on each side. Tool: get_player_props. - [How do I see how an NHL line moved from open to close?](https://puckapi.com/guides/nhl-line-movement-open-to-close-python): Each sportsbook's snapshots of a game's moneyline, puck line and total in time order, so you can measure how far the price moved and which books moved first. Tool: get_line_movement. - [How do I get today's NHL schedule and scores in Python?](https://puckapi.com/guides/nhl-scores-and-schedule-python): Every NHL game on a date with teams, score, venue and game state, loaded into pandas. October 10 had 14 games and 5.36 goals per game. Tool: get_games. - [How do I get NHL standings in Python?](https://puckapi.com/guides/nhl-standings-python): The NHL table for the current season: record, points, goal differential and 5v5 possession for all 32 teams, grouped by division in pandas. Tool: get_standings. - [How do I get NHL player stats and top scorers in Python?](https://puckapi.com/guides/nhl-top-scorers-python): The top 15 NHL skaters of 2025-26 by points, with goals, assists, shooting percentage and ice time. Connor McDavid led with 138 points in 82 games. Tool: get_skater_season_stats. - [How often does an NHL player go over his shots on goal line?](https://puckapi.com/guides/nhl-shots-on-goal-prop-history-python): One row per game with a player's shots on goal line, the price, how many shots he took and whether he went over. Auston Matthews went over in 27 of 49. Tool: get_prop_history. - [How often does an NHL star go over his points line?](https://puckapi.com/guides/nhl-points-prop-history-python): One row per game with a player's points line, the price, his points and whether he went over. Connor McDavid's line was 1.5 all season and he went over in 43 of 83. Tool: get_prop_history. - [How often does an NHL goalie go over his saves line?](https://puckapi.com/guides/nhl-goalie-saves-prop-history-python): One row per start with a goalie's saves line, the price, his saves and whether he went over. Connor Hellebuyck went over in 21 of 39 lined starts last season. Tool: get_prop_history. - [How often does an NHL player score when he is priced to?](https://puckapi.com/guides/nhl-anytime-goal-scorer-prop-history-python): One row per game with a player's anytime goal price, his goals and whether he scored, to set the odds beside what happened. Auston Matthews scored in 23 of 60. Tool: get_prop_history. - [How often does an NHL player go over his assists line?](https://puckapi.com/guides/nhl-assists-prop-history-python): One row per game with a player's assists line, the price, his assists and whether he went over. Nathan MacKinnon went over in 43 of 80 graded games. Tool: get_prop_history. ### Claude skills 28 free Claude skills (SKILL.md files) wired to these tools: https://github.com/PuckAPI/claude-sports-analytics/tree/main/skills. Overview: https://puckapi.com/skills - game-lookup (Data Exploration): Find games by date, team, season. Scores and schedule. - team-analysis (Data Exploration): Standings, stats, strength of schedule, rankings. - player-scouting (Data Exploration): Player search, stats, comparison, NHLe translation. - goalie-analysis (Data Exploration): GSAA, xSV%, high-danger save%, workload tracking. - odds-explorer (Data Exploration): Multi-book odds comparison, line movement detection. - nl-to-query (Data Exploration): Natural language to structured data queries. - game-preview (Data Exploration): Full game preview: matchup, goalie, trends, odds. - hockey-analytics (Hockey Analytics): Corsi, Fenwick, xG, PDO, RAPM, WAR definitions and context. - xg-model-building (Hockey Analytics): Build an expected goals model from play-by-play shot data. - feature-engineering (Methodology): Rolling windows, shift(1) leakage detection, feature catalogs. - walk-forward-validation (Methodology): Temporal cross-validation. Refuses k-fold on time series. - model-building (Methodology): LR to RF to XGBoost ladder. Hard-vote ensemble. - elo-engineering (Methodology): 5 Elo variants with NHL-tuned configs. - probability-calibration (Methodology): Platt scaling, isotonic regression, Brier score decomposition. - odds-analysis (Methodology): 4 devigging methods (power, multiplicative, Shin, worst-case). - data-pipeline (Methodology): GitHub Actions automation, SQLite schema, credit budgeting. - edge-detection (Betting): EV calculation, Kelly criterion sizing, CLV tracking. - backtesting (Betting): Walk-forward historical strategy simulation. - daily-card (Betting): Full slate analysis with edge rankings. Requires your model. - bet-tracker (Betting): Log predictions, track CLV, test statistical significance. - visualization (Betting): Calibration plots, edge charts, player cards, correlation matrices. - totals-modeling (Sport-Specific Models): Over/under prediction. Pace metrics, Poisson, under bias. - prop-modeling (Sport-Specific Models): Player prop projections. TOI-first architecture, SGP correlation. - war-gar-decomposition (Sport-Specific Models): RAPM ridge regression, component GAR, contract surplus. - playoff-simulation (Sport-Specific Models): Monte Carlo season and bracket simulation. - ai-hockey-workflow (Workflow): 4 workflow patterns for hypothesis testing with Claude. - dispatch (Workflow): Routes requests to the right 2-3 skills automatically. - puckapi-tool (Infrastructure): Routes all MCP tool calls. 22 endpoints, credit tracking, BYOD support.