Athlete Game Lineups

Get detailed lineup and performance data for a specific athlete in a specific game

GET /athletes/games/lineups

Athlete Game Lineups

cURL

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

200

{
  "members": [
    {
      "status": 123,
      "statusText": "<string>",
      "position": {},
      "formation": {},
      "yardFormation": {
        "line": 123,
        "fieldPosition": 123,
        "fieldLine": 123,
        "fieldSide": 123
      },
      "ranking": 123,
      "hasHighestRanking": true,
      "hasStats": true,
      "stats": "<array>",
      "heatMap": "<string>",
      "hasShotChart": true,
      "athleteId": 123,
      "name": "<string>",
      "shortName": "<string>",
      "jerseyNumber": 123
    }
  ],
  "statsCategories": "<array>",
  "chartEvents": {},
  "sports": "<array>",
  "countries": "<array>",
  "competitions": "<array>",
  "competitors": "<array>",
  "games": "<array>"
}

Athlete Game Lineups

Retrieve comprehensive lineup information, statistics, heat maps, and shot chart data for a specific athlete’s performance in a particular game.

Endpoint

GET /athletes/games/lineups

Parameters

Parameter	Type	Required	Default	Description
athleteId	number	Yes	-	The unique identifier of the athlete
gameId	number	Yes	-	The unique identifier of the game
appTypeId	number	No	5	Application type identifier
langId	number	No	1	Language ID (1 = English)
timezoneName	string	No	Auto-resolved	Timezone for date/time values (auto-resolved, or specify e.g., America/New_York)
userCountryId	number	No	65	User’s country ID

All startTime fields in game data use ISO 8601 format with a dynamic timezone offset based on the resolved or specified timezone.

Example Request

curl -X GET "https://v1.football.sportsapipro.com/athletes/games/lineups?athleteId=80392&gameId=4609054" \
  -H "x-api-key: YOUR_API_KEY"

const response = await fetch(
  'https://v1.football.sportsapipro.com/athletes/games/lineups?athleteId=80392&gameId=4609054',
  {
    headers: {
      'x-api-key': 'YOUR_API_KEY'
    }
  }
);
const data = await response.json();

Response Structure

{
  "members": [
    {
      "status": 1,
      "statusText": "Starting",
      "position": {
        "id": 2,
        "name": "Defender"
      },
      "formation": {
        "id": 5,
        "name": "Centre Back",
        "shortName": "Centre Back"
      },
      "yardFormation": {
        "line": 2,
        "fieldPosition": 3,
        "fieldLine": 25,
        "fieldSide": 50
      },
      "ranking": 5.7,
      "hasHighestRanking": true,
      "hasStats": true,
      "stats": [...],
      "heatMap": "https://v1.football.sportsapipro.com/images/heatmaps/...",
      "competitorNum": 2,
      "hasShotChart": true,
      "id": 50800163,
      "athleteId": 80392,
      "name": "Maxence Lacroix",
      "shortName": "Lacroix",
      "jerseyNumber": 5,
      "nameForURL": "maxence-lacroix",
      "imageVersion": 27
    }
  ],
  "statsCategories": [...],
  "chartEvents": {...},
  "sports": [...],
  "countries": [...],
  "competitions": [...],
  "competitors": [...],
  "games": [...]
}

Response Fields

Member Object

Field	Type	Description
status	number	Player status (1 = Starting, 2 = Substitute, etc.)
statusText	string	Human-readable status (“Starting”, “Substitute”)
position	object	Player’s general position (Goalkeeper, Defender, Midfielder, Forward)
formation	object	Specific formation role (e.g., Centre Back, Left Back, etc.)
yardFormation	object	Field positioning data (see below)
ranking	number	Player’s match rating (1.0 - 10.0 scale)
hasHighestRanking	boolean	Whether player has highest rating on team
hasStats	boolean	Whether detailed stats are available
stats	array	Array of performance statistics
heatMap	string	URL to player’s heat map image (proxied through branded domain)
hasShotChart	boolean	Whether shot chart data is available
athleteId	number	Unique athlete identifier
name	string	Full player name
shortName	string	Short/display name
jerseyNumber	number	Player’s shirt number
nameForURL	string	URL-friendly name slug

