Introduction

The Sportradar AudioVisual API is an API used to integrate video streams from events covered by the AudioVisual unit of Sportradar into a web application or a mobile app.
This document describes how to integrate the API and is intended for developers.

Table of contents

New concepts compared to the Live Channel Online API

(only relevant for clients which integrated the Live Channel Online API)

The AudioVisual API is a completely new API. If you have already integrated the Live Channel Online API, we strongly recommend you to move to the new AudioVisual API in order to benefit from all of its new features and improvements. The AudioVisual API introduces new concepts in comparison to the Live Channel Online API, and it therefore requires a new integration. Below is a list of the main new concepts:

• New and simpler authentication mechanism: Bearer token instead of JWT token.
• No need to pass the “client ID” as “cid” parameter in the API URL: the Bearer token is now used to identify the client.
• Support for all AudioVisual products: Live Channel Online, Live Channel Retail Flex, Live Channel Trading, etc.
• AudioVisual events instead of “matches”: the Live Channel Online API was centered around the concept of Sportradar matches (with “match IDs”, also known in the Sportradar terminology as “sport events”). The new AudioVisual API is centered around the concept of AudioVisual events which are not necessarily associated to a Sportradar sport event. It provides more flexibility and clarity, access to more content, as well as support for a better data structure. Please note, however, that AudioVisual events for betting products such as Live Channel Online, Live Channel Retail Flex and Live Channel Trading will almost constantly be associated to a Sportradar sport event.
• A same event contains one or multiple contents (videos). There is always one content marked as “main” content for a given event. The main content is generally the stream of the full duration of the event.
• Support for Live and Video on demand (VOD).
• The properties “isActive” and “isLive” from the /streamed-matches endpoint of the Live Channel Online API have been replaced respectively by “event_status” (on event level) and “stream_status” (on stream level). See below in this documentation the section related to the GET /events endpoint for more details.
• No more support for SMIL files: SMIL format was used as a manifest for multi-bitrate RTMP streaming in the Live Channel Online API. The AudioVisual API does not support this format any more.
• Additional filter parameters. See below in this documentation the sections related to GET /events endpoint for more details.
• New URN-style IDs as ID scheme (see dedicated section below).
• Support for geo-restrictions on country subdivisions such as US states (support to be activated soon).
  
  

Access

The API is available via the HTTP protocol and must be called from the server(s) of the client and not from a frontend application.
Access to the API is restricted by IP. In order to access the API, Sportradar needs to whitelist the IP(s) of the client server(s) from which the API will be called.

URL

The API is hosted on https://av-api.betradar.com/.
The URLs of the endpoints follow the following pattern: https://av-api.betradar.com/<version>/<endpoint_path>?<query_parameters>
Example of URL: https://av-api.betradar.com/v1/events
Setting the version in the URL is optional. If it is omitted, the latest version of the API will be used.
The latest version of the API is “v1”.

Response formats

The API supports at the moment only JSON as response format. The support for XML will come soon.
The response format is defined via the “Accept” HTTP header. For JSON, use “application/json”. For XML, it will be “application/xml”. If no “Accept” HTTP header is sent, the API will use JSON by default.

Authentication

Authentication is required for all of the endpoints of the API. The authentication scheme used by the API is Bearer authentication (also called token authentication). To authenticate, an API key (bearer token) must be sent in the “Authorization” HTTP header when making requests to the API. The string “Bearer ” must be included before the API key, as follows:
Authorization: Bearer <api-key>

The API key is provided by Sportradar as part of an AudioVisual product. If you already have an API key with the Live Channel Online API, it is not possible to re-use it with the AudioVisual API. Please contact us if you need a new API key.

ID scheme

Like most of other APIs provided by Sportradar, the values for representing IDs are using URN-style IDs with the following format: “XXX:YYY:###”.

• “XXX” is some kind of context and can be “sr” or “av”. “sr” refers to an entity which is part of the Sportradar world and which is globally used for other products in the Sportradar catalogue. “av” refers to an entity which is specific to the Sportradar AudioVisual products.
• “YYY” is the name of the entity within the context. It is generally a string.
• “###” is typically a raw identifier for that entity. It is generally an integer.

Expected workflow

The following workflow is recommended for integrating the AudioVisual Client API:

1. The client server requests the GET /events endpoint to get the list of events and to have an overview of the different streams available for them.
2. When an end user wants to play the video stream of a content (e.g. via the client’s web site), a request is made from the client server to the GET /streams endpoint to get the stream URL. The IP of the end user must be passed to the API via the “X-Real-IP” HTTP header.
3. The stream URL returned in the response of the API should be passed on to the end user’s video player, which will then connect to a streaming server.
4. The streaming server will validate the stream URL (by doing an IP validation among others) and play the stream back to the end user.

