Competition Statistics

Retrieve player and team statistics for a specific competition, including top scorers, assists, clean sheets, and more.

GET /stats

Competition Statistics

cURL

curl --request GET \
  --url https://v1.basketball.sportsapipro.com/stats \
  --header 'x-api-key: <api-key>'

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 by the upstream service. You can override timezoneName with a specific timezone (e.g., America/New_York).

Request

cURL

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 Per Game",
        "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 Per Game"
          },
          {
            "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 Per Game”)
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	365 Ratings	Player ratings
8	Penalties Scored	Penalty conversion
9	Tackles Won Per Game	Defensive tackles
10	Interceptions Per Game	Interception leaders
11	Red Cards	Red card count
12	Yellow Cards	Yellow card count
13	Clean Sheets	Goalkeeper clean sheets
14	Goals Conceded Per Game	Goalkeeper stats
15	Saves Per Game	Goalkeeper saves
16	Penalties Saved	Penalty saves

Available Team Statistics

ID	Category Name	Description
1	Goals Per Game	Scoring rate
2	Conceded Per Game	Defensive record
3	Clean Sheets	Matches without conceding
4	Possession	Average possession %
5	Corners Per Game	Corner frequency
6	Penalties Scored	Team penalty record
7	Red Cards	Team red cards
8	Yellow Cards	Team yellow 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 Per Game	Interceptions
66	Goals Conceded Per Game	Goals against
67	Saves Per Game	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