Video Streaming API

The video streaming API is used by customers to:

• Retrieve the schedule of upcoming streams.
• Retrieve the streaming parameters for a particular fixture.
• Retrieve the full list of supported regions for playback.

This API does not deliver the video stream itself, it only tells what are the specific parameters for streaming a given
fixture. It is up to the users of this API to configure a video player with the streaming parameters.
This API must never be called from end-user browser/client code. Instead, the API should be integrated into server-side
systems.

Domain model

The diagram below illustrates the main objects exposed in the API and their relationships:

Fixtures

Fixtures are the main objects in the API. They encapsulate video streaming information for a given GeniusSports fixture.
One fixture contains basic information such as the Genius fixture ID, name, start time and phase (see below), as well as
a list of available LiveStreams to get video from.

The phase of a fixture is defined by the state-machine:

where:

• PRE_MATCH: indicates a fixture has not started yet.
• IN_PLAY: this phase starts when the current UTC time is greater or equal to the startAt date reported for the
  fixture.
• RESULTED: indicates that a fixture has been completed.

Live streams and deliveries

A LiveStream represents one video feed for a given fixture. Tipically, a fixture will only have one stream
available, however the API is designed to support several streams for the same fixture. Within each live stream, video
can be delivered on several transport protocols (HLS, DASH, etc), described by the StreamDeliveries object.

The StreamDeliveries object defines the sources for delivering the stream on a given transport protocol. Currently,
HLS and DASH are supported. For each protocol, there can be several sources serving the video content (e.g., primary and
backup CDN).

Each transport protocol defines its own {Protocol}Delivery object containing protocol-specific information.

Currently, the liveStreams capability is offered while a given fixture is in the IN_PLAY phase. After that,
the liveStreams becomes empty.

VOD streams and delivery

A VodStream represents the recording of a successfully completed fixture. The recording occurs after the fixture is
completed and transitions to the RESULTED phase. Internally, the recording is processed and becomes available to the
API after some period of time. During this processing, the API will return an empty vodStreams array. Currently,
only HLS recordings are supported, and shares the HLSDelivery type definition.

Permissions

Each live and VOD stream includes a list of permissions. These permissions encapsulates the licensing conditions to
stream content. In order to play a stream, viewers must fully comply with at least one permission.

Each permission object is defined by three attributes:

• region: indicates a geographic zone in the world where the streaming of the fixture is allowed. A region can be a
  country or a specific region/state/province inside a country. Example: GB (United Kingdom), US_CA (United states -
  California), ES (Spain).
• device: the current device types are:
• MOBILE: devices whose diagonal screen size is 7 inches or less.
• TABLET: portable devices (e.g. Android tablets or iPad) whose diagonal screen size is greater than 7 inches.
• DESKTOP: laptop and desktop machines.
• OTT: (Over The Top) devices such as game consoles, AndroidTV or AppleTV.
• maxPlayerSizePercentage: the maximum size, in percentage units in the range [0, 100], of the video player along the
  horizontal axis of the display screen. This attribute is intended to be used by websites to show the player with a
  permitted size in the screen.

The JSON example below illustrates a list of permissions:

• License is granted for the United Kingdom GB, for DESKTOP devices, with a maximum player size of 40% of the screen
  size.
• License is granted for streaming the fixture in Italy (IT) for MOBILE devices at 100% screen size, and
  for TABLET devices at 50% screen size.

{
  "permissions": [
    {
      "device": "DESKTOP",
      "maxPlayerSizePercentage": 40,
      "region": "GB"
    },
    {
      "device": "MOBILE",
      "maxPlayerSizePercentage": 100,
      "region": "IT"
    },
    {
      "device": "TABLET",
      "maxPlayerSizePercentage": 50,
      "region": "IT"
    }
  ]
}

DMAs

Each live and VOD stream includes a list of dmas. This list encapsulates the licensing conditions to stream content
in some DMAs (Designated Market Area) inside the United States. In order to play a stream, the viewer must be in one of
the alllowed areas.

Each DmaPermission object is defined by just one attribute:

• dma: Defines the DMA code inside United States where the content can be consumed. Example:
  501 refers to the New York City DMA code, which contains some areas in the states of Connecticut (CT), New Jersey
  (NJ), New York (NY) and Pensilvania (PA).

The JSON example below illustrates a list of dmas:

• License is granted for the DMAs 501 and 811 which refers to the cities of New York and Reno in the United states,
  The list of dmas is associated to the list of permissions, i.e. you will only see DMAs that are available in the
  regions to which you have a license.

