Competition Statistics - SportsAPI Pro

Overview

The Competition Statistics endpoint provides comprehensive statistical data for a competition including:

Athlete Statistics: Goals, assists, expected goals, ratings, cards, clean sheets, saves, and more
Team Statistics: Goals per game, possession, corners, clean sheets, and disciplinary records

All statistics are organized by category with leaderboard-style rankings.

Parameters

competitions

string

required

Competition ID to retrieve statistics for (e.g., 7685 for UEFA Conference League).

competitors

string

Optional filter by team ID to get statistics for a specific team’s players.

phaseNum

integer

default:"-1"

Competition phase number. Use -1 for overall/total statistics.

withSeasons

boolean

default:"true"

Include season and stage information in the response.

lastUpdateId

integer

For incremental updates. Pass the lastUpdateId from a previous response to get only changed data.

Parameters like appTypeId, langId, timezoneName, and userCountryId are automatically resolved. You can override timezoneName with a specific timezone (e.g., America/New_York).

Request

curl -X GET "https://v1.football.sportsapipro.com/stats?competitions=7685&withSeasons=true" \
  -H "x-api-key: YOUR_API_KEY"

Response

{
  "lastUpdateId": 5494811901,
  "requestedUpdateId": -1,
  "ttl": 60,
  "stats": {
    "athletesStats": [
      {
        "id": 1,
        "name": "Goals",
        "competitionId": 7685,
        "rows": [
          {
            "position": 0,
            "secondaryStatName": "Penalties Scored: 0",
            "entity": {
              "id": 83722,
              "name": "Franko Kovačević",
              "shortName": "F. Kovačević",
              "nameForURL": "franko-kovacevic",
              "countryId": 38,
              "competitorId": 2345,
              "positionName": "Centre Forward",
              "positionShortName": "Centre Forward",
              "imageVersion": 7
            },
            "stats": [
              {
                "typeId": 1,
                "value": "5"
              },
              {
                "typeId": 10,
                "value": "0"
              }
            ]
          }
        ],
        "statsTypes": [
          {
            "typeId": 1,
            "name": "Goals"
          },
          {
            "typeId": 10,
            "name": "Goal In Penalties"
          }
        ]
      }
    ],
    "competitorsStats": [
      {
        "id": 1,
        "name": "Goals Scored",
        "competitionId": 7685,
        "averageStat": {
          "text": "Average Per Team",
          "value": "1.30"
        },
        "rows": [
          {
            "position": 1,
            "secondaryStatName": "Total Goals: 11",
            "entity": {
              "id": 1024,
              "name": "AEK Athens",
              "countryId": 13,
              "countryName": "Greece",
              "competitorId": 1024
            },
            "stats": [
              {
                "typeId": 3,
                "value": "2.2"
              },
              {
                "typeId": 2,
                "value": "11"
              }
            ]
          }
        ],
        "statsTypes": [
          {
            "typeId": 3,
            "name": "Goals Scored"
          },
          {
            "typeId": 2,
            "name": "Total Goals"
          }
        ]
      }
    ]
  },
  "sports": [...],
  "countries": [...],
  "competitions": [...]
}

Response Fields

Root Level

Field	Type	Description
`lastUpdateId`	integer	Version ID for incremental updates
`requestedUpdateId`	integer	Requested update ID (-1 for latest)
`ttl`	integer	Cache TTL in seconds (typically 60)
`stats`	object	Container for all statistics
`sports`	array	Related sports metadata
`countries`	array	Related countries metadata
`competitions`	array	Competition details with seasons

Stats Object

Field	Type	Description
`athletesStats`	array	Player statistics categories
`competitorsStats`	array	Team statistics categories

Athlete Stats Category

Field	Type	Description
`id`	integer	Category identifier
`name`	string	Category name (e.g., “Goals”, “Assists”)
`competitionId`	integer	Associated competition ID
`rows`	array	Leaderboard entries for this category
`statsTypes`	array	Stat type definitions for the columns

Athlete Stats Row

Field	Type	Description
`position`	integer	Rank position (0-indexed)
`secondaryStatName`	string	Additional context stat
`entity`	object	Player information
`stats`	array	Statistical values for this player

Player Entity

