🏆Leagues
Access comprehensive league data through the Sportmonks Football API. The Leagues endpoints provide information about domestic and international football competitions.
Overview
Every continent has countries, every country has one or multiple leagues, and every league has one or more seasons. For most applications, the leagues endpoint serves as the starting point for accessing football data. Use these endpoints to gather complete overviews of all available leagues within your subscription, retrieve basic league information, or enrich your response with season and fixture data.
Available Endpoints
There are 6 league endpoints available, each serving specific use cases:
GET All Leagues: Returns all leagues accessible within your subscription
GET League by ID: Returns a single league by its unique identifier
GET Leagues by Live: Returns leagues currently with live fixtures
GET Leagues by Fixture Date: Returns leagues with fixtures on a specific date
GET Leagues by Country ID: Returns all leagues from a specific country
GET Leagues Search by Name: Returns leagues matching your search query
Understanding league structures
Football leagues have fundamentally different organisational structures depending on the competition type. Understanding these structures is crucial for correctly requesting and displaying data such as standings, fixtures, and statistics.
The hierarchy
Every league follows a hierarchical structure:
League
└── Season (e.g., "2025/2026")
└── Stage(s) (e.g., "Regular Season", "Group Stage", "Quarter-finals")
└── Round(s) (e.g., "Round 1", "Round 2", "Matchweek 15")
└── Group(s) (optional - e.g., "Group A", "Group B")
└── Fixtures (individual matches)Key components:
League: The competition itself (e.g., Premier League, Champions League)
Season: A specific edition of the league (e.g., 2024/2025, 2023/2024)
Stage: A distinct phase within a season (e.g., "Regular Season", "Playoffs", "Group Stage", "Semi-finals")
Round: A specific matchday or game week within a stage
Group: Optional groupings within stages (used in tournaments with group phases)
Fixture: An individual match between two teams
League classification by structure
Different leagues are organized in distinct ways. Here's how to identify and work with each structure type:
1. Simple domestic leagues
Characteristics:
Single "Regular Season" stage
Round-robin format where every team plays every other team twice (home and away)
Sequential rounds representing match weeks
One unified standings table
Stage type: Group stage (type_id: 223)
Examples: English Premier League, La Liga, Serie A, Bundesliga
Structure:
League: English Premier League (league_id: 8)
└── Season: 2025/2026
└── Stage: "Regular Season" (Group Stage)
└── Rounds: 1, 2, 3... up to 38API request example:
GET /v3/football/leagues/8?api_token=YOUR_TOKEN&include=currentSeason.stagesResponse example:
{
"data": {
"id": 8,
"sport_id": 1,
"country_id": 462,
"name": "Premier League",
"active": true,
"short_code": "UK PL",
"image_path": "https:\/\/cdn.sportmonks.com\/images\/soccer\/leagues\/8\/8.png",
"type": "league",
"sub_type": "domestic",
"last_played_at": "2025-11-24 20:00:00",
"category": 1,
"has_jerseys": false,
"currentseason": {
"id": 25583,
"sport_id": 1,
"league_id": 8,
"tie_breaker_rule_id": 1526,
"name": "2025\/2026",
"finished": false,
"pending": false,
"is_current": true,
"starting_at": "2025-08-15",
"ending_at": "2026-05-24",
"standings_recalculated_at": "2025-11-24 22:00:53",
"games_in_current_week": true,
"stages": [
{
"id": 77476879,
"sport_id": 1,
"league_id": 8,
"season_id": 25583,
"type_id": 223,
"name": "Regular Season",
"sort_order": 1,
"finished": false,
"is_current": true,
"starting_at": "2025-08-15",
"ending_at": "2026-05-24",
"games_in_current_week": false,
"tie_breaker_rule_id": null
}
]
}
},
}Key observations:
Only one stage for the entire season (typical for simple domestic leagues)
The stage type is Group Stage (type_id: 223), which indicates a round-robin format with standings
38 rounds represent the complete double round-robin schedule (20 teams × 2 = 38 matches per team)
To access the league table, use the standings endpoint with the season_id:
/v3/football/standings/seasons/25583
2. Multi-phase domestic leagues
Characteristics:
Multiple sequential stages within a single season
Each phase may have different structures or participant configurations
Common in leagues that split into championship and relegation groups
Stage types: Multiple Group Stages (type_id: 223)
Example: Liga Profesional de Fútbol (Argentina)
Structure:
League: Argentine Liga Profesional (league_id: 636)
└── Season: 2025 (season_id: 24969)
├── Stage: "1st Phase" (Group Stage - type_id: 223)
│ └── Group rounds with all teams
├── Stage: "1st Phase - 8th Finals" (Knock Out - type_id: 224)
├── Stage: "1st Phase - Quarter-finals" (Knock Out - type_id: 224)
├── Stage: "1st Phase - Semi-finals" (Knock Out - type_id: 224)
├── Stage: "1st Phase - Final" (Knock Out - type_id: 224)
├── Stage: "2nd Phase" (Group Stage - type_id: 223)
│ └── Group rounds with all teams
├── Stage: "2nd Phase - 8th Finals" (Knock Out - type_id: 224)
├── Stage: "2nd Phase - Quarter-finals" (Knock Out - type_id: 224)
├── Stage: "2nd Phase - Semi-finals" (Knock Out - type_id: 224)
└── Stage: "2nd Phase - Final" (Knock Out - type_id: 224)API request example:
GET /v3/football/leagues/636?api_token=YOUR_TOKEN&include=currentSeason.stagesResponse example:
{
"data": {
"id": 636,
"name": "Liga Profesional de Fútbol",
"type": "league",
"sub_type": "domestic",
"currentSeason": {
"data": {
"id": 24969,
"name": "2025",
"stages": {
"data": [
{
"id": 77475076,
"name": "1st Phase",
"type_id": 223,
"sort_order": 1,
"finished": true,
"is_current": false
},
{
"id": 77475075,
"name": "1st Phase - 8th Finals",
"type_id": 224,
"sort_order": 2,
"finished": true,
"is_current": false
},
{
"id": 77475074,
"name": "1st Phase - Quarter-finals",
"type_id": 224,
"sort_order": 3,
"finished": true,
"is_current": false
},
{
"id": 77475073,
"name": "1st Phase - Semi-finals",
"type_id": 224,
"sort_order": 4,
"finished": true,
"is_current": false
},
{
"id": 77475072,
"name": "1st Phase - Final",
"type_id": 224,
"sort_order": 5,
"finished": true,
"is_current": false
},
{
"id": 77475071,
"name": "2nd Phase",
"type_id": 223,
"sort_order": 6,
"finished": true,
"is_current": false
},
{
"id": 77475070,
"name": "2nd Phase - 8th Finals",
"type_id": 224,
"sort_order": 7,
"finished": false,
"is_current": true
},
{
"id": 77475069,
"name": "2nd Phase - Quarter-finals",
"type_id": 224,
"sort_order": 8,
"finished": false,
"is_current": false
},
{
"id": 77475068,
"name": "2nd Phase - Semi-finals",
"type_id": 224,
"sort_order": 9,
"finished": false,
"is_current": false
},
{
"id": 77475067,
"name": "2nd Phase - Final",
"type_id": 224,
"sort_order": 10,
"finished": false,
"is_current": false
}
]
}
}
}
}
}Key observations:
Multiple stages exist within one season
sort_orderindicates the sequence of stagesis_current: trueshows which stage is actively being playedAfter the 1st Phase concludes, teams progress to different groups based on their standings
3. International cup tournaments
Characteristics:
Multiple stages with different types (Qualifying, Group Stage, Knockout)
Groups within the Group Stage
Progressive elimination format
Complex structure spanning multiple competition phases
Stage types: Qualifying (type_id: 225), Group Stage (type_id: 223), Knock Out (type_id: 224)
Examples: UEFA Champions League, FIFA World Cup, Copa Libertadores, UEFA Europa League
Structure:
League: UEFA Champions League (league_id: 2)
└── Season: 2025/2026 (season_id: 25580)
├── Stage: "Qualification Round 1" (Qualifying - type_id: 225)
├── Stage: "Qualification Round 2" (Qualifying - type_id: 225)
├── Stage: "Qualification Round 3" (Qualifying - type_id: 225)
├── Stage: "Play-offs" (Qualifying - type_id: 225)
├── Stage: "League Stage" (Group Stage - type_id: 223)
│ └── Rounds: 1, 2, 3, 4, 5, 6, 7, 8
├── Stage: "Knockout Round Play-offs" (Knock Out - type_id: 224)
├── Stage: "8th Finals" (Knock Out - type_id: 224)
├── Stage: "Quarter-finals" (Knock Out - type_id: 224)
├── Stage: "Semi-finals" (Knock Out - type_id: 224)
└── Stage: "Final" (Knock Out - type_id: 224)API request example:
GET /v3/football/leagues/2?api_token=YOUR_TOKEN&include=currentSeason.stagesResponse example:
{
"data": {
"id": 2,
"sport_id": 1,
"country_id": 41,
"name": "Champions League",
"active": true,
"short_code": "UEFA CL",
"image_path": "https:\/\/cdn.sportmonks.com\/images\/soccer\/leagues\/2.png",
"type": "league",
"sub_type": "cup_international",
"last_played_at": "2025-11-25 20:00:00",
"category": 1,
"has_jerseys": false,
"currentseason": {
"id": 25580,
"sport_id": 1,
"league_id": 2,
"tie_breaker_rule_id": 33094,
"name": "2025\/2026",
"finished": false,
"pending": false,
"is_current": true,
"starting_at": "2025-07-08",
"ending_at": "2026-01-28",
"standings_recalculated_at": "2025-11-25 22:05:19",
"games_in_current_week": true,
"stages": [
{
"id": 77477731,
"sport_id": 1,
"league_id": 2,
"season_id": 25580,
"type_id": 225,
"name": "Play-offs",
"sort_order": 4,
"finished": true,
"is_current": false,
"starting_at": "2025-08-19",
"ending_at": "2025-08-27",
"games_in_current_week": false,
"tie_breaker_rule_id": null
},
{
"id": 77478049,
"sport_id": 1,
"league_id": 2,
"season_id": 25580,
"type_id": 223,
"name": "League Stage",
"sort_order": 5,
"finished": false,
"is_current": true,
"starting_at": "2025-09-16",
"ending_at": "2026-01-28",
"games_in_current_week": false,
"tie_breaker_rule_id": null
},
{
"id": 77476876,
"sport_id": 1,
"league_id": 2,
"season_id": 25580,
"type_id": 225,
"name": "Qualification Round 1",
"sort_order": 1,
"finished": true,
"is_current": false,
"starting_at": "2025-07-08",
"ending_at": "2025-07-16",
"games_in_current_week": false,
"tie_breaker_rule_id": null
},
{
"id": 77476881,
"sport_id": 1,
"league_id": 2,
"season_id": 25580,
"type_id": 225,
"name": "Qualification Round 2",
"sort_order": 2,
"finished": true,
"is_current": false,
"starting_at": "2025-07-22",
"ending_at": "2025-07-30",
"games_in_current_week": false,
"tie_breaker_rule_id": null
},
{
"id": 77477369,
"sport_id": 1,
"league_id": 2,
"season_id": 25580,
"type_id": 225,
"name": "Qualification Round 3",
"sort_order": 3,
"finished": true,
"is_current": false,
"starting_at": "2025-08-05",
"ending_at": "2025-08-12",
"games_in_current_week": false,
"tie_breaker_rule_id": null
}
]
}
}
}4. Domestic cup competitions
Characteristics:
Knockout-only format (no league table)
Progressive rounds of elimination
Single or two-legged ties
Stage type: Knock Out (type_id: 224)
Examples: FA Cup, Copa del Rey, DFB Pokal, Coppa Italia
Structure:
League: FA Cup (league_id: 24)
└── Season: 2025/2026 (season_id: 25567)
├── Stage: "1st Round Qualifying" (Knock Out - type_id: 224)
├── Stage: "2nd Round Qualifying" (Knock Out - type_id: 224)
├── Stage: "3rd Round Qualifying" (Knock Out - type_id: 224)
├── Stage: "4th Round Qualifying" (Knock Out - type_id: 224)
├── Stage: "1st Round" (Knock Out - type_id: 224)
├── Stage: "2nd Round" (Knock Out - type_id: 224)
├── Stage: "3rd Round" (Knock Out - type_id: 224)
├── Stage: "4th Round" (Knock Out - type_id: 224)
├── Stage: "5th Round" (Knock Out - type_id: 224)
├── Stage: "Quarter-finals" (Knock Out - type_id: 224)
├── Stage: "Semi-finals" (Knock Out - type_id: 224)
└── Stage: "Final" (Knock Out - type_id: 224)GET /v3/football/leagues/24?api_token=YOUR_TOKEN&include=currentSeason.stagesResponse example:
{
"data": {
"id": 24,
"sport_id": 1,
"country_id": 462,
"name": "FA Cup",
"active": true,
"short_code": "UK FA Cup",
"image_path": "https:\/\/cdn.sportmonks.com\/images\/soccer\/leagues\/24\/24.png",
"type": "league",
"sub_type": "domestic_cup",
"last_played_at": "2025-11-03 19:30:00",
"category": 2,
"has_jerseys": false,
"currentseason": {
"id": 25919,
"sport_id": 1,
"league_id": 24,
"tie_breaker_rule_id": 171,
"name": "2025\/2026",
"finished": false,
"pending": false,
"is_current": true,
"starting_at": "2025-08-01",
"ending_at": "2025-09-30",
"standings_recalculated_at": null,
"games_in_current_week": true,
"stages": [
{
"id": 77477926,
"sport_id": 1,
"league_id": 24,
"season_id": 25919,
"type_id": 225,
"name": "1st Round Qualifying",
"sort_order": 5,
"finished": true,
"is_current": false,
"starting_at": "2025-08-29",
"ending_at": "2025-09-03",
"games_in_current_week": false,
"tie_breaker_rule_id": null
},
{
"id": 77477864,
"sport_id": 1,
"league_id": 24,
"season_id": 25919,
"type_id": 225,
"name": "Preliminary Round Replays",
"sort_order": 4,
"finished": true,
"is_current": false,
"starting_at": "2025-08-18",
"ending_at": "2025-08-26",
"games_in_current_week": false,
"tie_breaker_rule_id": null
},
{
"id": 77478105,
"sport_id": 1,
"league_id": 24,
"season_id": 25919,
"type_id": 224,
"name": "2nd Round Qualifying",
"sort_order": 6,
"finished": true,
"is_current": false,
"starting_at": "2025-09-12",
"ending_at": "2025-09-23",
"games_in_current_week": false,
"tie_breaker_rule_id": null
},
{
"id": 77478660,
"sport_id": 1,
"league_id": 24,
"season_id": 25919,
"type_id": 224,
"name": "Round 1",
"sort_order": 4,
"finished": true,
"is_current": false,
"starting_at": "2025-10-31",
"ending_at": "2025-11-03",
"games_in_current_week": false,
"tie_breaker_rule_id": null
},
{
"id": 77478863,
"sport_id": 1,
"league_id": 24,
"season_id": 25919,
"type_id": 224,
"name": "Round 2",
"sort_order": 7,
"finished": false,
"is_current": false,
"starting_at": "2025-12-05",
"ending_at": "2025-12-08",
"games_in_current_week": false,
"tie_breaker_rule_id": null
},
{
"id": 77478288,
"sport_id": 1,
"league_id": 24,
"season_id": 25919,
"type_id": 225,
"name": "3rd Round Qualifying",
"sort_order": 7,
"finished": true,
"is_current": false,
"starting_at": "2025-09-27",
"ending_at": "2025-09-30",
"games_in_current_week": false,
"tie_breaker_rule_id": null
},
{
"id": 77477212,
"sport_id": 1,
"league_id": 24,
"season_id": 25919,
"type_id": 225,
"name": "Extra Preliminary Round",
"sort_order": 1,
"finished": true,
"is_current": false,
"starting_at": "2025-08-01",
"ending_at": "2025-08-03",
"games_in_current_week": false,
"tie_breaker_rule_id": null
},
{
"id": 77477213,
"sport_id": 1,
"league_id": 24,
"season_id": 25919,
"type_id": 225,
"name": "Preliminary Round",
"sort_order": 3,
"finished": true,
"is_current": false,
"starting_at": "2025-08-15",
"ending_at": "2025-08-19",
"games_in_current_week": false,
"tie_breaker_rule_id": null
},
{
"id": 77477536,
"sport_id": 1,
"league_id": 24,
"season_id": 25919,
"type_id": 224,
"name": "Extra Preliminary Round Replays",
"sort_order": 2,
"finished": true,
"is_current": false,
"starting_at": "2025-08-04",
"ending_at": "2025-08-12",
"games_in_current_week": false,
"tie_breaker_rule_id": null
},
{
"id": 77478393,
"sport_id": 1,
"league_id": 24,
"season_id": 25919,
"type_id": 225,
"name": "Qualification Round 4",
"sort_order": 4,
"finished": true,
"is_current": false,
"starting_at": "2025-10-11",
"ending_at": "2025-10-14",
"games_in_current_week": false,
"tie_breaker_rule_id": null
}
]
}
},
}5. Play-off competitions
Characteristics:
Post-season tournaments
Determine promotion, relegation, or championship
Often part of a larger league system
Stage types: Qualifying (type_id: 225) or Knock Out (type_id: 224)
Examples: Various promotion/relegation playoffs, championship playoffs
Structure:
League: Playoff Competition
└── Season: 2025/2026
├── Stage: "Semi-finals" (Knock Out)
└── Stage: "Final" (Knock Out)Stage Types Reference
The API uses three main stage types to classify different phases of competitions:
223
Group Stage
Round-robin format where teams play within a group or league structure
Regular seasons, group phases in tournaments
224
Knock Out
Elimination format where losing teams are eliminated
Cup rounds, tournament knockout phases
225
Qualifying
Preliminary rounds to determine tournament participants
Qualification rounds, playoffs for main competition entry
League types and Sub-types
Leagues are classified by type and sub-type to help identify their nature:
League Types
League: A standard league competition
Phase: A specific phase within a league structure
League Sub-types
Domestic
A league within one country
English Premier League, Serie A, La Liga, Bundesliga
Domestic_cup
A cup competition within one country
FA Cup, DFB Pokal, Coppa Italia, Copa del Rey
International
A league for international teams
FIFA World Cup, European Championship, Copa America
Cup_international
An international cup competition
UEFA Champions League, Copa Libertadores, UEFA Europa League
Play-offs
A playoff competition
Various promotion/relegation playoffs
Friendly
Friendly matches
Club Friendlies, International Friendlies
Practical use cases
Understanding league structures is essential for:
1. Requesting standings correctly
Simple league:
GET /v3/football/standings/seasons/23690?api_token=YOUR_TOKEN
# Returns one unified league tableTournament with groups:
GET /v3/football/standings/seasons/23456?api_token=YOUR_TOKEN
# Returns multiple group tables (Group A, B, C, etc.)2. Determining current competition phase
Check the is_current field on stages to identify which phase is active:
GET /v3/football/seasons/8?api_token=YOUR_TOKEN&include=stagesLook for "is_current": true to find the active stage.
3. Understanding round structure
Different leagues have different round structures based on their format:
Simple domestic leagues:
Premier League (league_id: 8): 38 rounds (20 teams playing home and away)
La Liga (league_id: 564): 38 rounds (20 teams playing home and away)
Bundesliga (league_id: 82): 34 rounds (18 teams playing home and away)
Multi-phase domestic leagues:
Argentine Liga Profesional (league_id: 636):
1st Phase: 27 rounds (group stage)
1st Phase Playoffs: Multiple knockout rounds (8th Finals → Quarter-finals → Semi-finals → Final)
2nd Phase: 27 rounds (group stage)
2nd Phase Playoffs: Multiple knockout rounds (8th Finals → Quarter-finals → Semi-finals → Final)
International cup tournaments:
Champions League (league_id: 2):
Qualification Rounds: 2-leg ties per round
League Stage: 8 rounds (single round-robin format, new in 2024/25)
Knockout stages: Typically 2-leg ties per round (except Final which is single match)
Domestic cup competitions:
FA Cup (league_id: 20): Each stage is a single elimination round (single match with potential replays in early rounds)
Copa del Rey: Earlier rounds single-leg, later rounds typically two-leg ties
Play-off competitions:
Championship Playoff (league_id: 1371):
Semi-finals: 2-leg ties
Final: Single match at neutral venue
4. Filtering fixtures by stage
When requesting fixtures, you can filter by specific stages using the stage_id:
Example 1: Get fixtures from a specific stage
GET /v3/football/fixtures/between/{start_date}/{end_date}
?api_token=YOUR_TOKEN&filters=fixtureStages:77478049Returns only fixtures from Champions League "League Stage" (stage_id: 77478049)
Example 2: Get current stage fixtures for a league
GET /v3/football/leagues/636?api_token=YOUR_TOKEN&include=currentSeason.stagesFirst, identify the current stage (where is_current: true), then use that stage_id to filter fixtures.
Example 3: Get fixtures from multiple stages
GET /v3/football/fixtures/between/2025-11-01/2025-11-30
?api_token=YOUR_TOKEN&filters=fixtureStages:77475070,77475069Returns fixtures from both "2nd Phase - 8th Finals" and "2nd Phase - Quarter-finals" stages of Argentine Liga Profesional.
Example 4: Get all fixtures for a specific season
GET /v3/football/fixtures/seasons/25583?api_token=YOUR_TOKENReturns all fixtures across all stages for Premier League 2025/2026 season.
Practical workflow:
Query the league to get current season and stages
Identify the stage_id you need (using
is_current,finished, orname)Use that stage_id in your fixtures filter
Combine with date ranges for more precise results
5. Checking if standings are available
Not all stages have standings tables. To determine if standings data exists for a stage:
Check stage type_id
Group Stage (type_id: 223) → Usually has standings tables
Knock Out (type_id: 224) → No standings tables
Qualifying (type_id: 225) → May or may not have standings (verify with API)
Tips for working with different structures
Always check stages first
Before requesting data, understand the league structure:
GET /v3/football/leagues/{league_id}?api_token=YOUR_TOKEN&include=currentSeason.stagesThis reveals:
How many stages exist
What type each stage is (type_id: 223, 224, or 225)
Which stage is currently active (
is_current: true)Stage progression order (
sort_order)
Use sort_order for stage progression
sort_order for stage progressionThe sort_order field indicates the sequence of stages. Lower numbers occur first, higher numbers occur later in the season.
Groups within stages
Some tournaments have groups within stages. Check for group_id in fixtures to identify group memberships:
GET /v3/football/fixtures/18535517?api_token=YOUR_TOKENIf "group_id": 244365, this fixture belongs to a specific group (e.g., Group A).
Monitor is_current for active stages
is_current for active stagesThe is_current field tells you which stage is actively being played. This is crucial for displaying current standings and fixtures.
Common include options
Enrich your league requests with additional data:
sport
Sport information
country
Country details
stages
All stages within the current season
currentSeason
Active season information
seasons
Historical seasons
latest
Most recent fixture
upcoming
Next scheduled fixture
inplay
Currently live fixtures
today
Today's fixtures
Example:
GET /v3/football/leagues/501?api_token=YOUR_TOKEN&include=currentSeason.stagesThis returns the league with its current season and all stages.
To get rounds, make a separate request:
GET /v3/football/stages/{stage_id}?api_token=YOUR_TOKEN&include=roundsOr retrieve rounds for all stages in a season:
GET /v3/football/seasons/25598?api_token=YOUR_TOKEN&include=stages.roundsNote: The API limits nested includes to 2 levels maximum. You cannot use currentSeason.stages.rounds in a single request. Instead, use separate requests or structure your includes to stay within the 2-level limit (e.g., stages.rounds when querying a season directly).
Related entities
For complete field descriptions and available includes, see:
League, Season, Schedule, Stage and Round Entity Documentation
Stages Endpoint Documentation
Rounds Endpoint Documentation
Standings Documentation
Need Help?
If you have questions about league structures or need assistance implementing league data in your application, contact our support team at [email protected].
Last updated
Was this helpful?