Skip to content

Livematches in play

Demo: Matchboard, opens in a new tab
Docs v2

Leagues

Top teams

GET

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

All plans

View as MarkdownTry 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.

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.

Parameters

id

pathrequired

league id issued by DataSportsAPI, a positive integer

season

queryrequired

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

type

query

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

category

query

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

limit

query

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

page

query

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

Response

meta
season, type (the value actually applied), category (null when every leaderboard is included), limit, page, count (how many categories), hasNextPage
errors
400 bad_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 unknown404 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

Any /v2 call can also come back with one of the common errors.

curl -H "Authorization: Bearer sk_live_…" \
    "https://api.datasportsapi.com/v2/leagues/{id}/top-teams?season=…"
Example
{ "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 } }