Field	Type	Description
`id`	integer	Player unique identifier
`name`	string	Full player name
`shortName`	string	Abbreviated name
`nameForURL`	string	URL-safe name slug
`countryId`	integer	Player nationality country ID
`competitorId`	integer	Current team ID
`positionName`	string	Playing position
`positionShortName`	string	Abbreviated position
`imageVersion`	integer	Player image version

Competitor Stats Category

Field	Type	Description
`id`	integer	Category identifier
`name`	string	Category name (e.g., “Goals Scored”)
`competitionId`	integer	Associated competition ID
`averageStat`	object	League average for this stat
`rows`	array	Leaderboard entries for teams
`statsTypes`	array	Stat type definitions

Team Entity

Field	Type	Description
`id`	integer	Team unique identifier
`name`	string	Team name
`shortName`	string	Abbreviated team name
`countryId`	integer	Team country ID
`countryName`	string	Team country name
`competitorId`	integer	Competitor ID

Available Athlete Statistics

ID	Category Name	Description
1	Goals	Top scorers with penalty breakdown
2	Expected Goals	xG rankings
3	Assists	Assist leaders with xA
4	Expected Assists	xA rankings
5	Goals and Assists	Combined G+A
6	Expected Goals + Assists	Combined xG+xA
7	Shots On Target	Shots on goal
8	Big Chances Created	High-quality chances created
9	Successful Dribbles	Completed take-ons
10	Tackles Won	Defensive tackles
11	Interceptions	Interception leaders
12	Clearances	Defensive clearances
13	Clean Sheets	Goalkeeper clean sheets
14	Saves	Goalkeeper saves
15	Yellow Cards	Yellow card count
16	Red Cards	Red card count

Available Team Statistics

ID	Category Name	Description
1	Goals Scored	Total goals scored
2	Goals Conceded	Total goals conceded
3	Shots On Target	Team shots on goal
4	Possession %	Average possession
5	Pass Accuracy %	Pass completion rate
6	Tackles Won	Team tackles
7	Clean Sheets	Matches without conceding
8	Yellow Cards	Team yellow cards
9	Red Cards	Team red cards

Stat Type IDs

Type ID	Name	Description
1	Goals	Total goals scored
2	Assists	Total assists
3	Yellow Cards	Yellow card count
4	Red Cards	Red card count
10	Goal In Penalties	Penalties scored
12	Clean Sheets	Matches without conceding
14	Penalties Saved	Penalties stopped
36	Rating	Player rating
38	Tackles	Tackles won
42	Expected Goals	xG value
44	Expected Assists	xA value
61	Goals And Assists	Combined G+A
63	Interceptions	Interceptions
66	Goals Conceded	Goals against
67	Saves	Goalkeeper saves
68	Expected Goals And Assists	Combined xG+xA

Notes

Statistics are updated periodically; use lastUpdateId for efficient polling
The ttl value indicates recommended cache duration (60 seconds)
Position values in rows may be 0-indexed or 1-indexed depending on the category
Player images can be fetched using: /images/athletes/{athleteId}
Team images can be fetched using: /images/competitors/{competitorId}

When using the competitors parameter to fetch team-specific data, the competitors array in the response may include additional related teams. Always filter by the specific ID you need:

const targetCompetitor = data.competitors?.find(c => c.id === parseInt(competitorId));

Authorizations

x-api-key

string

header

required

Your SportsAPI Pro API key

Query Parameters

competitions

integer

required

Competition ID (e.g., 132 for NBA)

Example:

132

competitors

integer

Filter by team ID

withSeasons

boolean

default:false

Include season information

Response

200

Statistics retrieved successfully

​Overview

​Parameters

​Request

​Response

​Response Fields

​Root Level

​Stats Object

​Athlete Stats Category

​Athlete Stats Row

​Player Entity

​Competitor Stats Category

​Team Entity

​Available Athlete Statistics

​Available Team Statistics

​Stat Type IDs

​Notes

Authorizations

Query Parameters

Response

Overview

Parameters

Request

Response

Response Fields

Root Level

Stats Object

Athlete Stats Category

Athlete Stats Row

Player Entity

Competitor Stats Category

Team Entity

Available Athlete Statistics

Available Team Statistics

Stat Type IDs

Notes