# GET /v2/leagues/{id}/standings

Group: Leagues

League tables for a single season. With no extra parameters you get the one table marked primary for the season — the league table, or in a group stage the first group; meta.overall tells you whether it includes every team. Add group=all to get every table (conferences, divisions, groups), or type=home / type=away for a table built from home or away games alone.

Plans: Every plan, Free included.

Note: A season may hold several tables, listed in our data source’s order — for example two conferences, four divisions and a league table in the NHL, two conferences and an overall table in MLS, and one table per group at a World Cup. Exactly one table is flagged primary and served by default — the league table if there is one, otherwise the largest table, and the first group when all are the same size. overall is true solely for a table that contains every team in the season. position always runs 1..n; we re-rank rows whenever the source’s numbering does not. A column that does not apply to a sport is null — the NBA ranks on winPercentage, so its points column is null; draws is null in any table where a draw is impossible (basketball, ice hockey, baseball, volleyball, …); overtimeLosses is filled in ice hockey; scoresFor / scoresAgainst are measured in scoreUnit (goals, points, runs, sets, …); streak (+3 means three straight wins, −2 two straight losses) appears where the source provides it (NBA, EuroLeague, Liga ACB, …). form, added on 2026-10-24, lists up to five of the team’s most recent results in this competition season, oldest first — only home or only away results in the home / away tables — and is null where the source has none. Football publishes split home / away tables, and so do a number of basketball, handball, volleyball and ice-hockey competitions — the KHL, the SuperLega, Liga ACB, the EuroLeague and the Handball-Bundesliga among them. The NBA and NHL publish none and the NFL stops updating its versions, so for those three sports (basketball, ice hockey, American football) we compute them ourselves (meta.source computed) from the finished regular-season fixtures: a home row counts only home games, an away row only away games. They carry only the columns that the same method, run over every game, reproduces exactly for the overall table (NBA: wins, losses, winPercentage, gamesBehind within each table, scores; NFL: wins, losses, draws, winPercentage, scores; NHL: wins, losses, overtimeLosses — defeats in overtime or a shoot-out — and points at 2 per win plus 1 per overtime loss, scores). In those sports a published home / away table that lacks games is swapped for the computed one. In winPercentage a tie is worth half a win. Rows are ordered by points or win share, with ties broken by wins and then score difference — head-to-head is never used. Updated once a day.

## Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | yes | league id issued by DataSportsAPI, a positive integer |
| `season` | query | yes | season id, as listed by /v2/leagues/{id}/seasons |
| `group` | query | no | pass all to get the season’s complete set of tables, typed StandingsGroup[] |
| `type` | query | no | which games count: overall (all of them; the default), home or away (only that side’s games); total, the old name for overall, keeps working for one more release |

## Response

- `data`: `StandingsRow[] (default) | StandingsGroup[] (group=all)`
- `meta`: season, type, source (upstream = taken from our data source, computed = derived by us from the fixtures), count (number of rows, or of tables with group=all); without group=all it also includes group (name of the table), groupCount (number of tables in the season), overall (true if the table includes every team), tieBreakRule, scoreUnit
- Objects: StandingsRow (https://datasportsapi.com/markdown/reference.md#standingsrow), StandingsGroup (https://datasportsapi.com/markdown/reference.md#standingsgroup)

## Errors

- 400 bad_request — one of: season missing or invalid; a group value other than all; a type outside overall|home|away
- 404 no_data — this season lacks that table at the source (a home / away table it never publishes, say — except in basketball, ice hockey and American football, where we compute it); 404 not_found — DataSportsAPI never issued this id
- 404 not_found — the season id does not belong to this league; the error message names the offending parameter, and /v2/leagues/{id}/seasons lists the valid ones

Plus the common errors (https://datasportsapi.com/markdown/docs.md#errors).

## Request

cURL:

```bash
curl -H "Authorization: Bearer sk_live_…" \
    "https://api.datasportsapi.com/v2/leagues/{id}/standings?season=…"
```

TypeScript:

```ts
const { data, meta } = await client.leagues.standings(id, { season });
```

Python:

```python
res = client.leagues.standings(id, season=season)
```

Go:

```go
res, err := client.Leagues.Standings(ctx, id, &datasportsapi.LeaguesStandingsParams{Season: season})
```

CLI:

```bash
$ dsa leagues standings <id> --season <season>
```

## Example response

```json
{ "data": [ { "position": 1, "team": { "id": 4438, "name": "Manchester City", … },
    "played": 7, "wins": 7, "draws": 0, "losses": 0, "overtimeWins": null, "overtimeLosses": null,
    "scoresFor": 19, "scoresAgainst": 7, "scoreDifference": 12, "points": 21,
    "winPercentage": null, "gamesBehind": null, "zone": "Champions League", "form": ["win", "win", "win", "win", "win"] }, … ],
  "meta": { "season": 200386, "type": "overall", "source": "upstream", "group": "Premier League 26/27", "groupCount": 1,
            "count": 20, "overall": true, "tieBreakRule": null, "scoreUnit": "goals" } }
```

---

Base URL: https://api.datasportsapi.com. Authenticate each /v2 call with the header `Authorization: Bearer <key>` (secret keys begin with `sk_live_`).
HTML: https://datasportsapi.com/docs/leagues/standings/ · All docs: https://datasportsapi.com/markdown/docs.md · Data reference: https://datasportsapi.com/markdown/reference.md
