Docs / Football API free

Leagues, seasons & standings#

Everything competition-level lives here. The one habit to build: resolve the current season through the API (/leagues/{id}/season/) instead of hardcoding season ids.

List leagues#

GET /api/v2/leagues/

Param	Type	Description
`country`	string	Country name filter, e.g. `Argentina`
`is_women`	bool	Women's competitions only
`include_inactive`	bool	Also return leagues we no longer sync (hidden by default)
`limit` / `offset`	int	Pagination

curl -H "Authorization: Token YOUR_API_KEY" \
     "https://sports.bzzoiro.com/api/v2/leagues/?country=Argentina"

League detail#

GET /api/v2/leagues/{id}/          # cached 5 min

Seasons#

GET /api/v2/leagues/{id}/seasons/  # all seasons, cached 60 min
GET /api/v2/leagues/{id}/season/   # current season only, cached 30 min

{ "id": 1635, "name": "Primera LPF 2026", "year": 2026,
  "start_date": "2026-01-01", "end_date": "2026-12-31", "is_current": true }

Season ids feed the season_id filter on events, standings and leaderboards.

Standings#

GET /api/v2/leagues/{id}/standings/?season_id=1635    # cached 10 min

Rows carry position, team_id, team name, played, won/drawn/lost, goals for/against, points and recent form. Cup-style competitions return a groups array (one table per group) instead of a single table — handle both.

Leaderboards#

GET /api/v2/leagues/{id}/top/{stat}/    # cached 10 min

Param	Type	Description
`stat` (path)	string	`scorers` · `assists` · `yellowcards` · `redcards` · `fouls`
`season_id`	int	Defaults to the current season
`limit`	int	Default 20, max 50

Each row: rank, player_id, player_name, position, team_id, team_name, value, matches.

Best XI#

GET /api/v2/leagues/{id}/bestxi/{season_id}/                   # season best XI, cached 30 min
GET /api/v2/leagues/{id}/bestxi/{season_id}/{round_number}/    # matchday best XI, cached 10 min

Best-rated eleven in a formation layout — render straight onto a pitch graphic (combine with the Image API for faces).

Competition venues#

GET /api/v2/leagues/{id}/venues/?season_id=…
GET /api/v2/leagues/{id}/seasons/{season_id}/venues/

The second form is for tournament-style competitions and supports host_country_code, hosts_final, hosts_opening, hosts_third_place and round filters — built for World-Cup-style venue pages.