API Documentation

The BSD API provides read-only access to football data and machine learning predictions. All responses are JSON.

Every API request requires a token. Get yours by registering a free account.

Include the token in the Authorization header:

Authorization: Token YOUR_API_KEY

Example:

curl -H "Authorization: Token abc123def456" https://sports.bzzoiro.com/api/leagues/

All list endpoints return paginated results with 50 items per page.

{
  "count": 243,
  "next": "https://sports.bzzoiro.com/api/events/?page=2",
  "previous": null,
  "results": [ ... ]
}

Use ?page=N to navigate pages.

Returns all active leagues/tournaments. Cached for 5 minutes.

Parameters

None. Returns all active leagues.

Response fields

Example

curl -H "Authorization: Token YOUR_API_KEY" \
     https://sports.bzzoiro.com/api/leagues/

{
  "count": 32,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 1,
      "api_id": 17,
      "name": "Premier League",
      "country": "England",
      "season_id": 61627
    },
    ...
  ]
}

Returns all teams. Cached for 5 minutes.

Query parameters

Response fields

Example

curl -H "Authorization: Token YOUR_API_KEY" \
     "https://sports.bzzoiro.com/api/teams/?country=Spain"

Returns matches. Defaults to the next 7 days if no date filters are provided. Cached for 2 minutes.

Query parameters

Status values

Response fields

Example

curl -H "Authorization: Token YOUR_API_KEY" \
     "https://sports.bzzoiro.com/api/events/?date_from=2026-02-08&date_to=2026-02-10&league=1"

Returns only matches currently in play with real-time scores, minute, incidents (goals, cards, substitutions) and live statistics. Cached for 30 seconds.

Query parameters

None. Automatically filters to live matches only.

Response fields

Same fields as Events, plus:

Example

curl -H "Authorization: Token YOUR_API_KEY" \
     https://sports.bzzoiro.com/api/live/

{
  "count": 3,
  "results": [
    {
      "id": 580,
      "home_team": "Liverpool",
      "away_team": "Arsenal",
      "home_score": 2,
      "away_score": 1,
      "current_minute": 67,
      "period": "2T",
      "status": "2nd_half",
      "incidents": [
        {"type": "goal", "minute": 12, "player_name": "Salah", "is_home": true},
        {"type": "goal", "minute": 34, "player_name": "Saka", "is_home": false},
        {"type": "goal", "minute": 55, "player_name": "Diaz", "is_home": true}
      ],
      "live_stats": {
        "home": {"ball_possession": 52, "total_shots": 14, "shots_on_target": 6, "corner_kicks": 5},
        "away": {"ball_possession": 48, "total_shots": 10, "shots_on_target": 4, "corner_kicks": 3}
      },
      "league": {"name": "Premier League", "country": "England"},
      ...
    }
  ]
}

Returns CatBoost ML predictions for football matches. Defaults to upcoming matches. Cached for 2 minutes.

Query parameters

Response fields

Example

curl -H "Authorization: Token YOUR_API_KEY" \
     https://sports.bzzoiro.com/api/predictions/

{
  "count": 48,
  "results": [
    {
      "id": 87,
      "event": {
        "id": 580,
        "home_team": "Liverpool",
        "away_team": "Arsenal",
        "event_date": "2026-02-10T17:30:00+0400",
        "league": {"name": "Premier League", "country": "England"},
        ...
      },
      "prob_home_win": 52.3,
      "prob_draw": 24.1,
      "prob_away_win": 23.6,
      "predicted_result": "H",
      "expected_home_goals": 1.82,
      "expected_away_goals": 1.14,
      "prob_over_15": 87.4,
      "prob_over_25": 61.2,
      "prob_over_35": 28.7,
      "prob_btts_yes": 58.9,
      "confidence": 0.72,
      "model_version": "CatBoost v4.0",
      "most_likely_score": "2-1",
      "favorite": "H",
      "favorite_prob": 52.3,
      "favorite_recommend": true,
      "over_25_recommend": true,
      "btts_recommend": true,
      ...
    }
  ]
}

Returns PNG images for teams, leagues, and players. Requires token authentication. Images are cached on disk for 365 days.

URL parameters

Response

Returns a image/png binary response. Returns 404 if the image is not found.

Response header: Cache-Control: public, max-age=31536000 (365 days).

Examples (curl)

