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. Default page size and navigation style vary by endpoint (see table below).

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

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,
      "name": "Premier League",
      "country": "England",
      "is_women": false,
      "current_season": {
        "id": 42,
        "name": "Premier League 25/26",
        "year": 2025,
        "start_date": "2025-08-16",
        "end_date": "2026-05-24"
      }
    },
    ...
  ]
}

Returns seasons for all leagues. Use this to discover available historical data and filter events by season. 8 major leagues with up to 15+ years of history (58,000+ matches total).

Query parameters

Response fields

Example

# Get all seasons for Premier League
curl -H "Authorization: Token YOUR_API_KEY" \
     "https://sports.bzzoiro.com/api/seasons/?league=1"

{
  "count": 16,
  "results": [
    {
      "id": 42,
      "league": "Premier League",
      "league_id": 1,
      "name": "Premier League 25/26",
      "year": 2025,
      "start_date": "2025-08-16",
      "end_date": "2026-05-24",
      "is_current": true
    },
    {
      "id": 41,
      "league": "Premier League",
      "league_id": 1,
      "name": "Premier League 24/25",
      "year": 2024,
      "start_date": "2024-08-17",
      "end_date": "2025-05-25",
      "is_current": false
    },
    ...
  ]
}

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"

{
  "count": 42,
  "results": [
    {
      "id": 44,
      "name": "Barcelona",
      "short_name": "Barcelona",
      "country": "Spain"
    },
    {
      "id": 2,
      "name": "Real Madrid",
      "short_name": "Real Madrid",
      "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"

Both are aliases for /api/events/. They return the same match data and accept all the same query parameters. Provided for compatibility with clients that expect /fixtures/ or /matches/ naming conventions.

Examples

curl -H "Authorization: Token YOUR_API_KEY" \
     "https://sports.bzzoiro.com/api/fixtures/?date_from=2026-04-20&league=1"

curl -H "Authorization: Token YOUR_API_KEY" \
     "https://sports.bzzoiro.com/api/matches/?date_from=2026-04-20&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": "card", "minute": 50, "player_name": "White", "card_type": "yellow", "is_home": false},
        {"type": "substitution", "minute": 60, "player_in": "Diaz", "player_out": "Nunez", "player_in_id": 982119, "player_out_id": 930829, "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. 8,900+ 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,
      "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,
        "name": "Barcelona",
        "short_name": "Barcelona",
        "country": "Spain"
      },
      "national_team": {
        "id": 475,
        "name": "Spain",
        "short_name": "Spain",
        "country": "Spain"
      },
      "transfers": [
        {
          "transfer_date": "2023-07-15",
          "from_team": {"id": 2, "name": "Real Madrid", "short_name": "Real Madrid", "country": "Spain", "coach": null},
          "to_team": {"id": 44, "name": "Barcelona", "short_name": "Barcelona", "country": "Spain", "coach": null},
          "from_team_name": "Real Madrid",
          "to_team_name": "Barcelona",
          "fee": 45000000,
          "fee_description": "€45M"
        }
      ]
    },
    ...
  ]
}

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,
        "home_team": "Swansea City",
        "away_team": "Sheffield Wednesday",
        "event_date": "2026-02-08T12:00:00Z",
        "home_score": 4,
        "away_score": 0
      },
      "player": {
        "id": 548194,
        "name": "Dan Fry",
        "short_name": "D. Fry",
        "position": "D",
        "team": "Swansea City"
      },
      "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,
      ...
    }
  ]
}

Multi-bookmaker odds with full price history. The listing endpoint refreshes consensus pricing every 6 hours; per-bookmaker prices refresh every 3 hours. Each row carries the previous price so movement is visible without a separate history call.

Endpoints

Filters

Bookmakers

Pinnacle, Bet365, Betano, Bwin, William Hill, Unibet, Betsson, Sportingbet, Interwetten, Mozzartbet, Novibet, Betway, 888Sport, 1xBet, plus a synthetic oddssafari-consensus entry that averages the rest.

Markets

1x2 (Match Result), double_chance (1X / 12 / X2), over_under_15, over_under_25, over_under_35, btts (Both Teams to Score), draw_no_bet.

Response fields (GET /api/odds/?event=ID)

When filtering by a single event, the response has a root-level event object and an odds array. For multi-event queries, the standard paginated envelope is returned.

Examples

GET /api/odds/?event=997&market=1x2 — raw odds list (paginated)

curl -H "Authorization: Token YOUR_API_KEY" \
     "https://sports.bzzoiro.com/api/odds/?event=997&market=1x2"

{
  "event": {
    "id": 997,
    "home_team": "Osasuna", "away_team": "Real Betis",
    "event_date": "2026-04-12T12:00:00Z", "league": "La Liga"
  },
  "count": 36,
  "odds": [
    {
      "id": 51713, "market": "1x2", "outcome": "HOME", "outcome_name": "Osasuna",
      "bookmaker": "Pinnacle", "bookmaker_code": "pinnacle",
      "decimal_odds": 2.11, "previous_decimal_odds": 2.18,
      "is_max_quote": false, "implied_probability": 0.4739,
      "movement": "SHORTENING", "updated_at": "2026-04-12T09:00:00Z"
    },
    ...
  ]
}

