Skip to content
datasportsAPI

LeaguesStandings

Documentation

/

Type to filter the docs by title or path.

LeaguesEndpoint 72 of 116

Standings

GET

/v2/leagues/{id}/standings

Plan
All plans
Auth
Bearer dsa_live_…
Parameters
2 required · 2 optional
Returns
An object (see Response)
Try in Playground

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.

Worth knowing

  • 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.

01Parameters

  • idpathRequired

    league id issued by DataSportsAPI, a positive integer

  • seasonqueryRequired

    season id, as listed by /v2/leagues/{id}/seasons

  • groupqueryOptional

    pass all to get the season’s complete set of tables, typed StandingsGroup[]

  • typequeryOptional

    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

02Request

The same call from the command line and each SDK. The SDK lines assume a client created with your key; left out, it is read from DATASPORTSAPI_API_KEY. Installing a client: SDKs & CLI.

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

03Response

The top-level keys of the JSON body. Each object links to its full shape in the data reference.

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
ObjectsStandingsRowStandingsGroup
Example response
{ "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" } }

04Errors

  • 400bad_request

    one of: season missing or invalid; a group value other than all; a type outside overall|home|away

  • 404no_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

  • 404not_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

Any key can also meet401unauthorized429rate_limited429quota_exceeded500internal_errorEvery error code