Season statistics

Keep track of exciting 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. There are multiple ways to retrieve season statistics, but the most commonly used is the GET Season by ID endpoint with the statistics include:

https://api.sportmonks.com/v3/football/seasons/{season_id}?api_token=YOUR_TOKEN&include=statistics 

Is this the first time you've heard about includes? Check our includes tutorial.

Let's take a look at the 2022/2023 season of the Scottish Premiership (season id 19735):

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

Response

{
  "data": {
    "id": 19735,
    "sport_id": 1,
    "league_id": 501,
    "tie_breaker_rule_id": 171,
    "name": "2022/2023",
    "finished": false,
    "pending": false,
    "is_current": true,
    "starting_at": "2022-07-30",
    "ending_at": "2023-04-22",
    "standings_recalculated_at": "2023-03-03 00:07:44",
    "games_in_current_week": false,
    "statistics": [
      {
        "id": 46371,
        "model_id": 19735,
        "type_id": 34,
        "relation_id": 53,
        "value": {
          "count": 194,
          "percentage": 12.08,
          "team_most_corners_id": 53,
          "team_most_corners_name": "Celtic"
        },
        "type": "array"
      },
      {
        "id": 46381,
        "model_id": 19735,
        "type_id": 188,
        "relation_id": null,
        "value": {
          "total": 198,
          "played": 159,
          "percentage": 80.3
        },
        "type": "array"
      },
//And more      

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/seasons/19735?api_token=YOUR_TOKEN&include=statistics.type

Response

{
  "data": {
    "id": 19735,
    "sport_id": 1,
    "league_id": 501,
    "tie_breaker_rule_id": 171,
    "name": "2022/2023",
    "finished": false,
    "pending": false,
    "is_current": true,
    "starting_at": "2022-07-30",
    "ending_at": "2023-04-22",
    "standings_recalculated_at": "2023-03-03 00:07:44",
    "games_in_current_week": false,
    "statistics": [
      {
        "id": 46371,
        "model_id": 19735,
        "type_id": 34,
        "relation_id": 53,
        "value": {
          "count": 194,
          "percentage": 12.08,
          "team_most_corners_id": 53,
          "team_most_corners_name": "Celtic"
        },
        "type": {
          "id": 34,
          "name": "Corners",
          "code": "corners",
          "developer_name": "CORNERS",
          "model_type": "statistic",
          "stat_group": "offensive"
        }
      },
      {
        "id": 46381,
        "model_id": 19735,
        "type_id": 188,
        "relation_id": null,
        "value": {
          "total": 198,
          "played": 159,
          "percentage": 80.3
        },
        "type": {
          "id": 188,
          "name": "Season Matches",
          "code": "matches",
          "developer_name": "MATCHES",
          "model_type": "statistic",
          "stat_group": null
        }
      },
      {
        "id": 46390,
        "model_id": 19735,
        "type_id": 189,
        "relation_id": null,
        "value": {
          "total": 12,
          "countries": 1
        },
        "type": {
          "id": 189,
          "name": "Season Teams",
          "code": "total-teams",
          "developer_name": "TOTAL_TEAMS",
          "model_type": "statistic",
          "stat_group": null
        }
      },
  //And more!    

Now, the season statistics' names and types are also returned. For example, at the time of writing, you can see 198 matches in the season; 159 have already been played, giving a percentage of 80.3%—this is a fantastic way to show the season's progression.

Please check the response carefully to see the correct values for 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 season statistics

The API returns a lot of season statistics, but we can imagine you're interested in only some of them. Therefore, it might be good to filter only the data you want.

Check out our filtering tutorial for valuable tips and tricks.

Let's continue with the previous example: the 2022/2023 season of the Scottish Premiership (season id 19735):

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

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 number of goals, cards, and clean sheets. In our case, this will result in the following steps:

1. Add the parameter &filters=

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

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

4. Fill in the IDs you're interested in: 191,193,194 (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 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: seasonStatistic

https://api.sportmonks.com/v3/football/seasons/19735?api_token=YOUR_TOKEN&include=statistics.type&filters=seasonStatisticTypes:191,193,194

Response

{
  "data": {
    "id": 19735,
    "sport_id": 1,
    "league_id": 501,
    "tie_breaker_rule_id": 171,
    "name": "2022/2023",
    "finished": false,
    "pending": false,
    "is_current": true,
    "starting_at": "2022-07-30",
    "ending_at": "2023-04-22",
    "standings_recalculated_at": "2023-03-03 00:07:44",
    "games_in_current_week": false,
    "statistics": [
      {
        "id": 46383,
        "model_id": 19735,
        "type_id": 191,
        "relation_id": null,
        "value": {
          "total": 460,
          "home": {
            "count": 271,
            "percentage": 58.91,
            "average": 1.7
          },
          "away": {
            "count": 189,
            "percentage": 41.09,
            "average": 2.43
          },
          "average": 2.89
        },
        "type": {
          "id": 191,
          "name": "Number Of Goals",
          "code": "number-of-goals",
          "developer_name": "NUMBER_OF_GOALS",
          "model_type": "statistic",
          "stat_group": null
        }
      },
      {
        "id": 46369,
        "model_id": 19735,
        "type_id": 193,
        "relation_id": null,
        "value": {
          "yellowcards": 660,
          "redcards": 31,
          "yellowredcards": 15,
          "average_yellowcards": 4.15,
          "average_redcards": 0.19,
          "average_yellowredcards": 0.09
        },
        "type": {
          "id": 193,
          "name": "Cards",
          "code": "cards",
          "developer_name": "CARDS",
          "model_type": "statistic",
          "stat_group": null
        }
      },
      {
        "id": 46370,
        "model_id": 19735,
        "type_id": 194,
        "relation_id": null,
        "value": {
          "count": 6,
          "percentage": 3.77
        },
        "type": {
          "id": 194,
          "name": "Cleansheets",
          "code": "cleansheets",
          "developer_name": "CLEANSHEET",
          "model_type": "statistic",
          "stat_group": null
        }
      }
    ]
  },