Skip to content
datasportsAPI

LeaguesTop players

Documentation

/

Type to filter the docs by title or path.

LeaguesEndpoint 75 of 116

Top players

GET

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

Plan
Pro + Business
Auth
Bearer dsa_live_…
Parameters
2 required · 4 optional
Returns
TopPlayersCategory[]
Try in Playground

Per-statistic player leaderboards for a season — rating, goals, xG, assists, tackles, saves and more, each holding up to 50 players at our data source. Results are paged with limit players on every leaderboard (10 by default); use category to fetch a single leaderboard.

Plan access

Requires a Pro or Business plan; every other plan receives 403 endpoint_not_in_plan.

Worth knowing

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

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-players?season=…"

03Response

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

data
TopPlayersCategory[]
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)
ObjectsTopPlayersCategory
Example response
{ "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 } }

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 (the message then lists the season’s categories)

  • 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