### Example: Calculate Goals Scored This Season

Source: https://sports.bzzoiro.com/docs/v2

An example demonstrating how to fetch player stats for a season and then sum the goals client-side. Requires a season_id and a limit.

```HTTP
// Goals scored this season
GET /api/v2/players/5821/stats/?season_id=243&limit=200
// Then sum results[].goals client-side
```

--------------------------------

### Get League/Season Venues with Filters

Source: https://sports.bzzoiro.com/docs/v2

Fetches venues for a specific league and season, with options to filter by host country, opening/final match hosting, and round. This example demonstrates filtering for the final round.

```curl
curl -H "Authorization: Token $TOKEN" \
  "https://sports.bzzoiro.com/api/v2/leagues/16/seasons/82/venues/?round=F"
```

--------------------------------

### HTML Examples for Image Embedding

Source: https://sports.bzzoiro.com/docs/static-data

Examples demonstrating how to embed team logos, player portraits, and venue photos in HTML using the image proxy URLs.

```html
<!-- Team logo from a match response -->
<img src="https://sports.bzzoiro.com/img/team/{{ event.home_team_id }}/" alt="home logo">
```

```html
<!-- Player portrait, rounded -->
<img src="https://sports.bzzoiro.com/img/player/{{ player.id }}/"
     style="width:64px;height:64px;border-radius:50%;object-fit:cover" alt="">
```

```html
<!-- Venue photo on the match detail page -->
<img src="https://sports.bzzoiro.com/img/venue/{{ event.venue_id }}/" alt="">
```

--------------------------------

### Get Predicted Lineup

Source: https://sports.bzzoiro.com/docs

Returns AI-predicted starting lineups for upcoming matches, including starters, substitutes, and unavailable players. This feature is in beta and only available for matches not yet played.

```APIDOC
## GET /api/predicted-lineup/<int:event_id>/ BETA

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

**Note:** Lineups are generated periodically and may not be available for every match. Returns `404` if not yet generated or event not found.

### Method
GET

### Endpoint
/api/predicted-lineup/{event_id}/

#### Path Parameters
- **event_id** (integer) - Required - Event ID (`id` from `/api/events/`).

### Request Example
```bash
curl -H "Authorization: Token YOUR_API_KEY" \
     https://sports.bzzoiro.com/api/predicted-lineup/42567/
```

### Response
#### Success Response (200)
- **event** (object) - Match context: `id`, `home_team`, `away_team`, `date`, `league`, `status`.
- **beta** (boolean) - Always `true` — feature is in beta.
- **lineups.home** (object) / **lineups.away** (object)
  - **team** (string) - Team name.
  - **predicted_formation** (string | null) - Predicted formation (e.g. "4-3-3").
  - **confidence** (float | null) - Lineup confidence score (0–1).
  - **starters** (array) - Predicted starting XI — each item: `{name, position, jersey_number, ai_score}`.
  - **substitutes** (array) - Predicted bench players — same structure as starters.
  - **unavailable** (array) - Injured or suspended players — each item: `{name, reason}`.
  - **updated_at** (datetime) - When the lineup prediction was last updated (ISO 8601).

### Response Example
```json
{
  "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": { ... }
  }
}
```
```

--------------------------------

### Polymarket Prediction Markets Response Example

Source: https://sports.bzzoiro.com/docs

Example JSON response for Polymarket prediction markets, including event details and odds for various markets like 1x2, over/under, and goalscorers.

```json
{
  "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"
    }
  ]
}
```

--------------------------------

### Raw Odds Response Example

Source: https://sports.bzzoiro.com/docs

Example JSON response for the raw odds list endpoint, showing event details and odds for each market outcome.

```json
{
  "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"
    },
    ...
  ]
}
```

--------------------------------

### Predicted Lineup Response Example

Source: https://sports.bzzoiro.com/docs

Example JSON response for the predicted lineup endpoint, including event details and predicted team formations, starters, substitutes, and unavailable players.

```json
{
  "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": { ... }
  }
}
```

--------------------------------

### GET /api/fixtures/ and GET /api/matches/

Source: https://sports.bzzoiro.com/docs

Aliases for GET /api/events/. These endpoints return the same match data and accept identical query parameters as the /api/events/ endpoint.

```APIDOC
## GET /api/fixtures/ and GET /api/matches/

### Description
These endpoints are aliases for `GET /api/events/`. They return the same match data and accept all the same query parameters.

### Method
GET

### Endpoint
/api/fixtures/
/api/matches/

### Parameters
All query parameters, response fields, filtering, and pagination behavior are identical to `GET /api/events/`. See the Events section for full documentation and field reference.

### Request Example
```
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"
```
```

