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

Group: Leagues

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.

Plans: Requires Pro, Business or Enterprise; a Free or Starter key receives 403 endpoint_not_in_plan.

Note: 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

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | yes | league id issued by DataSportsAPI, a positive integer |
| `season` | query | yes | season id, as listed by /v2/leagues/{id}/seasons |
| `type` | query | no | 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 | no | 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 | no | how many entries each leaderboard returns, 1–50 (10 if omitted) |
| `page` | query | no | which slice of limit entries to return, 0–49; 0 (the default) starts at the leaders |

## Response

- `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)
- Objects: TopPlayersCategory (https://datasportsapi.com/markdown/reference.md#topplayerscategory)

## 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

Plus the common errors (https://datasportsapi.com/markdown/docs.md#errors).

## Request

cURL:

```bash
curl -H "Authorization: Bearer sk_live_…" \
    "https://api.datasportsapi.com/v2/leagues/{id}/top-players?season=…"
```

TypeScript:

```ts
const { data, meta } = await client.leagues.topPlayers(id, { season });
for await (const page of client.leagues.topPlayersPages(id, { season })) { … }
```

Python:

```python
res = client.leagues.top_players(id, season=season)
for page in client.leagues.top_players_pages(id, season=season): ...
```

Go:

```go
res, err := client.Leagues.TopPlayers(ctx, id, &datasportsapi.LeaguesTopPlayersParams{Season: season})
for page, err := range client.Leagues.TopPlayersPages(ctx, id, &datasportsapi.LeaguesTopPlayersParams{Season: season}) { … }
```

CLI:

```bash
$ dsa leagues top-players <id> --season <season>
$ dsa leagues top-players <id> --season <season> --all -o csv
```

## Example response

```json
{ "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 } }
```

---

Base URL: https://api.datasportsapi.com. Authenticate each /v2 call with the header `Authorization: Bearer <key>` (secret keys begin with `sk_live_`).
HTML: https://datasportsapi.com/docs/leagues/top-players/ · All docs: https://datasportsapi.com/markdown/docs.md · Data reference: https://datasportsapi.com/markdown/reference.md
