Leagues

Get a list of available leagues with optional sport filtering.


GET /api/v1/leagues

Requires an API key. Available on all tiers (Free included). Unauthenticated requests return 401.

Query ParametersPermalink for this section

Parameter	Type	Default	Description
`sport`	string	all	Filter by sport (e.g., `basketball`, `football`)

Example RequestsPermalink for this section

cURL


# List all leagues
curl -X GET "https://api.sharpapi.io/api/v1/leagues" \
  -H "X-API-Key: YOUR_API_KEY"
 
# Filter by sport
curl -X GET "https://api.sharpapi.io/api/v1/leagues?sport=basketball" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript


const response = await fetch(
  'https://api.sharpapi.io/api/v1/leagues?sport=basketball',
  { headers: { 'X-API-Key': 'YOUR_API_KEY' } },
);
const { data, meta } = await response.json();
 
data.forEach(league => {
  console.log(`${league.name} (${league.sport}): ${league.event_count} events`);
});

Python


import requests
 
response = requests.get(
    'https://api.sharpapi.io/api/v1/leagues',
    params={'sport': 'basketball'},
    headers={'X-API-Key': 'YOUR_API_KEY'},
)
result = response.json()
 
for league in result['data']:
    print(f"{league['name']} ({league['sport']}): {league['event_count']} events")

ResponsePermalink for this section

Success (200)Permalink for this section


{
  "data": [
    {
      "id": "nba",
      "numerical_id": 87,
      "name": "NBA",
      "sport": "basketball",
      "event_count": 15,
      "live_count": 2
    },
    {
      "id": "ncaab",
      "numerical_id": 88,
      "name": "NCAAB",
      "sport": "basketball",
      "event_count": 27,
      "live_count": 1
    },
    {
      "id": "wnba",
      "numerical_id": 89,
      "name": "WNBA",
      "sport": "basketball",
      "event_count": 0,
      "live_count": 0
    }
  ],
  "meta": {
    "count": 3,
    "total": 3,
    "pagination": {
      "limit": 50,
      "offset": 0,
      "has_more": false,
      "next_offset": null
    },
    "updated_at": "2026-01-26T12:00:00Z",
    "filters": {
      "sport": "basketball"
    }
  }
}

All Leagues (No Filter)Permalink for this section


{
  "data": [
    {
      "id": "nba",
      "name": "NBA",
      "sport": "basketball",
      "event_count": 15,
      "live_count": 2
    },
    {
      "id": "ncaab",
      "name": "NCAAB",
      "sport": "basketball",
      "event_count": 27,
      "live_count": 1
    },
    {
      "id": "wnba",
      "name": "WNBA",
      "sport": "basketball",
      "event_count": 0,
      "live_count": 0
    },
    {
      "id": "nfl",
      "name": "NFL",
      "sport": "football",
      "event_count": 16,
      "live_count": 1
    },
    {
      "id": "ncaaf",
      "name": "NCAAF",
      "sport": "football",
      "event_count": 12,
      "live_count": 0
    },
    {
      "id": "nhl",
      "name": "NHL",
      "sport": "hockey",
      "event_count": 15,
      "live_count": 2
    },
    {
      "id": "mlb",
      "name": "MLB",
      "sport": "baseball",
      "event_count": 0,
      "live_count": 0
    },
    {
      "id": "epl",
      "name": "English Premier League",
      "sport": "soccer",
      "event_count": 10,
      "live_count": 2
    },
    {
      "id": "la_liga",
      "name": "La Liga",
      "sport": "soccer",
      "event_count": 10,
      "live_count": 1
    },
    {
      "id": "serie_a",
      "name": "Serie A",
      "sport": "soccer",
      "event_count": 10,
      "live_count": 1
    },
    {
      "id": "bundesliga",
      "name": "Bundesliga",
      "sport": "soccer",
      "event_count": 5,
      "live_count": 0
    },
    {
      "id": "mls",
      "name": "MLS",
      "sport": "soccer",
      "event_count": 0,
      "live_count": 0
    },
    {
      "id": "atp",
      "name": "ATP",
      "sport": "tennis",
      "event_count": 12,
      "live_count": 4
    },
    {
      "id": "wta",
      "name": "WTA",
      "sport": "tennis",
      "event_count": 6,
      "live_count": 2
    },
    {
      "id": "ufc",
      "name": "UFC",
      "sport": "mma",
      "event_count": 12,
      "live_count": 0
    },
    {
      "id": "pga",
      "name": "PGA Tour",
      "sport": "golf",
      "event_count": 4,
      "live_count": 1
    }
  ],
  "meta": {
    "count": 16,
    "total": 16,
    "pagination": {
      "limit": 50,
      "offset": 0,
      "has_more": false,
      "next_offset": null
    },
    "updated_at": "2026-01-26T12:00:00Z",
    "filters": {}
  }
}

