Top disciplinary
On this football API documentation page, we show you how you can get the top rudest players in a competition.
Our football API product will provide you with the possibility to get the top rudest players at the major international competitions: FIFA World Cup, UEFA EURO, Copa America, AFC Asian Cup, and the African Cup of Nations. The data includes most red and yellow card receivers for the final stages of these tournaments.
Endpoint
To get the nastiest players ina competition through our football API, all you need to do is to provide the competition ID. If you want to obtain the complete list with competitions so you have all the id-s at your disposal you can go through our competitions listing API endpoint documentation page. 2 examples of competitions could be the UEFA EURO (ID: 387) and Copa America (ID: 271).
Parameters
The competition top disciplinary player list in our football API requires one parameter called competition_id. Without it the API will return an error with a helpful message. A second optional parameter is the lang which if your package supports will cause the names of the competition, teams, and players to be translated in the provided 2 letter language ISO code.
| Name | Type | Required | Example | Description |
|---|---|---|---|---|
| competition_id | number | 1 | 244 | The id of the competition which top rude players we are getting. |
| lang | string | ar | 2 letter ISO 639-1 language code. Find out more on our data in various languages. |
Response
In the response from this football API endpoint you will receive the most booked and sent off footballers for the chosen competition_id (In the example below, we have listed only 5 players for brevity). Also, the example data is taken from the FIFA World Cup, you can use it for testing during development. The actual data provided by this endpoint supports the major competitions mentioned above.
Most of the data fields returned by this football API endpoint are exactly the same as the ones in the top goal scorers API enpoint. An exception are the fields red_cards and yellow_cards that are replacing the goals and assists ones.
{
"success": true,
"data": {
"competition": {
"id": 362,
"name": "FIFA World Cup",
"is_league": false,
"is_cup": true,
"tier": 0,
"has_groups": true,
"active": true,
"national_teams_only": false
},
"edition": {
"id": 683,
"season_id": 11,
"is_current": true
},
"season": {
"id": 11,
"name": "2022",
"start": "2022-01-01",
"end": "2022-12-31"
},
"topcards": [
{
"red_cards": 0,
"yellow_cards": 1,
"played": 1,
"team": {
"id": 1427,
"name": "Qatar",
"stadium": "Khalifa International Stadium",
"country_id": 116,
"logo": "https:\/\/cdn.live-score-api.com\/teams\/69b6f3219144187e564adc109d37fdcb.png"
},
"player": {
"id": 23802,
"name": "Saad Al Sheeb"
}
},
{
"red_cards": 0,
"yellow_cards": 1,
"played": 1,
"team": {
"id": 1427,
"name": "Qatar",
"stadium": "Khalifa International Stadium",
"country_id": 116,
"logo": "https:\/\/cdn.live-score-api.com\/teams\/69b6f3219144187e564adc109d37fdcb.png"
},
"player": {
"id": 23499,
"name": "Almoez Ali"
}
},
{
"red_cards": 0,
"yellow_cards": 1,
"played": 1,
"team": {
"id": 1427,
"name": "Qatar",
"stadium": "Khalifa International Stadium",
"country_id": 116,
"logo": "https:\/\/cdn.live-score-api.com\/teams\/69b6f3219144187e564adc109d37fdcb.png"
},
"player": {
"id": 23494,
"name": "Karim Boudiaf"
}
},
{
"red_cards": 0,
"yellow_cards": 1,
"played": 1,
"team": {
"id": 1427,
"name": "Qatar",
"stadium": "Khalifa International Stadium",
"country_id": 116,
"logo": "https:\/\/cdn.live-score-api.com\/teams\/69b6f3219144187e564adc109d37fdcb.png"
},
"player": {
"id": 23824,
"name": "Akram Afif"
}
},
{
"red_cards": 0,
"yellow_cards": 1,
"played": 1,
"team": {
"id": 1847,
"name": "Ecuador",
"stadium": "Estadio Ol\u00edmpico Atahualpa",
"country_id": 117,
"logo": "https:\/\/cdn.live-score-api.com\/teams\/02e0d32c2e6bf6d7d540c98d69ad8682.png"
},
"player": {
"id": 55173,
"name": "Moises Caicedo"
}
}
]
}
}| Name | Type | Example | Description |
|---|---|---|---|
| competition | object | An object holding the information about the competition. It has the structure of our standard competition object. | |
| edition | object | An object holding the information about the edition of the competition. It has the structure of our standard edition object. | |
| season | object | An object holding the information about the season of the competition for which we are getting the disciplinary records. It has the structure of our standard season object. | |
| topcards | list | The list with the competitions most sanctioned players. | |
| topcards.played | number | 15 | The number of matches that a player has taken part in during the current edition of the competition. |
| topcards.player | object | An object holding the information about the player. It has the structure of our standard player object. | |
| topcards.red_cards | number | 1 | The number of red cards that the player has received for the duration of the competition |
| topcards.team | object | An object holding the information about the team for which the player is competing. It has the structure of our standard team object. | |
| topcards.yellow_cards | number | 3 | The number of yellow cards that the player has received for the competition |
Getting Disciplinary Records In Different Languages
In order to have access to this football API feature, your subscription package needs to support translations of data, you can use the lang parameter to get get the names of the competition, teams, and players in the chosen language.
cUrl:
curl -XGET "https://livescore-api.com/api-client/competitions/topcards.json?key=demo_key&secret=demo_secret&competition_id=362&lang=ar"file_get_contents('https://livescore-api.com/api-client/competitions/topcards.json?key=demo_key\&secret=demo_secret\&competition_id=362&lang=ar');import urllib2
req = urllib2.Request('https://livescore-api.com/api-client/competitions/topcards.json?key=demo_key\&secret=demo_secret\&competition_id=362&lang=ar')
response = urllib2.urlopen(req)
print response.read()