v1 API (legacy)#
The original football API lives at /api/ and keeps working — its URLs are
frozen for compatibility. New projects should use
v2: v2 has more resources (transfers, referees'
matches, best XI, comparison grids), cleaner shapes and better caching.
What v1 offers#
Base URL: https://sports.bzzoiro.com/api/
| Endpoint | Notes |
|---|---|
GET /api/leagues/ · /{id}/ · /{id}/standings/ |
standings takes ?season= |
GET /api/teams/ · /{id}/ |
country, league, in_competition |
GET /api/events/ (aliases /fixtures/, /matches/) |
league, season, team, status, date_from/to, full=true expands lineups/stats, tz shifts datetimes |
GET /api/live/ |
Live matches, full, tz |
GET /api/predictions/ |
league, upcoming, date_from/to |
GET /api/players/ · /{id}/ |
search, team, nationality, position |
GET /api/player-stats/ |
player, event, team |
GET /api/odds/ + /compare/ + /best/ + /bookmakers/ + /polymarket/ |
Decimal odds |
GET /api/managers/ · /{id}/ |
search, team_id, profile, team_style |
GET /api/seasons/ |
league, current=true — also handy from v2 code |
GET /api/venues/ · /{id}/ |
city, country, min_capacity |
GET /api/tv-channels/ · /broadcasts/ |
TV data |
GET /api/referees/ |
league, name |
GET /api/predicted-lineup/{event_id}/ |
Predicted XI with confidence |
GET /api/social/ |
Deprecated — use /api/v2/social/ (v1 allowed anonymous access and extra types; v2 restricts to tweet/video) |
v1 uses page-number pagination (?page=) with page size 50, unlike v2's
limit/offset.
Differences that bite when migrating#
| Topic | v1 | v2 |
|---|---|---|
| Pagination | ?page= |
?limit=&offset= (max 200) |
| Timezones | ?tz= shifts datetimes |
Always UTC |
| Filters | league, season, team |
league_id, season_id, team_id |
| Expansion | ?full=true inlines lineups/stats |
Explicit sub-resources per concern |
| Social | Anonymous, includes news | Token required, tweet/video only |
| Players in spatial data | player_id — same ids as v2 |
player_id |
Player references in shotmap, average positions and incidents#
Both versions now name players by our player id — the one
/api/players/{id}/ and /api/v2/players/{id}/ answer to — under the key
player_id, and null when the player is not in our database.
v1 used to publish a pid key instead, holding an internal reference that was
never a valid player id here: joining it against /api/players/ returned
either nothing or, in about one case in twenty, a completely unrelated player
with no error to show for it. If you built against pid, read player_id and
the join works. The same applies to incidents, where player_id,
player_in_id, player_out_id and each sequence step now hold our ids too.
The complete v1 surface is browsable in Swagger UI and ReDoc.