LogoLogo
Quick StartFootball APIContactAPI 3.0
  • Welcome
  • Changelog
  • Getting Started
    • Get Started
    • Documentation for the documentation
  • Endpoint overview
    • Continents
      • GET All Continents
      • GET Continent by ID
    • Countries
      • GET All Countries
      • GET Country by ID
    • Leagues
      • GET All Leagues
      • GET League by ID
      • GET Leagues by Country ID
      • Search Leagues by Name
    • Seasons
      • GET All Seasons
      • GET Season by ID
    • Fixtures
      • GET Fixture by ID
      • GET Last Updated Fixtures
      • GET Fixtures by Date
      • GET Fixtures by Date Range
      • GET Fixtures by Date Range for Team
      • GET Fixtures by Multiple ID's
      • GET Deleted Fixtures
    • Statistics
    • Livescores
      • GET All Livescores
      • GET All In play Livescores
    • News API
      • GET All News
      • GET News For Upcoming Fixtures
      • GET News by Season ID
    • Commentaries
      • Commentaries by Fixture ID
    • Video Highlights
      • Get Video Highlights by Fixture ID
    • Head 2 Head
      • GET Head 2 Head by Team IDs
    • Standings
      • GET Standings by Season ID
      • GET LIVE Standings
      • GET Standings by Season ID and Round ID
      • GET Standings by Season and Date(time)
      • GET Standings Corrections by Season ID
    • Teams
      • GET Team by ID
      • GET Teams by Country ID
      • GET Teams by Season ID
      • Search Team by Name
      • GET Current Leagues by Team ID
      • Get All Leagues by Team ID
    • Players
      • GET Player by ID
      • GET Players by Country ID
      • Search Player by Name
    • Topscorers
      • GET Topscorers by Season ID
      • GET Topscorers Aggregated by Season ID
    • Rivals
      • GET Rivals by Team ID
    • Venues
      • GET Venue by ID
      • GET Venues by Season ID
    • Rounds
      • GET Rounds by Season ID
      • GET Round by ID
    • Odds
      • GET Odds by Fixture ID and Bookmaker ID
      • GET Odds by Fixture ID and Market ID
      • GET Odds by Fixture ID
      • GET Inplay Odds by Fixture ID
    • Coaches
      • GET Coach by ID
    • Stages
      • GET Stage by ID
      • GET Stages by Season ID
    • Bookmakers
      • GET All Bookmakers by Fixture ID
      • GET All Bookmakers
      • GET Bookmaker by ID
    • Markets
      • GET All Fixtures by Market ID
      • GET All Markets
      • GET Market by ID
    • Team Squads
      • GET Team Squad by Team and Season ID
    • TV Stations
      • GET TV Station by Fixture ID
    • Prediction API
      • GET Leagues and Performances
      • GET Probabilities
      • GET Probabilities by Fixture ID
      • GET Value Bets
      • GET Value Bet by Fixture ID
  • Tutorials
    • Introduction to our API
      • Make your first request
      • Set your time zone
      • Pagination
    • Enriching your response
      • Includes
      • Nested includes
    • Filtering, limiting & sorting
      • Filtering
      • Limiting
      • Sorting
    • Schedule, fixtures & livescores
      • Season schedule
      • Fixtures
      • Livescores
    • Statistics
      • Match statistics
      • Team statistics
      • Player statistics
      • Season statistics
    • League & topscorers standings
      • League standings
      • Topscorers standings
    • Odds & predictions
      • Odds
        • Odds by fixture, bookmaker and market id
        • FlatOdds
        • InplayOdds
      • Predictions
  • MySportmonks
    • How-to build a custom plan
    • ID Finder
  • How-to Guides
    • Get Started with our how-to guides
      • How-to build your API requests
    • Livescores & fixtures
      • How-to build a livescore website
      • How-to build a schedule page
    • Match & team pages
      • How-to build a match page with events and statistics
      • How-to build a match page with line-ups/formations
      • How-to build a team page with season stats and squads
    • How-to build standings and topscorer standings
      • League standings
      • Topscorer standings
    • Odds & predictions
      • How-to build a match page with odds
      • How-to build a betting odds portal
      • How-to use the predictions API
    • How-to build a fantasy game
    • Developer tools
      • How-to use Sportmonks' APIs in Postman
    • How-to keep your database in sync
    • World Cup 2022
    • EURO 2024
    • Football widgets
      • How-to set up football widgets in your web application
      • Configurations
      • Widgets overview
        • Livescore widget
        • International Cup widgets
  • API References
    • API reference guide
    • Data features
    • ID Finder
    • Code libraries
    • Demo response files
    • Statuses and definitions
    • API Rate limiting
    • Response codes
    • Meta description
  • General
  • Sportmonks
  • Plans & pricing
  • FAQ
  • Contact
Powered by GitBook
On this page
  • What are rounds?
  • Our request
  • What are stages?
  • The English Premier League
  • The Scottish Premiership
  • International cup: UEFA Champions League
  • What are groups?
  • Conclusion

Was this helpful?

Export as PDF
  1. Tutorials
  2. Schedule, fixtures & livescores

Season schedule

PreviousSchedule, fixtures & livescoresNextFixtures

Last updated 3 years ago

Was this helpful?

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 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...

What are rounds?

Our request

Here are the details of the Scottish Premiership (league id: 501 and season id: 17141).

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

data

Opens an array of data you've requested

id

The unique season id

name

The name of the season

league_id

The unique league id the season belongs to

is_current_season

Indicates if the season is the current one. Possible values are "true" or "false"

current_round_id

The unique id of the current round

current_stage_id

The unique id of the current stage

Rounds Field Description

Field

Description

id

The unique id of the round

name

The name of the round

league_id

The unique league id the round belongs to

season_id

The unique season id the round belongs to

stage_id

The unique stage id the round belongs to

start

The start date of the round

end

The end date of the round

What are stages?

The English Premier League

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

data

Opens an array of data you've requested

id

The unique season id

name

The name of the season

league_id

The unique league id the season belongs to

is_current_season

Indicates if the season is the current one. Possible values are "true" or "false"

current_round_id

The unique id of the current round

current_stage_id

The unique id of the current stage

Stages Field Description

Field

Description

id

The unique id of the stage

name

The name of the stage

type

Indicates what kind of type the stage is

league_id

The unique league id the stage belongs to

season_id

The unique season id the stage belongs to

sort_order

The order of the stages

has_standings

Indicates if the stage supports standings

Let’s take a look at another example.

The Scottish Premiership

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?

International cup: UEFA Champions League

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.

What are groups?

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

id

The unique id of the round

name

The name of the round

league_id

The unique league id the round belongs to

season_id

The unique season id the round belongs to

round_id

The unique id of the round

round_name

The name of the round

stage_id

The unique id of the stage

stage_name

The name of the stage

resource

Indicates to which stage the group is linked

Conclusion

https://soccer.sportmonks.com/api/v2.0/seasons/17299?api_token={API_TOKEN}&include=goalscorers.player&stage_ids=77448760

Most of the 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 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

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 .

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 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 (league id: 8), the Scottish Premiership (league id: 501) and the (league id: 2). Just like with rounds, you can best request an overview of all the stages of one season with our

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

For more detailed information, please refer to our

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 :

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 .

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 for more information.

football competitions
Sportmonks
season by id endpoint.
include
fixtures per round.
English Premier League
UEFA Champions League
season by id endpoint.
standings by season id.
standings tutorial.
season by id endpoint
many other endpoints
topscorers tutorial
API references