# PuckAPI

> The hockey data API. 15 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
Tool catalogue with JSON Schema: https://mcp.puckapi.com/v1/tools

## 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`
- 500 free credits on signup, 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.

## 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 goals for/against per game. -> get_standings (2 cr)

### Stats + aggregation
- Query games by date range, team, season, game state, or type. -> get_games (5 cr)
- Detailed stats for a specific team including advanced metrics and league rankings. -> 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. -> get_goalie_stats (5 cr)
- Skater leaderboard sorted by points, goals, assists, plus/minus, or shots. -> get_skater_season_stats (5 cr)

### Multi-table
- Odds for a specific game with optional bookmaker and snapshot type filters. -> get_odds (10 cr)
- Full game detail including odds snapshots and confirmed goalie starts. -> 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)

### 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 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 to rank skaters by points, goals or shots" -> get_skater_season_stats
- "I want betting odds for a game" -> get_odds
- "I want everything about a single 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 to see how betting lines moved over time" -> get_line_movement

## Links

- Docs: https://puckapi.com/docs
- Pricing: https://puckapi.com/pricing
- Sign up: https://puckapi.com/signup