GET

athletes

games

lineups

Athlete Game Lineups

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

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

fetch('https://api.sportsapipro.com/v1/football/athletes/games/lineups', 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/games/lineups",
  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/games/lineups"

	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/games/lineups")

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

{
  "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://api.sportsapipro.com/v1/football/athletes/games/lineups?athleteId=80392&gameId=4609054" \
  -H "x-api-key: YOUR_API_KEY"

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

Player Match Analysis: Get detailed performance metrics for a player in a specific match
Heat Map Visualization: Display player movement patterns during the game
Shot Chart Display: Visualize all shots taken in the match with xG data
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

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

Last modified on June 29, 2026

Athlete Game Lineups

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

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

fetch('https://api.sportsapipro.com/v1/football/athletes/games/lineups', 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/games/lineups",
  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/games/lineups"

	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/games/lineups")

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

{
  "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>"
}

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

Athlete Game Lineups

Athlete Game Lineups

Endpoint

Parameters

Example Request

Response Structure

Response Fields

Member Object

Formation vs YardFormation (Important Distinction)

Formation Object

Formation ID Reference

YardFormation Object (Authoritative Field Positioning)

FieldSide Values (Horizontal Position)

Line Values (Depth)

FieldLine Values (Vertical Position)

Deriving True Position from YardFormation

Stats Array

ChartEvents Object (Shot Chart)

Stats Categories

Use Cases

Notes

Authorizations

Query Parameters

Response

​Athlete Game Lineups

​Endpoint

​Parameters

​Example Request

​Response Structure

​Response Fields

​Member Object

​Formation vs YardFormation (Important Distinction)

​Formation Object

​Formation ID Reference

​YardFormation Object (Authoritative Field Positioning)

​FieldSide Values (Horizontal Position)

​Line Values (Depth)

​FieldLine Values (Vertical Position)

​Deriving True Position from YardFormation

​Stats Array

​ChartEvents Object (Shot Chart)

​Stats Categories

​Use Cases

​Notes

Authorizations

Query Parameters

Response

Athlete Game Lineups

Endpoint

Parameters

Example Request

Response Structure

Response Fields

Member Object

Formation vs YardFormation (Important Distinction)

Formation Object

Formation ID Reference

YardFormation Object (Authoritative Field Positioning)

FieldSide Values (Horizontal Position)

Line Values (Depth)

FieldLine Values (Vertical Position)

Deriving True Position from YardFormation

Stats Array

ChartEvents Object (Shot Chart)

Stats Categories

Use Cases

Notes