Events & live scores#
An event is one match. The list endpoint answers "which matches", the detail and sub-resources answer "everything about this match".
List matches#
GET /api/v2/events/
| Param | Type | Description |
|---|---|---|
league_id |
int | Filter by league |
season_id |
int | Filter by season (use for "this season's fixtures") |
team_id |
int | Matches of one team (home or away) |
team_name |
string | Fuzzy team-name filter when you don't have the id |
status |
string | upcoming · live · finished · cancelled · postponed |
date_from / date_to |
date | YYYY-MM-DD window (inclusive) |
limit / offset |
int | Pagination, default 50, max 200 |
curl -H "Authorization: Token YOUR_API_KEY" \
"https://sports.bzzoiro.com/api/v2/events/?league_id=85&status=upcoming&limit=10"
Live matches#
GET /api/v2/events/live/
Optional league_id, season_id, team_id. Returns a compact live shape —
score, period, current_minute, half-time score, penalty shootout state —
plus two capability flags:
live_websocket— this match can be followed on the WebSocketwebsocket_plus— full per-action coverage (individual events with pitch coordinates) is available for it
Server-cached ~10–30 s; poll at 10 s or subscribe to the WebSocket.
Match detail#
GET /api/v2/events/{id}/
Everything static about the match: teams (ids + names), coaches, referee,
venue, round/group, kickoff time, scores (FT/HT/ET/pens), weather, pitch
condition, attendance, derby/neutral-ground flags, travel distance,
highlights and a head-to-head summary. Also has_xg (whether shot-level xG
exists for this match) and previous_leg_event_id — set when the match is
the second leg of a two-legged knockout tie, pointing at the first leg's
event id.
Sub-resources#
Every deeper view of a match is its own endpoint under
/api/v2/events/{id}/…:
| Endpoint | Returns |
|---|---|
/stats/ |
Team stats (possession, shots, xG — per half where available), per-shot shotmap, momentum graph, average player positions, xG-per-minute series |
/lineups/ |
Confirmed XI + bench, each player flagged captain: true/false; before lineups are announced, an AI-predicted XI with confidence scores (never predicted for live/finished matches) |
/incidents/ |
Chronological goals, cards, substitutions, VAR decisions — each stamped with period_second for sub-minute ordering. Cards can carry rescinded: true when a card is overturned on review; overturned cards stay in the timeline but are excluded from card counts |
/player-stats/ |
Per-player match statistics, including an Advanced category (big chances, xG on target, ball-carry progression, goalkeeper sweeper actions) |
/h2h/ |
Past meetings, W/D/L, goals, win rates, recent results |
/odds/ |
Consensus decimal odds per market |
/odds/comparison/ |
Per-market × per-bookmaker grid |
/polymarket/ |
Prediction-market implied probabilities (0–1) |
/prediction/ |
Model probabilities per market (same shape as /api/v2/predictions/{id}/) |
/metadata/ |
Kit colours, fun facts, AI-generated match preview |
/broadcasts/ |
TV broadcasters, filterable by country_code |
/social/ |
Curated tweets/videos for the match (type filter) |
curl -H "Authorization: Token YOUR_API_KEY" \
"https://sports.bzzoiro.com/api/v2/events/223510/stats/"
{
"event_id": 223510,
"stats": {
"home": { "possession": 54, "shots_total": 13, "shots_on_target": 5, "xg": 1.62, "...": "..." },
"away": { "possession": 46, "shots_total": 9, "shots_on_target": 3, "xg": 0.88, "...": "..." },
"first_half": { "...": "..." }
},
"shotmap": [
{ "player_id": 40112, "minute": 23, "x": 88.2, "y": 44.1, "xg": 0.34, "result": "goal" }
],
"momentum": [ { "minute": 1, "value": 12 }, { "minute": 2, "value": -4 } ],
"average_positions": { "home": [ { "player_id": 40112, "x": 61.5, "y": 38.0 } ] },
"xg_per_minute": [ { "minute": 23, "home": 0.34, "away": 0.0 } ]
}
Note: shot-level xG and average positions exist for covered competitions; for others the arrays are empty rather than missing — code defensively either way.
Typical patterns#
- Match center page: detail +
/stats/+/incidents/+/lineups/on load; then poll/api/v2/events/live/?league_id=…or use the WebSocket for updates. - Fixtures widget: list with
season_id+status=upcoming, group byround_number. - Result + odds recap: list with
status=finished+/odds/per match.