Seasons

YOUR_TOKENYOUR_TOKENEvery league has an active season and, if available, multiple historical seasons. One of the main features of the seasons endpoints is the ability to retrieve full-season games, (historical) fixtures and statistics. This can be achieved by using the proper includes, which we’ll discuss later in this section.

You can gather an overview of all the historical and current seasons available within your subscription. This section will briefly discuss all the options available to request seasons.

An overview of all the options available:

• GET All Seasons: returns all the historical and active seasons available within your subscription.

• GET Season by ID: returns the single season you’ve requested by id.

• GET Seasons by Search by Name: returns all the seasons that match your search query.

Are you interested in a complete schedule? Then maybe our schedule endpoints are what you’re looking for: Schedule endpoint.

For all the seasons endpoints, the base URL is the same:

https://api.sportmonks.com/v3/football/season

Per endpoint the rest of the URL requires additional information. We will explain this per endpoint.

Requesting seasons

GET All Seasons

Like in the league’s endpoint, you can retrieve all the available seasons within your subscription. This might come in handy if you want to evaluate which historical seasons are available and what their unique id is.

You can do this via the GET All Seasons endpoint.

The URL to get all your season is the same as the base url for seasons. All you have to do is authorize the request with your API token. Check our authentication section for more info.

https://api.sportmonks.com/v3/football/seasons?api_token=YOUR_TOKEN

Response

{
  "data": [
    {
      "id": 759,
      "sport_id": 1,
      "league_id": 271,
      "tie_breaker_rule_id": 169,
      "name": "2016/2017",
      "finished": true,
      "pending": false,
      "is_current": false,
      "starting_at": "2016-07-15",
      "ending_at": "2017-06-01",
      "standings_recalculated_at": "2023-02-13 15:47:07",
      "games_in_current_week": false
    },
    {
      "id": 819,
      "sport_id": 1,
      "league_id": 513,
      "tie_breaker_rule_id": 169,
      "name": "2015/2016",
      "finished": true,
      "pending": false,
      "is_current": false,
      "starting_at": "2016-05-04",
      "ending_at": "2016-05-22",
      "standings_recalculated_at": "2022-09-27 08:13:05.900028",
      "games_in_current_week": false
    },
    {
      "id": 825,
      "sport_id": 1,
      "league_id": 501,
      "tie_breaker_rule_id": 169,
      "name": "2016/2017",
      "finished": true,
      "pending": false,
      "is_current": false,
      "starting_at": "2016-08-06",
      "ending_at": "2017-05-21",
      "standings_recalculated_at": "2023-02-13 15:47:09",
      "games_in_current_week": false
    },

Let’s take a look together at what the API returns. As you can see, the API returns all the seasons available in the free plan.

You can see the name of the season, the unique season id, the id of the league the season belongs to, the season status (current, pending or finished), the start and end date of the season, and how the season winner is determined

Now that you've requested all the seasons, you also know their unique season id. You can use this id in the second option: GET Season by ID.

Please note that you can also use the seasons include on the league endpoints.

GET Season by ID

This endpoint is useful if you only want information about one particular season. You’ll need to add the season id to your request:

https://api.sportmonks.com/v3/football/seasons/{season_id}

For example, if you’re only interested in the 2022/2023 season of the Scottish Premiership, your request will be:

https://api.sportmonks.com/v3/football/seasons/19735?api_token=YOUR_TOKEN

Response

{
  "data": {
    "id": 19735,
    "sport_id": 1,
    "league_id": 501,
    "tie_breaker_rule_id": 171,
    "name": "2022/2023",
    "finished": false,
    "pending": false,
    "is_current": true,
    "starting_at": "2022-07-30",
    "ending_at": "2023-04-22",
    "standings_recalculated_at": "2023-03-02 00:07:24",
    "games_in_current_week": false
  },

Easy isn’t it? You can now request information per season. Now, let’s imagine you’re looking for all historical 2018 seasons within your subscription. How can you achieve this? The GET Seasons by Name endpoint is perfectly suited for this.

GET Season Search by Name

This endpoint returns all the seasons based on your search query. This might come in handy if you cannot find a season or are interested in a specific year. To search on season name, you’ll need to add /search/{search_query} to the seasons base URL:

https://api.sportmonks.com/v3/football/seasons/search/{search_query}

For example, if you’re only interested in all 2018 seasons, your request will be:

https://api.sportmonks.com/v3/football/seasons/search/2023?api_token=YOUR_TOKEN

Response

{
  "data": [
    {
      "id": 19686,
      "sport_id": 1,
      "league_id": 271,
      "tie_breaker_rule_id": 171,
      "name": "2022/2023",
      "finished": false,
      "pending": false,
      "is_current": true,
      "starting_at": "2022-07-15",
      "ending_at": "2023-03-19",
      "standings_recalculated_at": "2023-03-02 00:07:22",
      "games_in_current_week": false
    },
    {
      "id": 19735,
      "sport_id": 1,
      "league_id": 501,
      "tie_breaker_rule_id": 171,
      "name": "2022/2023",
      "finished": false,
      "pending": false,
      "is_current": true,
      "starting_at": "2022-07-30",
      "ending_at": "2023-04-22",
      "standings_recalculated_at": "2023-03-02 00:07:24",
      "games_in_current_week": false
    }
  ],

The more complete your search query is, the more relevant response you’ll get.

Adding useful information

As you’ve learnt in the includes tutorial, you can enrich your request with includes. This section will discuss some of the most common requests used on the season’s endpoints.

First, you can find a list of all available includes on the endpoint pages. For the seasons, the commonly used include is fixtures. This include returns all the fixtures of the requested seasons. You can also request the season statistics or the league related to the season.

For example, if you’re interested in the league, statistics and fixtures of the Scottish Premiership 2022/2023 season, your request will be:

https://api.sportmonks.com/v3/football/seasons/19735?api_token=YOUR_TOKEN&include=fixtures;statistics;league

Don’t forget you can use nested includes as well. For example fixtures.participants to also include the team names in the response.

Selecting and filtering

In our filtering tutorial you’ve learnt how to select specific fields or filter only on the data you’re interested in. By default, our API returns a set of data related to the season. We can imagine you’re not interested in all the season data the API returns. Let’s say you’re only interested in the season name.

We’re going to use the GET All Seasons endpoint for this example.

https://api.sportmonks.com/v3/football/seasons?api_token=YOUR_TOKEN

You can add the &select= parameter followed by the fields you want. In our case: name. This results in the below request and response:

https://api.sportmonks.com/v3/football/seasons?api_token=YOUR_TOKEN&select=name

Response

{
  "data": [
    {
      "name": "2016/2017",
      "id": 759,
      "sport_id": 1,
      "league_id": 271
    },
    {
      "name": "2015/2016",
      "id": 819,
      "sport_id": 1,
      "league_id": 513
    },
    {
      "name": "2016/2017",
      "id": 825,
      "sport_id": 1,
      "league_id": 501
    },

Tip: Check our filtering tutorial for more information and tips.

In the next chapter you will learn more about a season’s structure.