The video streaming API is used by customers to:
\nThis API does not deliver the video stream itself, it only tells what are the specific parameters for streaming a given
\nfixture. It is up to the users of this API to configure a video player with the streaming parameters.
\nThis API must never be called from end-user browser/client code. Instead, the API should be integrated into server-side
\nsystems.
The diagram below illustrates the main objects exposed in the API and their relationships:
\nFixtures are the main objects in the API. They encapsulate video streaming information for a given GeniusSports fixture.
\nOne fixture contains basic information such as the Genius fixture ID, name, start time and phase (see below), as well as
\na list of available LiveStreams to get video from.
The phase of a fixture is defined by the state-machine:
\nwhere:
\nA LiveStream represents one video feed for a given fixture. Tipically, a fixture will only have one stream
\navailable, however the API is designed to support several streams for the same fixture. Within each live stream, video
\ncan 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,
\nHLS and DASH are supported. For each protocol, there can be several sources serving the video content (e.g., primary and
\nbackup 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,
\nthe liveStreams becomes empty.
A VodStream represents the recording of a successfully completed fixture. The recording occurs after the fixture is
\ncompleted and transitions to the RESULTED phase. Internally, the recording is processed and becomes available to the
\nAPI after some period of time. During this processing, the API will return an empty vodStreams array. Currently,
\nonly HLS recordings are supported, and shares the HLSDelivery type definition.
Each live and VOD stream includes a list of permissions. These permissions encapsulates the licensing conditions to
\nstream content. In order to play a stream, viewers must fully comply with at least one permission.
Each permission object is defined by three attributes:
\nregion: indicates a geographic zone in the world where the streaming of the fixture is allowed. A region can be adevice: 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 theThe JSON example below illustrates a list of permissions:
\nGB, for DESKTOP devices, with a maximum player size of 40% of the screenIT) for MOBILE devices at 100% screen size, andTABLET devices at 50% screen size.{\n "permissions": [\n {\n "device": "DESKTOP",\n "maxPlayerSizePercentage": 40,\n "region":\
\ "GB"\n },\n {\n "device": "MOBILE",\n "maxPlayerSizePercentage": 100,\n "region": "IT"\n },\n {\n "device": "TABLET",\n "maxPlayerSizePercentage": 50,\n "region": "IT"\n }\n ]\n}\nEach live and VOD stream includes a list of dmas. This list encapsulates the licensing conditions to stream content
\nin some DMAs (Designated Market Area) inside the United States. In order to play a stream, the viewer must be in one of
\nthe alllowed areas.
Each DmaPermission object is defined by just one attribute:
\ndma: 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 JerseyThe JSON example below illustrates a list of dmas:
\n501 and 811 which refers to the cities of New York and Reno in the United states,{\n "dmas": [\n {\n "dma": "501"\n },\n {\n "dma": "811"\n }\n ]\n}\nThe base URL for the API is https://api.geniussports.com/Video-v3/{STAGE}. where {STAGE} can be one of:
UATPRODPRMAuthentication must be performed using
\nGenisSports Authentication API.
\nFor 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\nOn the first usage of the login API, either for the video API or any other GeniusSports API, it is required to change
\nthe 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\nUpon sucessful authentication, the JSON response will contain an IdToken attribute. The value of this attribute must
\nbe passed on every call to the video API as an Authorization header.
Each API call requires two headers to for authentication and authorization:
\n| Header | \nValue | \n
|---|---|
| Authorization | \nIdToken obtained in the authentication call | \n
| x-api-key | \nA 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) | \n
The endpoints:
\nGET /fixturesGET /fixtures/{id}can be used to get the full schedule of available fixtures or just one of them, provided its Genius fixture ID.
\nThe full schedule endpoint offers\ \ several query parameters to filter the returned fixtures, examples include:
\nBOOKED fixtures only:bash\n curl -X GET https://api.geniussports.com/Video-v3/UAT/fixtures?bookingStatus=BOOKED \\\n -H \"accept: application/json\" \\\n -H \"x-api-key: environment_token\" \\\n -H \"Authorization: `IdToken`”
UNBOOKED fixtures only:bash\n curl -X GET https://api.geniussports.com/Video-v3/UAT/fixtures?bookingStatus=UNBOOKED \\\n -H \"accept: application/json\" \\\n -H \"x-api-key: environment_token\" \\\n -H \"Authorization: `IdToken`”
BOOKED fixtures within a time window, fromDate=2021-07-02T07:00:00Z to toDate=2021-07-10T09:00:00Z:bash\n 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 \\\n -H \"accept: application/json\" \\\n -H \"x-api-key: environment_token\" \\\n -H \"Authorization: `IdToken`”
The JSON below is an example of the response for the /fixtures/ endpoint. It contains the details of the
\nfixture 1300290721, which has one liveStream avaliable in HLS delivered through Akamai:
{\n "data": [\n {\n "id": 1300290721,\n "name": "Team A v Team B",\n "phase": "PRE_MATCH",\n "bookingStatus": "BOOKED",\n "startAt": "2021-07-29T13:00:00Z",\n "competitionId": "9530",\n "competitionName": "Test Comp",\n "sportId": 10,\n "sportName": "Football",\n "liveStreams": [\n {\n "id": "c8ed9f88",\n "permissions": [],\n "dmas": [],\n "deliveries": {\n "hls": [\n {\n "id": "AKAMAI"\n }\n ],\n "dash": []\n }\n }\n ]\n }\n ]\n}\n/fixturesThe permissions field in the liveStreams object is now deprecated for the /fixtures endpoint.
\nPlease update your process to no longer rely on this field.
To retrieve permissions, use the GET /fixtures/{id} endpoint, which will continue to provide permissions on a per-fixture basis.
/fixtures (permissions field removed in the future)/fixtures/{id} (still provides permissions per fixture)Update your integration to avoid issues moving forward.
\nIn case you still want to get the permissions in the /fixtures endpoint you should use the queryParam
\nshowPermissions=true, because by default the value is false and the permissions will not be shown.
This is a temporary solution to deprecate the permissions and dmas field of the /fixtures endpoint, the idea is
\nthat this information is obtained from the /fixtures/{id} endpoint and that the /fixtures endpoint works more like
\na schedule to know which fixtures are coming and the /fixtures/{id} endpoint presents specific information of the
\nfixture including the necessary information to consume the streaming parameters.
curl -X GET https://api.geniussports.com/Video-v3/UAT/fixtures?showPermissions=true\\\n -H\
\ "accept: application/json" \\\n -H "x-api-key: environment_token" \\\n -H "Authorization: `IdToken`” \nIt is important to mention that using the queryParam=true will automatically change the pagination limit to 50
\nfixtures per page, in case the limit used is less than 50, the limit of fixtures per page will be maintained.
queryParam=true.{\n "paging": {\n "cursors": {\n "after": "12345",\n "before": "12395"\n },\n "previous": "https://api.geniussports.com/Video-v3/UAT/fixtures?before=12395&limit=50&showPermissions=true",\n "next": "https://api.geniussports.com/Video-v3/UAT/fixtures?after=12345&limit=50&showPermissions=true"\n }\n}\nqueryParam=true and limit=100.{\n "paging": {\n "cursors": {\n "after": "12345",\n "before": "12395"\n },\n "previous": "https://api.geniussports.com/Video-v3/UAT/fixtures?before=12395&limit=50&showPermissions=true",\n "next": "https://api.geniussports.com/Video-v3/UAT/fixtures?after=12345&limit=50&showPermissions=true"\n }\n}\nqueryParam=true and limit=3.{\n "paging": {\n "cursors": {\n "after": "12345",\n "before": "12342"\n },\n "previous": "https://api.geniussports.com/Video-v3/UAT/fixtures?before=12342&limit=3&showPermissions=true",\n "next": "https://api.geniussports.com/Video-v3/UAT/fixtures?after=12345&limit=3&showPermissions=true"\n }\n}\nqueryParam=true.{\n "paging": {\n "cursors": {\n "after": "12345",\n "before": "12145"\n },\n "previous": "https://api.geniussports.com/Video-v3/UAT/fixtures?before=12145&limit=200&showPermissions=false",\n "next": "https://api.geniussports.com/Video-v3/UAT/fixtures?after=12345&limit=3&showPermissions=false"\n }\n}\nCall this resource:
\nGET /regions
This endpoint can be used to get all the territories used by the video API. The response contains a list of continents,
\na list of regions and a list of the DMAs (Designated Market Areas) inside the United States.
Example of a valid request:
\ncurl -X GET https://api.geniussports.com/Video-v3/UAT/regions \\\n -H "accept: application/json" \\\n -H "x-api-key: environment_token" \\\n -H "Authorization: `IdToken`”\nThe following example response contains a subset of each of the components of the real response:
\n{\n "continents": [\n {\n "code": "AF",\n "name": "Africa"\n },\n {\n "code": "AS",\n "name": "Asia"\n\
\ }\n ...\n ],\n "regions": [\n {\n "code": "AD",\n "name": "Andorra",\n "continent": "EU"\n },\n {\n "code": "AE",\n "name": "United Arab Emirates",\n "continent": "AS"\n },\n ...,\n {\n "code": "US_AL",\n "name": "United States - Alabama",\n "continent": "NA"\n },\n {\n "code": "US_AK",\n "name": "United States - Alaska",\n "continent": "NA"\n },\n ...\n ],\n "dmas": [\n {\n "code": "500",\n "cities": [\n "Portland",\n "Auburn"\n ],\n "regions": [\n "US_ME",\n "US_NH"\n ]\n },\n {\n "code": "501",\n "cities": [\n "New York"\n ],\n "regions": [\n "US_CT",\n "US_NJ",\n "US_NY",\n "US_PA"\n ]\n },\n ...\n ]\n}\nThe figure below illustrates the process to obtain streaming parameters to play a given fixture:
\nThe request is checked against the permissions for the particular fixture to see if streaming is allowed. If the check
\nis successful, the response will contain a plaback URL, a CDN access token, and, optionally, some DRM configuration.
\nThis data must the used to configure the video player of the end-user willing to watch the stream.
The endpoints:
\nPOST /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},
\nand {deliveryId} correspond to the fixture, live-stream and delivery ID provided by the Fixture object in any of
\nthe /fixtures endpoints.
The request body has the form:
\n{\n "endUserSessionId": "<some unique end-user identifier>",\n "region": "CO",\n "device": "DESKTOP"\n}\nwhere region must be one of the region codes returned by the /regions/ endpoint; device must be one of the allowed
\ndevice types, and endUserSessionId is a unique, non personally identifiable ID, representing the end-user.
Example of a valid request:
\ncurl --location --request POST 'https://api.geniussports.com/Video-v3/UAT/fixtures/1630290721/live-streams/c8ed9f88/deliveries/hls/AKAMAI' \\ \n --header 'accept: application/json' \\ \n --header 'Content-Type: application/json' \\ \n --header 'x-api-key: environment_token ' \\ \n --header 'Authorization: `IdToken` ' \\ \n --data-raw '{ \n "endUserSessionId": "1d34aacd-f0ab-4d72-b9ce-14a80233de23", \n "region": "CO", \n "device": "DESKTOP" \n }' \nAnd the response could be like this:
\n{\n "url": "https://stream-url/path/playlist.m3u8",\n "expiresAt": "2021-12-12T09:12:00",\n "token": "st=1627648558~exp=1627649158~acl=*~id=1d34aacd-f0ab-4d72-b9ce-14a80233de23~data=reg:CO~hmac=498c6a4842a4176dfe65b067b636a857eb9aab25700f78a13b44e5d510517ebd",\n "drm": {\n "fairplay": "http://...",\n "fairplayCertificate": "https://...",\n "playready": "https://...",\n "widevine": "https://..."\n }\n}\nThis sample response includes a URL, an expiration date and a token. The received token should be appended to the URL as
\na query string parameter when the player makes the request for content to the CDN. In this example the DRM object is not
\nnull, so DRM is required for streaming.
Viewer location and device are important pieces of data for selecting the right Livestream for a given end-user.
\nThe Video-API validates that the permissions for each Livestream are met and hence, correct data passing to the API is
\ncrucial. To this end, there is an HTTP endpoint that returns the location and device type when called from end-users’
\ndevices.
GET https://viewer-data.production.geniuslive.geniussports.comExample of the response from a Desktop computer located in New York(USA)
\n{\n "region": "US_NY",\n "dma": "501",\n "device": "DESKTOP"\n}\nThis endpoint return information such as the region, the\
\ dma and the user device from which the
\nrequest is made. The region and device are used in the livestream permissions and the dma
\nfield is mentioned in the list of valid dmas for each livestream. This information will be useful to choose the correct
\nlivestream and, to send the necessary fields in the request of the streaming parameters.
Consider two users of your website, using the endpoint https://viewer-data.production.geniuslive.geniussports.com
\nwe obtain that:
US_CA (USA California - DMA 803 Los Angeles) using DESKTOP as device.{\n "region": "US_CA",\n "dma": "803",\n "device": "DESKTOP"\n}\nMOBILE device.{\n "region": "JP",\n "dma": "",\n "device": "MOBILE"\n}\nConsider the response for fixture 1234 that looks like:
\n{\n "id": 1234,\n "name": "A v B ON DEMAND TEST On Demand",\n "phase": "IN_PLAY",\n "bookingStatus": "BOOKED",\n "startAt": "2023-08-30T17:50:00Z",\n "competitionId": "9530",\n "competitionName": "TEST COMPETITION",\n "sportId": 10,\n "sportName": "Football",\n "liveStreams": [\n {\n "id": "Livestream1",\n "permissions": [\n {\n "device": "DESKTOP",\n "maxPlayerSizePercentage": 100,\n "region": "US_CA"\n },\n {\n "device": "DESKTOP",\n "maxPlayerSizePercentage": 100,\n "region": "US_NY"\n }\n ],\n "dmas": [\n {\n "dma": "500"\n },\n {\n "dma": "803"\n }\n ],\n "deliveries": {\n "hls": [\n {\n "id": "Akamai"\n }\n ],\n "dash": [\n {\n "id": "Akamai"\n }\n ]\n }\n },\n {\n "id": "Livestream2",\n "permissions": [\n {\n "device": "MOBILE",\n "maxPlayerSizePercentage": 100,\n "region": "JP"\n },\n {\n "device": "DESKTOP",\n "maxPlayerSizePercentage": 100,\n "region": "GB"\n }\n ],\n "dmas": [ ],\n "deliveries": {\n "hls": [\n {\n "id": "Akamai"\n }\n ],\n "dash": [\n {\n "id": "Akamai"\n }\n ]\n }\n }\n ],\n "vodStreams": []\n}\nFor this fixture we have 2 livestreams, Livestream1 is for users within US_CA and US_NY that are
\nusing a DESKTOP computer, the livestream is available only if the users are also located in the DMAs 500 and 803.
\nThen, Livestream2 is for users located in Japan(JP) using MOBILE devices, and for the nited Kingdom(GB) for
\nDESKTOP computers.
For user_1 the livestream that should be used is the livestream1 since it complies with the permission to be in US_CA
\nusing 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
\nlivestream1.
POST /fixtures/1234/vod-streams/livestream1/deliveries/hls/AkamaiThe request body should contain the exact information already extracted from the viewer-data endpoint:
{\n "endUserSessionId": "<some unique end-user identifier>",\n "region": "US_CA",\n "device": "DESKTOP"\n}\nFor the user_2 the livestream that should be used is the livestream2 since it complies with the permission to be in
\nJapan JP using a MOBILE device, in this case there are no DMAs because we only support and validate DMAs inside
\nthe US
It is important to send the correct region and device values for user_1 when obtaining the streaming parameters for the
\nlivestream2.
POST /fixtures/1234/vod-streams/livestream2/deliveries/hls/AkamaiThe request body should contain the exact information already extracted from the viewer-data endpoint:
{\n "endUserSessionId": "<some unique end-user identifier>",\n "region": "JP",\n "device": "MOBILE"\n}\nNOTE: 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
\npossible that the video-api responds with a (403 access denied) mentioning that they do not have permissions to view
\nthat livestream.
Accessing VOD stream parameters follows the same process as live stream:
\nCurrently, only HLS is supported through the endpoint:
\nPOST /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
\nFixture object in any of the /fixtures endpoints.
The request body has the same structure as the one used for live streaming:
\n{\n "endUserSessionId": "<some unique end-user identifier>",\n "region": "CO",\n "device": "DESKTOP"\n}\nwhere region must be one of the region codes returned by the /regions/ endpoint, device must be one of the allowed
\ndevice 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
\ncompleted successfully, the response will contain the data needed for configuring a video-player to stream the content.
Example of a valid request:
\ncurl --location --request POST 'https://api.geniussports.com/Video-v3/UAT/fixtures/1630290721/vod-streams/c8ed9f88/deliveries/hls/AKAMAI' \\ \n--header 'accept: application/json' \\ \n--header 'Content-Type: application/json' \\ \n--header 'x-api-key: environment_token ' \\ \n--header 'Authorization: `IdToken` ' \\ \n--data-raw '{ \n "endUserSessionId": "1d34aacd-f0ab-4d72-b9ce-14a80233de23", \n "region": "CO", \n "device": "DESKTOP" \n}' \nAnd the response could be like this:
\n{\n "url": "https://stream-url/path/playlist.m3u8",\n "expiresAt": "2021-12-12T09:12:00",\n "token": "st=1627648558~exp=1627649158~acl=*~id=1d34aacd-f0ab-4d72-b9ce-14a80233de23~data=reg:CO~hmac=498c6a4842a4176dfe65b067b636a857eb9aab25700f78a13b44e5d510517ebd",\n "drm": null\n} \nIn this case, the response includes the playback URL, an expiration date and a token. The received token should be
\nappended to the URL as a query string parameter when the player makes the request for content to the CDN. The DRM object
\nis null, indicating no DRM is required for this stream.
The access token returned by the streaming parameters endpoint of the Video API should be attached as a query string
\nparameter to the URL for the manifest/index file. Consider a response from
\nthe /fixtures/{id}/live-streams/{streamId}/deliveries/hls/{deliveryId} endpoint:
{\n "url": "https://stream-url/path/playlist.m3u8",\n "expiresAt": "2021-12-12T09:12:00",\n "token": "st=1627648558~exp=1627649158~acl=*~id=1d34aacd-f0ab-4d72-b9ce-14a80233de23~data=reg:CO~hmac=498c6a4842a4176dfe65b067b636a857eb9aab25700f78a13b44e5d510517ebd",\n "drm": {\n "fairplay": "http://...",\n "fairplayCertificate": "https://...",\n "playready": "https://...",\n "widevine": "https://..."\n }\n} \nThe final URL to request the manifest to the CDN will be:
\nhttps://stream-url/path/playlist.m3u8?st=1627648558~exp=1627649158~acl=*~id=1d34aacd-f0ab-4d72-b9ce-14a80233de23~data=reg:CO~hmac=498c6a4842a4176dfe65b067b636a857eb9aab25700f78a13b44e5d510517ebd\n\
Session tokens are created by the CDN and are exchanged with the player during the streaming. For HLS, this session
\ntoken comes embedded in the master manifest. For DASH, the session token comes in a cookie, therefore the player must be
\nconfigured to send cookies in the request. However, some devices and browsers might not be configured to support
\ncookies, so it is important to validate this before selecting the stream delivery to play.
DRM (Digital Rights Management) is a method for adding security to digital content and prevent unauthorized use and
\npiracy. Some competitions require DRM for playback. For those cases, the video will be encrypted and the video player
\nmust 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
\nnot present, then DRM is not required for that delivery. Otherwise the DRM object contains a list of URLs for the
\ndecryption keys, one url for each supported technology. The player needs to select the technology that better suits the
\nclient platform, then get the key using the URL, and finally use that key to decrypt the content during the session.
Consider the following response:
\n{\n "url": "https://stream-url/path/playlist.m3u8",\n "expiresAt": "2021-12-12T09:12:00",\n "token": "st=1627648558~exp=1627649158~acl=*~id=1d34aacd-f0ab-4d72-b9ce-14a80233de23~data=reg:CO~hmac=498c6a4842a4176dfe65b067b636a857eb9aab25700f78a13b44e5d510517ebd",\n "drm": {\n "fairplay": "http://...",\n "fairplayCertificate": "https://...",\n "playready": "https://...",\n "widevine": "https://..."\n }\n}\nThere are three technologies supported for DRM:
\nfairplay and fairplayCertificate values returned in the response.If the selected video player library supports DRM, then it is quite probable that users of the library only have to pass
\nit the urls of decryption keys, and the player library will take the decision of which to use according to the platform.
\nOtherwise, it is possible to create such logic based on this table.
\n\nNote: Testing DRM on iOS requires the use of real devices, as DRM functionality does not work in simulators.
\n
\nEnsure you have access to an iPhone, iPad, or Apple TV to properly validate DRM playback.
The following are the DRM systems enabled by each streaming protocol:
\nThat means the streaming response from Video API will only show you the relevant DRM information by protocol.
\nHowever, if you receive an HLS stream with all three DRM systems (Fairplay, Playready and Widevine), then HLS can be
\nplayed on any platform.