Includes

The "Includes" parameter allows you to specify additional information to be included in the API response. For xG values, we offer two primary includes: xGFixture and the nested include lineups.xGLineup.

Expected by Team (xG by Team)

Fixtures

To retrieve the xG values by team for a fixture, we've introduced an include to use. You can use xGFixture on the Fixture entities, to retrieve the xG values for teams participating in a match. You can use this include as follows:

Request

https://api.sportmonks.com/v3/football/fixtures/date/2024-03-03??include=xGFixture

Response

      "expected": [
        {
          "id": 27141258,
          "fixture_id": 18842545,
          "type_id": 5304,
          "participant_id": 9,
          "data": {
            "value": 3.6439
          },
          "location": "home"
        },
        {
          "id": 27141259,
          "fixture_id": 18842545,
          "type_id": 5304,
          "participant_id": 14,
          "data": {
            "value": 0.3841
          },
          "location": "away"
        },
        {
          "id": 27141260,
          "fixture_id": 18842545,
          "type_id": 5305,
          "participant_id": 9,
          "data": {
            "value": 4.4602
          },
          "location": "home"
        },
        {
          "id": 27141261,
          "fixture_id": 18842545,
          "type_id": 5305,
          "participant_id": 14,
          "data": {
            "value": 0.2255
          },
          "location": "away"
        }
      ]
    }

Seasons

To retrieve the xG values by team for a season, we've implemented this to an existing include for you to use. You can use statistics.details.type on the Teams endpoints, to retrieve the xG values for teams participating in a season. You can use this include as follows:

Request

https://api.sportmonks.com/v3/football/teams/19?include=statistics.details.type&filters=teamStatisticSeasons:23614

Response