# Using query param (recommended)
curl -o real_madrid.png "https://sports.bzzoiro.com/img/team/2829/?token=YOUR_API_KEY"
curl -o premier_league.png "https://sports.bzzoiro.com/img/league/17/?token=YOUR_API_KEY"
curl -o player.png "https://sports.bzzoiro.com/img/player/990724/?token=YOUR_API_KEY"

# Using header (also supported)
curl -H "Authorization: Token YOUR_API_KEY" -o real_madrid.png \
     https://sports.bzzoiro.com/img/team/2829/

Usage in HTML

<!-- Team logo -->
<img src="https://sports.bzzoiro.com/img/team/2829/?token=YOUR_API_KEY" width="32" height="32" alt="Real Madrid">

<!-- League logo -->
<img src="https://sports.bzzoiro.com/img/league/17/?token=YOUR_API_KEY" width="24" height="24" alt="Premier League">

<!-- Player photo -->
<img src="https://sports.bzzoiro.com/img/player/990724/?token=YOUR_API_KEY" width="48" height="48" alt="Player">

Usage with API data

# Python: fetch events and display with logos
import requests

TOKEN = "YOUR_API_KEY"
BASE = "https://sports.bzzoiro.com"
headers = {"Authorization": f"Token {TOKEN}"}

events = requests.get(f"{BASE}/api/events/", headers=headers).json()

for event in events["results"]:
    league = event["league"]
    home = event.get("home_team_obj")
    away = event.get("away_team_obj")

    # Use ?token= for image URLs (works in <img> tags and browsers)
    league_logo = f"{BASE}/img/league/{league['api_id']}/?token={TOKEN}"
    home_logo = f"{BASE}/img/team/{home['api_id']}/?token={TOKEN}" if home else None
    away_logo = f"{BASE}/img/team/{away['api_id']}/?token={TOKEN}" if away else None

    print(f"League: {league['name']} (logo: {league_logo})")
    print(f"  {event['home_team']} vs {event['away_team']}")
    if home_logo:
        print(f"  Home logo: {home_logo}")
    if away_logo:
        print(f"  Away logo: {away_logo}")

1. Register: Create a free account at /register/
2. Get your token: After registering you'll be redirected to your dashboard where you can copy your API token.
3. Make a request:

   curl -H "Authorization: Token YOUR_API_KEY" https://sports.bzzoiro.com/api/leagues/

4. Explore: Use the endpoints above to fetch teams, events, live scores, and ML predictions.

import requests

API_TOKEN = "YOUR_API_KEY"
BASE_URL = "https://sports.bzzoiro.com/api"
headers = {"Authorization": f"Token {API_TOKEN}"}

# Get upcoming predictions
resp = requests.get(f"{BASE_URL}/predictions/", headers=headers)
data = resp.json()

for pred in data["results"]:
    event = pred["event"]
    print(f"{event['home_team']} vs {event['away_team']}")
    print(f"  Predicted: {pred['predicted_result']} "
          f"(H:{pred['prob_home_win']:.1f}% "
          f"D:{pred['prob_draw']:.1f}% "
          f"A:{pred['prob_away_win']:.1f}%)")
    print(f"  Over 2.5: {pred['prob_over_25']:.1f}%  "
          f"BTTS: {pred['prob_btts_yes']:.1f}%")
    print()

# Get live scores
live = requests.get(f"{BASE_URL}/live/", headers=headers).json()
for match in live["results"]:
    print(f"LIVE {match['current_minute']}' "
          f"{match['home_team']} {match['home_score']}-"
          f"{match['away_score']} {match['away_team']}")

const API_TOKEN = "YOUR_API_KEY";
const BASE_URL = "https://sports.bzzoiro.com/api";
const headers = { "Authorization": `Token ${API_TOKEN}` };

// Get upcoming events
const resp = await fetch(`${BASE_URL}/events/`, { headers });
const data = await resp.json();

data.results.forEach(event => {
    console.log(`${event.home_team} vs ${event.away_team}`);
    console.log(`  ${event.event_date} | ${event.league?.name}`);
});

// Poll live scores every 30s
setInterval(async () => {
    const live = await fetch(`${BASE_URL}/live/`, { headers });
    const { results } = await live.json();
    results.forEach(m => {
        console.log(`${m.current_minute}' ${m.home_team} ${m.home_score}-${m.away_score} ${m.away_team}`);
    });
}, 30000);