Athlete Chart Events

Get shot and goal event data with xG statistics for a specific athlete

GET /athletes/chartEvents

Athlete Chart Events

cURL

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

200

{
  "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://v1.football.sportsapipro.com/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

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

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

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

Example: Calculate Player xG Performance

const response = await fetch(
  "https://v1.football.sportsapipro.com/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

Related Endpoints

• 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

200

application/json

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