Skip to content
datasportsAPI

LeaguesTop teams

Documentation

/

Type to filter the docs by title or path.

LeaguesEndpoint 78 of 116

Top teams

GET

/v2/leagues/{id}/top-teams

Plan
All plans
Auth
Bearer dsa_live_…
Parameters
2 required · 4 optional
Returns
TopTeamsCategory[]
Try in Playground

Per-statistic team leaderboards for a season — average rating, goals scored, clean sheets, possession and more — paged the same way as top-players.

Worth knowing

  • Paging works as in /top-players, with limit teams on each leaderboard (10 by default).
  • Which categories exist depends on the sport; they are named after the statistic keys used by the team statistics.
  • statistic names the key inside each entry’s statistics that the leaderboard ranks by.
  • matches is null whenever our data source reports 0 alongside non-zero totals.
  • Leagues, seasons or types without leaderboards yield an empty array.

01Parameters

  • idpathRequired

    league id issued by DataSportsAPI, a positive integer

  • seasonqueryRequired

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

  • typequeryOptional

    overall \| home \| away \| regularSeason \| playoffs. When omitted, the season’s own default applies: overall if the season has it (football), otherwise regularSeason (NBA, NHL, …); meta.type reports the value used

  • categoryqueryOptional

    restricts the response to one leaderboard, given as one of this season’s categories (e.g. goals); an unknown value returns 400 with the season’s categories listed

  • limitqueryOptional

    how many entries each leaderboard returns, 1–50 (10 if omitted)

  • pagequeryOptional

    which slice of limit entries to return, 0–49; 0 (the default) starts at the leaders

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}/top-teams?season=…"

03Response

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

data
TopTeamsCategory[]
meta
season, type (the value actually applied), category (null when every leaderboard is included), limit, page, count (how many categories), hasNextPage
ObjectsTopTeamsCategory
Example response
{ "data": [ { "category": "averageRating", "statistic": "averageRating", "teams": [
      { "team": { "id": 4438, "name": "Manchester City", "code": "MCI", "image": "…", … },
        "value": 7.02, "matches": 7, "statistics": { "averageRating": 7.02, "matches": 7 } }, … ] },
    { "category": "goalsScored", "statistic": "goalsScored", "teams": [ … ] }, … ],
  "meta": { "season": 200386, "type": "overall", "category": null, "limit": 10, "page": 0, "count": 12, "hasNextPage": true } }

04Errors

  • 400bad_request

    one of: season missing or invalid; type outside overall, home, away, regularSeason, playoffs; limit not in 1–50; page not in 0–49; category unknown

  • 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