{
    "data": {
        "id": 19,
        "sport_id": 1,
        "country_id": 462,
        "venue_id": 204,
        "gender": "male",
        "name": "Arsenal",
        "short_code": "ARS",
        "image_path": "https://cdn.sportmonks.com/images/soccer/teams/19/19.png",
        "founded": 1886,
        "type": "domestic",
        "placeholder": false,
        "last_played_at": "2024-08-31 11:30:00",
        "statistics": [
            {
                "id": 346678,
                "team_id": 19,
                "season_id": 23614,
                "has_values": true,
                "details": [
                    {
                        "id": 4545753,
                        "team_statistic_id": 346678,
                        "type_id": 211,
                        "value": {
                            "rating": 8.13,
                            "player_id": 16827155,
                            "player_name": "Bukayo Saka"
                        },
                        "type": {
                            "id": 211,
                            "name": "Highest Rated Player",
                            "code": "highest-rated-player",
                            "developer_name": "HIGHEST_RATED_PLAYER",
                            "model_type": "statistic",
                            "stat_group": null
                        }
                    },
                    {
                        "id": 4545734,
                        "team_statistic_id": 346678,
                        "type_id": 5304,
                        "value": {
                            "expected": 3.8753,
                            "actual": 5,
                            "difference": 1.125
                        },
                        "type": {
                            "id": 5304,
                            "name": "Expected Goals (xG)",
                            "code": "expected-goals",
                            "developer_name": "EXPECTED_GOALS",
                            "model_type": "statistic",
                            "stat_group": "offensive"
                        }
                    },

Please note that not all season xG types are available yet. At the moment we only offer xG (type ID: 5304).

Expected by player (xG by Player)

Fixtures

To retrieve the xG values by player for a fixture, we've introduced a nested include to use. You can use lineups.xGLineup on the Fixture entities, to retrieve the xG values for players participating in a match. You can use this include as follows:

Request

https://api.sportmonks.com/v3/football/fixtures/date/2024-03-03?include=lineups.xGLineup

Response

        {
          "id": 8193384466,
          "sport_id": 1,
          "fixture_id": 18842545,
          "player_id": 154421,
          "team_id": 9,
          "position_id": 27,
          "formation_field": "5:1",
          "type_id": 11,
          "formation_position": 11,
          "player_name": "Erling Haaland",
          "jersey_number": 9,
          "expected": [
            {
              "id": 1068406356,
              "fixture_id": 18842545,
              "player_id": 154421,
              "team_id": 9,
              "lineup_id": 8193384466,
              "type_id": 5304,
              "data": {
                "value": 1.1634
              }
            },
            {
              "id": 1068406358,
              "fixture_id": 18842545,
              "player_id": 154421,
              "team_id": 9,
              "lineup_id": 8193384466,
              "type_id": 5305,
              "data": {
                "value": 1.1634
              }
            }
          ]

Seasons

We've added this to an existing include for you to use in order to access the xG values by player for a given season. To obtain the xG values for the teams taking part in a season, use the statistics.details.type include on the Players endpoints. This can be put to use for the following:

Request

https://api.sportmonks.com/v3/football/players/26823?include=statistics.details.type&filters=teamStatisticSeasons:23614

Response

{
    "data": {
        "id": 26823,
        "sport_id": 1,
        "country_id": 1578,
        "nationality_id": 1578,
        "city_id": null,
        "position_id": 26,
        "detailed_position_id": 150,
        "type_id": 26,
        "common_name": "M. Ødegaard",
        "firstname": "Martin",
        "lastname": "Ødegaard",
        "name": "Martin Ødegaard",
        "display_name": "M. Ødegaard",
        "image_path": "https://cdn.sportmonks.com/images/soccer/players/7/26823.png",
        "height": 178,
        "weight": 68,
        "date_of_birth": "1998-12-17",
        "gender": "male",
        "statistics": [
            {
                "id": 1324089238,
                "player_id": 26823,
                "team_id": 19,
                "season_id": 23614,
                "has_values": true,
                "position_id": 26,
                "jersey_number": 8,
                "details": [
                    {
                        "id": 37872088,
                        "player_statistic_id": 1324089238,
                        "type_id": 40,
                        "value": {
                            "total": 3
                        },
                        "type": {
                            "id": 40,
                            "name": "Captain",
                            "code": "captain",
                            "developer_name": "CAPTAIN",
                            "model_type": "statistic",
                            "stat_group": "overall"
                        }
                    },
                    {
                        "id": 37872190,
                        "player_statistic_id": 1324089238,
                        "type_id": 5304,
                        "value": {
                            "expected": 0.46190000000000003,
                            "actual": 0,
                            "difference": -0.462
                        },
                        "type": {
                            "id": 5304,
                            "name": "Expected Goals (xG)",
                            "code": "expected-goals",
                            "developer_name": "EXPECTED_GOALS",
                            "model_type": "statistic",
                            "stat_group": "offensive"
                        }
                    },

Please note that not all season xG types are available yet. At the moment we only offer xG (type ID: 5304).

Expected Points Table (xPTS Table)

To retrieve the xPTS table for a specific league, you can use an include that already exists and is widely used within our API. You can use the details.type include on any of the Standings endpoints. There you'll find the type ID 7393 for Expected Points (xPTS). Here's how you use that include:

Request

https://api.sportmonks.com/v3/football/standings/seasons/23614?include=details.type

Response

{
    "data": [
        {
            "id": 229327,
            "participant_id": 9,
            "sport_id": 1,
            "league_id": 8,
            "season_id": 23614,
            "stage_id": 77471288,
            "group_id": null,
            "round_id": 339237,
            "standing_rule_id": 117804,
            "position": 1,
            "result": "equal",
            "points": 9,
            "details": [
                {
                    "id": 3131200680,
                    "standing_type": "standing",
                    "standing_id": 229327,
                    "type_id": 146,
                    "value": 1,
                    "type": {
                        "id": 146,
                        "name": "Away Goals Conceded",
                        "code": "away-conceded",
                        "developer_name": "AWAY_CONCEDED",
                        "model_type": "standings",
                        "stat_group": "away"
                    }
                },
                {
                    "id": 3131200681,
                    "standing_type": "standing",
                    "standing_id": 229327,
                    "type_id": 179,
                    "value": 7,
                    "type": {
                        "id": 179,
                        "name": "Goal Difference",
                        "code": "goal-difference",
                        "developer_name": "OVERALL_GOAL_DIFFERENCE",
                        "model_type": "standings",
                        "stat_group": null
                    }
                {
                    "id": 3432092037,
                    "standing_type": "standing",
                    "standing_id": 229327,
                    "type_id": 7939,
                    "value": 6,
                    "type": {
                        "id": 7939,
                        "name": "Expected Points (xPTS)",
                        "code": "expected-points",
                        "developer_name": "EXPECTED_POINTS",
                        "model_type": "statistic",
                        "stat_group": "offensive"
                    }
                }
            ]
        },

If you've got any questions or comments about using these includes, feel free to reach out to us at [e-mail].