--------------------------------

### Referee Data Example

Source: https://sports.bzzoiro.com/docs

Example JSON response structure for the referees endpoint, showing referee statistics and career data.

```json
{
  "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
    },
    ...
  ]
}
```

--------------------------------

### GET /api/broadcasts/

Source: https://sports.bzzoiro.com/docs

Fetches event-to-channel broadcast mappings, indicating which licensed TV channel shows which match, in which country, and at what scheduled start time. Refreshed daily.

```APIDOC
## GET /api/broadcasts/

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

### Method
GET

### Endpoint
/api/broadcasts/

### Parameters
#### Query Parameters
- **event** (integer) - Optional - Filter by event ID
- **country** (string) - Optional - ISO-2 country code (e.g. `PT`, `ES`, `GB`)
- **channel** (integer) - Optional - Filter by internal channel `id` (from `/api/tv-channels/`)
- **league** (integer) - Optional - Filter by league ID (of the event)
- **date_from** (string) - Optional - Event date >= YYYY-MM-DD
- **date_to** (string) - Optional - Event date <= YYYY-MM-DD

### Response
#### Success Response (200)
- **id** (integer) - Broadcast mapping ID
- **event_id** (integer) - Event ID
- **home_team** (string) - Home team name
- **away_team** (string) - Away team name
- **league** (string) - League name
- **event_date** (datetime) - Event kickoff time (ISO 8601)
- **country_code** (string) - ISO-2 country where the broadcast applies
- **channel_id** (integer) - Upstream channel ID
- **channel_name** (string) - Channel name (e.g. `"Sport TV1"`)
- **channel_link** (string) - Official channel link / affiliate URL
- **scheduled_start_time** (datetime) - Broadcast start time as published by the rights-holder (may differ from `event_date` on delayed coverage)

### Request Example
```curl
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"
```
```

--------------------------------

### Player Stats Response Example

Source: https://sports.bzzoiro.com/docs

This is an example of the JSON response structure for player statistics. It includes event and player details along with various performance metrics.

```json
{
  "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,
      ...
    }
  ]
}
```

--------------------------------

### Aggregated Odds Response Example

Source: https://sports.bzzoiro.com/docs

Example JSON response for the aggregated odds view, detailing best odds and bookmaker-specific odds for each market.

```json
{
  "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": {"...": "..."}}
    }
  }
}
```

--------------------------------

### Ratio Shape Example

Source: https://sports.bzzoiro.com/docs/v2

Illustrates the structure for ratio-based statistics, including successful attempts, total attempts, and the rounded percentage.

```json
{
  "value": 2,    // successful
  "total": 14,   // attempts
  "pct":   14    // rounded percentage
}
```

--------------------------------

### GET /api/live/

Source: https://sports.bzzoiro.com/docs

Retrieves live scores for ongoing football matches. Returns an empty list if no matches are currently being played. The `incidents` and `live_stats` fields might be null for newly started matches.

```APIDOC
## GET /api/live/

### Description
Retrieves live scores for ongoing football matches. Returns an empty list if no matches are currently being played. The `incidents` and `live_stats` fields might be null for newly started matches.

### Method
GET

### Endpoint
/api/live/

### Response
#### Success Response (200)
- **count** (integer) - The total number of live matches.
- **results** (array) - A list of live match objects.
  - **id** (integer) - The unique identifier for the match.
  - **home_team** (string) - The name of the home team.
  - **away_team** (string) - The name of the away team.
  - **home_score** (integer) - The current score for the home team.
  - **away_score** (integer) - The current score for the away team.
  - **current_minute** (integer) - The current minute of the match.
  - **period** (string) - The current period of the match (e.g., "1T", "2T").
  - **status** (string) - The current status of the match (e.g., "1st_half", "2nd_half").
  - **incidents** (array) - A list of incidents that occurred during the match (e.g., goals, cards, substitutions).
    - **type** (string) - The type of incident.
    - **minute** (integer) - The minute the incident occurred.
    - **player_name** (string) - The name of the player involved.
    - **is_home** (boolean) - Whether the incident involved the home team.
    - **card_type** (string, optional) - The type of card issued (if applicable).
    - **player_in** (string, optional) - The name of the player substituted in.
    - **player_out** (string, optional) - The name of the player substituted out.
    - **player_in_id** (integer, optional) - The ID of the player substituted in.
    - **player_out_id** (integer, optional) - The ID of the player substituted out.
  - **live_stats** (object) - Live statistics for the match.
    - **home** (object) - Home team statistics.
      - **ball_possession** (integer) - Ball possession percentage.
      - **total_shots** (integer) - Total shots taken.
      - **shots_on_target** (integer) - Shots on target.
      - **corner_kicks** (integer) - Number of corner kicks.
    - **away** (object) - Away team statistics.
      - **ball_possession** (integer) - Ball possession percentage.
      - **total_shots** (integer) - Total shots taken.
      - **shots_on_target** (integer) - Shots on target.
      - **corner_kicks** (integer) - Number of corner kicks.
  - **league** (object) - Information about the league.
    - **name** (string) - The name of the league.
    - **country** (string) - The country of the league.

### Request Example
```json
{
  "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"}
    }
  ]
}
```
```