{
  "dmas": [
    {
      "dma": "501"
    },
    {
      "dma": "811"
    }
  ]
}

Backend integration

Base url

The base URL for the API is https://api.geniussports.com/Video-v3/{STAGE}. where {STAGE} can be one of:

• UAT
• PRODPRM

Authentication

Authentication must be performed using
GenisSports Authentication API.
For UAT and PRODPRM stages, one should authenticate using the PROD stage, as:

curl -H ‘Content-Type: application/json’ -X POST -d ‘{"user":"USERNAME","password":"YOUR_NEW_PASS"}’ https://api.geniussports.com/Auth-v1/PROD/login

On the first usage of the login API, either for the video API or any other GeniusSports API, it is required to change
the password, as:

curl -H ‘Content-Type: application/json’ -X POST -d ‘{"user":"USERNAME","password":"PASSWORD", "newpass":"SET_YOUR_PASS"}’ https://api.geniussports.com/Auth-v1/PROD/login

Upon sucessful authentication, the JSON response will contain an IdToken attribute. The value of this attribute must
be passed on every call to the video API as an Authorization header.

Authorization

Each API call requires two headers to for authentication and authorization:

Header	Value
Authorization	IdToken obtained in the authentication call
x-api-key	A unique API key. A GeniusSports account manager should provide this during the onbarding process. Use the apropriate key according to the target environment (UAT, PRODPRM)

Fixture schedule

The endpoints:

• GET /fixtures
• GET /fixtures/{id}

can be used to get the full schedule of available fixtures or just one of them, provided its Genius fixture ID.

The full schedule endpoint offers several query parameters to filter the returned fixtures, examples include:

• Return BOOKED fixtures only:

bash curl -X GET https://api.geniussports.com/Video-v3/UAT/fixtures?bookingStatus=BOOKED \ -H "accept: application/json" \ -H "x-api-key: environment_token" \ -H "Authorization: `IdToken`”

• Return UNBOOKED fixtures only:

bash curl -X GET https://api.geniussports.com/Video-v3/UAT/fixtures?bookingStatus=UNBOOKED \ -H "accept: application/json" \ -H "x-api-key: environment_token" \ -H "Authorization: `IdToken`”

• Return BOOKED fixtures within a time window, fromDate=2021-07-02T07:00:00Z to toDate=2021-07-10T09:00:00Z:

bash curl -X GET https://api.geniussports.com/Video-v3/UAT/fixtures?bookingStatus=BOOKED&fromDate=2021-07-02T07:00:00Z&toDate=2021-07-10T09:00:00Z \ -H "accept: application/json" \ -H "x-api-key: environment_token" \ -H "Authorization: `IdToken`”

The JSON below is an example of the response for the /fixtures/ endpoint. It contains the details of the
fixture 1300290721, which has one liveStream avaliable in HLS delivered through Akamai:

{
  "data": [
    {
      "id": 1300290721,
      "name": "Team A v Team B",
      "phase": "PRE_MATCH",
      "bookingStatus": "BOOKED",
      "startAt": "2021-07-29T13:00:00Z",
      "competitionId": "9530",
      "competitionName": "Test Comp",
      "sportId": 10,
      "sportName": "Football",
      "liveStreams": [
        {
          "id": "c8ed9f88",
          "permissions": [],
          "dmas": [],
          "deliveries": {
            "hls": [
              {
                "id": "AKAMAI"
              }
            ],
            "dash": []
          }
        }
      ]
    }
  ]
}

Request the region list

Call this resource:

GET /regions

This endpoint can be used to get all the territories used by the video API. The response contains a list of continents,
a list of regions and a list of the DMAs (Designated Market Areas) inside the United States.

Example of a valid request:

curl -X GET https://api.geniussports.com/Video-v3/UAT/regions \
  -H  "accept: application/json" \
  -H "x-api-key: environment_token" \
  -H "Authorization: `IdToken`”

The following example response contains a subset of each of the components of the real response:

{
  "continents": [
    {
      "code": "AF",
      "name": "Africa"
    },
    {
      "code": "AS",
      "name": "Asia"
    }
    ...
  ],
  "regions": [
    {
      "code": "AD",
      "name": "Andorra",
      "continent": "EU"
    },
    {
      "code": "AE",
      "name": "United Arab Emirates",
      "continent": "AS"
    },
    ...,
    {
      "code": "US_AL",
      "name": "United States - Alabama",
      "continent": "NA"
    },
    {
      "code": "US_AK",
      "name": "United States - Alaska",
      "continent": "NA"
    },
    ...
  ],
  "dmas": [
    {
      "code": "500",
      "cities": [
        "Portland",
        "Auburn"
      ],
      "regions": [
        "US_ME",
        "US_NH"
      ]
    },
    {
      "code": "501",
      "cities": [
        "New York"
      ],
      "regions": [
        "US_CT",
        "US_NJ",
        "US_NY",
        "US_PA"
      ]
    },
    ...
  ]
}