Special requirements for streaming in the USA, Canada and Mexico

When the end-user is located in one of these countries:

1. Client is only permitted to send requests to the API endpoints which return stream URLs if the end-user is located in a territory which is defined as a whitelisted area according to the agreement with Sportradar.
2. Additionally, two more HTTP headers must be sent in the request:
   • “Geo-Position”: comma-separated string containing the latitude and longitude values specifying the location of the end-user, in WGS84 format. For example: 40.714224,-73.961452.
   • “Geo-Position-Timestamp”: Unix timestamp of the latitude/longitude coordinates retrieval.

Based on this information, the API will perform a check to verify that the end-user is located in a territory which is allowed, and will make sure that the timestamp is not older than 1 minute ago. If this check fails, the stream URL will not be returned. Instead, an error will be returned in the response.

API endpoints

GET /events

HTTP method: GET
Path: /events

This endpoint returns the lists of booked events (booked manually via the Live Booking Calendar in betradar.com or booked automatically via a client package).

An event is defined by various properties described below and contains one or multiple “contents”. A content is a video in relation to the event. For instance, an event such as a football match will contain a video of the full duration of the match but can also contain videos for goal clips, highlights, interviews, etc.
A content itself contains one or multiple “streams”. Streams are distincted by AudioVisual product (Live Channel Online, Live Channel Retail Flex, Live Channel Trading, etc) and distribution (Live or VOD).

By using this endpoint, you will be able to retrieve only events in the time frame between now – 1 day and now + 14 days. Events out of this time frame are not available, whatever are the filtering parameters used.

Events are sorted by event start time.

Parameters as query parameters in the URL
The following parameters can be passed as query parameters in the URL. They are all optional. If none of these parameters are passed, the API will return by default the events which have a start time between now – 6 hours and now + 3 days or which have at least one stream with distribution type “Live” and broadcast status “On Air Broadcast”.

Example of response in JSON:

[  
   {  
      "id":"av:event:36852",
      "client_event_id": "ABCD-1234",
      "sport_event_id":"sr:match:17517635",
      "start_time":"2019-02-28T11:40:00+00:00",
      "end_time":null,
      "event_status":{  
         "id":"av:event_status:2",
         "name":"Confirmed"
      },
      "first_level_category":{  
         "id":"sr:sport:5",
         "name":"Tennis"
      },
      "second_level_category":{  
         "id":"sr:category:785",
         "name":"ITF Men"
      },
      "third_level_category":{  
         "id":"sr:competition:17630",
         "name":"ITF Portugal F2, Men Singles"
      },
      "competitors":[  
         {  
            "id":"sr:competitor:103625",
            "name":"GEERTS, MICHAEL",
            "qualifier":"home"
         },
         {  
            "id":"sr:competitor:153644",
            "name":"MONTEIRO, JOAO",
            "qualifier":"away"
         }
      ],
      "venue":{  
         "id":"sr:venue:27383",
         "name":"Court 1"
      },
      "contents":[  
         {  
            "id":"av:content:121364",
            "content_type":{  
               "id":"av:content_type:6",
               "name":"Full match"
            },
            "name":null,
            "is_main":true,
            "streams":[  
               {  
                  "id":"av:stream:107200",
                  "product":{  
                     "id":"av:product:1",
                     "name":"Live Channel Retail"
                  },
                  "distribution":{  
                     "id":"av:distribution:1",
                     "name":"Live"
                  },
                  "start_time":"2019-02-28T11:40:00+00:00",
                  "end_time":null,
                  "stream_status":{  
                     "id":"av:stream_status:2",
                     "name":"On Air Broadcast"
                  },
                  "languages":[],
                  "geo_restrictions":[  
                     {  
                        "device_category":{  
                           "id":"av:device_category:1",
                           "name":"Desktop"
                        },
                        "country_iso_alpha2_codes":"AT,NO"
                     }
                  ]
               },
               {  
                  "id":"av:stream:107202",
                  "product":{  
                     "id":"av:product:2",
                     "name":"Live Channel Online"
                  },
                  "distribution":{  
                     "id":"av:distribution:1",
                     "name":"Live"
                  },
                  "start_time":"2019-02-28T11:40:00+00:00",
                  "end_time":null,
                  "stream_status":{  
                     "id":"av:stream_status:2",
                     "name":"On Air Broadcast"
                  },
                  "languages":[],
                  "geo_restrictions":[  
                     {  
                        "device_category":{  
                           "id":"av:device_category:1",
                           "name":"Desktop"
                        },
                        "country_iso_alpha2_codes":"AT,NO,US",
                        "country_subdivision_iso_codes": {
                           "US": "US-NJ,US-NV"
                        }
                     },
                     {  
                        "device_category":{  
                           "id":"av:device_category:2",
                           "name":"Mobile"
                        },
                        "country_iso_alpha2_codes":"AT,NO,US",
                        "country_subdivision_iso_codes": {
                           "US": "US-NJ,US-NV"
                        }
                     }
                  ]
               }
            ]
         }
      ]
   }
]

