Fixtures

List all fixtures.

The Fixtures API lets developers list and manage competition fixtures of a specific season for which a client is licensed. This is a gateway into the Actions API and allows clients to determine which fixtures are live and available.

Applications don't need any input to list all fixtures, however information can be filtered by start date and end date among others. fixtures for which a client is licensed.

Per each competition, the endpoints will return the following information:

• Name of the competition

• Fixture date and kick-off time

• Home and Away team (with IDs)

• Venue

• Stage/Round/Group information

• Status (scheduled, live, completed, postponed)

Endpoints

List fixtures

GET https://dde-api.data.imgarena.com/snooker/fixtures

Retrieves a list of seasons for a specific sport.

Query Parameters

Name	Type	Description
live	Boolean	Allows users to determine which fixtures are live and available based on a user's licence. Example: true, false
status	String	Allows clients to filter based on the status of a match or group of matches. Example: scheduled, live, completed, postponed
dateFrom	Date	Allows clients to filter between specific dates. Example: 2023-01-01
dateTo	Date	Allows clients to filter between specific dates. Example: 2023-01-01
type	String	Allows clients to filter based on the type of a match or group of matches. Example: official, simulation, training
coverageLevel	String	The coverage level of a fixture. Examples: noCoverage, inVenue, lowLatencyStream, standardStream & video(postmatch)
sort	String	Assortment of the data within the fixtures API. We currently support name, asc, desc and startTime. Sort should be supplied in the form `sort=<field>,<direction>` where direction defaults to `asc` if not supplied. If wanting to sort by multiple fields then the sort parameter should be supplied for each field in the order the sort is desired. Default sort order is by startTime and name.
size	Integer	The page size. Default is 20 fixtures. Please be sensible specifying the size to ensure the most efficient results and API performance
page	Integer	The page number
includeDeleted	Boolean	Pass "false" to exclude deleted fixtures from the response. By default, this value is set to "true," meaning deleted fixtures will be included in the response.

Headers

Name	Type	Description
Accept*	String	application/vnd.imggaming.dde.api+json;version=1
Authorization*	String	Bearer ACCESS_TOKEN
Content-Type*	String	application/json

400: Bad Request

{
    Request is missing required HTTP header 'Accept'
}

401: Unauthorized

{
    The supplied authentication is invalid
}

200: OK

```json
{
    "id": "51f9a6be-98ad-4586-b99e-36581ecec242",
    "name": "Ding Junhui v Ali Carter",
    "status": "Scheduled",
    "collectionStatus": "CollectionScheduled",
    "type": "Official",
    "coverageLevel": "In Venue",
    "startDateUTC": "2024-07-16T11:30:00",
    "teams": [
        {
            "id": "3ff06750-8c3c-456c-8fac-58209b6f679e",
            "name": "Ding Junhui",
            "club": {
                "id": "379c6e7c-c0c7-4468-b1b6-2baab78e9ee3",
                "name": "Ding Junhui (JUN003)"
            },
            "category": {
                "id": 34,
                "name": "Unknown"
            },
            "homeTeam": true,
            "shortCode": "JUN3"
        },
        {
            "id": "c796b82d-1040-422d-b27d-9249310b99a3",
            "name": "Ali Carter",
            "club": {
                "id": "458f6697-3551-4fcb-918b-384d1907359f",
                "name": "Ali Carter (CAR004)"
            },
            "category": {
                "id": 34,
                "name": "Unknown"
            },
            "homeTeam": false,
            "shortCode": "CAR4"
        }
    ],
    "stage": {
        "id": "a0c6bea7-9b82-4f79-a3fc-5bd2df40496d",
        "name": "Main",
        "season": {
            "id": "5e73c517-f8eb-4917-91f5-8ac0ffe2bca0",
            "name": "2024/2025",
            "startDateUTC": "2024-06-03T12:00:00",
            "endDateUTC": "2025-05-31T12:00:00",
            "competition": {
                "id": "732562d0-2075-4166-93ac-59380af7ad24",
                "name": "Shanghai Masters 2024",
                "type": "Official",
                "category": {
                    "id": 34,
                    "name": "Unknown"
                },
                "location": {
                    "name": "Shanghai",
                    "country": {
                        "name": "China"
                    },
                    "continent": {
                        "name": "Asia"
                    }
                },
                "latestComment": "Collection status change - Collecting Live - REASONING: . Snooker - Shanghai Masters 2024 - 2024/2025 - Barry Hawkins v Zhou Yuelong - ID: 2af1663c-bc83-4653-adac-a73fcb045e2e. Fixture Start Date and Time: 2024-07-15 11:30:00 UTC",
                "commentCount": 24
            },
            "sport": "Snooker"
        },
        "startDateUTC": "2024-07-15T12:00:00",
        "endDateUTC": "2024-07-21T12:00:00"
    },
    "round": {
        "id": "eb369e31-1a5b-4f9c-9257-f1ecb31caedb",
        "name": "Round 2",
        "stageId": "a0c6bea7-9b82-4f79-a3fc-5bd2df40496d",
        "startDateUTC": "2024-07-15T12:00:00",
        "endDateUTC": "2024-07-15T12:00:00"
    },
    "venue": {
        "id": "77521fb4-1831-4d52-9dd8-0f9c847ff43f",
        "name": "The Grand Stage",
        "location": {
            "name": "Shanghai",
            "country": {
                "name": "China"
            },
            "continent": {
                "name": "Asia"
            }
        }
    },
    "subVenue": {
        "id": "f0c4eb92-4f46-4fa5-9ca3-645c457de2be",
        "name": "TABLE 1",
        "venue": {
            "id": "77521fb4-1831-4d52-9dd8-0f9c847ff43f",
            "name": "The Grand Stage",
            "location": {
                "name": "Shanghai",
                "country": {
                    "name": "China"
                },
                "continent": {
                    "name": "Asia"
                }
            }
        }
    },
    "sport": "Snooker",
    "fixtureDeleted": false
}
```