Request streaming parameters

Live stream

The figure below illustrates the process to obtain streaming parameters to play a given fixture:

The request is checked against the permissions for the particular fixture to see if streaming is allowed. If the check
is successful, the response will contain a plaback URL, a CDN access token, and, optionally, some DRM configuration.
This data must the used to configure the video player of the end-user willing to watch the stream.

The endpoints:

• POST /fixtures/{id}/live-streams/{streamId}/deliveries/hls/{deliveryId}
• POST /fixtures/{id}/live-streams/{streamId}/deliveries/dash/{deliveryId}

can be used to get live streaming parameters for HLS or DASH for a given GeniusSports fixture. The {id}, {streamId},
and {deliveryId} correspond to the fixture, live-stream and delivery ID provided by the Fixture object in any of
the /fixtures endpoints.

The request body has the form:

{
  "endUserSessionId": "<some unique end-user identifier>",
  "region": "CO",
  "device": "DESKTOP"
}

where region must be one of the region codes returned by the /regions/ endpoint; device must be one of the allowed
device types, and endUserSessionId is a unique, non personally identifiable ID, representing the end-user.

Example of a valid request:

curl --location --request POST 'https://api.geniussports.com/Video-v3/UAT/fixtures/1630290721/live-streams/c8ed9f88/deliveries/hls/AKAMAI' \ 
  --header 'accept: application/json' \ 
  --header 'Content-Type: application/json' \ 
  --header 'x-api-key: environment_token ' \ 
  --header 'Authorization:  `IdToken` ' \ 
  --data-raw '{ 
    "endUserSessionId": "1d34aacd-f0ab-4d72-b9ce-14a80233de23", 
    "region": "CO", 
    "device": "DESKTOP" 
  }' 

And the response could be like this:

{
  "url": "https://dummy-live-secure.akamaized.net/hls/live/2030959/uat_CONTINUOUS_TEST_1630290721/playlist.m3u8",
  "expiresAt": "2021-12-12T09:12:00",
  "token": "st=1627648558~exp=1627649158~acl=*~id=1d34aacd-f0ab-4d72-b9ce-14a80233de23~data=reg:CO~hmac=498c6a4842a4176dfe65b067b636a857eb9aab25700f78a13b44e5d510517ebd",
  "drm": {
    "fairplay": "http://...",
    "fairplayCertificate": "https://...",
    "playready": "https://...",
    "widevine": "https://..."
  }
}

This sample response includes a URL, an expiration date and a token. The received token should be appended to the URL as
a query string parameter when the player makes the request for content to the CDN. In this example the DRM object is not
null, so DRM is required for streaming.

Viewer Information Endpoint

Viewer location and device are important pieces of data for selecting the right Livestream for a given end-user.
The Video-API validates that the permissions for each Livestream are met and hence, correct data passing to the API is
crucial. To this end, there is an HTTP endpoint that returns the location and device type when called from end-users’
devices.

• GET https://viewer-data.production.geniuslive.geniussports.com

Example of the response from a Desktop computer located in New York(USA)

{
  "region": "US_NY",
  "dma": "501",
  "device": "DESKTOP"
}

This endpoint return information such as the region, the dma and the user device from which the
request is made. The region and device are used in the livestream permissions and the dma
field is mentioned in the list of valid dmas for each livestream. This information will be useful to choose the correct
livestream and, to send the necessary fields in the request of the streaming parameters.

Use case example

Consider two users of your website, using the endpoint https://viewer-data.production.geniuslive.geniussports.com
we obtain that:

• User_1 is located in US_CA (USA California - DMA 803 Los Angeles) using DESKTOP as device.

{
  "region": "US_CA",
  "dma": "803",
  "device": "DESKTOP"
}

• User_2 is located in JP (Japan) using a MOBILE device.

{
  "region": "JP",
  "dma": "",
  "device": "MOBILE"
}

Consider the response for fixture 1234 that looks like:

