---
title: Hockey API
description: Ice hockey data — leagues, teams with ELO ratings, matches with period scores, overtime/shootout flags and predictions.
badge: pro
---

# Hockey API

The Hockey API covers ice hockey (NHL and international leagues): leagues,
teams with ELO ratings, matches with period-by-period scores,
overtime/shootout flags, decimal odds and model-based predictions.

Base URL: `https://sports.bzzoiro.com/hockey/api/v2/`

## Access

Requires the **Sports Addon** ($5/month) — it unlocks the tennis, CS2, darts,
hockey, basketball and horse racing APIs plus their MCP servers. Get it at
[/addons/](/addons/). You also need a free account token from
[/register/](/register/).

```bash
Authorization: Token YOUR_API_KEY
```

Without a token you get **401**:

```json
{"error": "authentication required", "code": "authentication_required",
 "detail": "Send Authorization: Token <YOUR_TOKEN> on every request.",
 "register": "https://sports.bzzoiro.com/register/"}
```

With a token but no addon you get **402**:

```json
{"error": "Sports Addon required", "code": "addon_required",
 "detail": "Tennis, CS:GO, darts, hockey, basketball and horse racing APIs require the Sports Addon ($5/mo).",
 "pricing_url": "https://sports.bzzoiro.com/pricing/"}
```

List endpoints paginate with `limit` (default 50, max 200) and `offset`, and
return `{count, next, previous, results}`.

## Endpoints

| Endpoint | Description |
|---|---|
| `GET /hockey/api/v2/leagues/` | List leagues |
| `GET /hockey/api/v2/leagues/{id}/` | League detail |
| `GET /hockey/api/v2/teams/` | List/search teams with ELO |
| `GET /hockey/api/v2/teams/{id}/` | Team detail |
| `GET /hockey/api/v2/matches/` | List matches |
| `GET /hockey/api/v2/matches/live/` | Matches in play right now |
| `GET /hockey/api/v2/matches/{id}/` | Match detail with period scores and odds |
| `GET /hockey/api/v2/predictions/` | Model win probabilities |
| `GET /hockey/api/v2/predictions/{id}/` | One prediction |

The machine-readable schema is public at `/hockey/api/schema/`, with an
interactive UI at [/hockey/api/docs/](/hockey/api/docs/) and a themed explorer
at [/docs/explorer/hockey/](/docs/explorer/hockey/).

## Leagues

**Query parameters**

| Param | Type | Description |
|---|---|---|
| `country` | string | ISO country code |
| `include_inactive` | bool | Include inactive leagues |
| `limit` / `offset` | int | Pagination (default 50, max 200) |

```json
{"count": 14, "results": [
  {"id": 3, "name": "NHL", "country": "USA"}
]}
```

## Teams

**Query parameters**

| Param | Type | Description |
|---|---|---|
| `search` | string | Name search |
| `country` | string | ISO country code |
| `limit` / `offset` | int | Pagination |

Responses are cached ~5 minutes.

```bash
curl -H "Authorization: Token YOUR_API_KEY" \
  "https://sports.bzzoiro.com/hockey/api/v2/teams/?search=rangers"
```

```json
{"count": 1, "results": [
  {"id": 118, "name": "New York Rangers", "short_name": "NYR",
   "country_code": "US", "elo_rating": 1671}
]}
```

## Matches

**Query parameters**

| Param | Type | Description |
|---|---|---|
| `league` | int | Filter by league id |
| `team` | int | Matches involving this team id |
| `status` | string | `upcoming`, `live`, `finished` |
| `date_from` / `date_to` | date | `YYYY-MM-DD` |
| `limit` / `offset` | int | Pagination |

```bash
curl -H "Authorization: Token YOUR_API_KEY" \
  "https://sports.bzzoiro.com/hockey/api/v2/matches/?team=118&status=finished&date_from=2026-04-01"
```

```json
{"count": 22, "results": [
  {"id": 40312, "league": {"id": 3, "name": "NHL"},
   "home_team": {"id": 118, "name": "New York Rangers", "short_name": "NYR"},
   "away_team": {"id": 121, "name": "Boston Bruins", "short_name": "BOS"},
   "match_date": "2026-04-12T23:00:00+00:00", "status": "finished",
   "round_name": "Regular season", "home_score": 4, "away_score": 3,
   "is_overtime": true, "is_shootout": false, "winner_id": 118}
]}
```

`GET /matches/live/` returns in-play matches only (cached 30 seconds).
`GET /matches/{id}/` adds period scores, the current period/minute for live
games and decimal odds:

```json
{"id": 40390, "status": "live",
 "home_score": 2, "away_score": 1,
 "periods_score": "1-0, 1-1", "current_period": 3, "current_minute": 7,
 "odds_home": 1.85, "odds_away": 1.95}
```

> **Note:** `is_overtime` and `is_shootout` tell you how a finished game was
> decided — useful for regulation-time markets, where an overtime win counts
> differently.

## Predictions

**Query parameters**

| Param | Type | Description |
|---|---|---|
| `upcoming` | bool | Only matches not yet started |
| `limit` / `offset` | int | Pagination |

```json
{"count": 7, "results": [
  {"id": 5107, "match_id": 40395,
   "home_win_prob": 0.55, "away_win_prob": 0.45,
   "predicted_winner_id": 118, "confidence": 0.55}
]}
```