List season fixtures

GET https://dde-api.data.imgarena.com/snooker/seasons/{seasonId}/fixtures

Path Parameters

Name	Type	Description
seasonId*	UUID	unique id of a requested season

Query Parameters

Name	Type	Description
live	Boolean	Allows users to determine which fixtures are live and available based on a user's licence. Example: true, false
status	String	Allows clients to filter based on the status of a match or group of matches. Example: scheduled, live, completed, postponed
dateFrom	Date	Allows clients to filter between specific dates. Example: 2023-01-01
dateTo	Date	Allows clients to filter between specific dates. Example: 2023-01-01
type	String	Allows clients to filter based on the type of a match or group of matches. Example: official, simulation, training
sort	String	Assortment of the data within the fixtures API. We currently support name, asc, desc and startTime Sort should be supplied in the form `sort=<field>,<direction>` where direction defaults to `asc` if not supplied. If wanting to sort by multiple fields then the sort parameter should be supplied for each field in the order the sort is desired. Default sort order is by startTime and name.
size	Integer	The page size. Default is 20 fixtures. Please be sensible specifying the size to ensure the most efficient results and API performance
page	Integer	The page number
coverageLevel	String	The coverage level of a fixture. Examples: noCoverage, inVenue, lowLatencyStream, standardStream & video(postmatch)
includeDeleted	Boolean	Pass "false" to exclude deleted fixtures from the response. By default, this value is set to "true," meaning deleted fixtures will be included in the response.

200: OK