Formation vs YardFormation (Important Distinction)

The API provides two positioning fields with different purposes:

Field	Purpose	Accuracy
formation	General role label (e.g., “Left Back”, “Centre Back”)	Generalized - may group similar positions
yardFormation	Precise field coordinates	Authoritative - use this for accurate positioning

Note: The formation.name field represents a generalized tactical role and may show the same label for players in adjacent positions. For precise positioning (e.g., distinguishing a Left Back from a Left Centre Back), always use the yardFormation data.

Formation Object

The formation object provides a labeled tactical role:

Field	Type	Description
id	number	Formation position ID (see table below)
name	string	Full position name
shortName	string	Abbreviated position name

Formation ID Reference

ID	Name	Position Group
1	Goalkeeper	Goalkeeper
2	Left Back	Defender
3	Right Back	Defender
4	Left Wing Back	Defender
5	Centre Back	Defender
6	Right Wing Back	Defender
7	Sweeper	Defender
8	Left Midfielder	Midfielder
9	Right Midfielder	Midfielder
10	Defensive Midfielder	Midfielder
11	Central Midfielder	Midfielder
12	Attacking Midfielder	Midfielder
13	Left Winger	Midfielder
14	Right Winger	Midfielder
15	Second Striker	Forward
16	Centre Forward	Forward
17	Striker	Forward
18	Left Centre Back	Defender
19	Right Centre Back	Defender
20	Left Defensive Midfielder	Midfielder
21	Right Defensive Midfielder	Midfielder
22	Left Central Midfielder	Midfielder
23	Right Central Midfielder	Midfielder
24	Left Attacking Midfielder	Midfielder
25	Right Attacking Midfielder	Midfielder

Note: Formation IDs provide categorical position labels. For rendering players on a pitch diagram, use yardFormation coordinates instead.

YardFormation Object (Authoritative Field Positioning)

The yardFormation object describes the player’s exact position on a virtual pitch grid. This is the authoritative source for player positioning.

Field	Type	Description
line	number	Defensive depth line (1 = GK, 2 = Defense, 3 = Midfield, 4 = Attack)
fieldPosition	number	Position number within the line (1-5, ordered by horizontal position)
fieldLine	number	Vertical position as percentage (0 = own goal line, 100 = opponent goal)
fieldSide	number	Horizontal position as percentage (0 = left touchline, 100 = right touchline, 50 = center)

FieldSide Values (Horizontal Position)

fieldSide	Position Description
0	Left touchline (Left Back)
25-33	Left-center (Left Centre Back)
50	Center (Centre Back / Central Midfielder)
66-75	Right-center (Right Centre Back)
100	Right touchline (Right Back)

Line Values (Depth)

line	Position Group
1	Goalkeeper
2	Defenders
3	Midfielders
4	Forwards/Attackers

FieldLine Values (Vertical Position)

fieldLine	Typical Position
0-10	Goalkeeper area
20-35	Defensive line
40-60	Midfield
70-90	Attacking positions
90+	Striker/Forward positions

Example positions:

• Goalkeeper: line: 1, fieldPosition: 1, fieldLine: 0, fieldSide: 50
• Left Back: line: 2, fieldPosition: 2, fieldLine: 33, fieldSide: 0
• Left Centre Back: line: 2, fieldPosition: 3, fieldLine: 33, fieldSide: 33
• Centre Back: line: 2, fieldPosition: 3, fieldLine: 25, fieldSide: 50
• Right Back: line: 2, fieldPosition: 1, fieldLine: 33, fieldSide: 100
• Central Midfielder: line: 3, fieldPosition: 2, fieldLine: 50, fieldSide: 50
• Left Winger: line: 4, fieldPosition: 2, fieldLine: 75, fieldSide: 15
• Centre Forward: line: 4, fieldPosition: 1, fieldLine: 85, fieldSide: 50

