---
title: Basketball API
description: Basketball data — leagues, teams, games with box scores and team stats, pregame reports, standings and predictions.
badge: pro
---

# Basketball API

The Basketball API covers leagues, teams, players, games with full box scores
and team statistics, pregame reports, standings and model-based predictions.

Base URL: `https://sports.bzzoiro.com/basketball/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 /basketball/api/v2/leagues/` | List leagues |
| `GET /basketball/api/v2/leagues/{id}/` | League detail |
| `GET /basketball/api/v2/teams/` | List/search teams |
| `GET /basketball/api/v2/teams/{id}/` | Team detail |
| `GET /basketball/api/v2/events/` | List games |
| `GET /basketball/api/v2/events/live/` | Games in play right now |
| `GET /basketball/api/v2/events/{id}/` | Game detail |
| `GET /basketball/api/v2/events/{id}/box-score/` | Per-player box score |
| `GET /basketball/api/v2/events/{id}/team-stats/` | Team statistics for the game |
| `GET /basketball/api/v2/events/{id}/pregame/` | Pregame report |
| `GET /basketball/api/v2/players/` | List/search players |
| `GET /basketball/api/v2/players/{id}/` | Player detail |
| `GET /basketball/api/v2/players/{id}/games/` | Player game log |
| `GET /basketball/api/v2/managers/` | List/search coaches |
| `GET /basketball/api/v2/managers/{id}/` | Coach detail |
| `GET /basketball/api/v2/venues/` | List arenas |
| `GET /basketball/api/v2/venues/{id}/` | Arena detail |
| `GET /basketball/api/v2/standings/` | League standings |
| `GET /basketball/api/v2/predictions/` | Model predictions |
| `GET /basketball/api/v2/predictions/{id}/` | One prediction |

## Leagues and teams

**Leagues query parameters:** `country`, `include_inactive`, `limit`, `offset`.
**Teams query parameters:** `search`, `country_code`, `limit`, `offset`.

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

```json
{"count": 1, "results": [
  {"id": 402, "name": "Los Angeles Lakers", "short_name": "LAL",
   "country_code": "US"}
]}
```

## Games

**Query parameters**

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

```json
{"count": 82, "results": [
  {"id": 71204, "league": {"id": 12, "name": "NBA"},
   "home_team": {"id": 402, "name": "Los Angeles Lakers"},
   "away_team": {"id": 407, "name": "Denver Nuggets"},
   "event_date": "2026-04-09T02:30:00+00:00", "status": "finished",
   "home_score": 112, "away_score": 108}
]}
```

`GET /events/live/` returns in-play games only (cached 30 seconds).
`GET /events/{id}/` adds `officials` — a raw list of match officials as
reported upstream (typically `[{"name": "..."}]`, shape not normalized).
Usually an empty array — most competitions don't report it.

### Box score

`GET /events/{id}/box-score/` returns per-player lines for both teams:

```json
{"event_id": 71204, "home": [
  {"player_id": 9931, "name": "LeBron James", "minutes": 36,
   "points": 28, "rebounds": 9, "assists": 11, "steals": 1,
   "blocks": 1, "turnovers": 3, "fg": "10-19", "three_pt": "3-7", "ft": "5-6"}
]}
```

### Team stats

`GET /events/{id}/team-stats/` returns aggregate shooting, rebounding and
turnover numbers per quarter and for the full game.

### Pregame report

`GET /events/{id}/pregame/` bundles what you need before tip-off: coaches,
venue, current standings of both teams, form streaks and players to watch.

## Players

**Query parameters:** `search`, `team`, `position`, `country_code`, `limit`,
`offset`.

`GET /players/{id}/games/` returns the recent game log (`limit` supported):

```json
{"player_id": 9931, "games": [
  {"event_id": 71204, "date": "2026-04-09", "opponent": "Denver Nuggets",
   "points": 28, "rebounds": 9, "assists": 11}
]}
```

## Coaches, venues and standings

- `GET /managers/` — `search`, `team`, `limit`, `offset`; `GET /managers/{id}/`.
- `GET /venues/` — `search`, `country_code`, `limit`; `GET /venues/{id}/`.
- `GET /standings/` — `league` (required), `season`:

```json
{"league_id": 12, "standings": [
  {"position": 1, "team": {"id": 407, "name": "Denver Nuggets"},
   "played": 82, "wins": 57, "losses": 25, "win_pct": 0.695}
]}
```

## Predictions

**Query parameters**

| Param | Type | Description |
|---|---|---|
| `league` | int | Filter by league id |
| `days` | int | Look-ahead window in days |
| `confidence` | float | Minimum model confidence (0–1) |
| `limit` / `offset` | int | Pagination |

```json
{"count": 6, "results": [
  {"id": 8817, "event_id": 71250,
   "home_win_prob": 0.61, "away_win_prob": 0.39,
   "predicted_winner_id": 402, "confidence": 0.61}
]}
```