Get match lineups

Get both teams' starting XIs, substitutes and formations for one match. Before kickoff you get a predicted XI, then the official team sheet, and once the match starts, the players who actually took part.

curl "https://api.soccer-data.co/v1/matches/match_9pd0ck6g2m9i/lineups" \
  -H "X-Api-Key: $SOCCER_DATA_KEY"

const res = await fetch("https://api.soccer-data.co/v1/matches/match_9pd0ck6g2m9i/lineups", {
  headers: { "X-Api-Key": process.env.SOCCER_DATA_KEY },
});
const { data } = await res.json();

import os, requests

res = requests.get(
    "https://api.soccer-data.co/v1/matches/match_9pd0ck6g2m9i/lineups",
    headers={"X-Api-Key": os.environ["SOCCER_DATA_KEY"]},
)
data = res.json()["data"]

$data = Http::withHeaders(['X-Api-Key' => env('SOCCER_DATA_KEY')])
    ->get('https://api.soccer-data.co/v1/matches/match_9pd0ck6g2m9i/lineups')
    ->json('data');

{
    "data": {
        "match_id": "match_9pd0ck6g2m9i",
        "confirmed": true,
        "bench_available": true,
        "type": "played",
        "home": {
            "id": "team_4mimn5fmya2v",
            "name": "Aston Villa",
            "formation": "4-2-3-1",
            "starting_xi": [
                {
                    "id": "player_ck9wwtc7en6q",
                    "name": "Emiliano Martínez",
                    "position": "G",
                    "jersey_number": 23
                }
            ],
            "substitutes": [
                {
                    "id": "player_f9mb7kd0q4fa",
                    "name": "Marco Bizot",
                    "position": "G",
                    "jersey_number": 40
                }
            ]
        },
        "away": {
            "id": "team_74p8tg2k93z4",
            "name": "Liverpool",
            "formation": "4-2-3-1",
            "starting_xi": [
                {
                    "id": "player_nyb14jgqd9cz",
                    "name": "Giorgi Mamardashvili",
                    "position": "G",
                    "jersey_number": 25
                }
            ],
            "substitutes": [
                {
                    "id": "player_q8pk4m6ckqbk",
                    "name": "Freddie Woodman",
                    "position": "G",
                    "jersey_number": 28
                }
            ]
        }
    }
}

### GET /matches/{match_id}/lineups

Get match lineups

Get both teams' starting XIs, substitutes and formations for one match. Before kickoff you get a predicted XI, then the official team sheet, and once the match starts, the players who actually took part.
- type tells you which lineup you have. Before the team sheet is out it is predicted. The official team sheet usually arrives about an hour before kickoff. Once the match starts it becomes played.
- A predicted XI never has a bench, so bench_available is always false for it.
- The starting XI can be confirmed a few minutes before the bench is published. Wait for bench_available to turn true before you show substitutes.
- bench_available means the bench has been published, not that it is final. Late changes keep coming in until kickoff, so poll again close to the start.
- Returns 404 when there is no lineup for the match yet, or the match id is unknown.
- While a match is live, responses are normally at most 5 minutes old on Free and 15 seconds old on Pro and Business. If a fresh answer can't be fetched, you may get an older copy marked X-Cache: STALE instead: see [When an answer is stale](/docs/concepts/rate-limits#when-an-answer-is-stale).

Response fields:
- `data.match_id` (string): The match's id.
- `data.confirmed` (boolean): True for the official team sheet or the XI of a match that has started. False for a predicted XI.
- `data.bench_available` (boolean): True once both teams have at least one substitute listed. Always false for a predicted XI.
- `data.type` (string): predicted (an expected XI before the team sheet), team_sheet (the official pre-match XI) or played (the XI and substitutes of a match that has started or finished).
- `data.home` (object): Home team's lineup.
- `data.away` (object): Away team's lineup. Same fields as home.
- `data.home.id` (string): Team's id.
- `data.home.name` (string): Team's name.
- `data.home.formation` (string|null): Formation, such as 4-3-3 or 4-2-3-1. Null when unknown.
- `data.home.starting_xi[]` (array): The starting eleven, ordered goalkeeper, defenders, midfielders, forwards, then by shirt number. Handy for drawing a team sheet without sorting yourself.
- `data.home.substitutes[]` (array): The bench: players who came on and those who didn't. Can be empty before kickoff, for example with a predicted XI.
- `data.home.starting_xi[].id` (string): Player's id. Use it with the match player stats and match heatmap endpoints. Substitutes have the same fields.
- `data.home.starting_xi[].name` (string): Player's name.
- `data.home.starting_xi[].position` (string|null): G (goalkeeper), D (defender), M (midfielder) or F (forward). Null when unknown.
- `data.home.starting_xi[].jersey_number` (integer|null): Shirt number.

Example: curl "https://api.soccer-data.co/v1/matches/match_9pd0ck6g2m9i/lineups" -H "X-Api-Key: $SOCCER_DATA_KEY"