> ## Documentation Index
> Fetch the complete documentation index at: https://www.thestatsapi.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# GET /football/players/{player_id}/competitions/{competition_id}/seasons/{season_id}/heatmap

> Return aggregated 0-100 pitch-coordinate heatmap points for a player in one competition season.

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

## Endpoint

```text theme={null}
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

```json theme={null}
{
  "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 }
    ]
  }
}
```

<Note>
  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.
</Note>