Lineups
Retrieve the home and away lineups for a match.
- Requested
- From 40 minutes before kickoff until 120 minutes after
- Refresh interval
- Once every 15 minutes
The matchId comes from
matches.
Reading formation and initial lineup
These two fields are related, and getting the relationship right is what makes a pitch view render correctly.
formation is a string such as 4-2-3-1.
initialLineup is an array of rows, and each row is an array of players.
The first row is always the goalkeeper. Every row after it holds the
number of players that the corresponding position in formation specifies.
So for a formation of 4-2-3-1 the rows are the goalkeeper, then four
players, then two, then three, then one. Walk formation and
initialLineup together rather than assuming a fixed number of rows, since
formations vary.
The bench
substitutes sits alongside initialLineup and is a flat list
rather than a grid, since the bench has no shape to preserve.
Every player in both lists carries a name, a shirt number and a position, which is one
of Goalkeeper, Defender, Midfielder or
Forward. That is enough to group the bench by role without cross
referencing the players endpoint.
Parameters
| Parameter | Type | Description |
|---|---|---|
matchIdrequired
|
numberpath | Requested match id. |
Request
curl --request GET \
--url 'https://soccer.highlightly.net/lineups/{matchId}' \
--header 'x-rapidapi-key: YOUR_API_KEY'const response = await fetch('https://soccer.highlightly.net/lineups/{matchId}', {
headers: {
'x-rapidapi-key': process.env.HIGHLIGHTLY_API_KEY
}
})
if (!response.ok) {
throw new Error(`Highlightly responded ${response.status}`)
}
const data = await response.json()import os
import requests
response = requests.get(
'https://soccer.highlightly.net/lineups/{matchId}',
headers={
'x-rapidapi-key': os.environ['HIGHLIGHTLY_API_KEY'],
},
timeout=10,
)
response.raise_for_status()
data = response.json()Response
homeTeamLineupsTeamrequired14 fields
idnumberrequired
logostringrequired
formationstringrequired
namestringrequired
substitutesLineupsPlayer[]required4 fields
idnumber
namestringrequired
numbernumberrequired
positionstringrequiredGoalkeeperDefenderMidfielderForward
initialLineupLineupsPlayer[]required2D grid of players representing their position on the board. The first entry
will always be the goal keeper. Other entries will follow the team formation,
e.g. formation 4-2-3-1 means that there will be 4 more arrays each containing
the associated number of players in the correct order.4 fields
idnumber
namestringrequired
numbernumberrequired
positionstringrequiredGoalkeeperDefenderMidfielderForward
awayTeamLineupsTeamrequired14 fields
idnumberrequired
logostringrequired
formationstringrequired
namestringrequired
substitutesLineupsPlayer[]required4 fields
idnumber
namestringrequired
numbernumberrequired
positionstringrequiredGoalkeeperDefenderMidfielderForward
initialLineupLineupsPlayer[]required2D grid of players representing their position on the board. The first entry
will always be the goal keeper. Other entries will follow the team formation,
e.g. formation 4-2-3-1 means that there will be 4 more arrays each containing
the associated number of players in the correct order.4 fields
idnumber
namestringrequired
numbernumberrequired
positionstringrequiredGoalkeeperDefenderMidfielderForward
Example response
{
"homeTeam": {
"id": 66311,
"logo": "https://example.com/logo/preview/66311.png",
"formation": "4-2-3-1",
"name": "Angers",
"substitutes": [
{
"id": 24948,
"name": "Lilian Raolisoa",
"number": 27,
"position": "Defender"
}
],
"initialLineup": [
[
{
"name": "Yahia Fofana",
"number": 30,
"position": "Goalkeeper"
}
],
[
{
"name": "Florent Hanin",
"number": 26,
"position": "Defender"
},
{
"name": "Jordan Lefort",
"number": 21,
"position": "Defender"
},
{
"name": "Cédric Hountondji",
"number": 22,
"position": "Defender"
},
{
"name": "Yan Valery",
"number": 2,
"position": "Defender"
}
],
[
{
"name": "Himad Abdelli",
"number": 10,
"position": "Midfielder"
},
{
"name": "Zinédine Ould Khaled",
"number": 12,
"position": "Midfielder"
}
],
[
{
"name": "Justin-Noel Kalumba",
"number": 17,
"position": "Midfielder"
},
{
"name": "Pierrick Capelle",
"number": 15,
"position": "Midfielder"
},
{
"name": "Farid El Melali",
"number": 28,
"position": "Midfielder"
}
],
[
{
"name": "Loïs Diony",
"number": 9,
"position": "Forward"
}
]
]
},
"awayTeam": {
"id": 66311,
"logo": "https://example.com/logo/preview/66311.png",
"formation": "4-2-3-1",
"name": "Angers",
"substitutes": [
{
"id": 24948,
"name": "Lilian Raolisoa",
"number": 27,
"position": "Defender"
}
],
"initialLineup": [
[
{
"name": "Yahia Fofana",
"number": 30,
"position": "Goalkeeper"
}
],
[
{
"name": "Florent Hanin",
"number": 26,
"position": "Defender"
},
{
"name": "Jordan Lefort",
"number": 21,
"position": "Defender"
},
{
"name": "Cédric Hountondji",
"number": 22,
"position": "Defender"
},
{
"name": "Yan Valery",
"number": 2,
"position": "Defender"
}
],
[
{
"name": "Himad Abdelli",
"number": 10,
"position": "Midfielder"
},
{
"name": "Zinédine Ould Khaled",
"number": 12,
"position": "Midfielder"
}
],
[
{
"name": "Justin-Noel Kalumba",
"number": 17,
"position": "Midfielder"
},
{
"name": "Pierrick Capelle",
"number": 15,
"position": "Midfielder"
},
{
"name": "Farid El Melali",
"number": 28,
"position": "Midfielder"
}
],
[
{
"name": "Loïs Diony",
"number": 9,
"position": "Forward"
}
]
]
}
}Values are the examples declared in the OpenAPI spec, not a captured live response.
Errors
| Status | Description |
|---|---|
400 |
Bad request descriptive error. |
500 |
Internal server error. |