{
  "id": 1234,
  "name": "A v B ON DEMAND TEST On Demand",
  "phase": "IN_PLAY",
  "bookingStatus": "BOOKED",
  "startAt": "2023-08-30T17:50:00Z",
  "competitionId": "9530",
  "competitionName": "TEST COMPETITION",
  "sportId": 10,
  "sportName": "Football",
  "liveStreams": [
    {
      "id": "Livestream1",
      "permissions": [
        {
          "device": "DESKTOP",
          "maxPlayerSizePercentage": 100,
          "region": "US_CA"
        },
        {
          "device": "DESKTOP",
          "maxPlayerSizePercentage": 100,
          "region": "US_NY"
        }
      ],
      "dmas": [
        {
          "dma": "500"
        },
        {
          "dma": "803"
        }
      ],
      "deliveries": {
        "hls": [
          {
            "id": "Akamai"
          }
        ],
        "dash": [
          {
            "id": "Akamai"
          }
        ]
      }
    },
    {
      "id": "Livestream2",
      "permissions": [
        {
          "device": "MOBILE",
          "maxPlayerSizePercentage": 100,
          "region": "JP"
        },
        {
          "device": "DESKTOP",
          "maxPlayerSizePercentage": 100,
          "region": "GB"
        }
      ],
      "dmas": [ ],
      "deliveries": {
        "hls": [
          {
            "id": "Akamai"
          }
        ],
        "dash": [
          {
            "id": "Akamai"
          }
        ]
      }
    }
  ],
  "vodStreams": []
}

For this fixture we have 2 livestreams, Livestream1 is for users within US_CA and US_NY that are
using a DESKTOP computer, the livestream is available only if the users are also located in the DMAs 500 and 803.
Then, Livestream2 is for users located in Japan(JP) using MOBILE devices, and for the nited Kingdom(GB) for
DESKTOP computers.

For user_1 the livestream that should be used is the livestream1 since it complies with the permission to be in US_CA
using a DESKTOP computer and it is also in one of the DMAs allowed for this livestream, dma 803.

It is important to send the correct region and device values for user_1 when obtaining the streaming parameters for the
livestream1.

• POST /fixtures/1234/vod-streams/livestream1/deliveries/hls/Akamai

The request body should contain the exact information already extracted from the viewer-data endpoint:

{
  "endUserSessionId": "<some unique end-user identifier>",
  "region": "US_CA",
  "device": "DESKTOP"
}

For the user_2 the livestream that should be used is the livestream2 since it complies with the permission to be in
Japan JP using a MOBILE device, in this case there are no DMAs because we only support and validate DMAs inside
the US

It is important to send the correct region and device values for user_1 when obtaining the streaming parameters for the
livestream2.

• POST /fixtures/1234/vod-streams/livestream2/deliveries/hls/Akamai

The request body should contain the exact information already extracted from the viewer-data endpoint:

{
  "endUserSessionId": "<some unique end-user identifier>",
  "region": "JP",
  "device": "MOBILE"
}

NOTE: if any of the 2 users send an erroneous field in the body of the request such as the region or the device, it is
possible that the video-api responds with a (403 access denied) mentioning that they do not have permissions to view
that livestream.

VOD stream

Accessing VOD stream parameters follows the same process as live stream:

Currently, only HLS is supported through the endpoint:

• POST /fixtures/{id}/vod-streams/{streamId}/deliveries/hls/{deliveryId}

where {id}, {streamId}, and {deliveryId} correspond to the fixture, live-stream and delivery ID provided by the
Fixture object in any of the /fixtures endpoints.

The request body has the same structure as the one used for live streaming:

{
  "endUserSessionId": "<some unique end-user identifier>",
  "region": "CO",
  "device": "DESKTOP"
}

where region must be one of the region codes returned by the /regions/ endpoint, device must be one of the allowed
device types, and endUserSessionId is a unique, non personally identifiable ID, representing the end-user.

This data is checked against the permissions for the particular fixture to see if streaming is allowed. If the check is
completed successfully, the response will contain the data needed for configuring a video-player to stream the content.

Example of a valid request:

curl --location --request POST 'https://api.geniussports.com/Video-v3/UAT/fixtures/1630290721/vod-streams/c8ed9f88/deliveries/hls/AKAMAI' \ 
--header 'accept: application/json' \ 
--header 'Content-Type: application/json' \ 
--header 'x-api-key: environment_token ' \ 
--header 'Authorization:  `IdToken` ' \ 
--data-raw '{ 
  "endUserSessionId": "1d34aacd-f0ab-4d72-b9ce-14a80233de23", 
  "region": "CO", 
  "device": "DESKTOP" 
}' 

