Rounds

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.

https://api.sportmonks.com/v3/football/rounds?api_token=YOUR_TOKEN
Response
{
  "data": [
    {
      "id": 23317,
      "sport_id": 1,
      "league_id": 271,
      "season_id": 1273,
      "stage_id": 1086,
      "name": "1",
      "finished": true,
      "is_current": false,
      "starting_at": "2005-07-19",
      "ending_at": "2005-07-24",
      "games_in_current_week": false
    },
    {
      "id": 23318,
      "sport_id": 1,
      "league_id": 271,
      "season_id": 1273,
      "stage_id": 1086,
      "name": "2",
      "finished": true,
      "is_current": false,
      "starting_at": "2005-07-24",
      "ending_at": "2005-07-31",
      "games_in_current_week": false
    },

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:

https://api.sportmonks.com/v3/football/rounds/seasons/{season_id}

For example, if you’re interested in all the rounds of the Scottish Premiership 2022/2023 season:

https://api.sportmonks.com/v3/football/rounds/seasons/19735?api_token=YOUR_TOKEN
Response
{
  "data": [
    {
      "id": 274733,
      "sport_id": 1,
      "league_id": 501,
      "season_id": 19735,
      "stage_id": 77457866,
      "name": "20",
      "finished": true,
      "is_current": false,
      "starting_at": "2023-01-02",
      "ending_at": "2023-01-02",
      "games_in_current_week": false
    },
    {
      "id": 274716,
      "sport_id": 1,
      "league_id": 501,
      "season_id": 19735,
      "stage_id": 77457866,
      "name": "3",
      "finished": true,
      "is_current": false,
      "starting_at": "2022-08-13",
      "ending_at": "2022-08-14",
      "games_in_current_week": false
    },
    
    //and more

GET Rounds by Round ID

This endpoint is suited when you’re only interested in data of one round. For this, you will need to add the round id to your request:

https://api.sportmonks.com/v3/football/rounds/{round_id}

For example, if you’re interested in the last round of the Scottish Premiership 2022/2023 season:

https://api.sportmonks.com/v3/football/rounds/275096?api_token=YOUR_TOKEN
Response
{
  "data": {
    "id": 274733,
    "sport_id": 1,
    "league_id": 501,
    "season_id": 19735,
    "stage_id": 77457866,
    "name": "20",
    "finished": true,
    "is_current": false,
    "starting_at": "2023-01-02",
    "ending_at": "2023-01-02",
    "games_in_current_week": false
  },

GET Rounds Search by Name

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:

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

For example, if you’re interested in all the 31's rounds:

https://api.sportmonks.com/v3/football/rounds/search/31?api_token=YOUR_TOKEN
Response
{
  "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:

https://api.sportmonks.com/v3/football/rounds/274733?api_token=YOUR_TOKEN&include=league;season;stage;fixtures
Response
{
  "data": {
    "id": 274733,
    "sport_id": 1,
    "league_id": 501,
    "season_id": 19735,
    "stage_id": 77457866,
    "name": "20",
    "finished": true,
    "is_current": false,
    "starting_at": "2023-01-02",
    "ending_at": "2023-01-02",
    "games_in_current_week": false,
    "league": {
      "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
    },
    "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
    },
    "stage": {
      "id": 77457866,
      "sport_id": 1,
      "league_id": 501,
      "season_id": 19735,
      "type_id": 223,
      "name": "1st Phase",
      "sort_order": 1,
      "finished": false,
      "is_current": true,
      "starting_at": "2022-07-30",
      "ending_at": "2023-04-22",
      "games_in_current_week": true
    },
    "fixtures": [
      {
        "id": 18535606,
        "sport_id": 1,
        "league_id": 501,
        "season_id": 19735,
        "stage_id": 77457866,
        "group_id": null,
        "aggregate_id": null,
        "round_id": 274733,
        "state_id": 5,
        "venue_id": 219,
        "name": "St. Johnstone vs Dundee United",
        "starting_at": "2023-01-02 15:00:00",
        "result_info": null,
        "leg": "1/1",
        "details": null,
        "length": 90,
        "placeholder": false,
        "last_processed_at": "2023-02-17 10:19:54",
        "has_odds": true,
        "starting_at_timestamp": 1672671600
      },
      
  //And more    

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.

Easily add the &select=name,starting_at,ending_at

https://api.sportmonks.com/v3/football/rounds?api_token=YOUR_TOKEN&select=name,starting_at,ending_at
Response
{
  "data": [
    {
      "name": "1",
      "starting_at": "2005-07-19",
      "ending_at": "2005-07-24",
      "id": 23317,
      "sport_id": 1,
      "league_id": 271,
      "season_id": 1273,
      "stage_id": 1086
    },
    {
      "name": "2",
      "starting_at": "2005-07-24",
      "ending_at": "2005-07-31",
      "id": 23318,
      "sport_id": 1,
      "league_id": 271,
      "season_id": 1273,
      "stage_id": 1086
    },

Check our filtering tutorial for more information and tips.

Last updated