# Bzzoiro Sports Data API - Complete Reference

> REST API, WebSockets and MCP for football and six other sports. Football is free; the rest is a $5/month addon. 10 req/s per IP.

## Base URL
https://sports.bzzoiro.com/api/

## Authentication
Token-based. Register free at https://sports.bzzoiro.com/register/
Header: Authorization: Token YOUR_API_KEY

## Pagination
All list endpoints return paginated results with 50 items per page.
Response format: {"count": N, "next": "url", "previous": "url", "results": [...]}
Navigate with ?page=N

---

## GET /api/leagues/
Returns all active football leagues. Cached 5 min.

Response fields:
- id (integer): League ID
- name (string): League name (e.g. "Premier League")
- country (string): Country (e.g. "England")
- is_women (boolean): Whether this is a women's competition
- current_season (object): Current season info (id, name, year, start_date, end_date)

Example response:
{"count": 32, "results": [{"id": 1, "name": "Premier League", "country": "England", "is_women": false, "current_season": {"id": 301, "name": "Premier League 25/26", "year": 2025}}]}

---

## GET /api/teams/
Returns all football teams. Cached 5 min.

Parameters:
- country (string, optional): Filter by country (case-insensitive)

Response fields:
- id (integer): Team ID
- name (string): Full team name
- short_name (string): Short name
- country (string): Country of origin

---

## GET /api/events/
Returns football matches. Defaults to next 7 days. Cached 2 min.

Parameters:
- date_from (date, optional): Start date (YYYY-MM-DD)
- date_to (date, optional): End date (YYYY-MM-DD)
- league (integer, optional): Filter by league id
- status (string, optional): notstarted, inprogress, 1st_half, halftime, 2nd_half, finished, postponed, cancelled

Response fields:
- id, league (nested object), season (nested object), home_team, away_team
- home_team_obj, away_team_obj (nested team objects)
- event_date (datetime ISO 8601), status, home_score, away_score
- current_minute, period (1T, HT, 2T, FT)
- odds_home, odds_draw, odds_away (1X2 market odds)
- odds_over_15, odds_over_25, odds_over_35 (Over market odds)
- odds_under_15, odds_under_25, odds_under_35 (Under market odds)
- odds_btts_yes, odds_btts_no (Both Teams To Score odds)

---

## GET /api/live/
Returns only live matches with real-time data. Cached 30 sec.

Additional fields beyond Events:
- incidents (array): goals/cards: {type, minute, player_name, is_home}; substitutions: {type, minute, player_in, player_out, player_in_id, player_out_id, is_home}
- live_stats (object): {home: {ball_possession, total_shots, shots_on_target, corner_kicks, fouls, yellow_cards, red_cards, offsides}, away: {...}}
  Those eight keys are ALWAYS present on each side; the value is null when the match did not report that statistic. Coverage varies a lot — a friendly can carry four of the forty-four keys a fully covered league match carries — so anything beyond the eight should be read defensively. null means "not reported", never "zero".

---

## GET /api/predictions/
Analytic forecasts per market — Dixon-Coles goals, negative-binomial corners and a de-vigged market consensus, blended. Not machine-learned. Cached 2 min.

Parameters:
- upcoming (boolean, default true): Set false for past predictions

Response fields:
- id, event (nested event object), created_at
- prob_home_win, prob_draw, prob_away_win (0-100 scale)
- predicted_result (H/D/A)
- expected_home_goals, expected_away_goals
- prob_over_15, prob_over_25, prob_over_35 (0-100)
- prob_btts_yes (0-100)
- confidence (0-1), model_version
- most_likely_score (e.g. "2-1")
- favorite (H/A), favorite_prob, favorite_recommend (bool)
- over_15_recommend, over_25_recommend, over_35_recommend (bool)
- btts_recommend, winner_recommend (bool)

---

## GET /api/players/
Player profiles. 214,000+ players. Cached 5 min.

Parameters:
- team (integer, optional): Filter by team id
- nationality (string, optional): Filter by nationality
- position (string, optional): G/D/M/F (generic) OR CB/LB/RB/LWB/RWB/DM/CM/AM/LW/RW/ST/GK (specific)

Response fields:
- id, name, short_name, position, jersey_number
- height (cm), date_of_birth, nationality, market_value (EUR)
- current_team (nested team object)

---

## GET /api/player-stats/
Per-match player statistics. 139,000+ records. Cached 5 min.

Parameters:
- player (integer, optional): Filter by player id
- event (integer, optional): Filter by event id
- team (integer, optional): Filter by team id

Response fields:
- event (nested: id, home_team, away_team, event_date, scores)
- minutes_played, rating (1-10), touches
- goals, goal_assist, expected_goals (xG), expected_assists (xA)
- total_shots, shots_on_target
- total_pass, accurate_pass, key_pass
- total_cross, accurate_cross, total_long_balls, accurate_long_balls
- duel_won, duel_lost, aerial_won, aerial_lost
- total_tackle, won_tackle, total_clearance, interception, ball_recovery
- dispossessed, possession_lost, was_fouled, fouls
- yellow_card, red_card, saves, goals_conceded

---

## GET /img/{type}/{id}/
Team logos, league logos, and player photos.

URL params:
- type: "team", "league", "player", or "manager"
- id: The id from the respective endpoint

Auth: ?token=YOUR_API_KEY (query param) or Authorization header
Cache: 365 days

---

## Quick Start (Python)

```python
import requests

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

# Get upcoming predictions
predictions = requests.get(f"{BASE}/predictions/", headers=headers).json()
for p in predictions["results"]:
    e = p["event"]
    print(f"{e['home_team']} vs {e['away_team']}: {p['predicted_result']} ({p['confidence']:.0%})")
```

## Contact
Email: sports@bzzoiro.com