--------------------------------

### Get Player Detail

Source: https://sports.bzzoiro.com/docs/v2

Retrieves details for a single player.

```APIDOC
## GET /api/v2/players/{id}/

### Description
Retrieves details for a single player. The response shape is the same as a list item from the `/api/v2/players/` endpoint.

### Method
GET

### Endpoint
/api/v2/players/{id}/
```

--------------------------------

### GET /api/leagues/

Source: https://sports.bzzoiro.com/docs

Returns all active leagues and tournaments. This endpoint is cached for 5 minutes and does not require any parameters.

```APIDOC
## GET /api/leagues/

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

### Method
GET

### Endpoint
/api/leagues/

### Parameters
None.

### Response
#### Success Response (200)
- **id** (integer) - Internal league ID
- **name** (string) - League name (e.g. "Premier League")
- **country** (string) - Country (e.g. "England")
- **is_women** (boolean) - True if this is a women's competition
- **current_season** (object | null) - Current season details: `{id, name, year, start_date, end_date}`. Null if no season is marked as current.

### Response Example
{
  "example": "{\"id\": 1, \"name\": \"World Cup\", \"country\": \"International\", \"is_women\": false, \"current_season\": {\"id\": 10, \"name\": \"2026\", \"year\": 2026, \"start_date\": \"2026-06-01\", \"end_date\": \"2026-07-19\"}}"
```

--------------------------------

### GET /api/managers/

Source: https://sports.bzzoiro.com/docs

Retrieves head coaches and managers with their tactical fingerprint and aggregated match statistics.

```APIDOC
## GET /api/managers/

### Description
Retrieves 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.

### Method
GET

### Endpoint
/api/managers/

### Parameters
#### Query Parameters
- **team_id** (integer) - Optional - Filter by team ID to fetch the manager for a specific team.

### Request Example
```
curl -H "Authorization: Token YOUR_API_KEY" \
     "https://sports.bzzoiro.com/api/managers/"
```

### Response
#### Success Response (200)
- **[manager_data]** (object) - An object where keys are manager IDs and values are manager details.
  - **tactical_styles** (object or null) - Derived tactical styles if enough data is available.
  - **pressing_intensity** (float or null) - Derived pressing intensity if enough data is available.
  - **defensive_line** (float or null) - Derived defensive line height if enough data is available.
  - **[other_aggregated_stats]** (various) - Other aggregated match statistics.

#### Response Example
(Response structure for managers is not fully detailed in the source, but would include manager details and potentially tactical fingerprints.)
```

--------------------------------

### GET /api/odds/compare/

Source: https://sports.bzzoiro.com/docs

Provides a side-by-side comparison for a single match, highlighting the best price per outcome.

```APIDOC
## GET /api/odds/compare/

### Description
Provides a side-by-side comparison for a single match, highlighting the best price per outcome.

### Method
GET

### Endpoint
/api/odds/compare/

### Parameters
#### Query Parameters
- **event** (integer) - Required - The ID of the event for which to compare odds.
```

--------------------------------

### Get Single Player Stat Record

Source: https://sports.bzzoiro.com/docs

Retrieves a single player stat record by its ID. This endpoint is detailed in the source text but lacks a specific path in the provided examples.

```APIDOC
## GET /api/player-stats/{id}/

### Description
Returns a single stat record for a player, identified by its unique ID.

### Method
GET

### Endpoint
/api/player-stats/{id}/

### Parameters
#### Path Parameters
- **id** (integer) - Required - The unique identifier for the player stat record.

### Response
#### Success Response (200)
Returns a single player stat object with all the fields described in the `/api/player-stats/` endpoint response.

### Note
The specific path for this endpoint is inferred from the detail provided in the source text.
```

