Matches
Get match lineups
Returns both teams’ starting XI, substitutes and formation. Before kickoff you get a predicted XI, replaced by the official team sheet once it’s announced (about an hour before kickoff). For started and finished matches you get the XI that played, with every substitute (used and unused). type tells you which one you have (predicted, team_sheet or played), and confirmed is true only for a team sheet or a played match. Returns 404 when there’s no lineup data for the match yet.
Example: GET /football/matches/mt_838955483/lineups
GET
/
football
/
matches
/
{match_id}
/
lineups
Get match lineups
curl --request GET \
--url https://api.thestatsapi.com/api/football/matches/{match_id}/lineups \
--header 'Authorization: Bearer <token>'const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.thestatsapi.com/api/football/matches/{match_id}/lineups', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.thestatsapi.com/api/football/matches/{match_id}/lineups"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text){
"data": {
"match_id": "mt_838955483",
"confirmed": true,
"bench_available": true,
"type": "played",
"home": {
"id": "tm_1002",
"name": "Aston Villa",
"formation": "4-2-3-1",
"starting_xi": [
{
"id": "pl_5837699",
"name": "Emiliano Martínez",
"position": "G",
"jersey_number": 23
}
],
"substitutes": [
{
"id": "pl_1379750",
"name": "Marco Bizot",
"position": "G",
"jersey_number": 40
}
]
},
"away": {
"id": "tm_0406",
"name": "Liverpool",
"formation": "4-2-3-1",
"starting_xi": [
{
"id": "pl_30223540",
"name": "Giorgi Mamardashvili",
"position": "G",
"jersey_number": 25
}
],
"substitutes": [
{
"id": "pl_3847063",
"name": "Freddie Woodman",
"position": "G",
"jersey_number": 28
}
]
}
}
}Check
type and confirmed to know whether you have a predicted XI, the official team sheet or the XI that played. The player IDs work with match player stats and match heatmaps.Authorizations
Your API key, sent as Authorization: Bearer YOUR_API_KEY. Get one at https://www.thestatsapi.com/api-keys
Path Parameters
⌘I
Get match lineups
curl --request GET \
--url https://api.thestatsapi.com/api/football/matches/{match_id}/lineups \
--header 'Authorization: Bearer <token>'const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.thestatsapi.com/api/football/matches/{match_id}/lineups', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.thestatsapi.com/api/football/matches/{match_id}/lineups"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text){
"data": {
"match_id": "mt_838955483",
"confirmed": true,
"bench_available": true,
"type": "played",
"home": {
"id": "tm_1002",
"name": "Aston Villa",
"formation": "4-2-3-1",
"starting_xi": [
{
"id": "pl_5837699",
"name": "Emiliano Martínez",
"position": "G",
"jersey_number": 23
}
],
"substitutes": [
{
"id": "pl_1379750",
"name": "Marco Bizot",
"position": "G",
"jersey_number": 40
}
]
},
"away": {
"id": "tm_0406",
"name": "Liverpool",
"formation": "4-2-3-1",
"starting_xi": [
{
"id": "pl_30223540",
"name": "Giorgi Mamardashvili",
"position": "G",
"jersey_number": 25
}
],
"substitutes": [
{
"id": "pl_3847063",
"name": "Freddie Woodman",
"position": "G",
"jersey_number": 28
}
]
}
}
}