GET /football/players/{player_id}/competitions/{competition_id}/seasons/{season_id}/heatmap - The Stats API

Return an aggregated positional heatmap for a player across all matches they played in a single competition season.

Endpoint

GET https://api.thestatsapi.com/api/football/players/{player_id}/competitions/{competition_id}/seasons/{season_id}/heatmap

Each point uses x and y integer pitch coordinates from 0 to 100. count is the number of touches at that grid cell. For group-stage tournaments, the heatmap covers the whole tournament, including group and knockout matches.

Path parameters

Name	Type	Required	Description
`player_id`	string	Yes	Player ID. Example: `pl_84027040`
`competition_id`	string	Yes	Competition ID. Example: `comp_6107`
`season_id`	string	Yes	Season ID. Example: `sn_326766`

Response

{
  "data": {
    "player": {
      "id": "pl_84027040",
      "name": "Dusan Vlahovic"
    },
    "competition": {
      "id": "comp_6107",
      "name": "FIFA World Cup"
    },
    "season": {
      "id": "sn_326766",
      "name": "2022"
    },
    "points": [
      { "x": 41, "y": 73, "count": 3 },
      { "x": 42, "y": 74, "count": 1 }
    ]
  }
}

The endpoint returns 404 when no heatmap is available, for example when the season has not been played or the competition does not have movement coverage.