Fixture statistics

Team fixture statistics

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 GET Fixtures by ID endpoint.

Let's take a look at the match statistics for Celtic vs Rangers (id: 18535517) by using the statistics include:

https://api.sportmonks.com/v3/football/fixtures/18535517?api_token=YOUR_TOKEN&include=statistics

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:

https://api.sportmonks.com/v3/football/fixtures/18535517?api_token=YOUR_TOKEN&include=statistics.type

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",
        "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.

Check our filtering tutorial for valuable tips and tricks.

What if you're only interested in specific statistics like shots on target? To filter your request, you need to:

1. Add the parameter &filters=

2. Select the entity you want to filter on

3. Select the field you want to filter on

4. 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:

1. Add the parameter &filters=

2. Select the entity you want to filter on: fixtureStatistic

3. Select the field you want to filter on: Types (the statistics types)

4. 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

https://api.sportmonks.com/v3/football/fixtures/18535517?api_token=YOUR_TOKEN&include=statistics.type&filters=fixtureStatisticTypes:86

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",
        "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:

https://api.sportmonks.com/v3/football/fixtures/18535517?api_token=YOUR_TOKEN&include=lineups

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:

https://api.sportmonks.com/v3/football/fixtures/18535517?api_token=YOUR_TOKEN&include=lineups.details

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,
        "details": [
          {
            "id": 285241740,
            "fixture_id": 18535517,
            "player_id": 275,
            "team_id": 53,
            "lineup_id": 296138906,
            "type_id": 118,
            "data": {
              "value": 7.75
            }
          },
          {
            "id": 285241742,
            "fixture_id": 18535517,
            "player_id": 275,
            "team_id": 53,
            "lineup_id": 296138906,
            "type_id": 116,
            "data": {
              "value": 31
            }
          },
 //And more

Just like with the other statistics include, you can add .type to your include to obtain the statistics' names:

https://api.sportmonks.com/v3/football/fixtures/18535517?api_token=YOUR_TOKEN&include=lineups.details.type

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,
        "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:

1. Add the parameter &filters=

2. Select the entity you want to filter on

3. Select the field you want to filter on

4. 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:

1. Add the parameter &filters=

2. Select the entity you want to filter on: lineupDetail

3. Select the field you want to filter on: Types (the statistics types)

4. 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

https://api.sportmonks.com/v3/football/fixtures/18535517?api_token={your_token}&include=lineups.details.type&filters=lineupDetailTypes:80

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,
        "details": [
          {
            "id": 285241743,
            "fixture_id": 18535517,
            "player_id": 275,
            "team_id": 53,
            "lineup_id": 296138906,
            "type_id": 80,
            "data": {
              "value": 34
            },
            "type": {
              "id": 80,
              "name": "Passes",
              "code": "passes",
              "developer_name": "PASSES",
              "model_type": "statistic",
              "stat_group": "overall"
            }
          }
        ]
      },
      {
        "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,
        "details": [
          {
            "id": 285241760,
            "fixture_id": 18535517,
            "player_id": 173080,
            "team_id": 53,
            "lineup_id": 296138902,
            "type_id": 80,
            "data": {
              "value": 46
            },
            "type": {
              "id": 80,
              "name": "Passes",
              "code": "passes",
              "developer_name": "PASSES",
              "model_type": "statistic",
              "stat_group": "overall"
            }
          }
        ]
      },
  //And more

Want to combine the match and player stats? Easy, add the extra includes:

https://api.sportmonks.com/v3/football/fixtures/18535517?api_token=YOUR_TOKEN&include=statistics.type;lineups.details.type

Want to filter it?

https://api.sportmonks.com/v3/football/fixtures/18535517?api_token=YOUR_TOKEN&include=statistics.type;lineups.details.type&filters=lineupDetailTypes:80,119,116;fixtureStatisticTypes:86,78

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