# Fixtures

The Fixtures API lets developers list and manage season fixtures. This is a gateway into the Actions API.

Applications don't need any input to list all fixtures, however information can be filtered by start date and end date. The result is useful for obtaining competiton Ids, season Ids, and stage Ids.

## Endpoints

## List fixtures

<mark style="color:blue;">`GET`</mark> `https://dde-api.data.imgarena.com/{sport}/fixtures`

Retrieves a list of seasons for a specific sport.

#### Path Parameters

| Name                                    | Type   | Description                                                                                            |
| --------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------ |
| sport<mark style="color:red;">\*</mark> | String | A unique name for the requested sport. **Example**: `basketball`, `soccer`, `v2/volleyball`, `snooker` |
|                                         | String |                                                                                                        |

#### Query Parameters

| Name          | Type    | Description                                                                                                                             |
| ------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| subscribed    | Boolean | Lists the fixtures for which a user is licensed. **Example:** `true`, `false`                                                           |
| 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    | DAllows 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  |                                                                                                                                         |

#### Headers

| Name                                            | Type   | Description                                      |
| ----------------------------------------------- | ------ | ------------------------------------------------ |
| Accept<mark style="color:red;">\*</mark>        | String | application/vnd.imggaming.dde.api+json;version=1 |
| Authorization<mark style="color:red;">\*</mark> | String | Bearer ACCESS\_TOKEN                             |
| Content-Type<mark style="color:red;">\*</mark>  | 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
{
        "id": "2ffbf044-db53-43ea-9898-a43868ca014d",
        "name": "BC Lietkabelis Panevezys v Jonava BC Cbet",
        "status": "Scheduled",
        "type": "Official",
        "coverageLevel": "In Venue",
        "startDateUTC": "2023-01-07T15:00:00",
        "teams": [
            {
                "id": "f14fd931-a113-4a0b-9c5c-532057c96301",
                "name": "Jonava BC Cbet",
                "club": {
                    "id": "b6c236e8-b9df-4a65-ae01-932864572b93",
                    "name": "JONAVA BC CBET"
                },
                "category": {
                    "id": 1,
                    "name": "Men"
                },
                "homeTeam": false
            },
            {
                "id": "b184558c-d9dd-4ada-898d-520b3d387622",
                "name": "BC Lietkabelis Panevezys",
                "club": {
                    "id": "bda8ed69-da63-434e-8b79-a20980f32c2e",
                    "name": "BC LIETKABELIS PANEVEZYS"
                },
                "category": {
                    "id": 1,
                    "name": "Men"
                },
                "homeTeam": true
            }
        ],
        "stage": {
            "id": "96afe2dd-58e7-435d-a9f9-999d64ec8b86",
            "name": "Regular round",
            "season": {
                "id": "7ac2140e-dd57-404a-bc3a-54d7fcd97343",
                "name": "Season 2022/2023",
                "startDateUTC": "2022-09-24T12:00:00",
                "endDateUTC": "2023-05-31T12:00:00",
                "competition": {
                    "id": "5c50bf20-7b5e-4d19-b2fe-aa1d20a042b2",
                    "name": "Lithuania LKL",
                    "category": {
                        "id": 1,
                        "name": "Men"
                    },
                    "tour": {
                        "id": 45,
                        "name": "Lithuanian Basketball Federation (LKF)"
                    },
                    "location": {
                        "name": "Lithuania",
                        "country": {},
                        "continent": {
                            "name": "Europe"
                        }
                    }
                }
            },
            "startDateUTC": "2022-09-24T12:00:00",
            "endDateUTC": "2023-05-31T12:00:00"
        },
        "venue": {
            "id": "7d30af55-89e2-4b50-a107-db133dcb3730",
            "name": "Cido Arena",
            "location": {
                "name": "Panevezys",
                "country": {
                    "name": "Lithuania"
                },
                "continent": {
                    "name": "Europe"
                }
            }
        }
    }
```

{% endtab %}
{% endtabs %}

## List season fixtures

<mark style="color:blue;">`GET`</mark> `https://dde-api.data.imgarena.com/{sport}/seasons/{seasonId}/fixtures`

#### Path Parameters

| Name                                       | Type   | Description                                                                                            |
| ------------------------------------------ | ------ | ------------------------------------------------------------------------------------------------------ |
| sport<mark style="color:red;">\*</mark>    | String | A unique name for the requested sport. **Example**: `basketball`, `soccer`, `v2/volleyball`, `snooker` |
| seasonId<mark style="color:red;">\*</mark> | UUID   | unique id of a requested season                                                                        |

#### Query Parameters

| Name       | Type    | Description                                                                                                                             |
| ---------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| subscribed | Boolean | Lists the fixtures for which a user is licensed. **Example:** `true`, `false`                                                           |
| 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`            |

{% tabs %}
{% tab title="200: OK " %}

```json
{
        "id": "ffc47dc5-61e1-44e9-add7-6088c415aa42",
        "name": "Hapoel Tel Aviv v Ironi Kiryat Ata",
        "status": "Completed",
        "type": "Official",
        "coverageLevel": "In Venue",
        "startDateUTC": "2022-09-19T17:00:00",
        "teams": [
            {
                "id": "114aa40d-6895-48b9-9bfe-0abecc9d10c9",
                "name": "Hapoel Tel Aviv",
                "club": {
                    "id": "3bf65514-d1b3-4768-8119-cee69b574734",
                    "name": "HAPOEL TEL AVIV"
                },
                "category": {
                    "id": 1,
                    "name": "Men"
                },
                "homeTeam": true
            },
            {
                "id": "d4407cea-1880-4afa-8aa6-9c58b2d583f4",
                "name": "Ironi Kiryat Ata",
                "club": {
                    "id": "da2da316-8876-4939-873b-d4ce5bff3688",
                    "name": "IRONI KIRYAT ATA"
                },
                "category": {
                    "id": 1,
                    "name": "Men"
                },
                "homeTeam": false
            }
        ],
        "stage": {
            "id": "7eb6159c-94bf-45bd-a52d-4143fdbe47d0",
            "name": "Regular round",
            "season": {
                "id": "c7e3e6b7-e24f-4e76-8247-6d4626d17935",
                "name": "Season 2022/2023",
                "startDateUTC": "2022-09-19T12:00:00",
                "endDateUTC": "2023-05-31T12:00:00",
                "competition": {
                    "id": "7d6aeba6-2599-4231-a0f9-fd218f38bced",
                    "name": "Israel League Cup",
                    "category": {
                        "id": 1,
                        "name": "Men"
                    },
                    "tour": {
                        "id": 37,
                        "name": "Israeli Basketball Association (IBBA)"
                    },
                    "location": {
                        "name": "Israel",
                        "country": {},
                        "continent": {
                            "name": "Asia"
                        }
                    }
                }
            },
            "startDateUTC": "2022-11-01T12:00:00",
            "endDateUTC": "2023-05-31T12:00:00"
        },
        "venue": {
            "id": "665e9df6-4587-41b4-9a75-085e56e8579b",
            "name": "Drive in Arena",
            "location": {
                "name": "Tel Aviv",
                "country": {
                    "name": "Israel"
                },
                "continent": {
                    "name": "Asia"
                }
            }
        }
    }
```

{% 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

<mark style="color:blue;">`GET`</mark> `https://dde-api.data.imgarena.com/{sport}/fixtures/{fixtureId}`

#### Path Parameters

| Name                                        | Type   | Description                                                                                            |
| ------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------ |
| sport<mark style="color:red;">\*</mark>     | String | A unique name for the requested sport. **Example**: `basketball`, `soccer`, `v2/volleyball`, `snooker` |
| fixtureId<mark style="color:red;">\*</mark> | UUID   | Unique id of a requested fixture.                                                                      |

{% tabs %}
{% tab title="200: OK " %}

```json
{
    "id": "ffc47dc5-61e1-44e9-add7-6088c415aa42",
    "name": "Hapoel Tel Aviv v Ironi Kiryat Ata",
    "status": "Completed",
    "type": "Official",
    "coverageLevel": "In Venue",
    "startDateUTC": "2022-09-19T17:00:00",
    "teams": [
        {
            "id": "114aa40d-6895-48b9-9bfe-0abecc9d10c9",
            "name": "Hapoel Tel Aviv",
            "club": {
                "id": "3bf65514-d1b3-4768-8119-cee69b574734",
                "name": "HAPOEL TEL AVIV"
            },
            "category": {
                "id": 1,
                "name": "Men"
            },
            "homeTeam": true
        },
        {
            "id": "d4407cea-1880-4afa-8aa6-9c58b2d583f4",
            "name": "Ironi Kiryat Ata",
            "club": {
                "id": "da2da316-8876-4939-873b-d4ce5bff3688",
                "name": "IRONI KIRYAT ATA"
            },
            "category": {
                "id": 1,
                "name": "Men"
            },
            "homeTeam": false
        }
    ],
    "stage": {
        "id": "7eb6159c-94bf-45bd-a52d-4143fdbe47d0",
        "name": "Regular round",
        "season": {
            "id": "c7e3e6b7-e24f-4e76-8247-6d4626d17935",
            "name": "Season 2022/2023",
            "startDateUTC": "2022-09-19T12:00:00",
            "endDateUTC": "2023-05-31T12:00:00",
            "competition": {
                "id": "7d6aeba6-2599-4231-a0f9-fd218f38bced",
                "name": "Israel League Cup",
                "category": {
                    "id": 1,
                    "name": "Men"
                },
                "tour": {
                    "id": 37,
                    "name": "Israeli Basketball Association (IBBA)"
                },
                "location": {
                    "name": "Israel",
                    "country": {},
                    "continent": {
                        "name": "Asia"
                    }
                }
            }
        },
        "startDateUTC": "2022-11-01T12:00:00",
        "endDateUTC": "2023-05-31T12:00:00"
    },
    "venue": {
        "id": "665e9df6-4587-41b4-9a75-085e56e8579b",
        "name": "Drive in Arena",
        "location": {
            "name": "Tel Aviv",
            "country": {
                "name": "Israel"
            },
            "continent": {
                "name": "Asia"
            }
        }
    }
}
```

{% 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

The requested list of seasons

### Fixture attributes

* *id* (`uuid`) - The FastPath-assigned ID of the fixture
* *name* (`string`) - Descriptive name of the fixture
* *startDateUTC* (`datetime`) - Start date of the fixture
* *status* (`string`) - Competition information within the season
* *type* (`string`) - Round of match within a competition
* *coverageLevel* (`string`) - Round of match within a competition
* [*teams*](#teams) (`Teams`) - Round of match within a competition
* [*stage*](#stage) (`Stage`) - Round of match within a competition
* [*venue*](#venue) (`Venue`) - Round of match within a competition

### Teams

* *id* (`uuid`) - The FastPath-assigned ID of the competition within the season
* *name* (`string`) - Name of the competition. Example: `Israel League Cup`
* [*club*](#club) (`Club`) - Competition category information
* [*category*](#category) (`Category`) - Competition category information
* *homeTeam* (`boolean`) - Venue information of the competition

#### Club

* name

### Stage

* *id* (`uuid`) -
* *name* (`string`) -
* [*season*](https://docs.sportradar.com/basketball-media/seasons#season-attributes) (`Season`) -
* *startDateUTC* (`datetime`) -
* *endDateUTC* (`datetime`) -
* *rounds* (`object`) -
* *groups* (`object`) -

### Category

* *id* (`integer`) - The FastPath-assigned ID of the competiton category
* *name* (`string`) - Name of the competition category. Example: `Men`, `Women`

### Venue

* *id* (`string`) - The FastPath-assigned id of the venue. Example: `665e9df6-4587-41b4-9a75-085e56e8579b`
* *name* (`string`) - Descriptive name of the venue. Example: `Drive in Arena`
* [*location*](#location) (`Location`) - Geographic location of the venue. Usually it is the city, country and continent. Example: `Tel Aviv`, `Israel`, `Asia`

### Location

* *name* (`string`) - Name of the venue. Example: `Tel Aviv`
* [*country*](#country) (`Country`) - List of countries where the fixture is played out. Example: `Israel`
* [*continent*](#continent) (`Continent`) - List of continents where the fixture is played out. Example: `Asia`

### Country

* *name* (`string`) - Name of the country where the fixture plays out

### Continent

* *name* (`string`) - Name of the continent where the fixture plays out

## Polling frequency

We recommend the following frequency for your REST requests to ensure that you have the most up-to-date information at all times - `once per 12 hours`