GET /api/odds/compare/?event=997 — aggregated side-by-side view

curl -H "Authorization: Token YOUR_API_KEY" \
     "https://sports.bzzoiro.com/api/odds/compare/?event=997"

{
  "event_id": 997,
  "home_team": "Osasuna",
  "away_team": "Real Betis",
  "event_date": "2026-04-12T12:00:00Z",
  "league": "La Liga",
  "bookmakers_count": 12,
  "total_odds": 36,
  "markets": {
    "1x2": {
      "Osasuna": {
        "best_odds": 2.20,
        "best_bookmaker": "Interwetten",
        "ai_probability": null,
        "bookmakers": {
          "Pinnacle": {"decimal": 2.11, "movement": "SHORTENING"},
          "Bet365":   {"decimal": 2.10, "movement": "SHORTENING"},
          "Bwin":     {"decimal": 2.20, "movement": "SHORTENING"}
        }
      },
      "Draw": {"best_odds": 3.6, "best_bookmaker": "Unibet", "bookmakers": {"...": "..."}},
      "Real Betis": {"best_odds": 3.62, "best_bookmaker": "Pinnacle", "bookmakers": {"...": "..."}}
    }
  }
}

GET /api/odds/best/?market=1x2&league=8&days=3 — best odds per outcome across bookmakers

curl -H "Authorization: Token YOUR_API_KEY" \
     "https://sports.bzzoiro.com/api/odds/best/?market=1x2&league=8&days=3"

Polymarket Prediction Markets

Returns Polymarket prediction market prices for upcoming football matches. Prices are implied probabilities (0-1) — convert to decimal odds with 1/price. Synced every 30 minutes.

Response fields (each item)

In addition to event_id, home_team, away_team, event_date, league, league_id, and updated_at, each result contains:

• odds — nested object with markets: 1x2, over_under, btts, halftime, handicap
• exact_scores — object mapping scorelines to implied probability (e.g. {"1-0": 0.095})
• goalscorers — object mapping player names to anytime goalscorer probability

Markets included

1X2, Over/Under (1.5, 2.5, 3.5, 4.5), BTTS, Halftime result, Handicaps (-1.5, -2.5), Exact scores, Goalscorers.

Example

curl -H "Authorization: Token YOUR_API_KEY" \
     "https://sports.bzzoiro.com/api/odds/polymarket/?league=1"

{
  "count": 23,
  "results": [
    {
      "event_id": 325,
      "home_team": "Brentford",
      "away_team": "Fulham",
      "event_date": "2026-04-18T11:30:00Z",
      "league": "Premier League",
      "league_id": 1,
      "odds": {
        "1x2": {"home": 0.465, "draw": 0.255, "away": 0.275},
        "over_under": {"over_25": 0.555, "under_25": 0.445, ...},
        "btts": {"yes": 0.58, "no": 0.42},
        "halftime": {"home": 0.355, "draw": 0.405, "away": 0.225},
        "handicap": {"home_-1.5": 0.23, "away_-1.5": 0.115, ...}
      },
      "exact_scores": {"1-0": 0.095, "0-0": 0.08, ...},
      "goalscorers": {"B. Mbeumo": 0.42, "R. Jimenez": 0.31, ...},
      "updated_at": "2026-04-14T18:00:13Z"
    }
  ]
}

Returns head coaches and managers with their tactical fingerprint and aggregated match statistics. Each manager's style is derived from their actual match data (possession, pass completion, long-ball %, cross rate, pressing proxy, opponent pass disruption, defensive line height, set-piece goal share, shot efficiency, score variance) — no hand-mapped labels — and scored against 30 tactical styles across 6 categories. Requires ≥5 matches with complete stats to surface tactical_styles, pressing_intensity, and defensive_line. Use ?team_id= to fetch the manager for a specific team.

Query parameters

Response fields — identity

Response fields — tactical profile

Response fields — match statistics

Example

curl -H "Authorization: Token YOUR_API_KEY" \
     "https://sports.bzzoiro.com/api/managers/?team_id=42"

