Most football competitions are played once a week. The majority of the competitions handle a double round-robin structure, meaning that every team will play matches until everyone has played against each other twice.
Competitions have divided every match day into a specific round. This way, you can see exactly how many rounds are scheduled and which team plays against whom per round.
Every round has a name and unique round id in the API. This will greatly help you with requesting data about the rounds.
This section will briefly discuss all the options available to request rounds.
An overview of all available options:
GET All Rounds: returns all the rounds available within your subscription.
GET Rounds by ID: returns round information from your requested round id.
GET Rounds by Season ID: returns round information from your requested season id.
GET Rounds by Search by Name: returns all rounds that match your search query.
For all the rounds endpoints, the base URL is the same: https://api.sportmonks.com/v3/football/rounds
Per endpoint the rest of the URL requires additional information. We will explain this per endpoint.
Requesting Rounds
GET All Rounds
Just like with stages, you can request all rounds available via the GET All Rounds endpoint. The URL to get all your rounds is the same as the base URL for rounds. All you have to do is authorize the request with your API token. Check our authentication section for more info.
Let’s briefly evaluate the response. You can see the unique round id, start and end date, league and season id belonging to the round, the status and the name. Interested in more information? Keep reading and find out in the adding useful information section.
GET Rounds by Season ID
The previous request returned all the rounds in your subscription. But what if you’re only interested in the rounds of a particular season? You can use the GET Rounds by Season ID endpoint for this. You need to add the season id to your request:
This endpoint returns all the rounds based on your search query. This might come in handy if you want all the last rounds of a season. To search on round name, you’ll need to add /search/{search_query} to the rounds base url:
{"data": [ {"id":23332,"sport_id":1,"league_id":271,"season_id":1273,"stage_id":1086,"name":"14","finished":true,"is_current":false,"starting_at":"2006-03-19","ending_at":"2006-03-29","games_in_current_week":false }, {"id":23353,"sport_id":1,"league_id":271,"season_id":1274,"stage_id":1087,"name":"14","finished":true,"is_current":false,"starting_at":"2007-04-05","ending_at":"2007-04-09","games_in_current_week":false }, {"id":23393,"sport_id":1,"league_id":271,"season_id":1275,"stage_id":1088,"name":"14","finished":true,"is_current":false,"starting_at":"2008-03-30","ending_at":"2008-04-07","games_in_current_week":false },//and more
The more complete your search query is, the more relevant response you’ll get.
Adding useful information
You might’ve noticed that the rounds endpoints return limited information. But no worries, there are a lot of include options available to enrich your request.
For example, you can include information about:
To which stage the round belongs
The fixtures of the round
To which league the round belongs
To which season the round belongs
For this example we want all the above information for the last round in the Scottish Premiership:
Check our include tutorial for more information and tips about includes
Selecting and filtering
You can limit the data our API returns by default by selecting a specific field you’re interested in. For example, you want to retrieve all the rounds in your subscription but are only interested in the name, start date and end date.