Football API 3.0
Odds Core
Football API
API 2 (Deprecated) Widgets Contact

Schedules

Display complete season schedules for your favourite leagues and teams. The schedule endpoints allow you to quickly retrieve the up-to-date season schedules that interest you.

You can choose a variety of endpoints to retrieve the season schedules.

This section will briefly discuss all the options available to request schedules.

An overview of all available options:

  • GET Schedules by Season ID: returns the complete season schedule from your requested season id.

  • GET Schedules by Team ID: returns the complete schedule for the active seasons from your requested team id.

  • GET Schedules by Season ID and Team ID: returns the complete season schedule for one specific team from your requested season id.

For all the schedules endpoints the base URL is the same:

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

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

Requesting schedules

GET Schedules by Season ID

The GET Schedules by Season ID is the perfect endpoint to retrieve the full season schedule of the season you’re interested in. For example, if you’re interested in the full season schedule of the Danish Superliga.

You need to add the season id to your request:

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

First, you will need to retrieve the league id and active season id of the Danish Superliga. As you’ve learnt in our leagues and season tutorial, you can easily retrieve the league and season ids in multiple ways. Please check these tutorials for more info.

The league id of the Danish Superliga is 271, and the active season id is 19686. Now, you can use this season id to retrieve the full schedule.