{
  "count": 1,
  "results": [
    {
      "id": 128,
      "name": "Pep Guardiola",
      "short_name": "P. Guardiola",
      "country": "Spain",
      "current_team": {"id": 42, "name": "Manchester City"},
      "preferred_formation": "4-3-3",
      "formations_used": {"4-3-3": 18, "4-2-3-1": 6, "3-2-4-1": 2},
      "profile": "attacking",
      "team_style": "possession",
      "pressing_intensity": 0.51,
      "defensive_line": "high",
      "tactical_styles": [
        {"rank": 1, "code": "positional", "name": "Positional Play", "category": "possession", "emoji": "\u265f", "description": "Zone occupation and overloads", "score": 0.112},
        {"rank": 2, "code": "ball_dominant", "name": "Ball Dominant", "category": "possession", "emoji": "\u26bd", "description": "Keep the ball to control tempo and energy", "score": 0.109},
        {"rank": 3, "code": "total_football", "name": "Total Football", "category": "possession", "emoji": "\ud83c\udf00", "description": "Fluid rotations, every player attacks and defends", "score": 0.099},
        {"rank": 4, "code": "false_9", "name": "False 9 System", "category": "possession", "emoji": "\ud83c\udfa9", "description": "No fixed striker \u2014 central creator drops deep", "score": 0.088}
      ],
      "matches_total": 26,
      "wins": 18,
      "draws": 4,
      "losses": 4,
      "win_pct": 69.23,
      "avg_goals_scored": 2.31,
      "avg_goals_conceded": 0.96,
      "avg_goals_scored_1h": 1.04,
      "avg_goals_conceded_1h": 0.38,
      "avg_possession": 62.4,
      "avg_shots": 16.8,
      "avg_shots_on_target": 6.2,
      "avg_xg_for": 2.14,
      "avg_xg_against": 0.88,
      "avg_corners": 7.3,
      "avg_yellow_cards": 1.5,
      "avg_red_cards": 0.08,
      "avg_fouls": 9.4,
      "clean_sheet_pct": 46.15,
      "btts_pct": 38.46,
      "over_25_pct": 65.38,
      "over_15_pct": 88.46,
      "fail_to_score_pct": 7.69
    }
  ]
}

List all football venues (stadiums and arenas) with capacity, city, country, and the team that plays home there.

Query parameters

GET /api/venues/?country=Spain&min_capacity=50000
{
  "count": 14,
  "results": [
    {
      "id": 812,
      "name": "Santiago Bernabéu",
      "city": "Madrid",
      "country": "Spain",
      "capacity": 81044,
      "team": {"id": 2829, "name": "Real Madrid"}
    }
  ]
}

Returns social-media items — official club tweets and YouTube match-highlight videos — linked to teams, events, players and managers. Tweets refresh every 30 minutes, highlights every 6 hours. Ordered newest first. Deliberately not part of /api/live/ so the live endpoint stays fast; pull the social feed separately, or read the social field on /api/events/{id}/ and /api/teams/{id}/ (capped at 20 items each).

Query parameters

Response fields

Example

curl -H "Authorization: Token YOUR_API_KEY" \
     "https://sports.bzzoiro.com/api/social/?team=44&type=tweet"

curl -H "Authorization: Token YOUR_API_KEY" \
     "https://sports.bzzoiro.com/api/social/?event=13466949"

Catalogue of official TV broadcast channels per country. Only licensed rights-holders are ingested — no pirate streams. Updated daily.

Query parameters

Response fields

Example

curl -H "Authorization: Token YOUR_API_KEY" \
     "https://sports.bzzoiro.com/api/tv-channels/?country=PT"

Event-to-channel broadcast mappings — which licensed TV channel shows which match, in which country, and at what scheduled start time. Refreshed daily from the official rights-holder schedules.

Query parameters

Response fields

Example

curl -H "Authorization: Token YOUR_API_KEY" \
     "https://sports.bzzoiro.com/api/broadcasts/?country=PT&date_from=2026-04-25&date_to=2026-04-27"

Returns distinct referees aggregated from match data. Includes event count, yellow cards, and red cards across all their matches. Results sorted by number of matches officiated. Cached 10 minutes.

Query parameters

Response fields

Example

curl -H "Authorization: Token YOUR_API_KEY" \
     "https://sports.bzzoiro.com/api/referees/?league=1"

{
  "count": 682,
  "results": [
    {
      "name": "Anthony Taylor",
      "country": "England",
      "matches": 38,
      "total_yellow_cards": 156,
      "total_red_cards": 8,
      "avg_yellow_per_match": 4.11,
      "avg_red_per_match": 0.21,
      "avg_goals_per_match": 2.87,
      "avg_fouls_per_match": 21.4,
      "career_games": 320,
      "career_yellow_cards": 1240,
      "career_red_cards": 62
    },
    ...
  ]
}

Returns AI-predicted starting lineups for upcoming matches — predicted starters, substitutes, and unavailable players for each team. Only available for matches that have not yet been played.

URL parameters

Response fields

Example

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

{
  "event": {
    "id": 42567,
    "home_team": "Barcelona",
    "away_team": "Real Madrid",
    "date": "2026-04-20T19:00:00+00:00",
    "league": "La Liga",
    "status": "notstarted"
  },
  "beta": true,
  "lineups": {
    "home": {
      "team": "Barcelona",
      "predicted_formation": "4-3-3",
      "confidence": 0.74,
      "starters": [
        {"name": "I. Pena", "position": "G", "jersey_number": 13, "ai_score": 0.91},
        {"name": "L. Yamal", "position": "F", "jersey_number": 19, "ai_score": 0.88},
        ...
      ],
      "substitutes": [...],
      "unavailable": [
        {"name": "R. Araujo", "reason": "Muscle Injury"}
      ],
      "updated_at": "2026-04-19T06:00:00+00:00"
    },
    "away": { ... }
  }
}