Jump to:

  1. Endpoint
  2. Parameters
  3. Response
  4. Examples
  5. Getting Competitions By Country
  6. Getting Competitions By Federation

Competitions are our way of referring to any kind of football tournament that exists and that we support. Competitions include: national leagues (e.g. Premier League, LigaMX), international leagues (e.g. UEFA Champions League, UEFA Nations League), as well as national cups (e.g. Copa Del Rey, Coppa Italia, Copa Do Brasil) and international cups (e.g. UEFA Super Cup, FIFA World Cup). This includes both national teams (e.g. Brazil, France) and club teams (e.g. Real Madrid, Juventus, Manchester United).


ENDPOINT


In order, to get the list of all competitions that our football API provides and supports you need to call the URL bellow. In this example, we have used the demo api key and secret pair. If you login in, you will see all examples with your own api key and api secret


GET:

PARAMETERS


This football API endpoint supports several parameters that help you filter the football competitions based on countries or federations. By countries, we mean a sovereign country that can be found on the map (e.g. Russia, Italy, South Africa), and by federation we mean international football association (like: FIFA, CONMEBOL, CAF, AFC). You can read more on getting to know the countries in the getting countries list documentation page. To find out how federations work in the context of our football API please refer to the federations specific page.


NameTypeRequiredExampleDescription
country_idNumber1Will show the competitions from that specific country only
federation_idNumber1Will show the competitions from that specific federation only

NOTE: If you provide both a country_id and a federation_id the country will take precedence and you will see only football competitions from that country!


RESPONSE


If you call the URL in the box above, our football API will return a response similar to what is show in this section. First, in the table, we explain what fields are there, and then follows a JSON example. Review our [data formats page] (/documentation/reference/8/response_formats) for more information on data formats that our football API supports.


NameTypeExampleDescription
activenumber1Indicates whether we still support this competition (1). If the value is (0) it means that we have supported the competition before and we have historical data about it but we do not do that an longer
countrieslistList with all the countries to which the competition belongs to.
federationslistList with all the federations to which the competition belongs to.
has_groupsnumber1Indicates whether this competition has groups with standings (1) or is direct elimination only (0)
idNumber5The id of the competition which you can use as filters in other sequential requests.
is_cupnumber1Works in the opposite way of the is_league field if 0 then the competition is a league if 1 then the competition is a cup
is_leagueumber1Indicates whether the competition is a cup (0) like The FA Cup or a league(1) like the Bundesliga
nameStringSerie AThe name of the competition.
national_teams_onlynumber1Shows if the competition participants are only national teams like the FIFA World CUP, if the value 0 then the competition is for club teams like the UEFA Champions League
seasonobjectThe season of the current competition edition. The dates of the season are the start and end date of the season in relation to the world calendar and not the competition one.

{
    "success": true,
    "data": {
        "competition": [
            {
                "id": "244",
                "name": "Champions League",
                "is_league": "0",
                "is_cup": "1",
                "tier": "0",
                "has_groups": "1",
                "active": "1",
                "national_teams_only": "0",
                "countries": [],
                "federations": [
                    {
                        "id": "2",
                        "name": "UEFA"
                    }
                ],
                "season": {
                    "id": "13",
                    "name": "2021\/2022",
                    "start": "2021-07-01",
                    "end": "2022-06-30"
                }
            },
            {
                "id": "317",
                "name": "Championship",
                "is_league": "1",
                "is_cup": "0",
                "tier": "2",
                "has_groups": "1",
                "active": "1",
                "national_teams_only": "0",
                "countries": [
                    {
                        "id": "3",
                        "name": "Scotland",
                        "flag": "SCO.png",
                        "fifa_code": "SCO",
                        "uefa_code": "SCO",
                        "is_real": "1"
                    }
                ],
                "federations": [],
                "season": {
                    "id": "13",
                    "name": "2021\/2022",
                    "start": "2021-07-01",
                    "end": "2022-06-30"
                }
            }
        ]
    }
}


EXAMPLES


The following examples show you how to use this endpoint in various programming languages. In this example, we have used the demo api key and secret pair. If you login in, you will see all examples with your own api key and api secret cUrl:

curl -XGET "https://livescore-api.com/api-client/competitions/list.json?key=demo_key&secret=demo_secret"
PHP:
file_get_contents('https://livescore-api.com/api-client/competitions/list.json?key=demo_key\&secret=demo_secret');
Python:
import urllib2
req = urllib2.Request('https://livescore-api.com/api-client/competitions/list.json?key=demo_key\&secret=demo_secret')
response = urllib2.urlopen(req)
print response.read()


GETTING COMPETITIONS BY COUNTRY


To get the list of competitions for a certain country, you have to provide the id of the country as a get query parameter in the api endpoint URL. The parameter is country_id. In the example bellow we show you how to get all the competitions for Germany. To find our more about the countries and their ids visit the countries list documentation page. cUrl:

curl -XGET "https://livescore-api.com/api-client/competitions/list.json?key=demo_key&secret=demo_secret&country_id=1"
PHP:
file_get_contents('https://livescore-api.com/api-client/competitions/list.json?key=demo_key\&secret=demo_secret\&country_id=1');
Python:
import urllib2
req = urllib2.Request('https://livescore-api.com/api-client/competitions/list.json?key=demo_key\&secret=demo_secret\&country_id=1')
response = urllib2.urlopen(req)
print response.read()


GETTING COMPETITIONS BY FEDERATION


To get the list of competitions for a certain football federation, you have to provide the id of the federation as an http GET query parameter in the same api endpoint URL. The parameter is called federation_id. In the example bellow we show you how to get all the competitions for UEFA. You can find our more about the federations and their ids in the federations list documentation page. cUrl:

curl -XGET "https://livescore-api.com/api-client/competitions/list.json?key=demo_key&secret=demo_secret&federation_id=2"
PHP:
file_get_contents('https://livescore-api.com/api-client/competitions/list.json?key=demo_key\&secret=demo_secret\&federation_id=2');
Python:
import urllib2
req = urllib2.Request('https://livescore-api.com/api-client/competitions/list.json?key=demo_key\&secret=demo_secret\&federation_id=2')
response = urllib2.urlopen(req)
print response.read()


Didn't find what you need?

Do no hesitate to contact us. We will get back to you as soon as possible.


Jump to: