# Events API
{% hint style="info" %}
The infrastructure is cloud-based, therefore the IP address behind our hostname will change over time without prior notice. If your network rules require any sort of whitelisting then we suggest using our hostname for dynamic address resolution.
{% endhint %}
## Events
`GET` `https://api.livestreaming.srarena.io/api/v2/streaming/events` (was: `https://api.livestreaming.imgarena.com/api/v2/streaming/events`)
The Events API will allow you to list all your available live video streams once they have been booked. Please note that this API will only return future events, along with events that are currently live.
#### Query Parameters
| Name | Type | Description |
| --------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| operatorId | integer | Your company's identifier. This is provided to you by the Integrations team. |
| auth | string | The API token for this request. Please see the chapter "Authentication" for more information on how to generate the token. |
| timestamp | integer | The timestamp linked to the API token for this request. The timestamp value is the number of milliseconds since the Unix epoch, i.e the number of milliseconds since midnight (UTC) on January 1st, 1970. |
| page.size | integer | The maximum size of the result set returned by the API. Default value is 500 if not used. This parameter is used only if “restrictions” parameter was specified, ignored otherwise. The maximum value is 500 and a "400 Bad Request" response will be returned if a request is attempted with a greater value than 500. |
| page.page | integer | The page number of the request, used in conjunction with page.size. This parameter is used only if “restrictions” parameter was specified, ignored otherwise. |
| format | string | Can be "xml" or "json". Default is JSON. |
| live | string | If this is set to "true", this end point will only return events that are currently live on the platform. |
| imgDataID | string | If this is set to "true", this endpoint will return a correlating external ID from the IMG DDE, where applicable. |
| restrictions | string | Can be “whitelist” or “blacklist”. Will return a list of whitelisted or blacklisted country codes per event. Note, if the page.size is greater than 500, an error will be thrown. |
| subRestrictions | string | Can be “whitelist” or “blacklist”. Will return a list of whitelisted or blacklisted country codes per event and, if applicable, will also return a list of ISO 3166-2 country codes detailing whitelisted or blacklisted restrictions at a state level in the USA (e.g. US-NY). Note, if the page.size is greater than 500, an error will be thrown. |
{% tabs %}
{% tab title="200 A successful request to the events API will return you all upcoming and live events that you have booked. If you have no events booked, the response will be an empty array." %}
{% tabs %}
{% tab title="No Query Param" %}
```javascript
{
"id": 140027,
"title": "[13] Peter Polansky (CAN) vs Hugo Grenier (FRA)",
"tournament": {
"id": 2636,
"name": "Bangkok Open 2020",
"property": {
"id": 6,
"name": "ATP Challenger Tour",
"sport": {
"id": 5,
"name": "Tennis"
}
}
},
"updatedAt": "2020-01-22T22:40:56+0000",
"startDate": "2020-01-23T03:00:00+0000",
"endDate": "2020-01-24T03:00:00+0000"
}
```
{% endtab %}
{% tab title="imgDataId" %}
```javascript
{
"id": 140026,
"title": "Treat Huey (PHI) / Nathaniel Lammons (USA) vs Mao-Xin Gong (CHN) / Ze Zhang (CHN)",
"tournament": {
"id": 2636,
"name": "Bangkok Open 2020",
"property": {
"id": 6,
"name": "ATP Challenger Tour",
"sport": {
"id": 5,
"name": "Tennis"
}
}
},
"updatedAt": "2020-01-22T22:40:56+0000",
"startDate": "2020-01-23T03:00:00+0000",
"endDate": "2020-01-24T03:00:00+0000",
"imgdataID": "2020-7880-MD005"
}
```
{% endtab %}
{% tab title="restrictions" %}
```javascript
{
"id": 140026,
"title": "Treat Huey (PHI) / Nathaniel Lammons (USA) vs Mao-Xin Gong (CHN) / Ze Zhang (CHN)",
"tournament": {
"id": 2636,
"name": "Bangkok Open 2020",
"property": {
"id": 6,
"name": "ATP Challenger Tour",
"sport": {
"id": 5,
"name": "Tennis"
}
}
},
"restrictionRequest": "blacklist",
"countryList": [
"SD"
],
"updatedAt": "2020-01-22T22:40:56+0000",
"startDate": "2020-01-23T03:00:00+0000",
"endDate": "2020-01-24T03:00:00+0000"
}
```
{% endtab %}
{% tab title="subRestrictions" %}
```javascript
{
"id": 140026,
"title": "Treat Huey (PHI) / Nathaniel Lammons (USA) vs Mao-Xin Gong (CHN) / Ze Zhang (CHN)",
"tournament": {
"id": 2636,
"name": "Bangkok Open 2020",
"property": {
"id": 6,
"name": "ATP Challenger Tour",
"sport": {
"id": 5,
"name": "Tennis"
}
}
},
"restrictionRequest": "whitelist",
"countryList": [
"LT",
"PL",
"PM",
"PN"
],
"subDivisionList": [
"US-FL",
"US-NV",
"US-SC",
"US-WA",
"US-KY",
"US-GU",
"US-CO",
"US-SD",
],
"updatedAt": "2020-01-22T22:40:56+0000",
"startDate": "2020-01-23T03:00:00+0000",
"endDate": "2020-01-24T03:00:00+0000"
}
```
{% endtab %}
{% tab title="XML" %}
```markup
-
140026
Treat Huey (PHI) / Nathaniel Lammons (USA) vs Mao-Xin Gong (CHN) / Ze Zhang (CHN)
2636
Bangkok Open 2020
6
ATP Challenger Tour
5
Tennis
whitelist
NG
NI
NL
NO
NP
NR
NU
NZ
OM
PA
PE
PF
PG
PH
PK
PL
PM
PN
US-FL
US-NV
US-SC
US-VA
US-MD
US-IA
US-ME
US-UM
US-MA
US-UT
US-ID
US-MI
2020-01-22T22:40:56+0000
2020-01-23T03:00:00+0000
2020-01-24T03:00:00+0000
```
{% endtab %}
{% endtabs %}
{% endtab %}
{% tab title="400 A 400 will be returned if there are any invalid or missing required parameters." %}
```javascript
{
"statusCode": 401,
"statusText": "Unauthorized",
"message": null
}
```
{% endtab %}
{% tab title="401 For more information on why a 401 may be returned, please see the " %}
```javascript
{
"statusCode": 401,
"statusText": "Unauthorized",
"message": null
}
```
{% endtab %}
{% tab title="500 If you see a 503 response from this API please contact our support team." %}
```javascript
{
"statusCode": 500,
"statusText": "Internal Server Error",
"message": null
}
```
{% endtab %}
{% tab title="503 If you see a 503 response from this API please contact our support team." %}
```javascript
{
"statusCode": 503,
"statusText": "Service Unavailable",
"message": null
}
```
{% endtab %}
{% endtabs %}
{% hint style="success" %}
The Events API will never throw a 403 Forbidden response, because we never geo-restrict this endpoint - you will be able to call it from whatever location your servers are situated in.
{% endhint %}
{% hint style="info" %}
We recommend customers call the events API with the "live" parameter set to true periodically (e.g. every 30 seconds). Customers can then use this response to work out which events are live, and therefore which events they should call the Streaming API for to get event playback URLs.
If an event shows up in the response, you should start calling the streaming API to get a playback URL for that event. If an event is removed from the response, it is no longer live and you should no longer call the streaming API for that event.
{% endhint %}
## Response Model Table
| **Field Name** | **Type** | **Description** |
| ---------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **id** | int | The id of the event |
| **title** | string | The name of the event |
| **tournament** | Object | This will include the ID and Name of the Tournament |
| **property** | Object | This will include the ID and Name of the Property |
| **sport** | Object | This will include the ID and Name of the Sport |
| **updatedAt** | datetime | This is when the event was updated (In UTC timezone) |
| **startDate** | datetime | The start date of the tournament (In UTC timezone) |
| **endDate** | datetime | This is the end of the event (In UTC timezone) |
| **imgDataID** | string | This will show the corresponding ID of the event on the DDE (where applicable) |
| **restrictionRequest** | string | either "whitelist" or "blacklist", depending on the request made |
| **countryList** | Array | An array of countries that are either white or blacklisted, depending on the request made |
| **subDivisionList** | Array | An array of US States that are either white or blacklisted, depending on the request made. States are returned as ISO 3166-2 country codes (e.g. US-NY for the State of New York). |
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.sportradar.com/streaming-integration/apis/events-api.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.