Leagues

Every continent has countries, every country has one or multiple leagues, and every league has one or more seasons. Therefore, for most customers, the leagues endpoint is the starting point. Via this endpoint, you can gather a complete overview of all the leagues available within your subscription.

You can retrieve basic league information or enrich your response with season and fixture information.

This section will briefly discuss all the options available to request leagues.

An overview of all the options available:

  • GET All Leagues: returns all the leagues that are accessible within your subscription.

  • Get League by ID: returns the single league you’ve requested by id.

  • GET League by Country ID: returns all the leagues from your requested country id.

  • GET League Live: returns the leagues with live fixtures.

  • GET League by Fixture Date: returns all the leagues with fixtures from your requested fixture date.

  • GET League Search by Name: returns all the leagues that match your search query.

For all the league endpoints the base URL is the same: URL:

https://api.sportmonks.com/v3/football/leagues

Per endpoint the rest of the URL requires additional information. We will explain this per endpoint.

Requesting leagues

GET All Leagues

As mentioned before, a great starting point for your football application is to gather an overview of all the leagues available in your subscription. You can do this via the GET All Leagues endpoint.

The URL to get all your leagues is the same as the base URL for leagues. All you have to do is authorize the request with your API token. Check our authentication section for more info.

Your request:

https://api.sportmonks.com/v3/football/leagues?api_token=YOUR_TOKEN
Response
{
  "data": [
    {
      "id": 271,
      "sport_id": 1,
      "country_id": 320,
      "name": "Superliga",
      "active": true,
      "short_code": "DNK SL",
      "image_path": "https://cdn.sportmonks.com/images/soccer/leagues/271.png",
      "type": "league",
      "sub_type": "domestic",
      "last_played_at": "2023-02-27 18:00:00",
      "has_jerseys": false
    },
    {
      "id": 501,
      "sport_id": 1,
      "country_id": 1161,
      "name": "Premiership",
      "active": true,
      "short_code": "SCO P",
      "image_path": "https://cdn.sportmonks.com/images/soccer/leagues/501.png",
      "type": "league",
      "sub_type": "domestic",
      "last_played_at": "2023-02-25 15:00:00",
      "has_jerseys": false
    },
    {
      "id": 513,
      "sport_id": 1,
      "country_id": 1161,
      "name": "Premiership Play-Offs",
      "active": true,
      "short_code": "SCO P PO",
      "image_path": "https://cdn.sportmonks.com/images/soccer/leagues/1/513.png",
      "type": "league",
      "sub_type": "play-offs",
      "last_played_at": "2021-05-24 20:35:36",
      "has_jerseys": false
    },
    {
      "id": 1659,
      "sport_id": 1,
      "country_id": 320,
      "name": "Superliga Play-offs",
      "active": true,
      "short_code": null,
      "image_path": "https://cdn.sportmonks.com/images/soccer/leagues/27/1659.png",
      "type": "league",
      "sub_type": "play-offs",
      "last_played_at": "2019-05-19 14:00:00",
      "has_jerseys": false
    }
  ],

Let’s take a look together at what the API returns. As you can see, the API returns all the leagues available in the free plan.

You can see the name of the league, the unique league id, the league logo, and the type and sub_type of the leagues.

Now that you've requested all the leagues, you also know their unique league id. You can use this id in the second option: GET League by ID.

GET League by ID

This endpoint is useful if you only want information about one particular league. You need to add the league id to your request:

https://api.sportmonks.com/v3/football/leagues/{league_id}

For example, if you’re only interested in the Scottish Premier League, your request will be:

https://api.sportmonks.com/v3/football/leagues/501?api_token=YOUR_TOKEN
Response
{
  "data": {
    "id": 501,
    "sport_id": 1,
    "country_id": 1161,
    "name": "Premiership",
    "active": true,
    "short_code": "SCO P",
    "image_path": "https://cdn.sportmonks.com/images/soccer/leagues/501.png",
    "type": "league",
    "sub_type": "domestic",
    "last_played_at": "2023-02-25 15:00:00",
    "has_jerseys": false
  },

Easy isn’t it? You can now request information per league. Now let’s imagine you want an overview of all the leagues in a specific country. The GET Leagues by Country ID option could be just the endpoint you’re looking for.

GET League by Country ID

The leagues by country id only returns all the leagues from your requested country ID. To request this, you’ll need to add /countries/{country_id} to the leagues base URL:

https://api.sportmonks.com/v3/football/leagues/countries/{country_id}

Tip: You can request all countries with their unique id via the GET All Countries endpoint.

For example, if you’re only interested in Scottish leagues, your request will be:

https://api.sportmonks.com/v3/football/leagues/countries/1161?api_token=YOUR_TOKEN
Response
{
  "data": [
    {
      "id": 501,
      "sport_id": 1,
      "country_id": 1161,
      "name": "Premiership",
      "active": true,
      "short_code": "SCO P",
      "image_path": "https://cdn.sportmonks.com/images/soccer/leagues/501.png",
      "type": "league",
      "sub_type": "domestic",
      "last_played_at": "2023-02-25 15:00:00",
      "has_jerseys": false
    },
    {
      "id": 513,
      "sport_id": 1,
      "country_id": 1161,
      "name": "Premiership Play-Offs",
      "active": true,
      "short_code": "SCO P PO",
      "image_path": "https://cdn.sportmonks.com/images/soccer/leagues/1/513.png",
      "type": "league",
      "sub_type": "play-offs",
      "last_played_at": "2021-05-24 20:35:36",
      "has_jerseys": false
    }
  ],

Besides the fact that you, maybe, want to group the leagues per country, it’s also an option to group the leagues per name. The GET Leagues by Name endpoint is perfectly suited for this.

GET League Search by Name

This endpoint returns all the leagues based on your search query. This might come in handy if you cannot find a league or want to group leagues by name. To search on league name, you’ll need to add /search/{search_query} to the leagues base URL:

https://api.sportmonks.com/v3/football/leagues/search/{search_query}

For example, if you’re only interested in leagues with “Premier” in the name, your request will be:

https://api.sportmonks.com/v3/football/leagues/search/premier?api_token=YOUR_TOKEN
Response
{
  "data": [
    {
      "id": 501,
      "sport_id": 1,
      "country_id": 1161,
      "name": "Premiership",
      "active": true,
      "short_code": "SCO P",
      "image_path": "https://cdn.sportmonks.com/images/soccer/leagues/501.png",
      "type": "league",
      "sub_type": "domestic",
      "last_played_at": "2023-02-25 15:00:00",
      "has_jerseys": false
    },
    {
      "id": 513,
      "sport_id": 1,
      "country_id": 1161,
      "name": "Premiership Play-Offs",
      "active": true,
      "short_code": "SCO P PO",
      "image_path": "https://cdn.sportmonks.com/images/soccer/leagues/1/513.png",
      "type": "league",
      "sub_type": "play-offs",
      "last_played_at": "2021-05-24 20:35:36",
      "has_jerseys": false
    }
  ],

The more complete your search query is, the more relevant response you’ll get.

There is also an option to get all the leagues that have live fixtures.

GET Leagues by Live

The GET Leagues by Live returns the leagues that currently have live fixtures. It could be a nice option if you want an overview of all the leagues that currently have live matches. To request all the leagues that have live matches, you’ll need to add /live to the leagues base URL:

https://api.sportmonks.com/v3/football/leagues/live

https://api.sportmonks.com/v3/football/leagues/live/?api_token=YOUR_TOKEN

The response can be empty if there are no leagues in your subscription that have live matches at the time you’re making the request.

The last option to retrieve leagues is to GET League by Fixture Date.

GET League by Fixture Date

This endpoint returns all the leagues from your requested fixture date. This could be interesting if you want to know all the leagues that had fixtures on a specific date. You’ll need to add /date/{date} to the leagues base URL:

https://api.sportmonks.com/v3/football/leagues/date/{date}

https://api.sportmonks.com/v3/football/leagues/date/2022-09-03?api_token=YOUR_TOKEN
Response
{
  "data": [
    {
      "id": 501,
      "sport_id": 1,
      "country_id": 1161,
      "name": "Premiership",
      "active": true,
      "short_code": "SCO P",
      "image_path": "https://cdn.sportmonks.com/images/soccer/leagues/501.png",
      "type": "league",
      "sub_type": "domestic",
      "last_played_at": "2023-02-25 15:00:00",
      "has_jerseys": false
    },

Adding useful information

As you’ve learnt in the includes tutorial, you can enrich your request with includes. This section will discuss some of the most common requests used on the league’s endpoints.

First of all, you can find a list of all available includes on the endpoint pages. For the leagues, the most commonly used include is currentSeason. This include returns the unique active season. This id can be used on the seasons endpoint or as a filter option. We’ll come back to this in the seasons section.

Tip: If you’re interested in historical seasons, you need to use the seasons include.

You can also request the upcoming fixtures or the latest fixture of one particular league with the upcoming and latest include:

https://api.sportmonks.com/v3/football/leagues/501?api_token=YOUR_TOKEN&include=currentSeason;upcoming;latest
Response
{
  "data": {
    "id": 501,
    "sport_id": 1,
    "country_id": 1161,
    "name": "Premiership",
    "active": true,
    "short_code": "SCO P",
    "image_path": "https://cdn.sportmonks.com/images/soccer/leagues/501.png",
    "type": "league",
    "sub_type": "domestic",
    "last_played_at": "2023-02-25 15:00:00",
    "has_jerseys": false,
    "current_season": {
      "id": 19735,
      "sport_id": 1,
      "league_id": 501,
      "tie_breaker_rule_id": 171,
      "name": "2022/2023",
      "finished": false,
      "pending": false,
      "is_current": true,
      "starting_at": "2022-07-30",
      "ending_at": "2023-04-22",
      "standings_recalculated_at": "2023-03-02 00:07:24",
      "games_in_current_week": false
    },
    "upcoming": [
      {
        "id": 18538017,
        "sport_id": 1,
        "league_id": 501,
        "season_id": 19735,
        "stage_id": 77457866,
        "group_id": null,
        "aggregate_id": null,
        "round_id": 275098,
        "state_id": 1,
        "venue_id": 8928,
        "name": "Aberdeen vs Rangers",
        "starting_at": "2023-04-22 14:00:00",
        "result_info": null,
        "leg": "1/1",
        "details": null,
        "length": 90,
        "placeholder": false,
        "last_processed_at": null,
        "has_odds": false,
        "starting_at_timestamp": 1682172000
      },
      {
        "id": 18538018,
        "sport_id": 1,
        "league_id": 501,
        "season_id": 19735,
        "stage_id": 77457866,
        "group_id": null,
        "aggregate_id": null,
        "round_id": 275098,
        "state_id": 1,
        "venue_id": 8909,
        "name": "Celtic vs Motherwell",
        "starting_at": "2023-04-22 14:00:00",
        "result_info": null,
        "leg": "1/1",
        "details": null,
        "length": 90,
        "placeholder": false,
        "last_processed_at": null,
        "has_odds": false,
        "starting_at_timestamp": 1682172000
      },
      
    //and more

Selecting and filtering

In our filtering tutorial you’ve learnt how to select specific fields or filter only on the data you’re interested in. By default, our API returns a set of data related to the league. We can imagine you’re not interested in all the league data the API returns. Let’s say you’re only interested in the league name and logo.

We’re going to use the GET All Leagues endpoint for this example.

https://api.sportmonks.com/v3/football/leagues?api_token=YOUR_TOKEN

You can add the &select= parameter followed by the fields you want. In our case: name,image_path. This results in the below request and response:

https://api.sportmonks.com/v3/football/leagues?api_token=YOUR_TOKEN&select=name,image_path
Response
{
  "data": [
    {
      "name": "Superliga",
      "image_path": "https://cdn.sportmonks.com/images/soccer/leagues/271.png",
      "id": 271,
      "sport_id": 1,
      "country_id": 320
    },
    {
      "name": "Premiership",
      "image_path": "https://cdn.sportmonks.com/images/soccer/leagues/501.png",
      "id": 501,
      "sport_id": 1,
      "country_id": 1161
    },
    {
      "name": "Premiership Play-Offs",
      "image_path": "https://cdn.sportmonks.com/images/soccer/leagues/1/513.png",
      "id": 513,
      "sport_id": 1,
      "country_id": 1161
    },
    {
      "name": "Superliga Play-offs",
      "image_path": "https://cdn.sportmonks.com/images/soccer/leagues/27/1659.png",
      "id": 1659,
      "sport_id": 1,
      "country_id": 320
    }
  ],

Tip: Check our filtering tutorial for more information and tips.

Last updated