// Players

Player season heatmap

Where a player touched the ball across a whole competition season, added up into cells on the pitch. Use it to draw a season heatmap that shows the areas a player works in most.

GET https://api.soccer-data.co/v1/players/{player_id}/competitions/{competition_id}/seasons/{season_id}/heatmap

Every match the player played in that competition season goes into one map. For tournaments, group and knockout games are combined.
x and y are positions on the pitch as percentages from 0 to 100.
Returns 404 NOT_FOUND when there's no heatmap, for example for a season that hasn't been played yet or a competition without positional data.
The season has to belong to the competition in the path. Otherwise you get 400 SEASON_COMPETITION_MISMATCH.

Path parameters

player_idstringrequired

The player's id, like player_…. Find one with the ID guide.

competition_idstringrequired

The competition's id, like competition_…. Find one with the ID guide.

season_idstringrequired

The season's id, like season_…. Find one with the ID guide.

Response fields

data.player.idstring

The player's id.

data.player.namestring

The player's name.

data.competition.idstring

The competition's id.

data.competition.namestring

The competition's name.

data.season.idstring

The season's id.

data.season.namestring

The season's name.

data.points[]array

One entry per pitch cell where the player had the ball.

data.points[].xinteger

The cell's x coordinate, as a percentage of the pitch from 0 to 100.

data.points[].yinteger

The cell's y coordinate, as a percentage of the pitch from 0 to 100.

data.points[].countinteger

Touches in that cell over the season. Always at least 1.

curl "https://api.soccer-data.co/v1/players/player_zm7yzjr75yjn/competitions/competition_7vpwx91c7j7h/seasons/season_st2tyewgtq2j/heatmap" \
  -H "X-Api-Key: $SOCCER_DATA_KEY"

const res = await fetch("https://api.soccer-data.co/v1/players/player_zm7yzjr75yjn/competitions/competition_7vpwx91c7j7h/seasons/season_st2tyewgtq2j/heatmap", {
  headers: { "X-Api-Key": process.env.SOCCER_DATA_KEY },
});
const { data } = await res.json();

import os, requests

res = requests.get(
    "https://api.soccer-data.co/v1/players/player_zm7yzjr75yjn/competitions/competition_7vpwx91c7j7h/seasons/season_st2tyewgtq2j/heatmap",
    headers={"X-Api-Key": os.environ["SOCCER_DATA_KEY"]},
)
data = res.json()["data"]

$data = Http::withHeaders(['X-Api-Key' => env('SOCCER_DATA_KEY')])
    ->get('https://api.soccer-data.co/v1/players/player_zm7yzjr75yjn/competitions/competition_7vpwx91c7j7h/seasons/season_st2tyewgtq2j/heatmap')
    ->json('data');

200 · Example response

{
    "data": {
        "player": {
            "id": "player_zm7yzjr75yjn",
            "name": "Dušan Vlahović"
        },
        "competition": {
            "id": "competition_7vpwx91c7j7h",
            "name": "FIFA World Cup"
        },
        "season": {
            "id": "season_st2tyewgtq2j",
            "name": "World Cup 2022"
        },
        "points": [
            {
                "x": 41,
                "y": 73,
                "count": 3
            },
            {
                "x": 52,
                "y": 48,
                "count": 5
            },
            {
                "x": 78,
                "y": 55,
                "count": 2
            }
        ]
    }
}

Get a free key to try it

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

Player season heatmap

Where a player touched the ball across a whole competition season, added up into cells on the pitch. Use it to draw a season heatmap that shows the areas a player works in most.
- Every match the player played in that competition season goes into one map. For tournaments, group and knockout games are combined.
- x and y are positions on the pitch as percentages from 0 to 100.
- Returns 404 NOT_FOUND when there's no heatmap, for example for a season that hasn't been played yet or a competition without positional data.
- The season has to belong to the competition in the path. Otherwise you get 400 SEASON_COMPETITION_MISMATCH.

Response fields:
- `data.player.id` (string): The player's id.
- `data.player.name` (string): The player's name.
- `data.competition.id` (string): The competition's id.
- `data.competition.name` (string): The competition's name.
- `data.season.id` (string): The season's id.
- `data.season.name` (string): The season's name.
- `data.points[]` (array): One entry per pitch cell where the player had the ball.
- `data.points[].x` (integer): The cell's x coordinate, as a percentage of the pitch from 0 to 100.
- `data.points[].y` (integer): The cell's y coordinate, as a percentage of the pitch from 0 to 100.
- `data.points[].count` (integer): Touches in that cell over the season. Always at least 1.

Example: curl "https://api.soccer-data.co/v1/players/player_zm7yzjr75yjn/competitions/competition_7vpwx91c7j7h/seasons/season_st2tyewgtq2j/heatmap" -H "X-Api-Key: $SOCCER_DATA_KEY"