Deriving True Position from YardFormation

To determine a player’s actual position, combine line and fieldSide:

function getTruePosition(yardFormation) {
  const { line, fieldSide } = yardFormation;
  
  if (line === 1) return 'Goalkeeper';
  
  if (line === 2) { // Defenders
    if (fieldSide <= 15) return 'Left Back';
    if (fieldSide <= 40) return 'Left Centre Back';
    if (fieldSide <= 60) return 'Centre Back';
    if (fieldSide <= 85) return 'Right Centre Back';
    return 'Right Back';
  }
  
  if (line === 3) { // Midfielders
    if (fieldSide <= 20) return 'Left Midfielder';
    if (fieldSide <= 40) return 'Left Central Midfielder';
    if (fieldSide <= 60) return 'Central Midfielder';
    if (fieldSide <= 80) return 'Right Central Midfielder';
    return 'Right Midfielder';
  }
  
  if (line === 4) { // Attackers
    if (fieldSide <= 25) return 'Left Winger';
    if (fieldSide <= 75) return 'Striker';
    return 'Right Winger';
  }
}

Stats Array

Each stat object contains:

Field	Type	Description
type	number	Stat type identifier
value	string	Stat value (may include formatting like “23/29 (79%)“)
isTop	boolean	Whether this is a key/top stat
categoryId	number	Category (2 = Attacking, 3 = Defending)
name	string	Full stat name
shortName	string	Abbreviated stat name
order	number	Display order
imageId	number	Icon identifier

Common stat types:

Type	Name
3	Total Shots
19	Passes Completed
23	Goalkeeper Saves
26	Assists
27	Goals
30	Minutes
37	Was Fouled
39	Tackles Won
40	Clearances
41	Interceptions
42	Fouls Made
45	Touches
46	Key Passes
53	Long Passes Completed
54	Successful Dribbles
55	Ground Duels Won
56	Aerial Duels Won
73	Possession Lost
76	Expected Goals (xG)
78	Expected Assists (xA)
86	Ball Recovery

ChartEvents Object (Shot Chart)

Contains shot/goal events for the game:

Field	Type	Description
xg	string	Expected Goals value for the shot
xgot	string	Expected Goals on Target
bodyPart	string	Body part used (“Left foot”, “Right Foot”, “Header”)
goalDescription	string	Shot placement (“Low Centre”, “High Left”, etc.)
time	string	Minute of the event
playerId	number	ID of the player who took the shot
line	number	Vertical position on pitch (%)
side	number	Horizontal position on pitch (%)
outcome	object	Result of the shot (Goal, Saved, Missed, Blocked)

Stats Categories

ID	Name
2	Attacking
3	Defending

Use Cases

1. Player Match Analysis: Get detailed performance metrics for a player in a specific match
2. Heat Map Visualization: Display player movement patterns during the game
3. Shot Chart Display: Visualize all shots taken in the match with xG data
4. Player Comparison: Compare performances of players in the same match

Notes

• The yardFormation data helps accurately position players on a pitch visualization
• Heat map URLs are ready-to-use image URLs with WebP format
• Shot chart events include xG (Expected Goals) for quality analysis
• Stats are categorized into Attacking (categoryId: 2) and Defending (categoryId: 3)
• This endpoint provides more detailed player data than the general /game endpoint

Authorizations

x-api-key · string · header · required

Your SportsAPI Pro API key

Query Parameters

athleteId · integer · required

The unique identifier of the athlete

Example:

80392

gameId · integer · required

The unique identifier of the game

Example:

4609054

Response

200

application/json

Athlete lineup data retrieved successfully

members · object[]

Lineup member data with stats and positioning

Show child attributes

statsCategories · array

chartEvents · object

Shot chart data with xG

sports · array

countries · array

competitions · array

competitors · array

games · array