--------------------------------

### Goal Build-up Sequence Example

Source: https://sports.bzzoiro.com/docs

This JSON snippet shows the 'sequence' field within the 'incidents' array, detailing the full passing chain leading to a goal, including player actions and coordinates.

```json
"incidents": [
  {
    "type": "goal", "player": "D. Fry", "minute": 26,
    "is_home": true, "assist": "A. Browne",
    "home_score": 1, "away_score": 0,
    "sequence": [
      {"player": "A. Morris", "event": "pass",
       "pos": {"x": 83.4, "y": 11.5},
       "end": {"x": 82.3, "y": 20.7}},
      {"player": "A. Browne", "event": "cross",
       "pos": {"x": 82.8, "y": 22.5},
       "end": {"x": 96.1, "y": 54.2}, "assist": true},
      {"player": "D. Fry", "event": "goal",
       "pos": {"x": 96.1, "y": 54.2}, "body": "head",
       "gm": {"y": 54.4, "z": 13.9},
       "gk": {"x": 99.5, "y": 51.4}}
    ]
  }
  // ... other incidents (cards, subs, etc.)
]
```

--------------------------------

### API Authentication Example

Source: https://sports.bzzoiro.com/docs

Include your API token in the Authorization header for authenticated requests. Unauthenticated requests will result in a 401 Unauthorized error.

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

--------------------------------

### WebSocket Subscription Examples

Source: https://sports.bzzoiro.com/docs/websocket

Demonstrates how to subscribe to and unsubscribe from real-time odds data via WebSocket. Supports both default consensus odds and specific bookmaker odds.

```javascript
// Default (consensus)
ws.send(JSON.stringify({
  action: "subscribe",
  event_id: 205764
}));

// Per-bookmaker — only Pinnacle quotes for this match
ws.send(JSON.stringify({
  action: "subscribe",
  event_id: 205764,
  bookmaker_slug: "pinnacle"
}));

// Stop the per-book stream (event/livedata stays)
ws.send(JSON.stringify({
  action: "unsubscribe",
  event_id: 205764,
  bookmaker_slug: "pinnacle"
}));
```

--------------------------------

### Live Events Query

Source: https://sports.bzzoiro.com/docs/v2

Fetch a live, lightweight list of events within their active window. This endpoint is optimized for high-frequency polling and is cached. Query parameters like status and date are ignored; only league_id, season_id, and team_id are considered.

```bash
curl -H "Authorization: Token $TOKEN" \
  "https://sports.bzzoiro.com/api/v2/events/live/?league_id=49"
```

--------------------------------

### Query Events by Date

Source: https://sports.bzzoiro.com/docs/v2

Retrieve a list of events within a specified date range. Ensure your authorization token is set.

```bash
curl -H "Authorization: Token $TOKEN" \
  "https://sports.bzzoiro.com/api/v2/events/?date_from=2026-05-15&date_to=2026-05-15"
```

--------------------------------

### Loading Static Images

Source: https://sports.bzzoiro.com/docs/v2

Examples of how to embed static images for players, teams, and leagues directly into HTML using the provided image proxy endpoints. Ensure the correct IDs are used from the respective API endpoints.

```html
<img src="https://sports.bzzoiro.com/img/player/12994/" alt="Bukayo Saka" />
<img src="https://sports.bzzoiro.com/img/team/42/"    alt="Arsenal" />
<img src="https://sports.bzzoiro.com/img/league/17/"  alt="Premier League" />
```

--------------------------------

### Live WebSocket Add-on Connection

Source: https://sports.bzzoiro.com/docs/v2

Connect to the real-time push stream for live matches using this WebSocket URL. The add-on supports up to 10 concurrent matches per socket.

```websocket
wss://sports.bzzoiro.com/ws/live/?token=YOUR_TOKEN
```

--------------------------------

### GET /api/odds/bookmakers/

Source: https://sports.bzzoiro.com/docs

Lists all bookmakers currently observed in the feed.

```APIDOC
## GET /api/odds/bookmakers/

### Description
Lists all bookmakers currently observed in the feed.

### Method
GET

### Endpoint
/api/odds/bookmakers/
```

--------------------------------

### GET /api/live/

Source: https://sports.bzzoiro.com/docs

Fetches live data for matches currently in progress. This includes real-time scores, the current minute of the match, significant incidents (goals, cards, substitutions), and live statistics. The `full` query parameter can be used to include detailed spatial data.

