---
title: Leagues, seasons & standings
description: League lists, current-season resolution, standings tables, leaderboards, best XI and competition venues.
badge: 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 |

```bash
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
```

```json
{ "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](/docs/football/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](/docs/images/) 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.

## See also

- [Build a league page](/docs/guides/league-page/) — these endpoints
  assembled into a working page
- Season objects are also queryable globally: `GET /api/seasons/?league=85`
  and `?current=true` on the [v1 API](/docs/football/v1/)