# 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/soccer/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`, `standardStre`am & `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 | {% tabs %} {% tab title="400: Bad Request " %} ```json { Request is missing required HTTP header 'Accept' } ``` {% endtab %} {% tab title="401: Unauthorized " %} ```json { The supplied authentication is invalid } ``` {% endtab %} {% tab title="200: OK " %} ```json { "content": [ { "id": "a64ea10b-7d0e-4584-a1c6-5fee80478116", "name": "FC Admira Wacker Mödling v SV Horn", "status": "Scheduled", "collectionStatus": "CollectionScheduled", "type": "Official", "coverageLevel": "In Venue", "startDateUTC": "2025-05-25T15:00:00", "teams": [ { "id": "cd9a004d-15a8-4689-8ce1-c93a520fabd5", "name": "FC Admira Wacker Mödling", "club": { "id": "36ff15ed-4d6b-45ce-835a-d67b666ccf3e", "name": "FC ADMIRA WACKER MÖDLING" }, "category": { "id": 1, "name": "Men" }, "homeTeam": true }, { "id": "7551a365-659b-434b-8d0e-f27deecc4358", "name": "SV Horn", "club": { "id": "b3c0dd7a-cb5e-41bc-94a4-fb8de690fa02", "name": "SV HORN" }, "category": { "id": 1, "name": "Men" }, "homeTeam": false } ], "stage": { "id": "c209807f-8965-4a9f-8f51-1211d22af841", "name": "Regular Round", "season": { "id": "0cc91432-284e-40f6-9228-1b61a74aec1f", "name": "2024/2025", "startDateUTC": "2024-08-02T12:00:00", "endDateUTC": "2025-05-25T12:00:00", "competition": { "id": "afd67a8c-3aee-4e4e-8818-b8bc404e9642", "name": "Austria 2 Liga", "type": "Official", "category": { "id": 1, "name": "Men" }, "tour": { "id": 67, "name": "European Leagues" }, "location": { "name": "Austria", "country": {}, "continent": { "name": "Europe" } }, "latestComment": "Match rescheduled\n\nSoccer - Austria 2 Liga - 2024/2025 - Floridsdorfer AC v SKN St. Pölten - ID: (3cf8d21b-79e5-4ba4-b405-6fd5c2ac1b7a)\n\nPrevious Fixture Start Date and Time:\n03/08/2024, 15:00 UTC\nNew Fixture Start Date and Time:\n04/08/2024, 8:30 UTC", "commentCount": 73 }, "sport": "Soccer" }, "startDateUTC": "2024-08-02T12:00:00", "endDateUTC": "2025-05-25T12:00:00" }, "venue": { "id": "f0ea7c86-2273-4e50-b921-6fffe0d9d51c", "name": "BSFZ-Arena", "location": { "name": "Maria Enzersdorf", "country": { "name": "Austria" }, "continent": { "name": "Europe" } } }, "sport": "Soccer", "fixtureDeleted": false }, { "id": "4edebec3-b5e8-4e9c-9209-ac43f25f373a", "name": "Floridsdorfer AC v SK Sturm Graz II", "status": "Scheduled", "collectionStatus": "CollectionScheduled", "type": "Official", "coverageLevel": "In Venue", "startDateUTC": "2025-05-25T15:00:00", "teams": [ { "id": "b5d8abb4-b5ff-4d8e-bbca-2776c58dc246", "name": "Floridsdorfer AC", "club": { "id": "025c8d3f-62b2-4f3f-ab17-f7f5db837d25", "name": "FLORIDSDORFER AC" }, "category": { "id": 1, "name": "Men" }, "homeTeam": true }, { "id": "b6e6f92a-3585-49ff-8a16-da14a96b0aa8", "name": "SK Sturm Graz II", "club": { "id": "b6dafa0c-b74a-4305-b99b-b625a621a44d", "name": "SK STURM GRAZ" }, "category": { "id": 1, "name": "Men" }, "homeTeam": false } ], "stage": { "id": "c209807f-8965-4a9f-8f51-1211d22af841", "name": "Regular Round", "season": { "id": "0cc91432-284e-40f6-9228-1b61a74aec1f", "name": "2024/2025", "startDateUTC": "2024-08-02T12:00:00", "endDateUTC": "2025-05-25T12:00:00", "competition": { "id": "afd67a8c-3aee-4e4e-8818-b8bc404e9642", "name": "Austria 2 Liga", "type": "Official", "category": { "id": 1, "name": "Men" }, "tour": { "id": 67, "name": "European Leagues" }, "location": { "name": "Austria", "country": {}, "continent": { "name": "Europe" } }, "latestComment": "Match rescheduled\n\nSoccer - Austria 2 Liga - 2024/2025 - Floridsdorfer AC v SKN St. Pölten - ID: (3cf8d21b-79e5-4ba4-b405-6fd5c2ac1b7a)\n\nPrevious Fixture Start Date and Time:\n03/08/2024, 15:00 UTC\nNew Fixture Start Date and Time:\n04/08/2024, 8:30 UTC", "commentCount": 73 }, "sport": "Soccer" }, "startDateUTC": "2024-08-02T12:00:00", "endDateUTC": "2025-05-25T12:00:00" }, "venue": { "id": "376cbea9-7442-4a26-b178-9c189a9b09e2", "name": "FAC Platz", "location": { "name": "Wien", "country": { "name": "Austria" }, "continent": { "name": "Europe" } } }, "sport": "Soccer", "fixtureDeleted": false }, ], "pageable": { "pageNumber": 0, "pageSize": 20, "sort": { "empty": false, "unsorted": false, "sorted": true }, "offset": 0, "paged": true, "unpaged": false }, "totalPages": 2002, "totalElements": 40032, "last": false, "size": 20, "number": 0, "sort": { "empty": false, "unsorted": false, "sorted": true }, "numberOfElements": 20, "first": true, "empty": false } ``` {% endtab %} {% endtabs %} ## List season fixtures `GET` `https://dde-api.data.imgarena.com/soccer/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`, `standardStre`am & `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.