```APIDOC
## GET /api/live/

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

### Method
GET

### Endpoint
/api/live/

### Parameters
#### Query Parameters
- **tz** (string) - Optional - Timezone for dates (e.g. `Europe/Warsaw`). See Timezone Support
- **full** (boolean) - Optional - Set to `true` to include spatial data fields (`lineups`, `shotmap`, `momentum`, `average_positions`). Excluded by default for faster responses. Momentum and shotmap update in real time during the match.

### Response Fields
#### Success Response (200)
- **incidents** (array) - null - List of match incidents. Each item has `type` (`"goal"`, `"card"`, `"substitution"`), `minute`, `is_home`. Goals and cards also have `player_name`. Substitutions have `player_in` (substitute coming on) and `player_out` (player being replaced), plus `player_in_id` and `player_out_id`.
- **live_stats** (object) - null - Live statistics with `home` and `away` sub-objects containing: `ball_possession`, `total_shots`, `shots_on_target`, `corner_kicks`, `fouls`, `yellow_cards`, `red_cards`, `offsides`, etc.
- **home_xg_live** (float) - null - Home team total xG so far in the match (sum of per-shot xG from the live shotmap). Updates in real time alongside the shotmap. Returned by default — no `?full=true` needed — so xG-based live models don't have to fetch the full shotmap on every poll.
- **away_xg_live** (float) - null - Away team total xG so far in the match (sum of per-shot xG from the live shotmap). Updates in real time. Returned by default.
- **lineups** (array) - null - Team lineups with player positions. Each item: `{player_name, position, x, y, is_home}`. Requires `?full=true`. See Spatial Data.
- **shotmap** (array) - null - All shots so far in the match with per-shot xG and pitch coordinates. Each item: `{min, type, sit, body, home, xg, xgot, pos, gm, gml, pid}`. Updates in real time. Requires `?full=true`. See Spatial Data.
- **momentum** (array) - null - Minute-by-minute pressure index. Each item: `{m: minute (int), v: pressure (signed int)}`. Positive `v` = home dominance, negative = away. Updates every minute. Requires `?full=true`. See Spatial Data.
- **xg_per_minute** (array) - null - Per-minute xG buckets aggregated from the live shotmap. Each item: `{m, xg_home, xg_away, cum_home, cum_away}`. Updates in real time. Requires `?full=true`. See Spatial Data.
- **average_positions** (array) - null - Average pitch positions per player accumulated so far in the match. Requires `?full=true`. See Spatial Data.

### Request Example
```json
{
  "tz": "Europe/London",
  "full": true
}
```

### Response Example
```json
{
  "incidents": [
    {
      "type": "goal",
      "minute": 15,
      "is_home": true,
      "player_name": "Striker"
    }
  ],
  "live_stats": {
    "home": {
      "ball_possession": 60,
      "total_shots": 10,
      "shots_on_target": 5,
      "corner_kicks": 3,
      "fouls": 5,
      "yellow_cards": 1,
      "red_cards": 0,
      "offsides": 2
    },
    "away": {
      "ball_possession": 40,
      "total_shots": 5,
      "shots_on_target": 2,
      "corner_kicks": 1,
      "fouls": 7,
      "yellow_cards": 2,
      "red_cards": 0,
      "offsides": 0
    }
  },
  "home_xg_live": 1.23,
  "away_xg_live": 0.45,
  "lineups": [
    {"player_name": "Defender", "position": "DEF", "x": 70.5, "y": 30.1, "is_home": true}
  ],
  "shotmap": [
    {"min": 10, "type": "open_play", "sit": "normal", "body": "right_foot", "home": true, "xg": 0.15, "xgot": 0.08, "pos": {"x": 85.2, "y": 40.5}, "gm": 1, "gml": 1, "pid": 12345}
  ],
  "momentum": [
    {"m": 10, "v": 50},
    {"m": 11, "v": -20}
  ],
  "xg_per_minute": [
    {"m": 10, "xg_home": 0.15, "xg_away": 0.0, "cum_home": 0.15, "cum_away": 0.0}
  ],
  "average_positions": [
    {"player": "Midfielder", "pid": 67890, "pos": {"x": 55.0, "y": 50.0}, "number": 8}
  ]
}
```
```

--------------------------------

### Shotmap Data Example

Source: https://sports.bzzoiro.com/docs

This JSON snippet illustrates the structure of the 'shotmap' field, detailing per-shot expected goals (xG) with pitch coordinates for each shot in a match.

