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. 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

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 football players. 21,000+ players across all covered leagues. Each player has a club team (current_team) and optionally a national team (national_team). Cached for 5 minutes.

Query parameters

Response fields

Examples

# Get all Brazilian forwards
curl -H "Authorization: Token YOUR_API_KEY" \
     "https://sports.bzzoiro.com/api/players/?position=F&nationality=Brazil"

# Get Spain national team squad
curl -H "Authorization: Token YOUR_API_KEY" \
     "https://sports.bzzoiro.com/api/players/?national_team=475"

# Get Barcelona squad
curl -H "Authorization: Token YOUR_API_KEY" \
     "https://sports.bzzoiro.com/api/players/?team=44"

{
  "count": 27,
  "results": [
    {
      "id": 1234,
      "api_id": 1402912,
      "name": "Lamine Yamal",
      "short_name": "L. Yamal",
      "position": "M",
      "jersey_number": 19,
      "height": 180,
      "date_of_birth": "2007-07-13",
      "nationality": "Spain",
      "market_value": 150000000,
      "current_team": {
        "id": 44,
        "api_id": 2817,
        "name": "Barcelona",
        "short_name": "Barcelona",
        "country": "Spain"
      },
      "national_team": {
        "id": 475,
        "api_id": 4698,
        "name": "Spain",
        "short_name": "Spain",
        "country": "Spain"
      }
    },
    ...
  ]
}

Returns per-match player statistics. 139,000+ stat records across all covered leagues. Cached for 5 minutes.

Query parameters

Response fields

Example

# Get all stats for a player
curl -H "Authorization: Token YOUR_API_KEY" \
     "https://sports.bzzoiro.com/api/player-stats/?player=1234"

# Get all player stats for a specific match
curl -H "Authorization: Token YOUR_API_KEY" \
     "https://sports.bzzoiro.com/api/player-stats/?event=917"

{
  "count": 31,
  "results": [
    {
      "event": {
        "id": 3746,
        "api_id": 14059824,
        "home_team": "Swansea City",
        "away_team": "Sheffield Wednesday",
        "event_date": "2026-02-08T12:00:00Z",
        "home_score": 4,
        "away_score": 0
      },
      "minutes_played": 90,
      "rating": 7.8,
      "goals": 1,
      "goal_assist": 1,
      "expected_goals": 0.85,
      "expected_assists": 0.32,
      "total_shots": 3,
      "shots_on_target": 2,
      "total_pass": 41,
      "accurate_pass": 32,
      "key_pass": 2,
      "touches": 56,
      "duel_won": 4,
      "duel_lost": 2,
      "total_tackle": 1,
      "won_tackle": 1,
      "yellow_card": 0,
      "red_card": 0,
      "saves": 0,
      "goals_conceded": 0,
      ...
    }
  ]
}

Returns PNG images for teams, leagues, and players. No authentication required — images are public. 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)

# No authentication needed
curl -o real_madrid.png "https://sports.bzzoiro.com/img/team/2829/"
curl -o premier_league.png "https://sports.bzzoiro.com/img/league/17/"
curl -o player.png "https://sports.bzzoiro.com/img/player/990724/"

Usage in HTML

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

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

<!-- Player photo -->
<img src="https://sports.bzzoiro.com/img/player/990724/" 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")

    # Image URLs are public — no token needed
    league_logo = f"{BASE}/img/league/{league['api_id']}/"
    home_logo = f"{BASE}/img/team/{home['api_id']}/" if home else None
    away_logo = f"{BASE}/img/team/{away['api_id']}/" 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}")

Returns CS2 tournaments. Cached 5 min.

Returns CS2 teams. 400+ teams. Cached 5 min.

Query parameters

Returns CS2 player profiles. Cached 5 min.

Query parameters

Returns CS2 matches with map results. Defaults to next 7 days. Cached 2 min.

Query parameters

Key response fields

Returns ML predictions for CS2 matches. Defaults to upcoming. Cached 2 min.

Query parameters

Key response fields

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);