https://api.sportmonks.com/v3/football/schedules/seasons/19686?api_token=YOUR_TOKEN
Response
{
  "data": [
    {
      "id": 77457696,
      "sport_id": 1,
      "league_id": 271,
      "season_id": 19686,
      "type_id": 223,
      "name": "Regular Season",
      "sort_order": 1,
      "finished": false,
      "is_current": true,
      "starting_at": "2022-07-15",
      "ending_at": "2023-03-19",
      "games_in_current_week": true,
      "rounds": [
        {
          "id": 273988,
          "sport_id": 1,
          "league_id": 271,
          "season_id": 19686,
          "stage_id": 77457696,
          "name": "1",
          "finished": true,
          "is_current": false,
          "starting_at": "2022-07-15",
          "ending_at": "2022-07-18",
          "games_in_current_week": false,
          "fixtures": [
            {
              "id": 18528474,
              "sport_id": 1,
              "league_id": 271,
              "season_id": 19686,
              "stage_id": 77457696,
              "group_id": null,
              "aggregate_id": null,
              "round_id": 273988,
              "state_id": 5,
              "venue_id": 1467,
              "name": "Viborg vs AaB",
              "starting_at": "2022-07-17 12:00:00",
              "result_info": "Viborg won after full-time.",
              "leg": "1/1",
              "details": null,
              "length": 90,
              "placeholder": false,
              "last_processed_at": "2023-02-17 10:21:45",
              "has_odds": true,
              "starting_at_timestamp": 1658059200,
              "participants": [
                {
                  "id": 2447,
                  "sport_id": 1,
                  "country_id": 320,
                  "venue_id": 1467,
                  "gender": "male",
                  "name": "Viborg",
                  "short_code": null,
                  "image_path": "https://cdn.sportmonks.com/images/soccer/teams/15/2447.png",
                  "founded": 1896,
                  "type": "domestic",
                  "placeholder": false,
                  "last_played_at": "2023-02-26 13:00:00",
                  "meta": {
                    "location": "home",
                    "winner": true,
                    "position": 12
                  }
                },
                {
                  "id": 1020,
                  "sport_id": 1,
                  "country_id": 320,
                  "venue_id": 85765,
                  "gender": "male",
                  "name": "AaB",
                  "short_code": "AAB",
                  "image_path": "https://cdn.sportmonks.com/images/soccer/teams/28/1020.png",
                  "founded": 1885,
                  "type": "domestic",
                  "placeholder": false,
                  "last_played_at": "2023-02-26 15:00:00",
                  "meta": {
                    "location": "away",
                    "winner": false,
                    "position": 4
                  }
                }
              ],
              "scores": [
                {
                  "id": 11284382,
                  "fixture_id": 18528474,
                  "type_id": 1,
                  "participant_id": 2447,
                  "score": {
                    "goals": 1,
                    "participant": "home"
                  },
                  "description": "1ST_HALF"
                },
                {
                  "id": 11284383,
                  "fixture_id": 18528474,
                  "type_id": 1,
                  "participant_id": 1020,
                  "score": {
                    "goals": 0,
                    "participant": "away"
                  },
                  "description": "1ST_HALF"
                },
                {
                  "id": 11284384,
                  "fixture_id": 18528474,
                  "type_id": 2,
                  "participant_id": 2447,
                  "score": {
                    "goals": 2,
                    "participant": "home"
                  },
                  "description": "2ND_HALF"
                },
                {
                  "id": 11284385,
                  "fixture_id": 18528474,
                  "type_id": 2,
                  "participant_id": 1020,
                  "score": {
                    "goals": 1,
                    "participant": "away"
                  },
                  "description": "2ND_HALF"
                },
                {
                  "id": 11284386,
                  "fixture_id": 18528474,
                  "type_id": 1525,
                  "participant_id": 2447,
                  "score": {
                    "goals": 2,
                    "participant": "home"
                  },
                  "description": "CURRENT"
                },
                {
                  "id": 11284387,
                  "fixture_id": 18528474,
                  "type_id": 1525,
                  "participant_id": 1020,
                  "score": {
                    "goals": 1,
                    "participant": "away"
                  },
                  "description": "CURRENT"
                }
              ]
            },
            //And more

As you can see, the response contains all the fixtures of the requested season. This is suited to display the full schedule in your application. You can also retrieve the schedule of your favourite teams.

GET Schedules by Team ID

Retrieve the full season schedule of your favourite teams with the GET Schedules by Team ID endpoint. This endpoint returns the complete schedule of all active seasons the team is in. Let’s take a look at how this works.

You need to add the team id to your schedule request:

https://api.sportmonks.com/v3/football/schedules/teams/{team_id}

So for example, if you’re interested in the full-season schedule for Rangers (team id: 62):

https://api.sportmonks.com/v3/football/schedules/teams/62?api_token=YOUR_TOKEN
Response
{
  "data": [
    {
      "id": 77457866,
      "sport_id": 1,
      "league_id": 501,
      "season_id": 19735,
      "type_id": 223,
      "name": "1st Phase",
      "sort_order": 1,
      "finished": false,
      "is_current": true,
      "starting_at": "2022-07-30",
      "ending_at": "2023-04-22",
      "games_in_current_week": true,
      "aggregates": [
        
      ],
      "rounds": [
        {
          "id": 274733,
          "sport_id": 1,
          "league_id": 501,
          "season_id": 19735,
          "stage_id": 77457866,
          "name": "20",
          "finished": true,
          "is_current": false,
          "starting_at": "2023-01-02",
          "ending_at": "2023-01-02",
          "games_in_current_week": false,
          "fixtures": [
            {
              "id": 18535605,
              "sport_id": 1,
              "league_id": 501,
              "season_id": 19735,
              "stage_id": 77457866,
              "group_id": null,
              "aggregate_id": null,
              "round_id": 274733,
              "state_id": 5,
              "venue_id": 8914,
              "name": "Rangers vs Celtic",
              "starting_at": "2023-01-02 12:30:00",
              "result_info": "Game ended in draw.",
              "leg": "1/1",
              "details": null,
              "length": 90,
              "placeholder": false,
              "last_processed_at": "2023-02-17 10:19:54",
              "has_odds": true,
              "starting_at_timestamp": 1672662600,
              "participants": [
                {
                  "id": 53,
                  "sport_id": 1,
                  "country_id": 1161,
                  "venue_id": 8909,
                  "gender": "male",
                  "name": "Celtic",
                  "short_code": "CEL",
                  "image_path": "https://cdn.sportmonks.com/images/soccer/teams/21/53.png",
                  "founded": 1888,
                  "type": "domestic",
                  "placeholder": false,
                  "last_played_at": "2023-02-26 15:00:00",
                  "meta": {
                    "location": "away",
                    "winner": false,
                    "position": 1
                  }
                },
                {
                  "id": 62,
                  "sport_id": 1,
                  "country_id": 1161,
                  "venue_id": 8914,
                  "gender": "male",
                  "name": "Rangers",
                  "short_code": "RAN",
                  "image_path": "https://cdn.sportmonks.com/images/soccer/teams/30/62.png",
                  "founded": 1873,
                  "type": "domestic",
                  "placeholder": false,
                  "last_played_at": "2023-02-26 15:00:00",
                  "meta": {
                    "location": "home",
                    "winner": false,
                    "position": 2
                  }
                }
              ],
              "scores": [
                {
                  "id": 11956908,
                  "fixture_id": 18535605,
                  "type_id": 1,
                  "participant_id": 62,
                  "score": {
                    "goals": 0,
                    "participant": "home"
                  },
                  "description": "1ST_HALF"
                },
                {
                  "id": 11956909,
                  "fixture_id": 18535605,
                  "type_id": 1,
                  "participant_id": 53,
                  "score": {
                    "goals": 1,
                    "participant": "away"
                  },
                  "description": "1ST_HALF"
                },
                {
                  "id": 11956914,
                  "fixture_id": 18535605,
                  "type_id": 1525,
                  "participant_id": 53,
                  "score": {
                    "goals": 2,
                    "participant": "away"
                  },
                  "description": "CURRENT"
                },
                {
                  "id": 11956915,
                  "fixture_id": 18535605,
                  "type_id": 1525,
                  "participant_id": 62,
                  "score": {
                    "goals": 2,
                    "participant": "home"
                  },
                  "description": "CURRENT"
                },
                {
                  "id": 11956978,
                  "fixture_id": 18535605,
                  "type_id": 2,
                  "participant_id": 62,
                  "score": {
                    "goals": 2,
                    "participant": "home"
                  },
                  "description": "2ND_HALF"
                },
                {
                  "id": 11956979,
                  "fixture_id": 18535605,
                  "type_id": 2,
                  "participant_id": 53,
                  "score": {
                    "goals": 2,
                    "participant": "away"
                  },
                  "description": "2ND_HALF"
                }
              ]
            }
          ]
        },
        //And more

Please note that the response is based on the leagues in your plan. Therefore, if you’re missing a specific league, it’s possible that you don’t have access to it. Check our league tutorial for more info.

If you’re only interested in the schedule of a specific team in a specific league, the GET Schedule by Season and Team ID is best suited.

GET Schedules by Season ID and Team ID

Retrieve the full season schedule of your favourite teams in a specific season with the GET Schedule by Season and Team ID. This endpoint returns the complete schedule of one team in the requested season.

You need to add the season id and team id to your schedule request:

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

So for example, if you’re interested in the full-season schedule for Rangers (team id: 62) in the Scottish Premiership (season id 19735):

https://api.sportmonks.com/v3/football/schedules/seasons/19735/teams/62?api_token=YOUR_TOKEN
Response
{
  "data": [
    {
      "id": 77457866,
      "sport_id": 1,
      "league_id": 501,
      "season_id": 19735,
      "type_id": 223,
      "name": "1st Phase",
      "sort_order": 1,
      "finished": false,
      "is_current": true,
      "starting_at": "2022-07-30",
      "ending_at": "2023-04-22",
      "games_in_current_week": true,
      "aggregates": [
        
      ],
      "rounds": [
        {
          "id": 274733,
          "sport_id": 1,
          "league_id": 501,
          "season_id": 19735,
          "stage_id": 77457866,
          "name": "20",
          "finished": true,
          "is_current": false,
          "starting_at": "2023-01-02",
          "ending_at": "2023-01-02",
          "games_in_current_week": false,
          "fixtures": [
            {
              "id": 18535605,
              "sport_id": 1,
              "league_id": 501,
              "season_id": 19735,
              "stage_id": 77457866,
              "group_id": null,
              "aggregate_id": null,
              "round_id": 274733,
              "state_id": 5,
              "venue_id": 8914,
              "name": "Rangers vs Celtic",
              "starting_at": "2023-01-02 12:30:00",
              "result_info": "Game ended in draw.",
              "leg": "1/1",
              "details": null,
              "length": 90,
              "placeholder": false,
              "last_processed_at": "2023-02-17 10:19:54",
              "has_odds": true,
              "starting_at_timestamp": 1672662600,
              "participants": [
                {
                  "id": 53,
                  "sport_id": 1,
                  "country_id": 1161,
                  "venue_id": 8909,
                  "gender": "male",
                  "name": "Celtic",
                  "short_code": "CEL",
                  "image_path": "https://cdn.sportmonks.com/images/soccer/teams/21/53.png",
                  "founded": 1888,
                  "type": "domestic",
                  "placeholder": false,
                  "last_played_at": "2023-02-26 15:00:00",
                  "meta": {
                    "location": "away",
                    "winner": false,
                    "position": 1
                  }
                },
                {
                  "id": 62,
                  "sport_id": 1,
                  "country_id": 1161,
                  "venue_id": 8914,
                  "gender": "male",
                  "name": "Rangers",
                  "short_code": "RAN",
                  "image_path": "https://cdn.sportmonks.com/images/soccer/teams/30/62.png",
                  "founded": 1873,
                  "type": "domestic",
                  "placeholder": false,
                  "last_played_at": "2023-02-26 15:00:00",
                  "meta": {
                    "location": "home",
                    "winner": false,
                    "position": 2
                  }
                }
              ],
              "scores": [
                {
                  "id": 11956908,
                  "fixture_id": 18535605,
                  "type_id": 1,
                  "participant_id": 62,
                  "score": {
                    "goals": 0,
                    "participant": "home"
                  },
                  "description": "1ST_HALF"
                },
                {
                  "id": 11956909,
                  "fixture_id": 18535605,
                  "type_id": 1,
                  "participant_id": 53,
                  "score": {
                    "goals": 1,
                    "participant": "away"
                  },
                  "description": "1ST_HALF"
                },
                {
                  "id": 11956914,
                  "fixture_id": 18535605,
                  "type_id": 1525,
                  "participant_id": 53,
                  "score": {
                    "goals": 2,
                    "participant": "away"
                  },
                  "description": "CURRENT"
                },
                {
                  "id": 11956915,
                  "fixture_id": 18535605,
                  "type_id": 1525,
                  "participant_id": 62,
                  "score": {
                    "goals": 2,
                    "participant": "home"
                  },
                  "description": "CURRENT"
                },
                {
                  "id": 11956978,
                  "fixture_id": 18535605,
                  "type_id": 2,
                  "participant_id": 62,
                  "score": {
                    "goals": 2,
                    "participant": "home"
                  },
                  "description": "2ND_HALF"
                },
                {
                  "id": 11956979,
                  "fixture_id": 18535605,
                  "type_id": 2,
                  "participant_id": 53,
                  "score": {
                    "goals": 2,
                    "participant": "away"
                  },
                  "description": "2ND_HALF"
                }
              ]
            }
          ]
        },

In the next section, we’ll explain a few more things about the structure of the season.

Adding useful information

There are no include options for the schedule endpoints.

Selecting and filtering

There are limited selecting options available.

PreviousSeason scheduleNextStages

Last updated