Lineups

Learn how to get lineups for a fixture.

We'll cover the following

Anxious to see if your favorite player is part of the starting lineup or not? Api-Football can help you check the team lineups of the upcoming and ongoing fixtures to confirm. Not only that, but we can also get the lineups for previous fixtures using this API.

Fetch lineups of fixtures

We use the Lineups endpoint to get the lineups of a fixture. For upcoming fixtures, lineups are available between 20 and 40 minutes before the fixture when the competition covers this feature. Some competitions may not have any lineups available before the fixture. This can be the case for minor competitions.

We get the formation, coach, starting XI, and substitutes in response when we call this endpoint.

Request parameters

The following query parameters can be used with the Lineups endpoint:

Parameters

Type

Category

Description

fixture

Integer

Required

This is the ID of the fixture. We can get the ID of the fixture using the Fixtures endpoint.

team

Integer

Optional

This is the ID of the team whose lineups we want in response. We can get the ID of the team using the Teams information endpoint.

player

Integer

Optional

This is the ID of the starting player whose information we want to filter out. This parameter is useful when we don't want to scroll through the list of the whole team and just want to see if a specific player is in the lineup or not. We can get this ID using the Players endpoint.

type

String

Optional

This is the type of information we want. We can use Formation, Coach, Start XI, or Substitutes as input for this parameter.

We can use the fixture parameter with the Lineups endpoint to get information about the lineups of both teams from that fixture. Click the “Run” button to get the lineups.

Press + to interact
const endpointUrl = new URL('https://v3.football.api-sports.io/fixtures/lineups');
const queryParameters = new URLSearchParams({
  fixture: '592872' // 592872 is the fixture id for the match between 
                    // Manchester City and Everton, which took place on 2021-05-23    
});
headerParameters = {
  'x-rapidapi-host': 'v3.football.api-sports.io',
  'x-rapidapi-key': '{{API_KEY}}'
}
const options = {
  method: 'GET',
  headers: headerParameters
};
async function fetchLineups() {
  try {
    endpointUrl.search = queryParameters;
    const response = await fetch(endpointUrl, options);
    printResponse(response);
  } 
  catch (error) {
    printError(error);
  }
}
fetchLineups();

Following is the code explanation:

  • Line 1: We set the URL to https://v3.football.api-sports.io/fixtures/lineups.

  • Lines 3–11: We define the query parameters and header parameters. We can change the fixture ID in line 4 to get the lineups for another fixture.

  • Lines 13–16: We set the request type and appropriate header.

  • Lines 18–27: We define a function, fetchLineups(). It calls the endpoint and prints the response.

Note: We can use the Fixtures endpoint to get the fixture ID, as explained in the Fixtures Information lesson.

We can use the team and fixture parameters, as in the code below, to get the lineup for one team from a fixture. Click the “Run” button to get the lineup of the team.

Press + to interact
const endpointUrl = new URL('https://v3.football.api-sports.io/fixtures/lineups');
const queryParameters = new URLSearchParams({
  fixture: '592872', // 592872 is the fixture id for the match between 
                      // Manchester City and Everton, which took place on 2021-05-23  
  team: '50' // 50 is the team id for Manchester City  
});
headerParameters = {
  'x-rapidapi-host': 'v3.football.api-sports.io',
  'x-rapidapi-key': '{{API_KEY}}'
}
const options = {
  method: 'GET',
  headers: headerParameters
};
async function fetchLineup() {
  try {
    endpointUrl.search = queryParameters;
    const response = await fetch(endpointUrl, options);
    printResponse(response);
  } 
  catch (error) {
    printError(error);
  }
}
fetchLineup();

Let’s look at how we’ve modified the code:

  • Line 6: We add the team parameter to get the lineup for a specific team. We can change the provided ID to get the lineup for the other team.
  • Line 19: We change the function’s name to fetchLineup().

Note: We can use the Teams information endpoint to get the team ID, as explained in the Teams Information lesson.

We can filter the type of data we got from the first two widgets by using the type parameters. The code below filters the data we got from the first widget using this parameter. Click the “Run” button to get the specific type of data.

Press + to interact
const endpointUrl = new URL('https://v3.football.api-sports.io/fixtures/lineups');
const queryParameters = new URLSearchParams({
  fixture: '592872', // 592872 is the fixture id for the match between 
                      // Manchester City and Everton, which took place on 2021-05-23    
  type: 'startXI'
});
headerParameters = {
  'x-rapidapi-host': 'v3.football.api-sports.io',
  'x-rapidapi-key': '{{API_KEY}}'
}
const options = {
  method: 'GET',
  headers: headerParameters
};
async function fetchLineupInfo() {
  try {
    endpointUrl.search = queryParameters;
    const response = await fetch(endpointUrl, options);
    printResponse(response);
  } 
  catch (error) {
    printError(error);
  }
}
fetchLineupInfo();

Let’s look at how we’ve changed the code:

  • Line 6: We replace the team parameter with the type parameter.
  • Line 19: We change the function’s name to fetchLineupInfo().

Response fields

The table below contains some important response fields of this endpoint:

Response Fields

Type

Description

team

Object

This object contains the team's information, such as its name, ID, and logo.

formation

String

This is the formation of the team in the fixture.

startXI

Object [array]

This array contains information about the players in the starting XI. It has all that information in an object named player.

substitutes

Object [array]

This array contains information about the players in the substitutes. It has all that information in an object named player.

coach

Object

This object contains the ID, name, and link for the photo of the coach.