And the response could be like this:

{
  "url": "https://dummy-live-secure.akamaized.net/hls/vod/2030959/uat_CONTINUOUS_TEST_1630290721/playlist.m3u8",
  "expiresAt": "2021-12-12T09:12:00",
  "token": "st=1627648558~exp=1627649158~acl=*~id=1d34aacd-f0ab-4d72-b9ce-14a80233de23~data=reg:CO~hmac=498c6a4842a4176dfe65b067b636a857eb9aab25700f78a13b44e5d510517ebd",
  "drm": null
} 

In this case, the response includes the playback URL, an expiration date and a token. The received token should be
appended to the URL as a query string parameter when the player makes the request for content to the CDN. The DRM object
is null, indicating no DRM is required for this stream.

Video Player integration

Using the CDN access token

The access token returned by the streaming parameters endpoint of the Video API should be attached as a query string
parameter to the URL for the manifest/index file. Consider a response from
the /fixtures/{id}/live-streams/{streamId}/deliveries/hls/{deliveryId} endpoint:

{
  "url": "https://dummy-live-secure.akamaized.net/hls/live/2030959/uat_CONTINUOUS_TEST_1630290721/playlist.m3u8",
  "expiresAt": "2021-12-12T09:12:00",
  "token": "st=1627648558~exp=1627649158~acl=*~id=1d34aacd-f0ab-4d72-b9ce-14a80233de23~data=reg:CO~hmac=498c6a4842a4176dfe65b067b636a857eb9aab25700f78a13b44e5d510517ebd",
  "drm": {
    "fairplay": "http://...",
    "fairplayCertificate": "https://...",
    "playready": "https://...",
    "widevine": "https://..."
  }
} 

The final URL to request the manifest to the CDN will be:

https://dummy-live-secure.akamaized.net/hls/live/2030959/uat_CONTINUOUS_TEST_1630290721/playlist.m3u8?st=1627648558~exp=1627649158~acl=*~id=1d34aacd-f0ab-4d72-b9ce-14a80233de23~data=reg:CO~hmac=498c6a4842a4176dfe65b067b636a857eb9aab25700f78a13b44e5d510517ebd

Using the CDN session token

Session tokens are created by the CDN and are exchanged with the player during the streaming. For HLS, this session
token comes embedded in the master manifest. For DASH, the session token comes in a cookie, therefore the player must be
configured to send cookies in the request. However, some devices and browsers might not be configured to support
cookies, so it is important to validate this before selecting the stream delivery to play.

Using DRM

DRM (Digital Rights Management) is a method for adding security to digital content and prevent unauthorized use and
piracy. Some competitions require DRM for playback. For those cases, the video will be encrypted and the video player
must retrieve extra data to decrypt it.

Upon a call to the streaming parameters endpoint, the response might include a drm object. If this object is null or
not present, then DRM is not required for that delivery. Otherwise the DRM object contains a list of URLs for the
decryption keys, one url for each supported technology. The player needs to select the technology that better suits the
client platform, then get the key using the URL, and finally use that key to decrypt the content during the session.

Consider the following response:

{
  "url": "https://dummy-live-secure.akamaized.net/hls/live/2030959/uat_CONTINUOUS_TEST_1630290721/playlist.m3u8",
  "expiresAt": "2021-12-12T09:12:00",
  "token": "st=1627648558~exp=1627649158~acl=*~id=1d34aacd-f0ab-4d72-b9ce-14a80233de23~data=reg:CO~hmac=498c6a4842a4176dfe65b067b636a857eb9aab25700f78a13b44e5d510517ebd",
  "drm": {
    "fairplay": "http://...",
    "fairplayCertificate": "https://...",
    "playready": "https://...",
    "widevine": "https://..."
  }
}

There are three technologies supported for DRM:

• Google Widevine: the content can be played in Chrome and Firefox web browsers, as well as Android and Chromecast
  devices.
• Apple FairPlay: content can be played in Safari on OS X, as well as iPhone, iPad, and AppleTV. This DRM protection
  scheme requires both the fairplay and fairplayCertificate values returned in the response.
• Microsoft PlayReady: content can be played in Internet Explorer and Edge browsers, Windows Phone, Xbox, and other
  platforms via SDKs.

If the selected video player library supports DRM, then it is quite probable that users of the library only have to pass
it the urls of decryption keys, and the player library will take the decision of which to use according to the platform.
Otherwise, it is possible to create such logic based on this table.

https://api.geniussports.com/Video-v3/PRODPRM