Stages
Last updated
Was this helpful?
Last updated
Was this helpful?
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.
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 for more info.
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.
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):
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}
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:
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
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
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 for this. You need to add the season id to your request:
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:
Check our for more information and tips about includes.
Check our for more information and tips.