Season schedule
This tutorial will teach you how competitions are structured and how you can use this to your advantage. We will walk through different stages, groups and rounds together. Please visit our API references for a complete overview of the possible values of the stages attribute. Let’s get started with the definitions of rounds, groups and stages:
Rounds: represent the game-week the season is in. For example round 1.
Stages: represent the stage the season is in. For example: ‘regular season’, ‘semi-finals’.
Groups: represent the groups of the season. For example group A, group B etc...
Most of the football competitions are played once a week. The majority of the competitions handles a double round-robin structure, meaning that every team will play matches until everyone has played against each other twice. Competitions have divided every match day into a specific round. This way, you can see exactly how many rounds are scheduled and which team plays against whom per round. Quite convenient, huh? We at Sportmonks have given every round a name and a unique round id. This will greatly help you with requesting data about the rounds. We’ll show you how the rounds are structured. For instance, imagine you want to know how many rounds are scheduled for the Scottish Premiership’s current season. We use the season by id endpoint.
Here are the details of the Scottish Premiership (league id: 501 and season id: 17141).
If you have followed our previous tutorials, you will know that the API returns a basic response by default. Let’s enrich our response by using the rounds include.
https://soccer.sportmonks.com/api/v2.0/seasons/17141?api_token={API_TOKEN}&include=rounds
{"data": {"id": 17141,"name": "2020/2021","league_id": 501,"is_current_season": true,"current_round_id": 194976,"current_stage_id": 77447501,"rounds": {"data": [{"id": 194968,"name": 1,"league_id": 501,"season_id": 17141,"stage_id": 77447501,"start": "2020-08-01","end": "2020-08-03"},{"id": 194969,"name": 2,"league_id": 501,"season_id": 17141,"stage_id": 77447501,"start": "2020-08-08","end": "2020-08-09"},{"id": 194970,"name": 3,"league_id": 501,"season_id": 17141,"stage_id": 77447501,"start": "2020-08-11","end": "2020-08-12"},{"id": 194971,"name": 4,"league_id": 501,"season_id": 17141,"stage_id": 77447501,"start": "2020-08-15","end": "2020-08-16"},{"id": 194972,"name": 5,"league_id": 501,"season_id": 17141,"stage_id": 77447501,"start": "2020-08-22","end": "2020-08-23"},
Season Field Description
Field | Description |
| Opens an array of data you've requested |
| The unique season id |
| The name of the season |
| The unique league id the season belongs to |
| Indicates if the season is the current one. Possible values are "true" or "false" |
| The unique id of the current round |
| The unique id of the current stage |
Rounds Field Description
Field | Description |
| The unique id of the round |
| The name of the round |
| The unique league id the round belongs to |
| The unique season id the round belongs to |
| The unique stage id the round belongs to |
| The start date of the round |
| The end date of the round |
And just like that, you’ve successfully requested all the rounds including their ID of the Scottish Premiership 20/21 season! You can use these ids to request fixtures per round. However, you might’ve noticed that the API also returns a stage id. What exactly is this stage id?
Every competition has the main stage, which is often the regular season with the double round-robin structure. Teams that do well in the main stage get to advance to the next stage, which is the play-offs. Sounds confusing? Let’s take a look together at three examples: The English Premier League (league id: 8), the Scottish Premiership (league id: 501) and the UEFA Champions League (league id: 2). Just like with rounds, you can best request an overview of all the stages of one season with our season by id endpoint.
Instead of rounds we are going to request all the stages of this season. Of course, you can also request both in the same request.
https://soccer.sportmonks.com/api/v2.0/seasons/17420?api_token={API_TOKEN}&include=stages
{"data": {"id": 17420,"name": "2020/2021","league_id": 8,"is_current_season": true,"current_round_id": 201973,"current_stage_id": 77448322,"stages": {"data": [{"id": 77448322,"name": "Regular Season","type": "Group Stage","league_id": 8,"season_id": 17420,"sort_order": 1,"has_standings": true}]}},
Season Field Description
Field | Description |
| Opens an array of data you've requested |
| The unique season id |
| The name of the season |
| The unique league id the season belongs to |
| Indicates if the season is the current one. Possible values are "true" or "false" |
| The unique id of the current round |
| The unique id of the current stage |
Stages Field Description
Field | Description |
| The unique id of the stage |
| The name of the stage |
| Indicates what kind of type the stage is |
| The unique league id the stage belongs to |
| The unique season id the stage belongs to |
| The order of the stages |
| Indicates if the stage supports standings |
You can see that there is one regular season, which is an indication that this is the ‘main’ stage of the competition. Want to know which team plays in the Champions League based on the standings? You can find this out by requesting the standings by season id.
For more detailed information, please refer to our standings tutorial.
Let’s take a look at another example.
Once again, we request the stages for the current season of the league we’re interested in:
https://soccer.sportmonks.com/api/v2.0/seasons/17141?api_token={API_TOKEN}&include=stages
{"data": {"id": 17141,"name": "2020/2021","league_id": 501,"is_current_season": true,"current_round_id": 194976,"current_stage_id": 77447501,"stages": {"data": [{"id": 77447500,"name": "2nd Phase","type": "Group Stage","league_id": 501,"season_id": 17141,"sort_order": 1,"has_standings": false},{"id": 77447501,"name": "1st Phase","type": "Group Stage","league_id": 501,"season_id": 17141,"sort_order": -1,"has_standings": true}]}
You can see that this season contains multiple phases and that it’s not one regular season. It has a first and second phase. You can see that the current stage id is the first phase. The second phase will start when the first one has ended.
We just looked at two domestic leagues. But how does a cup work?
https://soccer.sportmonks.com/api/v2.0/seasons/17299?api_token={API_TOKEN}&include=stages
{"data": {"id": 17299,"name": "2020/2021","league_id": 2,"is_current_season": true,"current_round_id": 211702,"current_stage_id": 77448760,"stages": {"data": [{"id": 77447933,"name": "Final","type": "Knock Out","league_id": 2,"season_id": 17299,"sort_order": 11,"has_standings": false},{"id": 77447934,"name": "Semi-finals","type": "Knock Out","league_id": 2,"season_id": 17299,"sort_order": 10,"has_standings": false},{"id": 77447935,"name": "Quarter-finals","type": "Knock Out","league_id": 2,"season_id": 17299,"sort_order": 9,"has_standings": false},{"id": 77447936,"name": "8th Finals","type": "Knock Out","league_id": 2,"season_id": 17299,"sort_order": 8,"has_standings": false},{"id": 77448760,"name": "Group Stage","type": "Group Stage","league_id": 2,"season_id": 17299,"sort_order": 7,"has_standings": true},{"id": 77447937,"name": "Play-offs","type": "Qualifying","league_id": 2,"season_id": 17299,"sort_order": 6,"has_standings": false},{"id": 77447938,"name": "3rd Qualifying Round","type": "Qualifying","league_id": 2,"season_id": 17299,"sort_order": 5,"has_standings": false},{"id": 77447939,"name": "2nd Qualifying Round","type": "Qualifying","league_id": 2,"season_id": 17299,"sort_order": 4,"has_standings": false},{"id": 77447940,"name": "1st Qualifying Round","type": "Qualifying","league_id": 2,"season_id": 17299,"sort_order": 3,"has_standings": false},{"id": 77447941,"name": "Preliminary Round - Final","type": "Knock Out","league_id": 2,"season_id": 17299,"sort_order": 2,"has_standings": false},{"id": 77447942,"name": "Preliminary Round - Semi-finals","type": "Knock Out","league_id": 2,"season_id": 17299,"sort_order": 1,"has_standings": false}
This season has a lot of different stages. First, teams need to qualify via the preliminary stages for the qualifying stages. Once they’ve placed themselves for the qualifying rounds, they will need to progress through the play-offs before entering the group stage. As you can see, the group stage is the current stage. Based on the group stages’ standings, some teams will progress to the next stage: 8th finals and some will be knocked out. It’s crucial that you read the response properly to avoid confusion.
We just mentioned groups briefly. Now let’s have a look at how our API shows you this data. We will continue with our example of the Champions League. Just like the stages and rounds, you can use groups as an include on the season by id endpoint:
https://soccer.sportmonks.com/api/v2.0/seasons/17299?api_token={API_TOKEN}&include=groups
{"data": {"id": 17299,"name": "2020/2021","league_id": 2,"is_current_season": true,"current_round_id": 211702,"current_stage_id": 77448760,"groups": {"data": [{"id": 244365,"name": "Group A","league_id": 2,"season_id": 17299,"round_id": 211702,"round_name": 1,"stage_id": 77448760,"stage_name": "Group Stage","resource": "group"},{"id": 244366,"name": "Group B","league_id": 2,"season_id": 17299,"round_id": 211702,"round_name": 1,"stage_id": 77448760,"stage_name": "Group Stage","resource": "group"},{"id": 244367,"name": "Group C","league_id": 2,"season_id": 17299,"round_id": 211702,"round_name": 1,"stage_id": 77448760,"stage_name": "Group Stage","resource": "group"},{"id": 244368,"name": "Group D","league_id": 2,"season_id": 17299,"round_id": 211702,"round_name": 1,"stage_id": 77448760,"stage_name": "Group Stage","resource": "group"},{"id": 244369,"name": "Group E","league_id": 2,"season_id": 17299,"round_id": 211702,"round_name": 1,"stage_id": 77448760,"stage_name": "Group Stage","resource": "group"},{"id": 244370,"name": "Group F","league_id": 2,"season_id": 17299,"round_id": 211702,"round_name": 1,"stage_id": 77448760,"stage_name": "Group Stage","resource": "group"},{"id": 244371,"name": "Group G","league_id": 2,"season_id": 17299,"round_id": 211702,"round_name": 1,"stage_id": 77448760,"stage_name": "Group Stage","resource": "group"},{"id": 244372,"name": "Group H","league_id": 2,"season_id": 17299,"round_id": 211702,"round_name": 1,"stage_id": 77448760,"stage_name": "Group Stage","resource": "group"}]}
Group Field Description
Field | Description |
| The unique id of the round |
| The name of the round |
| The unique league id the round belongs to |
| The unique season id the round belongs to |
| The unique id of the round |
| The name of the round |
| The unique id of the stage |
| The name of the stage |
| Indicates to which stage the group is linked |
Let’s evaluate the response. You can see eight groups ( A – H ). The field description is available in the third tab. Just like with the stage and round ids, you can use the group ids as a filter on many other endpoints.
Armed with information about rounds, groups and stages of a season, you’re now capable of filtering your requests. For example, the below request will give us the top scorers of the group stage in the UEFA Champions League. Please refer to our topscorers tutorial for more information.
https://soccer.sportmonks.com/api/v2.0/seasons/17299?api_token={API_TOKEN}&include=goalscorers.player&stage_ids=77448760