```json
"shotmap": [
  {
    "min": 26, "type": "goal", "sit": "corner", "body": "head",
    "home": true, "xg": 0.383, "xgot": 0.949,
    "pos": {"x": 3.9, "y": 45.8}, "gm": {"y": 54.4, "z": 13.9},
    "gml": "low-left", "pid": 548194
  },
  {
    "min": 53, "type": "save", "sit": "open-play", "body": "right-foot",
    "home": false, "xg": 0.071, "xgot": 0.023,
    "pos": {"x": 18.2, "y": 31.4}, "gm": {"y": 45.1, "z": 8.2},
    "gml": "centre", "pid": 219847
  }
  // ... all shots in the match
]
```

--------------------------------

### Get Single Manager

Source: https://sports.bzzoiro.com/docs

Retrieves details for a specific manager by their ID.

```APIDOC
## GET /api/managers/{id}/

### Description
Retrieves detailed information for a single manager identified by their unique ID.

### Method
GET

### Endpoint
/api/managers/{id}/

### Parameters
#### Path Parameters
- **id** (integer) - Required - The unique identifier of the manager.

### Response
#### Success Response (200)
Returns a single manager object with detailed statistics (same fields as the list endpoint).

### Response Example
```json
{
  "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
}
```
```

--------------------------------

### Retrieve Fixtures by Date and League

Source: https://sports.bzzoiro.com/docs

Fetches fixtures for a given date range and league. This endpoint is an alias for `/api/events/` and accepts the same parameters.

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

--------------------------------

### GET /api/events/

Source: https://sports.bzzoiro.com/docs

Retrieves a list of events with various filtering options.

```APIDOC
## GET /api/events/

### Description
Retrieves a list of events with various filtering options.

### Method
GET

### Endpoint
/api/events/

### Parameters
#### Query Parameters
- **date_from** (date) - Optional - Start date (YYYY-MM-DD). If omitted (and no `date_to`), defaults to today.
- **date_to** (date) - Optional - End date (YYYY-MM-DD). If omitted (and no `date_from`), defaults to today + 7 days.
- **league** (integer) - Optional - Filter by league `id` (get IDs from `/api/leagues/`).
- **season** (integer) - Optional - Filter by season `id` (get IDs from `/api/seasons/`). Bypasses the default 7-day window. E.g. `?season=42`.
- **team** (string) - Optional - Filter by team name (case-insensitive, partial match). E.g. `?team=Madrid`.
- **team_id** (integer) - Optional - Filter by team `id` (exact match, home or away). E.g. `?team_id=2932`.
- **status** (string) - Optional - Filter by status (see values below).
- **tz** (string) - Optional - Timezone for dates (e.g. `Europe/Warsaw`). See Timezone Support.
- **full** (boolean) - Optional - Set to `true` to include spatial data fields (`lineups`, `shotmap`, `momentum`, `average_positions`). Excluded by default for faster responses. Also applies to `GET /api/events/{id}/`.

### Status values
notstarted, inprogress, 1st_half, halftime, 2nd_half, finished, postponed, cancelled
```

--------------------------------

### Get Prediction Detail

Source: https://sports.bzzoiro.com/docs/v2

Retrieves the details of a specific prediction by its ID.

```APIDOC
## Prediction detail

### Description
Retrieves the details of a specific prediction by its ID. The response shape is the same as a list item from the predictions list.

### Method
GET

### Endpoint
/api/v2/predictions/{id}/

### Parameters
#### Path Parameters
- **id** (int) - Required - The ID of the prediction to retrieve.
```

--------------------------------

### List Leagues

Source: https://sports.bzzoiro.com/docs

Retrieves a list of all available leagues. Requires an API key for authorization.

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

```json
{
  "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"
      }
    },
    ...
  ]
}
```

--------------------------------

### Unavailable Lineup Response

Source: https://sports.bzzoiro.com/docs/v2

Example of a response when lineup data is unavailable for an event.

```json
{
  "event_id": 204851,
  "lineup_status": "unavailable",
  "beta": false,
  "lineups": null,
  "unavailable_players": null,
  "updated_at": null
}
```

--------------------------------

### GET /api/odds/polymarket/

Source: https://sports.bzzoiro.com/docs

Retrieves Polymarket prediction market prices, represented as probabilities between 0 and 1.

```APIDOC
## GET /api/odds/polymarket/

### Description
Retrieves Polymarket prediction market prices, represented as probabilities between 0 and 1.

### Method
GET

### Endpoint
/api/odds/polymarket/
```