Athlete Chart Events

GET

athletes

chartEvents

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

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.sportsapipro.com/v1/football/athletes/chartEvents', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sportsapipro.com/v1/football/athletes/chartEvents",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sportsapipro.com/v1/football/athletes/chartEvents"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.sportsapipro.com/v1/football/athletes/chartEvents")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "chartEvents": [
    {
      "athleteId": 123,
      "mostCommonGoalZone": [
        "<string>"
      ],
      "penaltyGoals": "<string>",
      "penaltyConversions": "<string>",
      "events": [
        {
          "xg": "<string>",
          "xgot": "<string>",
          "bodyPart": "<string>",
          "goalDescription": "<string>",
          "time": "<string>",
          "gameId": 123,
          "line": 123,
          "side": 123,
          "outcome": {
            "id": 123,
            "name": "<string>",
            "y": 123,
            "z": 123
          }
        }
      ]
    }
  ],
  "athletes": "<array>",
  "games": "<array>",
  "competitions": "<array>"
}

Endpoint

GET https://api.sportsapipro.com/v1/football/athletes/chartEvents

Overview

Retrieves comprehensive shot and goal event data for a specific athlete, including expected goals (xG), shot positions, goal zones, and penalty conversion statistics. This endpoint is ideal for building player performance visualizations, shot maps, and detailed attacking analytics.

Query Parameters

Parameter	Type	Required	Description
`athletes`	integer	Yes	Athlete ID to fetch chart events for
`appTypeId`	integer	No	Application type (auto-resolved)
`langId`	integer	No	Language ID (auto-resolved)
`timezoneName`	string	No	Timezone for date/time values (auto-resolved or specify e.g., `America/New_York`)
`userCountryId`	integer	No	User country ID (auto-resolved)

Parameters like appTypeId, langId, timezoneName, and userCountryId are auto-resolved based on request context.

Request Examples

curl -X GET "https://api.sportsapipro.com/v1/football/athletes/chartEvents?athletes=874" \
  -H "x-api-key: YOUR_API_KEY"

const response = await fetch(
  "https://api.sportsapipro.com/v1/football/athletes/chartEvents?athletes=874",
  {
    headers: { "x-api-key": "YOUR_API_KEY" }
  }
);
const data = await response.json();

// Access chart events data
const chartEvents = data.chartEvents?.[0];
console.log('Total xG:', chartEvents?.events?.reduce((sum, e) => sum + parseFloat(e.xg || 0), 0));

import requests

response = requests.get(
    "https://api.sportsapipro.com/v1/football/athletes/chartEvents",
    params={"athletes": 874},
    headers={"x-api-key": "YOUR_API_KEY"}
)
data = response.json()

# Access chart events data
chart_events = data.get("chartEvents", [])[0] if data.get("chartEvents") else None
if chart_events:
    total_xg = sum(float(e.get("xg", 0)) for e in chart_events.get("events", []))
    print(f"Total xG: {total_xg}")

Response Structure

{
  "chartEvents": [
    {
      "athleteId": 874,
      "mostCommonGoalZone": ["Low Left"],
      "penaltyGoals": "3/4",
      "penaltyConversions": "75 %",
      "events": [
        {
          "xg": "0.79",
          "xgot": "0.98",
          "bodyPart": "Left foot",
          "goalDescription": "High Centre",
          "key": "34318756",
          "competitorNum": 2,
          "time": "32'",
          "status": 6,
          "playerId": 77832,
          "line": 50.0,
          "side": 88.5,
          "type": 0,
          "subType": 9,
          "gameId": 4318756,
          "outcome": {
            "y": 51.3,
            "z": 28.5,
            "id": 2,
            "name": "Saved"
          }
        }
      ],
      "eventTypes": [
        {
          "id": 8,
          "value": 0,
          "name": "Regular Play"
        }
      ],
      "statuses": [
        {
          "id": 6,
          "name": "1st Half",
          "symbolName": "1st",
          "isActive": true
        }
      ],
      "eventSubTypes": [
        {
          "id": 81,
          "value": 9,
          "name": "Penalty"
        }
      ]
    }
  ],
  "athletes": [
    {
      "id": 874,
      "name": "Lionel Messi",
      "shortName": "Messi",
      "nameForURL": "lionel-messi",
      "sportId": 1,
      "clubId": 54729,
      "nationalityId": 10,
      "imageVersion": 53,
      "clubName": "Inter Miami"
    }
  ],
  "sports": [...],
  "countries": [...],
  "competitions": [...],
  "games": [...]
}

Response Fields

Chart Events Object

Field	Type	Description
`athleteId`	integer	ID of the athlete these events belong to
`mostCommonGoalZone`	string[]	Array of goal zones the player most frequently targets
`penaltyGoals`	string	Penalty goals ratio (e.g., “3/4”)
`penaltyConversions`	string	Penalty conversion percentage (e.g., “75 %“)
`events`	array	Array of shot/goal event objects
`eventTypes`	array	Types of events (Regular Play, Set Piece, etc.)
`statuses`	array	Match period statuses (1st Half, 2nd Half, etc.)
`eventSubTypes`	array	Sub-types of events (Penalty, Free Kick, etc.)

Event Object