League Object SchemaPermalink for this section

Field	Type	Description
`id`	string	League identifier (lowercase, use in API filters)
`numerical_id`	integer \| null	Stable integer key for the league (frozen, never reused). New (May 2026) — additive, optional. See Entity reference IDs.
`name`	string	Human-readable league name
`sport`	string	Parent sport ID
`event_count`	integer	Total events currently available with odds
`live_count`	integer	Events currently live/in-play

New (May 2026): `numerical_id`Permalink for this section

numerical_id is a frozen, dense-from-1 integer assigned per league in the SharpAPI atlas. The full registry currently spans ~1,000 leagues across all 19 sports. Use it as a compact join/index key when storing rows in your own database.

Frozen: never reused or remapped.
Optional: absent (or null) for leagues that haven’t been mapped yet — slug id is always present.
Domain-scoped: unique across leagues only.

Every odds row and opportunity leg also carries a matching league_ref block ({id, label, numerical_id}) so you don’t need to second-fetch this endpoint just to label a row. See Entity reference IDs for the full contract.

Common LeaguesPermalink for this section

The endpoint is the canonical source of truth — call GET /api/v1/leagues for the complete, up-to-date list. The atlas registry catalogs 600+ leagues across 30+ sports including UEFA continental competitions, multiple basketball circuits per country, and full tennis/golf/MMA/esports/cricket coverage. The illustrative subset below shows the highest-volume entries you’ll typically filter on:

Sport	Common league IDs
Basketball	`nba`, `ncaab`, `wnba`
Football	`nfl`, `ncaaf`
Hockey	`nhl`
Baseball	`mlb`
Soccer	`england_-_premier_league`, `spain_-_la_liga`, `italy_-_serie_a`, `germany_-_bundesliga`, `france_-_ligue_1`, `uefa_-_champions_league`, `usa_-_major_league_soccer`
Tennis	`atp`, `wta`, `atp_challenger`, `itf_men`, `itf_women`
MMA	`ufc`, `pfl`
Golf	`pga`, `liv`, `dp_world_tour`, `lpga`

League IDs use canonical slug form (england_-_premier_league, not epl). Some short forms are accepted as filter input for backward compatibility, but the canonical slug is what /leagues returns and what other endpoints emit on response payloads.
The event_count and live_count values are dynamic. Off-season leagues (e.g., MLB in winter, WNBA in fall) show 0 events but stay in the catalog.
For programmatic access (e.g. building dropdown filters), call /api/v1/leagues and use the response — never hard-code a list.

Using Leagues in FiltersPermalink for this section

Use the league id as a filter parameter on other endpoints:


# Get NBA odds
curl "https://api.sharpapi.io/api/v1/odds?league=nba" \
  -H "X-API-Key: YOUR_API_KEY"
 
# Get best odds for NFL and NBA
curl "https://api.sharpapi.io/api/v1/odds/best?league=nfl,nba" \
  -H "X-API-Key: YOUR_API_KEY"

Sports - List available sports
Odds Snapshot - Filter odds by league
Events - Filter events by league