{
  "content": [
    {
      "id": "b003a95a-f2ab-4571-a1db-ff2b967939fb",
      "name": "Dominic Dale v Ben Woollaston",
      "status": "Completed",
      "collectionStatus": "CollectionCompleted",
      "type": "Official",
      "coverageLevel": "In Venue",
      "startDateUTC": "2024-06-15T19:00:00",
      "teams": [
        {
          "id": "86fd8e51-3964-497c-97c3-729cef44b1f0",
          "name": "Dominic Dale",
          "club": {
            "id": "0d44f12d-b671-4c9e-a096-9ce51e93b0ce",
            "name": "Dominic Dale (DAL001)"
          },
          "category": {
            "id": 34,
            "name": "Unknown"
          },
          "homeTeam": true,
          "shortCode": "DAL1"
        },
        {
          "id": "8ad4ff3f-9f92-44ba-a884-6c8a8e0dcf08",
          "name": "Ben Woollaston",
          "club": {
            "id": "cda9bbbe-61c4-4028-9988-dabc15fdbf96",
            "name": "Ben Woollaston (WOO008)"
          },
          "category": {
            "id": 34,
            "name": "Unknown"
          },
          "homeTeam": false,
          "shortCode": "WOO8"
        }
      ],
      "stage": {
        "id": "274d91a4-4f9a-44d0-b62e-0195f0dbe6c3",
        "name": "Main",
        "season": {
          "id": "a441737a-dd31-4b0b-9190-3e89f5976a87",
          "name": "2024/2025",
          "startDateUTC": "2024-06-03T12:00:00",
          "endDateUTC": "2025-05-31T12:00:00",
          "competition": {
            "id": "8286b57d-e365-4ea0-abaf-9e4339855f8b",
            "name": "BetVictor Championship League Snooker 2024 (Stage One/WK1)",
            "type": "Official",
            "category": {
              "id": 34,
              "name": "Unknown"
            },
            "location": {
              "name": "Leicester",
              "country": {
                "name": "England"
              },
              "continent": {
                "name": "Europe"
              }
            },
            "commentCount": 0
          },
          "sport": "Snooker"
        },
        "startDateUTC": "2024-06-10T12:00:00",
        "endDateUTC": "2024-06-15T12:00:00"
      },
      "round": {
        "id": "80219180-8ff7-4af5-abe4-5e8aff6c40d3",
        "name": "Stage One/WK1",
        "stageId": "274d91a4-4f9a-44d0-b62e-0195f0dbe6c3",
        "startDateUTC": "2024-06-10T12:00:00",
        "endDateUTC": "2024-06-10T12:00:00"
      },
      "venue": {
        "id": "9dfc5c0a-3399-42ad-9cf4-35de76b069b5",
        "name": "Mattioli Arena",
        "location": {
          "name": "Leicester",
          "country": {
            "name": "England"
          },
          "continent": {
            "name": "Europe"
          }
        }
      },
      "subVenue": {
        "id": "1fc8ba73-70a1-4087-a6f9-4469563a3959",
        "name": "TABLE 1",
        "venue": {
          "id": "9dfc5c0a-3399-42ad-9cf4-35de76b069b5",
          "name": "Mattioli Arena",
          "location": {
            "name": "Leicester",
            "country": {
              "name": "England"
            },
            "continent": {
              "name": "Europe"
            }
          }
        }
      },
      "fixtureSummary": {
        "isTied": false,
        "periods": [
          {
            "id": 1,
            "end": "2024-06-15T19:15:47",
            "type": "Regular",
            "label": "1st frame",
            "start": "2024-06-15T19:05:01",
            "awayTeamScore": 0,
            "homeTeamScore": 1,
            "awayTeamPeriodScore": 3,
            "homeTeamPeriodScore": 66
          },
          {
            "id": 2,
            "end": "2024-06-15T19:31:09",
            "type": "Regular",
            "label": "2nd frame",
            "start": "2024-06-15T19:18:07",
            "awayTeamScore": 1,
            "homeTeamScore": 1,
            "awayTeamPeriodScore": 78,
            "homeTeamPeriodScore": 0
          },
          {
            "id": 3,
            "end": "2024-06-15T19:48:46",
            "type": "Regular",
            "label": "3rd frame",
            "start": "2024-06-15T19:33:24",
            "awayTeamScore": 2,
            "homeTeamScore": 1,
            "awayTeamPeriodScore": 71,
            "homeTeamPeriodScore": 2
          },
          {
            "id": 4,
            "end": "2024-06-15T20:07:35",
            "type": "Regular",
            "label": "4th frame",
            "start": "2024-06-15T19:51:44",
            "awayTeamScore": 3,
            "homeTeamScore": 1,
            "awayTeamPeriodScore": 75,
            "homeTeamPeriodScore": 1
          }
        ],
        "finished": true,
        "awayTeamScore": 3,
        "currentPeriod": 4,
        "currentStatus": "Completed",
        "homeTeamScore": 1,
        "collectionStatus": "CollectionCompleted",
        "currentClockTime": "15:51",
        "currentClockState": "stopped",
        "isHomeTeamInPossesion": true
      },
      "sport": "Snooker",
      "fixtureDeleted": false
    },
    {
      "id": "79f183da-6d0b-417f-8820-0b68b369243b",
      "name": "Jamie Jones v Liu Hongyu",
      "status": "Completed",
      "collectionStatus": "CollectionCompleted",
      "type": "Official",
      "coverageLevel": "In Venue",
      "startDateUTC": "2024-06-15T19:00:00",
      "teams": [
        {
          "id": "a85bdd17-6038-43c8-9cec-d492e4a8a2df",
          "name": "Jamie Jones",
          "club": {
            "id": "6e569cf7-f750-4029-a614-4efeecc7ff12",
            "name": "Jamie Jones (JON015)"
          },
          "category": {
            "id": 34,
            "name": "Unknown"
          },
          "homeTeam": true,
          "shortCode": "JON5"
        },
        {
          "id": "b614e094-3724-419a-a052-13261ace5b05",
          "name": "Liu Hongyu",
          "club": {
            "id": "1ddc8299-1725-4946-95b5-3d2f0f2c313e",
            "name": "Liu Hongyu (HON000)"
          },
          "category": {
            "id": 34,
            "name": "Unknown"
          },
          "homeTeam": false,
          "shortCode": "HON0"
        }
      ],
      "stage": {
        "id": "274d91a4-4f9a-44d0-b62e-0195f0dbe6c3",
        "name": "Main",
        "season": {
          "id": "a441737a-dd31-4b0b-9190-3e89f5976a87",
          "name": "2024/2025",
          "startDateUTC": "2024-06-03T12:00:00",
          "endDateUTC": "2025-05-31T12:00:00",
          "competition": {
            "id": "8286b57d-e365-4ea0-abaf-9e4339855f8b",
            "name": "BetVictor Championship League Snooker 2024 (Stage One/WK1)",
            "type": "Official",
            "category": {
              "id": 34,
              "name": "Unknown"
            },
            "location": {
              "name": "Leicester",
              "country": {
                "name": "England"
              },
              "continent": {
                "name": "Europe"
              }
            },
            "commentCount": 0
          },
          "sport": "Snooker"
        },
        "startDateUTC": "2024-06-10T12:00:00",
        "endDateUTC": "2024-06-15T12:00:00"
      },
      "round": {
        "id": "80219180-8ff7-4af5-abe4-5e8aff6c40d3",
        "name": "Stage One/WK1",
        "stageId": "274d91a4-4f9a-44d0-b62e-0195f0dbe6c3",
        "startDateUTC": "2024-06-10T12:00:00",
        "endDateUTC": "2024-06-10T12:00:00"
      },
      "venue": {
        "id": "9dfc5c0a-3399-42ad-9cf4-35de76b069b5",
        "name": "Mattioli Arena",
        "location": {
          "name": "Leicester",
          "country": {
            "name": "England"
          },
          "continent": {
            "name": "Europe"
          }
        }
      },
      "subVenue": {
        "id": "b1960f4e-5a50-4c4b-9cea-776ac0e722a8",
        "name": "TABLE 2",
        "venue": {
          "id": "9dfc5c0a-3399-42ad-9cf4-35de76b069b5",
          "name": "Mattioli Arena",
          "location": {
            "name": "Leicester",
            "country": {
              "name": "England"
            },
            "continent": {
              "name": "Europe"
            }
          }
        }
      },
      "fixtureSummary": {
        "isTied": true,
        "periods": [
          {
            "id": 1,
            "end": "2024-06-15T19:33:50",
            "type": "Regular",
            "label": "1st frame",
            "start": "2024-06-15T19:18:01",
            "awayTeamScore": 1,
            "homeTeamScore": 0,
            "awayTeamPeriodScore": 83,
            "homeTeamPeriodScore": 14
          },
          {
            "id": 2,
            "end": "2024-06-15T19:45:03",
            "type": "Regular",
            "label": "2nd frame",
            "start": "2024-06-15T19:35:58",
            "awayTeamScore": 1,
            "homeTeamScore": 1,
            "awayTeamPeriodScore": 7,
            "homeTeamPeriodScore": 99
          },
          {
            "id": 3,
            "end": "2024-06-15T19:58:27",
            "type": "Regular",
            "label": "3rd frame",
            "start": "2024-06-15T19:46:29",
            "awayTeamScore": 1,
            "homeTeamScore": 2,
            "awayTeamPeriodScore": 20,
            "homeTeamPeriodScore": 68
          },
          {
            "id": 4,
            "end": "2024-06-15T20:22:25",
            "type": "Regular",
            "label": "4th frame",
            "start": "2024-06-15T19:59:31",
            "awayTeamScore": 2,
            "homeTeamScore": 2,
            "awayTeamPeriodScore": 78,
            "homeTeamPeriodScore": 47
          }
        ],
        "finished": true,
        "awayTeamScore": 2,
        "currentPeriod": 4,
        "currentStatus": "Completed",
        "homeTeamScore": 2,
        "collectionStatus": "CollectionCompleted",
        "currentClockTime": "22:53",
        "currentClockState": "stopped",
        "isHomeTeamInPossesion": true
      },
      "sport": "Snooker",
      "fixtureDeleted": false
    }
  ],
  "pageable": {
    "pageNumber": 0,
    "pageSize": 20,
    "sort": {
      "empty": false,
      "unsorted": false,
      "sorted": true
    },
    "offset": 0,
    "paged": true,
    "unpaged": false
  },
  "last": false,
  "totalPages": 4,
  "totalElements": 72,
  "size": 20,
  "number": 0,
  "sort": {
    "empty": false,
    "unsorted": false,
    "sorted": true
  },
  "first": true,
  "numberOfElements": 20,
  "empty": false
}

