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

Group: Leagues

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

Plans: Every plan, Free included.

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

| 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`: `TopTeamsCategory[]`
- `meta`: season, type (the value actually applied), category (null when every leaderboard is included), limit, page, count (how many categories), hasNextPage
- Objects: TopTeamsCategory (https://datasportsapi.com/markdown/reference.md#topteamscategory)

## 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
- 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-teams?season=…"
```

TypeScript:

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

Python:

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

Go:

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

CLI:

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

## Example response

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

---

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-teams/ · All docs: https://datasportsapi.com/markdown/docs.md · Data reference: https://datasportsapi.com/markdown/reference.md
