Fixture statistics are available for the teams participating in the fixture and the players. You can access a fixture via one of our fixtures endpoints. For this example, we will be using the Fixtures by ID endpoint.
Let's take a look at the match statistics for Celtic vs Rangers (id: 18535517) by using the statistics include:
Is this the first time you've heard about includes? Check our includes tutorial.
Response
{"data": {"id":18535517,"sport_id":1,"league_id":501,"season_id":19735,"stage_id":77457866,"group_id":null,"aggregate_id":null,"round_id":274719,"state_id":5,"venue_id":8909,"name":"Celtic vs Rangers","starting_at":"2022-09-03 11:30:00","result_info":"Celtic won after full-time.","leg":"1/1","details":null,"length":90,"placeholder":false,"last_processed_at":"2023-03-02 17:47:38","has_odds":true,"starting_at_timestamp":1662204600,"statistics": [ {"id":5914502,"fixture_id":18535517,"type_id":86,"participant_id":53,"data": {"value":6 },"location":"home" }, {"id":5914520,"fixture_id":18535517,"type_id":78,"participant_id":62,"data": {"value":17 },"location":"away" },//And more
The statistics include returns the match statistics for both teams. Our API returns many values, but what do they mean exactly? And how can you display the type of statistic? You can use the nested include statistics.type for this:
{"data": {"id":18535517,"sport_id":1,"league_id":501,"season_id":19735,"stage_id":77457866,"group_id":null,"aggregate_id":null,"round_id":274719,"state_id":5,"venue_id":8909,"name":"Celtic vs Rangers","starting_at":"2022-09-03 11:30:00","result_info":"Celtic won after full-time.","leg":"1/1","details":null,"length":90,"placeholder":false,"last_processed_at":"2023-03-02 17:47:38","has_odds":true,"starting_at_timestamp":1662204600,"statistics": [ {"id":5914502,"fixture_id":18535517,"type_id":86,"participant_id":53,"data": {"value":6 },"location":"home","type": {"id":86,"name":"Shots On Target","code":"shots-on-target","developer_name":"SHOTS_ON_TARGET","model_type":"statistic","stat_group":"offensive" } }, {"id":5914520,"fixture_id":18535517,"type_id":78,"participant_id":62,"data": {"value":17 },"location":"away","type": {"id":78,"name":"Tackles","code":"tackles","developer_name":"TACKLES","model_type":"statistic","stat_group":"defensive" } },//And more
Please check the response carefully to see the correct values with the types.
Including .type is not recommended as an include on any endpoint. Types are used throughout the entire API. We recommend retrieving all types from the types endpoint and storing them in your database or other data structure. Only include the type if no other option is available or when testing the API.
Filtering team fixture statistics
The API returns a lot of statistics, but we can imagine you're interested in only some of them.
What if you're only interested in specific statistics like shots on target? To filter your request, you need to:
Add the parameter &filters=
Select the entity you want to filter on
Select the field you want to filter on
Fill in the IDs you're interested in
Let's say you're only interested in the shots on goal. In our case, this will result in the following steps:
Add the parameter &filters=
Select the entity you want to filter on: fixtureStatistic
Select the field you want to filter on: Types (the statistics types)
Fill in the IDs you're interested in: 86 (You can retrieve them via the Types endpoint or by looking at the previous request)
It's important to note that you can retrieve statistics from multiple entities. Therefore, you also need to specify for which entity you want to filter the statistics. You can do this by prefixing the filter with the entity's name. So in our case: fixtureStatistic
{"data": {"id":18535517,"sport_id":1,"league_id":501,"season_id":19735,"stage_id":77457866,"group_id":null,"aggregate_id":null,"round_id":274719,"state_id":5,"venue_id":8909,"name":"Celtic vs Rangers","starting_at":"2022-09-03 11:30:00","result_info":"Celtic won after full-time.","leg":"1/1","details":null,"length":90,"placeholder":false,"last_processed_at":"2023-03-02 17:47:38","has_odds":true,"starting_at_timestamp":1662204600,"statistics": [ {"id":5914502,"fixture_id":18535517,"type_id":86,"participant_id":53,"data": {"value":6 },"location":"home","type": {"id":86,"name":"Shots On Target","code":"shots-on-target","developer_name":"SHOTS_ON_TARGET","model_type":"statistic","stat_group":"offensive" } }, {"id":5914503,"fixture_id":18535517,"type_id":86,"participant_id":62,"data": {"value":2 },"location":"away","type": {"id":86,"name":"Shots On Target","code":"shots-on-target","developer_name":"SHOTS_ON_TARGET","model_type":"statistic","stat_group":"offensive" } } ] },
Are you interested in more statistics? Add more statistics IDs to your request by separating them with a comma (,). Check our syntax section for more helpful information.
Player fixture statistics
You might wonder, how can I retrieve the statistics of the players per fixture? While the statistics include only returns the team statistics, the lineups include produces the player statistics.
Let's look at how to retrieve these statistics for Celtic vs Rangers (id: 18535517).
As mentioned, player statistics for a specific fixture are available in the lineups include:
Is this the first time you've heard about includes? Check our includes tutorial.
Response
{"data": {"id":18535517,"sport_id":1,"league_id":501,"season_id":19735,"stage_id":77457866,"group_id":null,"aggregate_id":null,"round_id":274719,"state_id":5,"venue_id":8909,"name":"Celtic vs Rangers","starting_at":"2022-09-03 11:30:00","result_info":"Celtic won after full-time.","leg":"1/1","details":null,"length":90,"placeholder":false,"last_processed_at":"2023-03-02 17:47:38","has_odds":true,"starting_at_timestamp":1662204600,"lineups": [ {"id":296138906,"sport_id":1,"fixture_id":18535517,"player_id":275,"team_id":53,"position_id":24,"formation_field":"1:1","type_id":11,"formation_position":1,"player_name":"Joe Hart","jersey_number":1 }, {"id":296138902,"sport_id":1,"fixture_id":18535517,"player_id":173080,"team_id":53,"position_id":25,"formation_field":"2:4","type_id":11,"formation_position":5,"player_name":"Greg Taylor","jersey_number":3 },//And more
However, as you can see, the lineups only return player info by default: not the statistics. To retrieve the statistics, you need to add the nested include .details to your request. This results in the below request:
{"data": {"id":18535517,"sport_id":1,"league_id":501,"season_id":19735,"stage_id":77457866,"group_id":null,"aggregate_id":null,"round_id":274719,"state_id":5,"venue_id":8909,"name":"Celtic vs Rangers","starting_at":"2022-09-03 11:30:00","result_info":"Celtic won after full-time.","leg":"1/1","details":null,"length":90,"placeholder":false,"last_processed_at":"2023-03-02 17:47:38","has_odds":true,"starting_at_timestamp":1662204600,"lineups": [ {"id":296138906,"sport_id":1,"fixture_id":18535517,"player_id":275,"team_id":53,"position_id":24,"formation_field":"1:1","type_id":11,"formation_position":1,"player_name":"Joe Hart","jersey_number":1,"details": [ {"id":285241740,"fixture_id":18535517,"player_id":275,"team_id":53,"lineup_id":296138906,"type_id":118,"data": {"value":7.75 },"type": {"id":118,"name":"Rating","code":"rating","developer_name":"RATING","model_type":"statistic","stat_group":"overall" } },//And more
Please check the response carefully to see the correct values with the types.
Including .type is not recommended as an include on any endpoint. Types are used throughout the entire API. We recommend retrieving all types from the types endpoint and storing them in your database or other data structure. Only include the type if no other option is available or when testing the API.
Filtering player fixture statistics
What if you're only interested in specific statistics like passes? To filter your request, you need to:
Add the parameter &filters=
Select the entity you want to filter on
Select the field you want to filter on
Fill in the IDs you're interested in
Let's say you're only interested in the passes. In our case, this will result in the following steps:
Add the parameter &filters=
Select the entity you want to filter on: lineupDetail
Select the field you want to filter on: Types (the statistics types)
Fill in the IDs you're interested in: 80 (You can retrieve them via the Types endpoint or by looking at the previous request)
It's important to note that you can retrieve statistics from multiple entities. Therefore, you also need to specify for which entity you want to filter the statistics. You can do this by prefixing the filter with the entity's name. So in our case: lineupDetail
Are you only interested in the name of the type? Use our select functionality: https://api.sportmonks.com/v3/football/fixtures/18535517?api_token=YOUR_TOKEN&include=statistics.type:name;lineups.details.type:name&filters=lineupDetailTypes:80,119,116;fixtureStatisticTypes:86,78