400: Bad Request

{
    Request is missing required HTTP header 'Accept'
}

401: Unauthorized

{
    The supplied authentication is invalid
}

Get fixture

GET https://dde-api.data.imgarena.com/snooker/fixtures/{fixtureId}

Path Parameters

Name	Type	Description
fixtureId*	UUID	Unique id of a requested fixture.

200: OK

```json
{
    "id": "b003a95a-f2ab-4571-a1db-ff2b967939fb",
    "name": "Dominic Dale v Ben Woollaston",
    "status": "Completed",
    "collectionStatus": "CollectionCompleted",
    "type": "Official",
    "coverageLevel": "In Venue",
    "startDateUTC": "2024-06-15T19:00:00",
    "teams": [
        {
            "id": "86fd8e51-3964-497c-97c3-729cef44b1f0",
            "name": "Dominic Dale",
            "club": {
                "id": "0d44f12d-b671-4c9e-a096-9ce51e93b0ce",
                "name": "Dominic Dale (DAL001)"
            },
            "category": {
                "id": 34,
                "name": "Unknown"
            },
            "homeTeam": true,
            "shortCode": "DAL1"
        },
        {
            "id": "8ad4ff3f-9f92-44ba-a884-6c8a8e0dcf08",
            "name": "Ben Woollaston",
            "club": {
                "id": "cda9bbbe-61c4-4028-9988-dabc15fdbf96",
                "name": "Ben Woollaston (WOO008)"
            },
            "category": {
                "id": 34,
                "name": "Unknown"
            },
            "homeTeam": false,
            "shortCode": "WOO8"
        }
    ],
    "stage": {
        "id": "274d91a4-4f9a-44d0-b62e-0195f0dbe6c3",
        "name": "Main",
        "season": {
            "id": "a441737a-dd31-4b0b-9190-3e89f5976a87",
            "name": "2024/2025",
            "startDateUTC": "2024-06-03T12:00:00",
            "endDateUTC": "2025-05-31T12:00:00",
            "competition": {
                "id": "8286b57d-e365-4ea0-abaf-9e4339855f8b",
                "name": "BetVictor Championship League Snooker 2024 (Stage One/WK1)",
                "type": "Official",
                "category": {
                    "id": 34,
                    "name": "Unknown"
                },
                "location": {
                    "name": "Leicester",
                    "country": {
                        "name": "England"
                    },
                    "continent": {
                        "name": "Europe"
                    }
                },
                "commentCount": 0
            },
            "sport": "Snooker"
        },
        "startDateUTC": "2024-06-10T12:00:00",
        "endDateUTC": "2024-06-15T12:00:00"
    },
    "round": {
        "id": "80219180-8ff7-4af5-abe4-5e8aff6c40d3",
        "name": "Stage One/WK1",
        "stageId": "274d91a4-4f9a-44d0-b62e-0195f0dbe6c3",
        "startDateUTC": "2024-06-10T12:00:00",
        "endDateUTC": "2024-06-10T12:00:00"
    },
    "venue": {
        "id": "9dfc5c0a-3399-42ad-9cf4-35de76b069b5",
        "name": "Mattioli Arena",
        "location": {
            "name": "Leicester",
            "country": {
                "name": "England"
            },
            "continent": {
                "name": "Europe"
            }
        }
    },
    "subVenue": {
        "id": "1fc8ba73-70a1-4087-a6f9-4469563a3959",
        "name": "TABLE 1",
        "venue": {
            "id": "9dfc5c0a-3399-42ad-9cf4-35de76b069b5",
            "name": "Mattioli Arena",
            "location": {
                "name": "Leicester",
                "country": {
                    "name": "England"
                },
                "continent": {
                    "name": "Europe"
                }
            }
        }
    },
    "fixtureSummary": {
        "isTied": false,
        "periods": [
            {
                "id": 1,
                "end": "2024-06-15T19:15:47",
                "type": "Regular",
                "label": "1st frame",
                "start": "2024-06-15T19:05:01",
                "awayTeamScore": 0,
                "homeTeamScore": 1,
                "awayTeamPeriodScore": 3,
                "homeTeamPeriodScore": 66
            },
            {
                "id": 2,
                "end": "2024-06-15T19:31:09",
                "type": "Regular",
                "label": "2nd frame",
                "start": "2024-06-15T19:18:07",
                "awayTeamScore": 1,
                "homeTeamScore": 1,
                "awayTeamPeriodScore": 78,
                "homeTeamPeriodScore": 0
            },
            {
                "id": 3,
                "end": "2024-06-15T19:48:46",
                "type": "Regular",
                "label": "3rd frame",
                "start": "2024-06-15T19:33:24",
                "awayTeamScore": 2,
                "homeTeamScore": 1,
                "awayTeamPeriodScore": 71,
                "homeTeamPeriodScore": 2
            },
            {
                "id": 4,
                "end": "2024-06-15T20:07:35",
                "type": "Regular",
                "label": "4th frame",
                "start": "2024-06-15T19:51:44",
                "awayTeamScore": 3,
                "homeTeamScore": 1,
                "awayTeamPeriodScore": 75,
                "homeTeamPeriodScore": 1
            }
        ],
        "finished": true,
        "awayTeamScore": 3,
        "currentPeriod": 4,
        "currentStatus": "Completed",
        "homeTeamScore": 1,
        "collectionStatus": "CollectionCompleted",
        "currentClockTime": "15:51",
        "currentClockState": "stopped",
        "isHomeTeamInPossesion": true
    },
    "sport": "Snooker",
    "fixtureDeleted": false
}
```

400: Bad Request

{
    Request is missing required HTTP header 'Accept'
}

401: Unauthorized

{
    The supplied authentication is invalid
}

Response fields

fixture Fixtures []	The requested list of fixtures or a single fixture.

Efficient Polling

Although not real-time, API polling involves the repetitive transmission of client requests to an endpoint for the purpose of identifying changes in information. To maintain optimal performance for all customers, our API implements rate limits.We recommend the following frequency for your REST requests to ensure that you have the most up-to-date information at all times.

Live fixtures

Every 30 seconds

Live upcoming fixtures

Every 60 seconds

All fixtures

Every 24 hours

Pagination

Please find the following link to the pagination page.

We kindly request your thorough perusal of this section in order to familiarize yourself with forthcoming alterations scheduled for implementation on the 31st of July, 2023.

These modifications, primarily encompassing the introduction of supplementary parameters, are anticipated to be of a straightforward nature and aim to enhance the query efficiency of our Fixtures API, thereby affording you considerable advantages.