Field	Type	Description
`xg`	string	Expected goals value for the shot (0-1 scale)
`xgot`	string	Expected goals on target value
`bodyPart`	string	Body part used (“Left foot”, “Right Foot”, “Header”)
`goalDescription`	string	Goal zone description (“Low Left”, “High Centre”, etc.)
`key`	string	Unique event identifier
`competitorNum`	integer	Team number (1 = home, 2 = away)
`time`	string	Minute of the event (e.g., “32’“)
`status`	integer	Match period status ID
`playerId`	integer	Player ID who took the shot
`line`	number	Vertical position on pitch (0-100)
`side`	number	Horizontal position on pitch (0-100)
`type`	integer	Event type ID
`subType`	integer	Event sub-type ID
`gameId`	integer	ID of the match where event occurred
`outcome`	object	Shot outcome with goal position and result

Outcome Object

Field	Type	Description
`y`	number	Horizontal goal position (0-100)
`z`	number	Vertical goal position (0-100, 0 = ground level)
`id`	integer	Outcome ID (0 = Goal, 1 = Blocked, 2 = Saved, 3 = Off Target)
`name`	string	Outcome name

Outcome Types

ID	Name	Description
0	Goal	Shot resulted in a goal
1	Blocked	Shot was blocked
2	Saved	Shot was saved by the goalkeeper
3	Off Target	Shot went off target

Goal Zones

Common goal zone descriptions:

Low Left - Bottom left corner
Low Right - Bottom right corner
Low Centre - Low center of goal
High Left - Top left corner
High Right - Top right corner
High Centre - Top center of goal

Use Cases

Shot Maps: Use line and side coordinates to plot shots on a pitch visualization
Goal Zone Heatmaps: Use goalDescription and outcome to show where players aim
xG Analysis: Calculate total xG vs actual goals for finishing analysis
Penalty Statistics: Display penalty conversion rates
Body Part Analysis: Show which foot/header the player favors
Match Context: Link events to specific games for detailed breakdowns

Example: Calculate Player xG Performance

const response = await fetch(
  "https://api.sportsapipro.com/v1/football/athletes/chartEvents?athletes=874",
  { headers: { "x-api-key": "YOUR_API_KEY" } }
);
const data = await response.json();

const events = data.chartEvents?.[0]?.events || [];
const goals = events.filter(e => e.outcome?.id === 0).length;
const totalXg = events.reduce((sum, e) => sum + parseFloat(e.xg || 0), 0);
const xgDiff = goals - totalXg;

console.log(`Goals: ${goals}`);
console.log(`Total xG: ${totalXg.toFixed(2)}`);
console.log(`xG Difference: ${xgDiff > 0 ? '+' : ''}${xgDiff.toFixed(2)}`);
// Positive = overperforming, Negative = underperforming

Athlete Next Game - Get upcoming match for an athlete
Athlete Game Lineups - Get lineup data for athlete in a game
Top Athletes - Get list of top players

Authorizations

x-api-key

string

header

required

Your SportsAPI Pro API key

Query Parameters

athletes

integer

required

Athlete ID to fetch chart events for

Example:

874

Response

Athlete chart events retrieved successfully

chartEvents

object[]

Chart events data for the athlete

Show child attributes

athletes

array

Athlete information

games

array

Referenced games

competitions

array

Referenced competitions

Last modified on June 29, 2026

Athlete Chart Events

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

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.sportsapipro.com/v1/football/athletes/chartEvents', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sportsapipro.com/v1/football/athletes/chartEvents",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sportsapipro.com/v1/football/athletes/chartEvents"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.sportsapipro.com/v1/football/athletes/chartEvents")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "chartEvents": [
    {
      "athleteId": 123,
      "mostCommonGoalZone": [
        "<string>"
      ],
      "penaltyGoals": "<string>",
      "penaltyConversions": "<string>",
      "events": [
        {
          "xg": "<string>",
          "xgot": "<string>",
          "bodyPart": "<string>",
          "goalDescription": "<string>",
          "time": "<string>",
          "gameId": 123,
          "line": 123,
          "side": 123,
          "outcome": {
            "id": 123,
            "name": "<string>",
            "y": 123,
            "z": 123
          }
        }
      ]
    }
  ],
  "athletes": "<array>",
  "games": "<array>",
  "competitions": "<array>"
}

API Reference

Guides

Popular Sports

Team Sports

Racquet & Precision Sports

Specialty Sports

V3 API

V4 Odds API

V6 AiScore API

V1 Legacy

Football V1

Basketball V1

Tennis V1

Hockey V1

Endpoint

Overview

Query Parameters

Request Examples

Response Structure

Response Fields

Chart Events Object

Event Object

Outcome Object

Outcome Types

Goal Zones

Use Cases

Example: Calculate Player xG Performance

Authorizations

Query Parameters

Response

​Endpoint

​Overview

​Query Parameters

​Request Examples

​Response Structure

​Response Fields

​Chart Events Object

​Event Object

​Outcome Object

​Outcome Types

​Goal Zones

​Use Cases

​Example: Calculate Player xG Performance

​Related Endpoints

Authorizations

Query Parameters

Response

Endpoint

Overview

Query Parameters

Request Examples

Response Structure

Response Fields

Chart Events Object

Event Object

Outcome Object

Outcome Types

Goal Zones

Use Cases

Example: Calculate Player xG Performance

Related Endpoints