Welcome to the tutorial about statistics. At Sportmonks we have plenty of statistics to offer you, such as match, team, season, player and in-play player statistics.
In this tutorial, we will go through every option one by one.
Let’s get started.
Match statisticsTeam statisticsPlayer statisticsSeason statisticsOne of the most frequently asked questions is: “How can I get match statistics just like below?”.
There are many possible ways, thanks to the flexibility of our API.
As you've seen in our previous tutorials, every fixture has a unique id. Therefore, you can use one of our fixtures by id endpoints, or you can request them by date. In our fixtures tutorial, we’ve discussed all the different ways to access fixtures.
Now, as you have read in our , you can enrich the API response. If you want statistics, you can add the include stats.
Stats Field Description
Nothing more, nothing less.
Let’s say you want the statistics of matches that are currently live. As you can use our to request all the in-play fixtures:
The only thing you need to do is to add the stats include:
The stats include will enrich your response with all the match statistics of all games that are currently live.
If you only want to have stats for certain live fixtures, then you can . For instance, if you only want all the live matches from the (league id: 8) with stats, you can use this request:
ongoal
The number of shots on goal in a fixture of one team
blocked
The times the opponent has blocked a shot
offgoal
The number of shots off goal in a fixture of one team
insidebox
The number of shots from inside the box (16-meter area) in a fixture of one team
outsidebox
The number of shots from outside the box (16-meter area) in a fixture of one team
passes
Opens an array containing the pass statistics
total
The number of passes in a fixture of one team
accurate
The total accurate passes in a fixture of one team
percentage
The accurate passes (in percentage %) in a fixture of one team
attacks
Opens an array containing the attacks statistics
attacks
The attacks in a fixture of one team
dangerous_attacks
The dangerous attacks in a fixture of one team. A dangerous attack is calculated when the attack almost resulted in a goal.
fouls
The number of fouls committed of one team
corners
The number of corners of one team
offsides
The number of times one team was flagged offside by the (assistant) referee
possesiontime
The number of times one team has had the ball in percentage
yellowcards
The number of yellow cards for one team
yellowredcards
The total times a second yellow card has resulted in a red card for one team
redcards
The total number of red cards for one team
saves
The total number of saves the goalkeeper of one team has made
substitutions
The total number of substitutions of one team
goal_kicks
The number of goal kicks for one team
goal_attempts
The number of goal attempt of one team
free_kick
The number of free kicks for one team
throw_in
The amount of throw ins for one team
ball_safe
This is the number of times the attacking team plays the ball back to their own half.
For example:
Barcelona is on the attack and are on the half of the opposition, but decide to pass the ball back to their own half.
This is ball safe 1.
goals
The number of goals for one team
penalties
The number of penalties for one team
injuries
The number of injuries for one team
Field
Description
team_id
The unique id of the team to which the stats belong
fixture_id
A unique fixture id
shots
Opens an array containing the shots statistics
https://soccer.sportmonks.com/api/v2.0/fixtures/16475287?api_token={API_TOKEN}&include=stats "stats": {
"data": [
{
"team_id": 53,
"fixture_id": 16475287,
"shots": {
"total": 28,
"ongoal": 15,
"blocked": 6,
"offgoal": 13,
"insidebox": 18,
"outsidebox": 7
},
"passes": {
"total": 670,
"accurate": 587,
"percentage": 87.61
},
"attacks": {
"attacks": 115,
"dangerous_attacks": 55
},
"fouls": 9,
"corners": 11,
"offsides": 0,
"possessiontime": 80,
"yellowcards": 1,
"redcards": 0,
"yellowredcards": 0,
"saves": 1,
"substitutions": 4,
"goal_kick": null,
"goal_attempts": 19,
"free_kick": null,
"throw_in": null,
"ball_safe": 91,
"goals": 5,
"penalties": 0,
"injuries": 0
},
{
"team_id": 338,
"fixture_id": 16475287,
"shots": {
"total": 6,
"ongoal": 2,
"blocked": 1,
"offgoal": 4,
"insidebox": 4,
"outsidebox": 3
},
"passes": {
"total": 157,
"accurate": 85,
"percentage": 54.14
},
"attacks": {
"attacks": 70,
"dangerous_attacks": 41
},
"fouls": 9,
"corners": 8,
"offsides": 2,
"possessiontime": 20,
"yellowcards": 3,
"redcards": 0,
"yellowredcards": 0,
"saves": 9,
"substitutions": 3,
"goal_kick": null,
"goal_attempts": 7,
"free_kick": null,
"throw_in": null,
"ball_safe": 67,
"goals": 1,
"penalties": 0,
"injuries": 1
}
]
}https://soccer.sportmonks.com/api/v2.0/livescores/now?api_token={API_TOKEN}&include=statshttps://soccer.sportmonks.com/api/v2.0/livescores/now?api_token={API_TOKEN}&include=stats&leagues=8
Last but not least: we offer season statistics. We calculate a wide range of stats for you like the number of matches, matches played, goals scored, clean sheets, yellow cards, average goals per minute, etc
To request this, you can use our season by id endpoint with the include stats. The response below will give you all the season statistics of the Bundesliga 2019/2020 ( id: 16264) season.
https://soccer.sportmonks.com/api/v2.0/seasons/16264?api_token={API_TOKEN}&include=stats{
"data": {
"id": 16264,
"name": "2019/2020",
"league_id": 82,
"is_current_season": false,
Season Field Description
Season Stats Field Description
And that rounds up the tutorial about statistics.
In our next extra tutorial, we’re going to discuss standings.
The number of goals in the requested season
matches_both_teams_scored
The number of times both teams scored in a match in the requested season
number_of_yellowcards
The number of yellow cards in the requested season
number_of_yellowredcards
The number of yellow-red cards in the requested season
number_of_redcards
The number of red cards in the requested season
avg_goals_per_match
The average goals per match in the requested season
avg_yellowcards_per_match
The average yellow cards per match in the requested season
avg_yellowredcards_per_match
The average yellow-red cards per match in the requested season
avg_redcards_per_match
The average red cards per match in the requested season
team_with_most_goals_id
The unique team id of the team that scored the most goals in the requested season
team_with_most_goals_number
The number of goals from the team that scored the most goals in the requested season
team_with_most_conceded_goals_id
The unique team id of the team that conceded the most goals in the requested season
team_with_most_conceded_goals_number
The number of conceded goals from the team that conceded the most goals in the requested season
team_with_most_goals_per_match_id
The unique team id of the team that scored the most goals per match in the requested season
team_with_most_goals_per_match_number
The number of goals from the team that scored the most goals per match in the requested season
season_topscorer_id
The unique player id of the player that scored the most goals in the requested season
season_topscorer_number
The number of goals from the player that scored the most goals in the requested season
season_assist_topscorer_id
The unique player id of the player that assisted the most goals in the requested season
season_assist_topscorer_number
The number of assists from the player that assisted the most goals in the requested season
team_most_cleansheets_id
The unique team id of the team that has the most clean sheets in the requested season
team_most_cleansheets_number
The number of clean sheets from the team that has the most clean sheets in the requested season
goals_scored_minute
The total amount of goals in the season divided in minute periods
goalkeeper_most_cleansheets_id
The unique player id of the goalkeeper that has the most clean sheets in the requested season
goalkeeper_most_cleansheets_number
The number of clean sheets from the goalkeeper that has the most clean sheets in the requested season
goal_scored_every_minutes
How many minutes per goal in the requested season
btts
The amount of times both teams scored in percentage in the requested season
goal_line
The average goal line market in the requested season
avg_corners_per_match
The average amount of corners per game in the requested season
team_most_corners_count
The number of corners from the team that has the most corners in the requested season
team_most_corners_id
The unique team id of the team that has the most corners in the requested season
goals_conceded
The average amount of goals conceded in the requested season. Divided in all, home and away
goals_scored
The average amount of goals scored in the requested season. Divided in all, home and away
win_percentage
The average win percentage in the requested season. Divided in all, home and away
defeat_percentage
The average defeat percentage in the requested season. Divided in all, home and away
draw_percentage
The average draw percentage in the requested season
avg_homegoals_per_match
The average amount of home goals per match in the requested season
avg_awaygoals_per_match
The average amount of away goals per match in the requested season
avg_player_rating
The average player rating in the requested season
Field
Description
data
Opens an array of data you've requested
id
A unique season id
name
The name of the season
league_id
The unique league id the season belongs to
is_current_season
Indicates if the season is the current one. Possible values are "true" or "false"
current_round_id
The unique id of the current round
current_stage_id
The unique id of the current stage
Field
Description
season_id
The unique season id the stats belong to
league_id
The unique league id the stats belongs to
number_of_clubs
The number of clubs in the requested season
number_of_matches
The number of matches in the requested season
number_of_matches_played
The number of matches played in the requested season
number_of_goals
You've just learnt how you can request match and team statistics. Now, we’re going to request the statistics of one specific player.
For this example, we’ll go with Robert Lewandowski (player id: 31000). The endpoint you'll need to use is our player by id endpoint. Just like with the match and team stats, you'll only need to use the stats include.
Be aware that, just like with the team statistics, this request will give you all the player statistics of the seasons the player has played or is active in. If you only want the player’s statistics of one particular season, you can filter on it.
For example, below request return the statistics of Robert Lewandowski for his German Bundesliga 2019/2020 season (season id: 16264)
Player Field Description
You might notice that the stats include on our fixtures/livescores endpoint will only provide you with statistics of the match. But, where are the player statistics? Great question! The player statistics are available via the lineup include.
The lineup include will provide you with the starting eleven of both teams. Next to that, each player will also have an array of stats.
For example, below you can view the in-play stats of Marcus Rashford in the Champions League match PSG – United.
As you can see the lineup include will return all the statistics of the players in the match. Furthermore, we used the nested include.playerto include some basic player information. More information about nested includes can be found in our
If you also want access to stats from players who were substituted later on, you will need to use thebenchinclude as well.
https://soccer.sportmonks.com/api/v2.0/players/31000?api_token={API_TOKEN}&include=stats https://soccer.sportmonks.com/api/v2.0/players/31000?api_token={API_TOKEN}&include=stats&seasons=16264The common name the player is known for
display_name
The display name of the player. Often used to show in the lineup formation
fullname
The full name of the player
firstname
The first name of the player
lastname
The last name of the player
nationality
The nationality of the player
birthdate
The date of birth of the player
birthcountry
The country the player was born in
birthplace
The place the player was born in
height
The height of the player
weight
The weight of the player
image_path
The URL of the player image
Player Stats Field Description
Field
Description
player_id
The unique id of the player
team_id
The unique id of the team the player plays for
league_id
The unique id of the league the season belongs to
season_id
The unique id of the season you've requested the stats for
captain
The total number of times the player was captain in the requested season
Field
Description
player_id
The unique id of the main player
team_id
The unique id of the team the player belongs to
country_id
The unique id of the country the player is from
position_id
The unique id of the position the player plays in
common_name
{
"data": {
"player_id": 31000,
"team_id": 503,
"country_id": 2,
"position_id": 4,
"common_name": "R. Lewandowski",
"display_name": "Robert Lewandowski",
"fullname": "Robert Lewandowski",
"firstname": "Robert",
"lastname": "Lewandowski",
"nationality": "Poland",
"birthdate": "21/08/1988",
"birthcountry": "Poland",
"birthplace": "Warszawa",
"height": "184 cm",
"weight": "80 kg",
"image_path": "https://cdn.sportmonks.com/images/soccer/players/24/31000.png",
"stats": {
"data": [
{
"player_id": 31000,
"team_id": 503,
"league_id": 82,
"season_id": 16264,
"captain": 0,
"minutes": 2761,
"appearences": 31,
"lineups": 31,
"substitute_in": 0,
"substitute_out": 2,
"substitutes_on_bench": 0,
"goals": 34,
"owngoals": 0,
"assists": 4,
"saves": 0,
"inside_box_saves": 0,
"dispossesed": 0,
"interceptions": 7,
"yellowcards": 5,
"yellowred": 0,
"redcards": 0,
"type": "domestic",
"tackles": 17,
"blocks": 1,
"hit_post": 3,
"cleansheets": 13,
"rating": "7.67",
"fouls": {
"committed": 32,
"drawn": 43
},
"crosses": {
"total": 22,
"accurate": 10
},
"dribbles": {
"attempts": 88,
"success": 57,
"dribbled_past": 12
},
"duels": {
"total": 86,
"won": 34
},
"passes": {
"total": 561,
"accuracy": 73,
"key_passes": 36
},
"penalties": {
"won": 1,
"scores": 5,
"missed": null,
"committed": null,
"saves": null
}
}
]
}
},https://soccer.sportmonks.com/api/v2.0/livescores/now?api_token={API_TOKEN}&include=lineup.player{
"team_id": 14,
"fixture_id": 17361246,
"player_id": 1878,
"player_name": "Marcus Rashford",
"number": 10,
"position": "A",
"additional_position": null,
"formation_position": 11,
"posx": null,
"posy": null,
"captain": false,
"type": "lineup",
"stats": {
"shots": {
"shots_total": 4,
"shots_on_goal": 3
},
"goals": {
"scored": 1,
"assists": 0,
"conceded": 0,
"owngoals": 0
},
"fouls": {
"drawn": 0,
"committed": 0
},
"cards": {
"yellowcards": 0,
"redcards": 0,
"yellowredcards": 0
},
"passing": {
"total_crosses": 0,
"crosses_accuracy": 0,
"passes": 22,
"accurate_passes": 17,
"passes_accuracy": 77,
"key_passes": 1
},
"dribbles": {
"attempts": 7,
"success": 2,
"dribbled_past": 1
},
"duels": {
"total": 14,
"won": 3
},
"other": {
"aerials_won": 0,
"punches": 0,
"offsides": 0,
"saves": 0,
"inside_box_saves": 0,
"pen_scored": 0,
"pen_missed": 0,
"pen_saved": 0,
"pen_committed": 0,
"pen_won": 0,
"hit_woodwork": 0,
"tackles": 1,
"blocks": 0,
"interceptions": 0,
"clearances": 2,
"dispossesed": 1,
"minutes_played": 90
},
"rating": "7.65"
},
"player": {
"data": {
"player_id": 1878,
"team_id": 14,
"country_id": 462,
"position_id": 4,
"common_name": "M. Rashford",
"display_name": "Marcus Rashford",
"fullname": "Marcus Rashford",
"firstname": "Marcus",
"lastname": "Rashford",
"nationality": "England",
"birthdate": "31/10/1997",
"birthcountry": "England",
"birthplace": "Manchester",
"height": "180 cm",
"weight": "70 kg",
"image_path": "https://cdn.sportmonks.com/images/soccer/players/22/1878.png"
}
}
},
minutes
The total number of minutes played in the requested season
appearences
The total number of appearences in the requested season
lineups
The total number of times the player was included in the lineup in the requested season
substitute_in
The total number of times the player was substituted into the field in the requested season
substitute_out
The total number of times the player was substituted off the field in the requested season
substitutes_on_bench
Number of times the player is in the squad, but starts a match on the bench
goals
The total number of goals the player has scored in the requested season
owngoals
The total number of own goals the player has scored in the requested season
assists
The total number of assists the player has given in the requested season
saves
The total number of saves the player has made. (only available for goalkeepers.)
inside_box_saves
The total number of inside the box (the goalkeeper area) saves the player has made. (only available for goalkeepers)
dispossesed
The total number of times the player was dispossesed in the requested season
interceptions
The total number of interceptions the player has made in the requested season
yellowcards
The total number of yellow cards the player has received in the requested season
yellowred
The total number of yellow-red cards the player has received in the requested season. In other words: if the player received a second yellow card that resulted in a red card.
redcards
The total number of red cards the player has received in the requested season
type
The season type
tackles
The total number of tackles the player has made in the requested season
blocks
The total number of blocks the player has made in the requested season
hit_post
The total number of times the player has hit the woodwork in the requested season
cleansheets
The total number of times the player has maintained a clean sheet in the requested season
rating
The average player rating in the requested season
fouls
Opens an array containing information about the fouls committed and drawn in the requested season
crosses
Opens an array containing information about the crosses the player has made in the requested season. Divided by total and accurate
dribbles
Opens an array containing information about dribbles the player was involved with in the requested season. Divided by attempts, success and the times an opponent dribbled past him
duels
Opens an array containing information about the duels the player was involved with in the requested season. Divided by total and won.
passes
Opens an array containing information about the passes the player has made in the requested season. Divided by total, accurate and key passes
penalties
Opens an array containing information about the penalties the player was involved with in the requested season. Divided by won, scored, missed, committed and saved
It’s possible to request statistics per team. This could be really interesting if you want to build a football application showing all the statistics of your favorite team. Requesting team statistics is easy!
Simply, use the team by id endpoint and once again use the include stats. For this example, we’ll request the team statistics of Real Madrid (team id: 3468):
Be aware that this request will give you all the team statistics of the seasons the team has played or is active in. Therefore, it might be useful to add a filter to only request the team statistics of the season you’re interested in.
For example, the request below will return all the team statistics of Real Madrid, but only for the Spanish La Liga 2019/2020 season (season id: 16326).
https://soccer.sportmonks.com/api/v2.0/teams/3468?api_token={API_TOKEN}&include=stats&seasons=16326Team Field Description
https://soccer.sportmonks.com/api/v2.0/teams/3468?api_token={API_TOKEN}&include=stats
The official twitter page of the team
country_id
The unique country id the team is from
national_team
Indicates if the team is a national team
founded
The year when the team was founded
logo_path
The logo URL path of the team logo
venue_id
The official venue of the team
current_season_id
The unique id of the season the team is active in
is_placeholder
Added a property on both fixture and team responses called is_placeholder. This property indicates if the resource is used to display dummy data. The false of this property will always be a boolean value.
Team Stats Field Description
Field
Description
team_id
The unique id of the team
season_id
The id of the season you've requested the stats for
stage_id
The id of the stage the stats belong to
win
Opens an array containing information about the number of times the team won a match in the requested season and stage. Divided by total, home and away
draw
Opens an array containing information about the number of times the team has played a match which ended in a draw in the requested season and stage. Divided by total, home and away
Field
Description
id
The unique id of the team
legacy_id
This was for our API version 1.0. It's only of use for old users of our API
name
The name of the team
short_code
The short code of the team
{
"data": {
"id": 3468,
"legacy_id": 117,
"name": "Real Madrid",
"short_code": "RMA",
"twitter": "@realmadrid",
"country_id": 32,
"national_team": false,
"founded": 1902,
"logo_path": "https://cdn.sportmonks.com/images//soccer/teams/12/3468.png",
"venue_id": 2020,
"current_season_id": 17480,
"is_placeholder": false,
"stats": {
"data": [
{
"team_id": 3468,
"season_id": 16326,
"stage_id": 77444988,
"win": {
"total": 26,
"home": 15,
"away": 11
},
"draw": {
"total": 9,
"home": 4,
"away": 5
},
"lost": {
"total": 3,
"home": 0,
"away": 3
},
"goals_for": {
"total": 70,
"home": 40,
"away": 30
},
"goals_against": {
"total": 25,
"home": 11,
"away": 14
},
"clean_sheet": {
"total": 19,
"home": 11,
"away": 8
},
"failed_to_score": {
"total": 6,
"home": 2,
"away": 4
},
"scoring_minutes": [
{
"period": [
{
"minute": "0-15",
"count": 8,
"percentage": 11.4
},
{
"minute": "15-30",
"count": 9,
"percentage": 12.9
},
{
"minute": "30-45",
"count": 13,
"percentage": 18.6
},
{
"minute": "45-60",
"count": 10,
"percentage": 14.3
},
{
"minute": "60-75",
"count": 15,
"percentage": 21.4
},
{
"minute": "75-90",
"count": 15,
"percentage": 21.4
}
]
}
],
"goals_conceded_minutes": [
{
"period": [
{
"minute": "0-15",
"count": 5,
"percentage": 20
},
{
"minute": "15-30",
"count": 0,
"percentage": 0
},
{
"minute": "30-45",
"count": 2,
"percentage": 8
},
{
"minute": "45-60",
"count": 3,
"percentage": 12
},
{
"minute": "60-75",
"count": 5,
"percentage": 20
},
{
"minute": "75-90",
"count": 10,
"percentage": 40
}
]
}
],
"avg_goals_per_game_scored": {
"total": 1.84,
"home": 2.11,
"away": 1.58
},
"avg_goals_per_game_conceded": {
"total": 0.66,
"home": 0.58,
"away": 0.74
},
"avg_first_goal_scored": {
"total": "42m",
"home": "39m",
"away": "45m"
},
"avg_first_goal_conceded": {
"total": "52m",
"home": "51m",
"away": "53m"
},
"attacks": 4557,
"dangerous_attacks": 2466,
"avg_ball_possession_percentage": "59.00",
"fouls": 476,
"avg_fouls_per_game": "12.53",
"offsides": 84,
"redcards": 4,
"yellowcards": 82,
"shots_blocked": 19,
"shots_off_target": 335,
"avg_shots_off_target_per_game": "8.82",
"shots_on_target": 229,
"avg_shots_on_target_per_game": "6.03",
"avg_corners": "5.05",
"total_corners": 192,
"btts": 44.74,
"goal_line": {
"over": {
"0_5": {
"home": 89.47,
"away": 89.47
},
"1_5": {
"home": 78.95,
"away": 57.89
},
"2_5": {
"home": 47.37,
"away": 52.63
},
"3_5": {
"home": 31.58,
"away": 26.32
},
"4_5": {
"home": 15.79,
"away": 5.26
},
"5_5": {
"home": 5.26,
"away": 0
}
},
"under": {
"0_5": {
"home": 10.53,
"away": 10.53
},
"1_5": {
"home": 21.05,
"away": 42.11
},
"2_5": {
"home": 52.63,
"away": 47.37
},
"3_5": {
"home": 68.42,
"away": 73.68
},
"4_5": {
"home": 84.21,
"away": 94.74
},
"5_5": {
"home": 94.74,
"away": 100
}
}
},
"avg_player_rating": 6.81,
"avg_player_rating_per_match": 6.82,
"tackles": null
}
]
}
},twitter
lost
Opens an array containing information about the number of times the team lost a match in the requested season and stage. Divided by total, home and away
goals_for
Opens an array containing information about the number of times the team has scored a goal in the requested season and stage. Divided by total, home and away
goals_against
Opens an array containing information about the number of times the team has conceded a goal in the requested season and stage. Divided by total, home and away
clean_sheet
Opens an array containing information about the number of times the team has maintained a clean sheet in the requested season and stage. Divided by total, home and away
failed_to_score
Opens an array containing information about the number of times the team has failed to score in a match in the requested season and stage. Divided by total, home and away
scoring_minutes
The total number of times the team has scored divided in minute periods
goals_conceded_minutes
The total number of times the team has conceded a goal divided in minute periods
avg_goals_per_game_scored
Opens an array containing information about the average goals the team has scored per game. Divided by total, home and away
avg_goals_per_game_conceded
Opens an array containing information about the average goals the team has conceded per game. Divided by total, home and away
avg_first_goal_scored
Opens an array containing information about the average minute the team has scored the first goal per game. Divided by total, home and away
avg_first_goal_conceded
Opens an array containing information about the average minute the team has conceded the first goal per game. Divided by total, home and away
attacks
The total number of attacks in the requested season and stage
dangerous_attacks
The total number of dangerous attacks in the requested season and stage
avg_ball_possession_percentage
The average ball possession, in percentage % in the requested season and stage
fouls
The total number of fouls in the requested season and stage
avg_fouls_per_game
The total number of fouls per game in the requested season and stage
offsides
The total number of offsides in the requested season and stage
redcards
The total number of red cards in the requested season and stage
yellowcards
The total number of yellow cards in the requested season and stage
shots_blocked
The total number of shots blocked by the opponent in the requested season and stage
shots_off_target
The total number of shots off target in the requested season and stage
avg_shots_off_target_per_game
The average number of shots off target per game in the requested season and stage
shots_on_target
The total number of shots on target in the requested season and stage
avg_shots_on_target_per_game
The average number shots on target per game in the requested season and stage
avg_corners
The average number of corners per game in the requested season and stage
total_corners
The total number of corners in the requested season and stage
btts
The number of times both teams scored in percentage in the requested season and stage
goal_line
The average goal line market in the requested season and stage
avg_player_rating
The average player rating in the requested season and stage
avg_player_rating_per_match
The average player rating per match in the requested season and stage
tackles
The total number of tackles in the requested season and stage