| {% tabs %} {% tab title="200: OK " %} ```json [ { "id": "a4ce43a2-fcab-42d3-a087-7f053bc68930", "name": "Spartak Pleven v Dunav Ruse", "status": "Completed", "collectionStatus": "PostMatchChecked", "type": "Official", "coverageLevel": "In Venue", "startDateUTC": "2023-06-04T15:00:00", "teams": [ { "id": "78310f66-a8dd-4cee-a49c-3bc3e33e5323", "name": "Spartak Pleven", "club": { "id": "b4838ade-4cde-47b1-be47-254e27d11ecd", "name": "SPARTAK PLEVEN" }, "category": { "id": 1, "name": "Men" }, "homeTeam": true }, { "id": "411faad1-4ab5-4946-971e-f5cc1e2e8764", "name": "Dunav Ruse", "club": { "id": "03d7f6b2-2567-47ff-95bc-4a64e90d1199", "name": "DUNAV RUSE" }, "category": { "id": 1, "name": "Men" }, "homeTeam": false } ], "stage": { "id": "b3696820-4a6a-40b6-9a7e-8520b933c7fa", "name": "Regular Round", "season": { "id": "44050b42-dd13-40c5-a76d-88ed60c9e506", "name": "2022/2023", "startDateUTC": "2022-07-14T12:00:00", "endDateUTC": "2023-06-11T12:00:00", "competition": { "id": "d837ffc2-855c-4739-9a66-055ad97748e6", "name": "Bulgaria 2 Liga", "type": "Official", "category": { "id": 1, "name": "Men" }, "tour": { "id": 70, "name": "BFU" }, "location": { "name": "Bulgaria", "country": {}, "continent": { "name": "Europe" } }, "latestComment": "Collection status change - Collecting Live - REASONING: Connectivity issue has been resolved. Soccer - Bulgaria 2 Liga - 2024/2025 - Football Club Pirin JSCo v Dobrudzha Dobrich - ID: 26bf0293-e029-41a5-8022-d0f0681c0940. Fixture Start Date and Time: 2024-11-22 12:15:00 UTC", "commentCount": 326 }, "sport": "Soccer" }, "startDateUTC": "2022-07-14T12:00:00", "endDateUTC": "2023-06-10T12:00:00" }, "venue": { "id": "2f55c70c-b661-4ac5-aa3d-31e7f59fbaca", "name": "Pleven Stadium", "location": { "name": "Pleven", "country": { "name": "Bulgaria" }, "continent": { "name": "Europe" } } }, "fixtureSummary": { "isTied": true, "periods": [ { "id": 1, "end": "2023-06-04T15:47:20", "type": "Regular", "label": "1st half", "start": "2023-06-04T15:00:53", "awayTeamScore": 0, "homeTeamScore": 0, "awayTeamPeriodScore": 0, "homeTeamPeriodScore": 0 }, { "id": 2, "end": "2023-06-04T16:51:31", "type": "Regular", "label": "2nd half", "start": "2023-06-04T16:03:10", "awayTeamScore": 0, "homeTeamScore": 0, "awayTeamPeriodScore": 0, "homeTeamPeriodScore": 0 } ], "finished": true, "awayTeamScore": 0, "currentPeriod": 2, "currentStatus": "Completed", "homeTeamScore": 0, "collectionStatus": "PostMatchChecked", "currentClockTime": "45:00", "isHomeTeamInPossesion": true }, "sport": "Soccer", "fixtureDeleted": false, "updateCount": 0 }, { "id": "db914dee-a47d-449e-8991-29ee127fb14e", "name": "Dunav Ruse v Strumska Slava", "status": "Completed", "collectionStatus": "PostMatchChecked", "type": "Official", "coverageLevel": "In Venue", "startDateUTC": "2023-05-30T15:00:00", "teams": [ { "id": "411faad1-4ab5-4946-971e-f5cc1e2e8764", "name": "Dunav Ruse", "club": { "id": "03d7f6b2-2567-47ff-95bc-4a64e90d1199", "name": "DUNAV RUSE" }, "category": { "id": 1, "name": "Men" }, "homeTeam": true }, { "id": "6ecb51c8-f4c9-4756-84a2-fe961c79d941", "name": "Strumska Slava", "club": { "id": "41661738-f6d3-43ee-80d9-5d8d04b542b8", "name": "STRUMSKA SLAVA" }, "category": { "id": 1, "name": "Men" }, "homeTeam": false } ], "stage": { "id": "b3696820-4a6a-40b6-9a7e-8520b933c7fa", "name": "Regular Round", "season": { "id": "44050b42-dd13-40c5-a76d-88ed60c9e506", "name": "2022/2023", "startDateUTC": "2022-07-14T12:00:00", "endDateUTC": "2023-06-11T12:00:00", "competition": { "id": "d837ffc2-855c-4739-9a66-055ad97748e6", "name": "Bulgaria 2 Liga", "type": "Official", "category": { "id": 1, "name": "Men" }, "tour": { "id": 70, "name": "BFU" }, "location": { "name": "Bulgaria", "country": {}, "continent": { "name": "Europe" } }, "latestComment": "Collection status change - Collecting Live - REASONING: Connectivity issue has been resolved. Soccer - Bulgaria 2 Liga - 2024/2025 - Football Club Pirin JSCo v Dobrudzha Dobrich - ID: 26bf0293-e029-41a5-8022-d0f0681c0940. Fixture Start Date and Time: 2024-11-22 12:15:00 UTC", "commentCount": 326 }, "sport": "Soccer" }, "startDateUTC": "2022-07-14T12:00:00", "endDateUTC": "2023-06-10T12:00:00" }, "venue": { "id": "6fca730b-8400-41cd-94b5-29dc9205d926", "name": "Gradski", "location": { "name": "Ruse", "country": { "name": "Bulgaria" }, "continent": { "name": "Europe" } } }, "fixtureSummary": { "isTied": false, "periods": [ { "id": 1, "end": "2023-05-30T15:48:16", "type": "Regular", "label": "1st half", "start": "2023-05-30T15:02:08", "awayTeamScore": 1, "homeTeamScore": 0, "awayTeamPeriodScore": 1, "homeTeamPeriodScore": 0 }, { "id": 2, "end": "2023-05-30T16:55:13", "type": "Regular", "label": "2nd half", "start": "2023-05-30T16:04:00", "awayTeamScore": 1, "homeTeamScore": 2, "awayTeamPeriodScore": 0, "homeTeamPeriodScore": 2 } ], "finished": true, "awayTeamScore": 1, "currentPeriod": 2, "currentStatus": "Completed", "homeTeamScore": 2, "collectionStatus": "PostMatchChecked", "currentClockTime": "45:00", "isHomeTeamInPossesion": true }, "sport": "Soccer", "fixtureDeleted": false, "updateCount": 0 } ``` {% endtab %} {% tab title="400: Bad Request " %} ```json { Request is missing required HTTP header 'Accept' } ``` {% endtab %} {% tab title="401: Unauthorized " %} ```json { The supplied authentication is invalid } ``` {% endtab %} {% endtabs %} ## Get fixture `GET` `https://dde-api.data.imgarena.com/soccer/fixtures/{fixtureId}` #### Path Parameters | Name | Type | Description | | ------------------------------------------- | ---- | --------------------------------- | | fixtureId\* | UUID | Unique id of a requested fixture. | {% tabs %} {% tab title="200: OK " %} ```json { "id": "a4ce43a2-fcab-42d3-a087-7f053bc68930", "name": "Spartak Pleven v Dunav Ruse", "status": "Completed", "collectionStatus": "PostMatchChecked", "type": "Official", "coverageLevel": "In Venue", "startDateUTC": "2023-06-04T15:00:00", "teams": [ { "id": "78310f66-a8dd-4cee-a49c-3bc3e33e5323", "name": "Spartak Pleven", "club": { "id": "b4838ade-4cde-47b1-be47-254e27d11ecd", "name": "SPARTAK PLEVEN" }, "category": { "id": 1, "name": "Men" }, "homeTeam": true }, { "id": "411faad1-4ab5-4946-971e-f5cc1e2e8764", "name": "Dunav Ruse", "club": { "id": "03d7f6b2-2567-47ff-95bc-4a64e90d1199", "name": "DUNAV RUSE" }, "category": { "id": 1, "name": "Men" }, "homeTeam": false } ], "stage": { "id": "b3696820-4a6a-40b6-9a7e-8520b933c7fa", "name": "Regular Round", "season": { "id": "44050b42-dd13-40c5-a76d-88ed60c9e506", "name": "2022/2023", "startDateUTC": "2022-07-14T12:00:00", "endDateUTC": "2023-06-11T12:00:00", "competition": { "id": "d837ffc2-855c-4739-9a66-055ad97748e6", "name": "Bulgaria 2 Liga", "type": "Official", "category": { "id": 1, "name": "Men" }, "tour": { "id": 70, "name": "BFU" }, "location": { "name": "Bulgaria", "country": {}, "continent": { "name": "Europe" } }, "latestComment": "Collection status change - Collecting Live - REASONING: Connectivity issue has been resolved. Soccer - Bulgaria 2 Liga - 2024/2025 - Football Club Pirin JSCo v Dobrudzha Dobrich - ID: 26bf0293-e029-41a5-8022-d0f0681c0940. Fixture Start Date and Time: 2024-11-22 12:15:00 UTC", "commentCount": 326 }, "sport": "Soccer" }, "startDateUTC": "2022-07-14T12:00:00", "endDateUTC": "2023-06-10T12:00:00" }, "venue": { "id": "2f55c70c-b661-4ac5-aa3d-31e7f59fbaca", "name": "Pleven Stadium", "location": { "name": "Pleven", "country": { "name": "Bulgaria" }, "continent": { "name": "Europe" } } }, "fixtureSummary": { "isTied": true, "periods": [ { "id": 1, "end": "2023-06-04T15:47:20", "type": "Regular", "label": "1st half", "start": "2023-06-04T15:00:53", "awayTeamScore": 0, "homeTeamScore": 0, "awayTeamPeriodScore": 0, "homeTeamPeriodScore": 0 }, { "id": 2, "end": "2023-06-04T16:51:31", "type": "Regular", "label": "2nd half", "start": "2023-06-04T16:03:10", "awayTeamScore": 0, "homeTeamScore": 0, "awayTeamPeriodScore": 0, "homeTeamPeriodScore": 0 } ], "finished": true, "awayTeamScore": 0, "currentPeriod": 2, "currentStatus": "Completed", "homeTeamScore": 0, "collectionStatus": "PostMatchChecked", "currentClockTime": "45:00", "isHomeTeamInPossesion": true }, "sport": "Soccer", "fixtureDeleted": false, "updateCount": 0 } ``` {% endtab %} {% tab title="400: Bad Request " %} ```json { Request is missing required HTTP header 'Accept' } ``` {% endtab %} {% tab title="401: Unauthorized " %} ```json { The supplied authentication is invalid } ``` {% endtab %} {% endtabs %} ### Response fields
PropertyDescription
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.
APIRecommendation
Live fixturesEvery 30 seconds
Live upcoming fixturesEvery 60 seconds
All fixturesEvery 24 hours
## Deleted fixtures In some cases, fixtures may be deleted. To manage this, each fixture includes a "fixtureDeleted" flag. By default, this flag is set to "false." If the flag is set to "true," it indicates that the fixture has been deleted and should be disregarded. ## Pagination Please find the following link to the [pagination](https://docs.sportradar.com/soccer/readme/pagination) page. {% hint style="warning" %} 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**. {% endhint %} 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. ## ExternalProvider To assist clients in correlating IMG Arena fixture IDs with those from external feed providers, such as OpenBet fixture IDs, you can specify the desired provider by passing "externalProvider" as a parameter. The response will include the fixture ID from the external provider. #### Path Parameters | Name | Type | Description | | ----------------------------------------- | ------ | --------------------------------------- | | openbet\* | string | Return OpenBet fixture Ids | | MLS\_STS | string | Return MLS provider tracking fixture Id | To access soccer fixtures data from the Data IMG Arena API with an external provider filter set to OpenBet, use the following URL: i,e: ``` https://dde-api.data.imgarena.com/soccer/fixtures?externalProvider=openbet ``` Sample response: ```` { "id": "fc3a9cf1-b868-4294-b988-d9b05c113caa", "externalId": "cfs:event:2686832", "name": "Manchester United v 1.FC Heidenheim 1846asdasdasda", "status": "Scheduled", "collectionStatus": "CollectionScheduled", "type": "Official", "coverageLevel": "In Venue", "startDateUTC": "2020-09-15T13:15:00", "teams": [ { "id": "ef323f25-8f76-44d1-a320-58d9aae685ee", "name": "Manchester United", "club": { "id": "8ee84d49-23b4-4554-8ac2-9b215a420697", "name": "Manchester United" }, "category": { "id": 1, "name": "Men" }, "homeTeam": true, "shortCode": "MUN" }, { "id": "803e7e7f-565d-4a60-a390-7e825635bac2", "name": "1.FC Heidenheim 1846", "club": { "id": "a61be76b-afd9-49b0-8189-b05d82ef9ba0", "name": "1.FC HEIDENHEIM 1846" }, "category": { "id": 1, "name": "Men" }, "homeTeam": false } ], "stage": { "id": "e104e6c6-bead-45d3-813d-4c6a739624e5", "name": "Qualificatio", "season": { "id": "6b89fcbb-cd85-4703-9b60-7c3285df379f", "name": "UEFA Europa League 2020/21", "startDateUTC": "2020-09-01T12:00:00", "endDateUTC": "2021-05-26T12:00:00", "competition": { "id": "632e0458-e5ac-4e24-83f6-0a599ede5677", "name": "UEFA Europa League", "type": "Official", "category": { "id": 1, "name": "Men" }, "location": { "name": "Europe", "country": {}, "continent": {} }, "commentCount": 0 } }, "startDateUTC": "2020-09-29T12:00:00", "endDateUTC": "2020-10-31T12:00:00" }, "venue": { "id": "12bdc62d-5407-4eb8-bcd9-0304ba170384", "name": "Data", "location": { "name": "World" } } } ``` ````