---
name: icehockeyapi
description: Ice hockey data from Ice Hockey API (icehockeyapi.com): leagues, seasons, teams, games with scores, goals, standings, players and odds, worldwide and back to the earliest recorded seasons. Use when an agent needs hockey results, fixtures, tables, box scores, player careers or prices.
---

# Ice Hockey API

Ice hockey data over a REST API and an MCP server: over a thousand leagues and competitions worldwide, with results back to the earliest recorded seasons, box scores for the top leagues that publish them, standings built from the results, players, venues and closing odds.

## When to use it

- Use it for: scores and results, fixtures, league tables, playoff series, head-to-head records, goals and scorers, line-ups, skater and goalie stats, player careers, and opening and closing odds for past games.
- Not for: live in-play odds, injuries or transactions, or anything outside ice hockey.

## Getting access

- Base URL: `https://api.icehockeyapi.com/v1`
- Every call needs a key. Send it as `Authorization: Bearer <key>` or `X-API-Key: <key>`, never in the address.
- A free key takes a minute at https://icehockeyapi.com/pricing and needs no card. It reads yesterday, today and games scheduled ahead, on the endpoints marked free.
- Paid plans: Live (current seasons, with odds), Archive (every past season, with odds) and Complete (both, with the highest limits).
- Ids carry their type: `lg_` league, `ss_` season, `tm_` team, `gm_` game, `pl_` player, `vn_` venue. Find an id with a list call first, then use it.

## The calls that answer the common questions

Games on a day (no filters gives today):

```bash
curl -H "Authorization: Bearer $KEY" "https://api.icehockeyapi.com/v1/games?date=2026-10-08"
```

```json
{"data": [{"id": "gm_...", "date": "2026-10-08", "start_time": "2026-10-08T15:30:00Z",
  "league": {"id": "lg_...", "name": "..."}, "season": {"id": "ss_...", "label": "2026-27"},
  "stage": "regular", "status": "final", "home_team": {"id": "tm_...", "name": "..."},
  "away_team": {"id": "tm_...", "name": "..."}, "home_goals": 3, "away_goals": 2,
  "ended_in": "overtime", "venue": {"id": "vn_...", "name": "...", "city": "...", "country": "..."},
  "attendance": 4200}],
 "meta": {"count": 1, "next_cursor": null, "plan": "Free key"}}
```

Filters on `/games`: `date`, `from`, `to`, `league_id`, `season_id`, `team_id`, `status` (scheduled, final, postponed, cancelled, awarded), `stage` (regular, playoffs, qualification, preseason, friendly, cup, other), `order` (asc or desc), `per_page` (up to 200) and `cursor`.

Yesterday's results, optionally for one league:

```bash
curl -H "Authorization: Bearer $KEY" "https://api.icehockeyapi.com/v1/results/yesterday?league_id=lg_..."
```

Find a league, then its seasons, then a table:

```bash
curl -H "Authorization: Bearer $KEY" "https://api.icehockeyapi.com/v1/leagues?q=..."
curl -H "Authorization: Bearer $KEY" "https://api.icehockeyapi.com/v1/leagues/lg_.../seasons"
curl -H "Authorization: Bearer $KEY" "https://api.icehockeyapi.com/v1/seasons/ss_.../standings"
```

Inside one game: `/games/{game_id}` (with odds on paid plans), `/periods`, `/goals`, `/penalties`, `/lineups`, `/skaters`, `/goalies`, `/team-stats`, `/events`, `/officials`, `/stars`, `/odds`.

Teams and players: `/teams`, `/teams/{team_id}/games`, `/teams/{team_id}/roster`, `/teams/{team_id}/head-to-head/{other_id}`, `/players`, `/players/{player_id}/seasons`, `/players/{player_id}/games`, `/draft/{year}`.

Your own plan and allowance (not counted): `/usage`. What the data holds (not counted): `/coverage`.

The full list, one page per endpoint: https://icehockeyapi.com/documentation

## MCP server

- URL: `https://icehockeyapi.com/mcp` (streamable HTTP), with the same key as `Authorization: Bearer <key>`.
- Tools: `find_games`, `get_game`, `game_odds`, `yesterdays_results`, `find_leagues`, `league_seasons`, `find_teams`, `get_standings`, `get_playoffs`, `season_leaders`, `head_to_head`, `game_scoring`, `find_players`, `player_career`, `my_usage`.

## Limits

- Free key: 10 calls a minute, 50 a day (resets 00:00 UTC); yesterday, today and scheduled games only; paid fields come back null.
- Live: 60 a minute, 100,000 a month. Archive: 60 a minute, 200,000 a month. Complete: 120 a minute, 500,000 a month. Monthly allowances reset on the 1st (UTC).
- Lists give 50 rows by default and up to 200 with `per_page`; follow `meta.next_cursor` for the next page.
- Box scores (goals, line-ups, player stats) exist for the leagues that publish them; most other leagues carry date, teams and score. Some very old games have a season but no day (`date` is null).
- All times are UTC.

## Errors

Every error has the same shape:

```json
{"error": {"code": "upgrade_required", "message": "...", "plan": "archive", "docs": "https://icehockeyapi.com/documentation/errors#upgrade_required"}}
```

- 400 `bad_request`: a parameter is missing or malformed (the message says which).
- 401 `unauthorized`: no key, or the key is not recognised.
- 403 `upgrade_required`: the data is on a higher plan; `plan` names the cheapest one that has it.
- 404 `not_found`: no such endpoint or record.
- 422 `unknown_parameter`: a parameter the endpoint does not take; the message lists the allowed ones.
- 429 `rate_limited` or `quota_exceeded`: wait for `Retry-After`; `resets_at` gives when the allowance resets.
- 500 `server_error`: logged on our side; try again later.

## A typical agent workflow

1. Call `/usage` once to learn the plan and what it covers.
2. Turn names into ids with `/leagues?q=`, `/teams?q=` or `/players?q=`.
3. Ask the narrow question: `/games` with a date or a team, `/seasons/{id}/standings`, `/teams/{id}/head-to-head/{other}`.
4. For a game in depth, add `/goals`, `/lineups`, `/skaters` or `/odds` with its `gm_` id.
5. On a 403, tell the user which plan the answer needs; on a 429, wait for `Retry-After` before trying again.

Ice Hockey API is operated by DeveloperData.net.