search
OddsCoreAPI 2 (Deprecated)WidgetsContact

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
chevron-rightResponsehashtag
{
  "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
chevron-rightResponsehashtag
{
  "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.

triangle-exclamation

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.

hashtag
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):

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 (goals), 193 (cards), 194 (clean sheets); find all season stat types in the Season Statistics Types Referencearrow-up-right

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

chevron-rightResponsehashtag

hashtag
See also

hashtag
Prerequisites

hashtag
Reference

hashtag
Related Tutorials

PreviousStatistics typesNextFixture statistics

Last updated

Was this helpful?