Stages

The stages endpoint can help you define the structure of the league. A league can have different types of stages.

For example: Many competitions have a main stage, which is often the regular season with the double round-robin structure. Teams that do well in the main stage often advance to the next stage, the play-offs. But there are more variations, like the World Cup. The World Cup has a group-stage, round of 16, quarter-finals, semi-finals, 3rd place final and final.

With the stages endpoint, we give you the ability to request data for all stages, a single stage or a whole season.

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

An overview of all available options:

• GET All Stages: returns all stages available within your subscription.

• GET Stages by ID: returns stage information from your requested stage ID.

• GET Stages by Season ID: returns stage information from your requested season ID.

• GET Stages by Search by Name: returns all stages that match your search query.

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

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

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

Many customers use the stages include on one of our seasons endpoints.

Requesting stages

GET All Stages

The first option is to request all stages available within your subscription. The URL to get all your stages is the same as the base URL for stages. 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/stages?api_token=YOUR_TOKEN

Response

{
  "data": [
    {
      "id": 1086,
      "sport_id": 1,
      "league_id": 271,
      "season_id": 1273,
      "type_id": 223,
      "name": "Regular Season",
      "sort_order": 1,
      "finished": true,
      "is_current": false,
      "starting_at": "2005-07-19",
      "ending_at": "2006-05-14",
      "games_in_current_week": false
    },
    {
      "id": 1087,
      "sport_id": 1,
      "league_id": 271,
      "season_id": 1274,
      "type_id": 223,
      "name": "Regular Season",
      "sort_order": 1,
      "finished": true,
      "is_current": false,
      "starting_at": "2006-07-19",
      "ending_at": "2007-05-27",
      "games_in_current_week": false
    },
    
    //and more

Let’s briefly evaluate the response. You can see the unique stage id, start and end date, league and season id belonging to the stage, stage status and name. Interested in more information? Keep reading and find out in the adding useful information section.

GET Stages by Season ID

The previous request returned all the stages in your subscription. But what if you’re only interested in the stages of a particular season? You can use the GET Stages by Season ID endpoint for this. You need to add the season id to your request:

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

For example, if you’re interested in all the stages of the Scottish Premiership 2022/2023 season (id: 19735):

https://api.sportmonks.com/v3/football/stages/seasons/19735?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
    },
    {
      "id": 77457865,
      "sport_id": 1,
      "league_id": 501,
      "season_id": 19735,
      "type_id": 223,
      "name": "2nd Phase",
      "sort_order": 2,
      "finished": false,
      "is_current": false,
      "starting_at": null,
      "ending_at": null,
      "games_in_current_week": false
    }
  ],

GET Stages by Stage ID

You can also choose the GET Stages by Stage ID if you’re only interested in data from one stage. For this, you will need to add the stage id to your request:

https://api.sportmonks.com/v3/football/stages/{stage_id}

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
  },

GET Stage Search by Name

This endpoint returns all the stages based on your search query. This might come in handy if you cannot find a stage or want to group stages by name. To search on a stage name, you’ll need to add /search/{search_query} to the leagues base URL:

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

For example, if you’re only interested in regular-season stages, your request will be:

https://api.sportmonks.com/v3/football/stages/search/regular?api_token=YOUR_TOKEN

Response

{
  "data": [
    {
      "id": 1086,
      "sport_id": 1,
      "league_id": 271,
      "season_id": 1273,
      "type_id": 223,
      "name": "Regular Season",
      "sort_order": 1,
      "finished": true,
      "is_current": false,
      "starting_at": "2005-07-19",
      "ending_at": "2006-05-14",
      "games_in_current_week": false
    },
    {
      "id": 1087,
      "sport_id": 1,
      "league_id": 271,
      "season_id": 1274,
      "type_id": 223,
      "name": "Regular Season",
      "sort_order": 1,
      "finished": true,
      "is_current": false,
      "starting_at": "2006-07-19",
      "ending_at": "2007-05-27",
      "games_in_current_week": false
    },
 //And more   

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

Adding useful information

You might’ve noticed that the stages endpoints return limited information. But no worries, there are a lot of include options available to enrich your request. For example, you can include information about what type of stage it is and add all the fixtures belonging to the stage. Easily add the &include=type;fixtures

https://api.sportmonks.com/v3/football/stages/77457866?api_token=YOUR_TOKEN&include=type;fixtures

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,
    "type": {
      "id": 223,
      "name": "Group Stage",
      "code": "group-stage",
      "developer_name": "GROUP_STAGE",
      "model_type": "stage_type",
      "stat_group": null
    },
    "fixtures": [
      {
        "id": 18537988,
        "sport_id": 1,
        "league_id": 501,
        "season_id": 19735,
        "stage_id": 77457866,
        "group_id": null,
        "aggregate_id": null,
        "round_id": 275093,
        "state_id": 1,
        "venue_id": 336296,
        "name": "Hearts vs St. Johnstone",
        "starting_at": "2023-03-04 15:00:00",
        "result_info": null,
        "leg": "1/1",
        "details": null,
        "length": 90,
        "placeholder": false,
        "last_processed_at": "2023-03-02 00:15:27",
        "has_odds": true,
        "starting_at_timestamp": 1677942000
      },
      {
        "id": 18537977,
        "sport_id": 1,
        "league_id": 501,
        "season_id": 19735,
        "stage_id": 77457866,
        "group_id": null,
        "aggregate_id": null,
        "round_id": 275091,
        "state_id": 5,
        "venue_id": 8946,
        "name": "Hibernian vs Kilmarnock",
        "starting_at": "2023-02-18 15:00:00",
        "result_info": "Hibernian won after full-time.",
        "leg": "1/1",
        "details": null,
        "length": 90,
        "placeholder": false,
        "last_processed_at": "2023-02-25 14:55:39",
        "has_odds": true,
        "starting_at_timestamp": 1676732400
      },

Check our include tutorial for more information and tips about includes.

Selecting and filtering

You can limit the data our API returns by default by selecting a specific field you’re interested in. For example, you want to retrieve all the stages in your subscription but are only interested in the name, start date and end date.

Easily add &select=name,starting_at,ending_at

https://api.sportmonks.com/v3/football/stages/77457866?api_token=YOUR_TOKEN&select=name,starting_at,ending_at

Response

{
  "data": {
    "name": "1st Phase",
    "starting_at": "2022-07-30",
    "ending_at": "2023-04-22",
    "id": 77457866,
    "type_id": 223,
    "season_id": 19735,
    "sport_id": 1,
    "league_id": 501
  },

Check our filtering tutorial for more information and tips.