Leagues
Last updated
Was this helpful?
Last updated
Was this helpful?
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.
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 endpoint.
Your request:
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.
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:
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}
For example, if you’re only interested in Scottish leagues, your request will be:
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:
There is also an option to get all the leagues that have live fixtures.
https://api.sportmonks.com/v3/football/leagues/live
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.
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}
You can also request the upcoming fixtures or the latest fixture of one particular league with the upcoming and latest include:
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:
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 for more info.
Now that you've requested all the leagues, you also know their unique league id. You can use this id in the second option: .
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 option could be just the endpoint you’re looking for.
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 endpoint is perfectly suited for this.
The 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:
The last option to retrieve leagues is to .
As you’ve learnt in the , 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 . 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
In our 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 endpoint for this example.
Tip: Check our for more information and tips.