Skip to content

Livematches in play

Demo: Matchboard, opens in a new tab
Docs v2

Leagues

Top players

GET

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

Pro and up

View as MarkdownTry in Playground →

Season leaderboards per statistic (rating, goals, assists, xG, tackles, saves and more; up to 50 players each at our data source), paged with limit players per board (10 by default), or one board via category.

Paging slices every leaderboard at the same places, so page 1 with limit 10 returns places 11–20 of each one. For a statistic’s complete top 50, request category=goals&limit=50 (a single leaderboard, about 20 KB) rather than every leaderboard at that depth (32 in football, roughly 550 KB at 50 entries each). The available categories depend on the sport (around 30 in football; points, rebounds, assists, … in basketball) and reuse the statistic key names (averageRating, goals, cleanSheets, goalInvolvements, …). statistic tells you which key inside each entry’s statistics the leaderboard is ranked on — football’s mostConceded / leastConceded, for instance, rank on goalsConceded. If type is omitted, the season’s default applies (regularSeason for the NBA, NHL, …). Leagues, seasons or types that have no 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 (true while at least one leaderboard has entries past this page)
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 unknown (the message then lists the season’s categories)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

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-players?season=…"
Example
{ "data": [ { "category": "goals", "statistic": "goals", "players": [
      { "player": { "id": 3801, "name": "Erling Haaland", "image": "…", … },
        "team": { "id": 4438, "name": "Manchester City", "code": "MCI", "image": "…", … },
        "value": 8, "appearances": 7, "playedEnough": true, "statistics": { "goals": 8, "appearances": 7 } }, … ] },
    { "category": "averageRating", "statistic": "averageRating", "players": [ … ] }, … ],
  "meta": { "season": 200386, "type": "overall", "category": null, "limit": 10, "page": 0, "count": 32, "hasNextPage": true } }