In this part of the tutorial series, we’re going to discuss standings. We’ll explain what standings are, how they can be displayed and most importantly, which endpoints and includes you can use to request various standings.
In this tutorial, we will teach you how to request the top scorers per stage and the entire season.
Let’s start right away.
You can use the top scorers by season id endpoint if you want to request all the top scorers per stage* of a season. The endpoint returns the top 25 players per type: goals, cards and assists. *Please check our stages tutorial for more information
Let's say you want to request the topscorers of the English Premier League season 20/21 (season id: 17420):
Season Field Description
Topscorers Field Description
In the response example, we only included the goalscorers type. If you look at the complete response you will also see the assists and card scorers.
Naturally, you can also enrich the response by using includes. However, you need to prefix the include.
Please read the responses carefully. Sometimes the standings for cards are based on points instead of the total amount of cards. A red card is worth 2 points and a yellow card 1.
What is prefixing exactly? With nested includes, you add the additional information at the end of the include, i.e., lineup.player
With prefixing, it’s just the other way around. You will need to prefix every available include with the actual include you’re looking for.
So, for example, if you want to have additional information about the goalscorers and team, you will need to include goalscorers.player and goalscorers.team.
A list of available includes are:
goalscorers.player
goalscorers.team
assistscorers.player
assistscorers.team
cardscorer.player
cardscorers.team
We're going to only show you additional information about the goalscorers for this tutorial:
As you can see, you now have more information about both the player himself and his team.
As mentioned before, the previous request will give you all the top scorers of goals, cards and assist per stage. But what if you want the total amount of a season? We have the aggregated topscorers endpoint for this.
This endpoint is often used for cups like the UEFA Champions and Europa League. The preliminary stages for these cups are not included in the response as we follow the official UEFA guidelines.
The response is the same as the previous one. The only difference is that it will give you a list of the entire season or the cup’s top scorers. You can also enrich the data response you get by using includes.
You will need to prefix every available include with the actual include you’re looking for. For example, if you want to have additional information about the goalscorers and team, you will need to include aggregatedGoalscorers.player and aggregatedGoalscorers.team.
A list of available includes are:
aggregatedGoalscorers.player
aggregatedGoalscorers.team
aggregatedAssistscorers.player
aggregatedAssistscorers.team
aggregatedCardscorers.player
aggregatedCardscorers.team
Field
Description
id
The unique id of the current stage
name
The name of the stage
league_id
The unique league id the stage belongs to
season_id
The unique id of the current season
round_id
The unique id of the current round
round_name
The name of the round
type
Indicates what kind of type this stage is
stage_id
The unique id of the current stage
stage_name
The name of the stage
Field
Description
position
The actual position in the rankings in the stage
player_id
The unique player id of the player in that position in the stage
team_id
The unique id of the the player plays for
stage_id
The unique id of the current stage
goals
The total number of goals the player has scored in the stage
penalty_goals
The total number of penalty goals the player has scored in the stage
type
The type of the standings. Possible values are: goals, cards or assists
Standings, also known as rankings, show the positions of the teams competing in a season. Standings show the total number of games played, won, lost, the number of goals for and against and the number of points they have accumulated.
So, how do you request all of this data yourself? We’re going to show you how! In this tutorial, we will first show you how to request standings for the English Premier League season 20/21 (season id: 17420 ).
Afterward, we’ll go more in-depth with an example about the Champions League’s standings. We’ll then show you how to request standings for groups and stages. And finally, how to request live standings!
Let’s get started.
The English Premier League is an example of a domestic league, similar to the Italian Serie A, German Bundesliga, etc.
Standings can easily be requested with the standings by season id endpoint.
In order to request the standings of the English Premier League, we need the following things:
A valid API token
Access to the English Premier League (league id: 8) in your paid plan
The season id of the English Premier League season 20/21 (season id: 17420 ).
This will result in the following request and response.
Season Field Description
Standings Field Description
Most of the data speaks for itself. Just like in our other tutorials, we've added a field description overview in the third tab.
However, a field that needs some further explanation is result.
This field will contain the standing rules of a season. Each season has its own standing rules. The number one at the end of the season will be crowned champions and “earns” something.
For example, the winner of the English Premier League will earn the right to compete in a different competition, such as the Champions League or Europa League.
Or, in case of finishing last, the team will relegate to a lower division. You can find the possible outcomes in our API references.
You can enrich your request with includes. But beware, the includes on our standings by season id endpoint requires additional action. Namely, you will need to prefix the include.
What is prefixing exactly? With nested includes, you add the additional information at the end of the include. i.e., lineup.player
With prefixing, it’s the other way around. You will need to prefix every available include with standings.
So, for example, if you want to have additional team information, you will need to prefix teams with standings like this: standings.team
For ‘normal’ domestic Leagues, the response format is different compared to Cups.
If you have Cups and ‘normal’ leagues in your plan, make sure to check out the response correctly. Let’s look at one of the most requested leagues: the Champions League 2020/2021 season (league id: 2 and season id: 17299).
You can use the same endpoint as with a standard league. However, the response will be very different.
Season Field Description
Standings Field Description
As you can see, the standings are grouped by ... groups!
We can’t stress this enough. It’s paramount that you read the response correctly.
Due to our unique group ids, you can also request the specific groups you’re interested in with the group_ids parameter.
Let’s say you only want the standings of Group C. You can add the group_idsparameter with the group id of Group C (244367) to the request. You can also request multiple groups by separating them with a comma.
As mentioned multiple times before, it's really important to check the API response carefully. The standings response of a particular season can be different compared to another season.
For example, the EURO U21 tournament has another season structure compared to the UEFA Champions League. This will result in different structured API response when you request the standings.
Now you know how to request the standings per group, but what about stages? As you know from our stages tutorial, a season can consist of multiple stages. Just like how you can request the standings per group, you can also request a stage’s standings by adding the stage_ids parameter.
You can identify whether a stage has standings by first requesting all the stages of a season. Please visit our stages tutorial for more info.
Besides regular standings, we also offer live standings. Live standings represent the rankings of teams in real-time. So if a game is currently being played, the live standing returns the season standings based on the score at that moment. For example: If team A leads with 2-0, the API sees them as the ‘winner.’
The principle is almost the same. You can use the live standings by season id endpoint and parse a valid season id:
Are you interested in live standings of a season with multiple stages?
If for example in one season two stages are played at the same time, you can add the stage_id parameter to filter on the stage you're interested in.
You do need to add thegroup_idsparameter for cups.
The standings by round id is the go-to endpoint if you want to request the standings until a specific round.
With this endpoint, you can request the standings of the teams until the round id you provided. So, if, for example:
The Spanish La Liga 2019/2020 season (league id: 564 and season id: 16326) ended and Real Madrid was crowned champions. But we want to know what the standings of the season were, halfway through. That’s why we make this request:
Want to know how to retrieve a round ID? Please check our rounds tutorial for more info.
Next to the standings by round id, you can also request the season by giving a specific date and time. This endpoint will calculate the games played up until the given date or time and provide the standing results.
The date time has to be parsed in the following format: YYYY-MM-DD-T-H-M-S. For example: 2020-10-19T18:45:04
Inplay games are not calculated using this endpoint. It will only take finished games into account.
On some occasions, a stage proceeds with standings from an earlier stage. In these situations, we will also provide correction objects to understand how a stage’s standing has been calculated.
Furthermore, in case a team got points corrections, they can be found on this endpoint. It will return an array of correction objects on a per stage basis.
Field
Description
id
The unique id of the current stage
name
The name of the stage
league_id
The unique league id the stage belongs to
season_id
The unique id of the current season
round_id
The unique id of the current round
round_name
The name of the round
type
Indicates what kind of type this stage is
stage_id
The unique id of the current stage
stage_name
The name of the stage
Field
Description
position
The actual position in the rankings in the stage
team_id
The unique team id of the team in that position in the stage
team_name
The team name in that position in the stage
round_id
The unique id of the current round
round_name
The name of the round
group_id
The unique id of the group, in which the team participates in
group_name
The name of the group, in which the team participates in
overall
The overall results of the team, i.e., the number of games, points and goals
home
The home results of the team, i.e., the number of games, points and goals
away
The away results of the team, i.e., the number of games, points and goals
total
The total points of the team and their goal difference
results
The standing rules of the place the team is in
points
The accumulated number of points the team has
recent_form
The recent form of the team
status
Will be available in API 3.0: Indicates if the team moves up on down based on the last standings.
Field
Description
id
The unique id of the current group
name
The name of the group
league_id
The unique league id the stage belongs to
season_id
The unique id of the current season
round_id
The unique id of the current round
round_name
The name of the round
stage_id
The unique id of the current stage
stage_name
The name of the stage
Field
Description
position
The actual position in the rankings in the group
team_id
The unique team id of the team in that position in the group
team_name
The team name in that position in the group
round_id
The unique id of the current round
round_name
The name of the round
group_id
The unique id of the group, in which the team participates in
group_name
The name of the group, in which the team participates in
overall
The overall results of the team, i.e., the number of games, points and goals
home
The home results of the team, i.e., the number of games, points and goals
away
The away results of the team, i.e., the number of games, points and goals
total
The total points of the team and their goal difference
results
The standing rules of the place the team is in
points
The accumulated number of points the team has
recent_form
The recent form of the team
status
Will be available in API 3.0: Indicates if the team moves up on down based on the last standings.
