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:
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:
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:
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:
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
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}
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:
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.
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:
Tip: Check our filtering tutorial for more information and tips.
Last updated