> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sportsapipro.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Leagues & Standings

> League discovery, categories, standings, top scorers, outright markets, and bookmaker offers

## Leagues

```
GET /api/v1/leagues
GET /api/v1/leagues?sport=football&topOnly=1&geoCode=US
```

| Param     | Type   | Default | Description                               |
| --------- | ------ | ------- | ----------------------------------------- |
| `sport`   | string | *(all)* | Sport slug                                |
| `topOnly` | string | `"0"`   | `"1"` returns only top / popular leagues  |
| `geoCode` | string | `"US"`  | Geographic region for popularity ordering |

```json theme={null}
{
  "leagues": [
    {
      "id": 1,
      "name": "UEFA Champions League",
      "slug": "champions-league",
      "sportId": 1,
      "categoryId": 574,
      "categoryName": "Europe",
      "matchCountPrematch": 16,
      "matchCountInplay": 0,
      "order": 100,
      "isTop": true
    }
  ]
}
```

Cache TTL: **10 minutes**.

***

## Categories

```
GET /api/v1/categories
GET /api/v1/categories?sport=football
```

Returns categories (countries / regions) with current match counts.

| Param       | Type   | Default    | Description |
| ----------- | ------ | ---------- | ----------- |
| `sport`     | string | `football` | Sport slug  |
| `startDate` | string | today      | ISO 8601    |
| `endDate`   | string | today      | ISO 8601    |

Cache TTL: **10 minutes**.

***

## League Standings

```
GET /api/v1/league/{leagueId}/standings
GET /api/v1/league/{leagueId}/standings?season=131129
```

| Param    | Type   | Description                                         |
| -------- | ------ | --------------------------------------------------- |
| `season` | number | Optional season ID — defaults to the current season |

```json theme={null}
{
  "hasGroupType": false,
  "standings": {
    "UEFA Champions League": {
      "total": [
        {
          "rank": 1,
          "rank_movement": 0,
          "current_outcome": "Playoffs",
          "played": "8",
          "win": "8",
          "draw": "0",
          "loss": "0",
          "goals_for": "23",
          "goals_against": "4",
          "goal_diff": "19",
          "points": "24",
          "form": "WWWDW?",
          "team_id": 2536,
          "team_name": "Arsenal",
          "team_abbr": "ARS"
        }
      ]
    }
  }
}
```

Cache TTL: **10 minutes**.

***

## Top Scorers

```
GET /api/v1/league/{leagueId}/top-scorers
```

```json theme={null}
{
  "teams":   { "1": { "id": 1, "name": "Real Madrid" } },
  "players": { "101": { "id": 101, "name": "Robert Lewandowski", "team_id": 3 } },
  "scorers": [ { "player_id": 101, "goals": 12, "assists": 5, "matches": 8 } ]
}
```

Cache TTL: **10 minutes**.

***

## League Outrights

```
GET /api/v1/league/{leagueId}/outrights
```

Returns outright / futures markets (e.g. league winner, group winner, top scorer).

```json theme={null}
{
  "oddsGroups": [
    { "id": 1500, "name": "Winner", "has_handicap": false }
  ],
  "maxOdds": {
    "1500": [
      {
        "team_name": "Arsenal",
        "team_id": 2536,
        "odd": { "val": 3.25, "bid": 170, "bookie_name": "Stake.com" },
        "count": 7
      }
    ]
  }
}
```

| Field        | Description                                |
| ------------ | ------------------------------------------ |
| `oddsGroups` | Available outright markets                 |
| `maxOdds`    | Keyed by odds group ID, best odds per team |
| `odd.val`    | Best available price                       |
| `count`      | Number of bookmakers offering this market  |

Cache TTL: **5 minutes**.

***

## League Special Offers

```
GET /api/v1/league/{leagueId}/special-offers?sport=football&category=europe&league=champions-league
```

| Param      | Type   | Default    | Description   |
| ---------- | ------ | ---------- | ------------- |
| `sport`    | string | `football` | Sport slug    |
| `category` | string | *(none)*   | Category slug |
| `league`   | string | *(none)*   | League slug   |

```json theme={null}
{
  "specialOffers": [
    { "id": 1, "bookmaker_name": "bet365", "title": "Bet $1 Get $200", "link": "https://..." }
  ],
  "welcomeBonuses": []
}
```

Cache TTL: **1 hour**.

***

## Example

```bash theme={null}
curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.sportsapipro.com/v4/football/league/627/standings"
```