Description of the properties

GET /events/<event_id>

HTTP method: GET
Path: /events/<event_id>

This endpoint returns the same response as the GET /events endpoint, but just for one event. The structure is the same except that the root element is an object instead of an array. Please see the documentation of GET /events endpoint for more information (note that the GET parameters from the GET /events endpoint do not apply to this endpoint).

Parameters in the path of the URL

GET /streams/<stream_id>/<stream_type>

HTTP method: GET
Path: /streams/<stream_id>/<stream_type>

This endpoint returns the URL of a stream by stream ID for a given stream type.

Parameters in the path of the URL

Parameters as query parameters in the URL

Parameters as HTTP headers

Example of response in JSON:

{
   "url": "https://sportradar-lco.akamaized.net/24770/121364/dash/desktop/tennis_itf_men_itf_portugal_f2_men_singles_17517635.mpd?cid=24770&mid=17517635&ecid=121364&pid=2&dtid=1&sid=538435715117&hdnts=ip=92.62.38.2~exp=1551450105~acl=%2F24770%2F121364%2Fdash%2Fdesktop%2F%2A~hmac=03185324934d24d5c581af8f6ed1d7775eb92ac7467d2563915c708283f99ae6"
}

For “RTMP” streams, the response contains an additional property for the stream name:

{
   "url": "rtmp://cp508682.live.edgefcs.net/live/",
   "stream_name": "avup_single_81@s752670?auth=da_cbdZdob6bqbbaeaYdzbXbFb.adaFdwb1-bCD.60-E-xAwAEoJorBoCFEa-o8sakdlcm5&aifp=v1&cid=24770&mid=17517635&ecid=121364&pid=2&dtid=1&sid=287080384538"
}

Important note regarding RTMP stream URLs

Responses for RTMP stream URLs are special because the stream URL is divided into two different properties: “url” and “stream_name”. Depending on the video player you use, you will have to keep these two properties separated or you will have to join them into one single “full” URL, the latter being the most common case. If you need to join the “url” and “stream_name” properties into one single “full” URL, you have to make sure to always include the actual stream name before the query parameters because, depending on the streaming server used to deliver the stream, the query parameters can be either in the “url” property or in the “stream_name” property.

Example with the query parameters in the “stream_name” property: let’s “url” be “rtmp://my.domain.com/path/” and “stream_name” be “my_stream_name?param1=value1”. The full URL to put in the player should then be “rtmp://my.domain.com/path/my_stream_name?param1=value1”.

Example with the query parameters in the “url” property: let’s “url” be “rtmp://my.otherdomain.com/otherpath/?otherparam1=othervalue1” and “stream_name” be “my_other_stream_name”. The full URL to put in the player should then be “rtmp://my.otherdomain.com/otherpath/my_other_stream_name?otherparam1=othervalue1”.

GET /contents/<content_id>/product/<product_id>/distribution/<distribution_id>/stream/<stream_type>

HTTP method: GET
Path: /contents/<content_id>/product/<product_id>/distribution/<distribution_id>/stream/<stream_type>

This endpoint returns the URL of a stream by content ID, product ID and distribution ID for a given stream type.

Parameters in the path of the URL

Parameters as query parameters in the URL

Same as for GET /streams/<stream_id>/<stream_type> endpoint.

Parameters as HTTP headers

Same as for GET /streams/<stream_id>/<stream_type> endpoint.

Response

Same as for GET /streams/<stream_id>/<stream_type> endpoint.

GET /event-statuses

HTTP method: GET
Path: /event-statuses

This endpoint returns an array with the list of possible event statuses.
See the section "Description of statuses" at the end of this document for more information.

GET /content-types

HTTP method: GET
Path: /content-types

This endpoint returns an array with the list of possible content types.

GET /products

HTTP method: GET
Path: /products

This endpoint returns an array with the list of possible products.

GET /distributions

HTTP method: GET
Path: /distributions

This endpoint returns an array with the list of possible distributions.

GET /stream-statuses

HTTP method: GET
Path: /stream-statuses

This endpoint returns an array with the list of possible stream statuses.
See the section "Description of statuses" at the end of this document for more information.

GET /device-categories

HTTP method: GET
Path: /device-categories

This endpoint returns an array with the list of possible device categories.

Description of statuses

Event statuses

Stream statuses

Please note that the stream status can change several times even during a live event. Streams might be available again shortly after an error has occurred.

Error responses

In case of errors, a response with the right HTTP code (4xx or 5xx) will be returned by the API and the body will contain an internal error code as well as a message with the description of the error.