API

Documentation

Video streaming products are available as a Video API solution and additionally as a Genius Live Player.

Genius Sports offers customers API keys, along with a username and password, to enable seamless access to the streaming service.

For comprehensive guidance, documentation is available at the following links:https://swaggerui.api.geniussports.com/?url=https://explorer.api.geniussports.com/Video%2Fv3%2FPRODPRM%2Fswagger-v3.1.0.json or https://explorer.api.geniussports.com/Video/v3/PRODPRM/public/index.html.

How to get API keys?

In order to obtain API keys, customers are required to contact Genius Sports. Specifically, please reach out to your Account Manager, who will assist you in initiating the integration process, receiving the API keys, and commencing testing.

When requesting access to the Video API, please ensure that you can provide the following information:

a) The territories where you will be operating the streaming product.
b) The email address responsible for booking the streaming.
c) The email address of the key technical personnel who should receive the API keys.

The Video streaming API enables customers to:

• Access the schedule of upcoming streams.

• Obtain the streaming parameters for specific fixtures.

• View the comprehensive list of supported regions for playback.

This API does not provide the video stream directly; rather, it supplies necessary deliverables at least 3 hours prior to the kickoff or tip-off of an event. It specifies the parameters required for streaming a particular fixture. Users of this API are responsible for configuring a video player using these streaming parameters.

Importantly, this API should never be invoked from end-user browser or client code. Instead, it is designed to be integrated into server-side systems.

Pagination

Pagination is a technique used to divide extensive datasets into smaller, more manageable "pages." This method facilitates efficient data management and retrieval, preventing system overload. When working with APIs or databases that return large volumes of data, delivering all the information in a single response is often impractical due to performance and usability concerns. Instead, the data is segmented into multiple pages, each containing a subset of the overall dataset.

It is crucial to implement pagination in your integration. Without this feature, you may not receive all the fixtures booked within a specified time frame on a single page if the total exceeds 200 when calling the endpoint GET /fixtures. In simpler terms, if you book more than 200 fixtures within a given time frame, this change will affect you, as you will be unable to see all the fixtures on a single page. Therefore, you will need to fetch multiple pages to access all the results.

You would need to use following URL https://api.geniussports.com/Video-v3/fixtures?bookingStatus=BOOKED. We anticipate that the customer will filter the results of this call using bookingStatus=BOOKED. This functionality enables the customer to view only the games that are relevant to them.

This is an example of a GET /fixtures endpoint call in which pagination is implemented:
/?limit=5 & before=null & after=11053033 & bookingStatus=BOOKED & fromDate=2024-05-12T00:00Z & toDate=2024-05-20T23:59:59Z
In this example, the limit is set at 5. This means that each time you call the endpoint, it will return 5 results, or in this context, 5 events that have already been BOOKED due to this filter being applied. Additionally, another notable feature is that the after parameter is assigned a specific value.

Open

To effectively retrieve fixtures from subsequent pages, check if the next cursor in the response holds a value. If it does, use this value as the after parameter in your next request. Continue this process, making additional calls as needed, until the response shows that the next cursor has a null value. This indicates that there are no more pages left to retrieve.

Open

Deliveries structure

The StreamDeliveries object specifies the sources for delivering the stream using a designated transport protocol. Presently, both HLS and DASH protocols are supported. For each protocol, multiple sources may be utilized to serve the video content, such as primary and backup CDNs.

Each transport protocol is associated with its own {Protocol}Delivery object, which contains information specific to that protocol.

At this time, the liveStreams capability is available while a given fixture is in the IN_PLAY phase. Subsequently, the liveStreams will be rendered empty.

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.

Genius Live Player

The Genius Live Player is our easy-integration feature designed to get customers live sports video content up and running quickly and with minimal friction. Using our fixture id, the Genius Live Player allows to load any stream that Genius Sports provides, on any device with all DRM and security needs from a streaming player side is taken care of. Customers can find the full user manual for Genius Live Player below.

If you would like to use Betvision product, Genius Live Player is an obligation to be integrated as the integrated widgets that genius Sports provide do not work on the 3rd party players.

Document: Genius Sports Integration Guide – Nextra

How to get Customer ID:

This information will be provided in the email the customer receives with their credentials to access the Video API.

Note about 3rd party player support:

At the moment we do not support any other player besides Genius Live Player.

Key concepts:

Content geoblocking

Genius Sports is handling geoblocking by setting up content restrictions and customer permissions. It restricts access to streaming content based on the viewer's geographic location.

Customer permissions

Permissions are allocated to a customer by region and device.

Some content can also have player-size restrictions. This is a percentage expressed as an integer/float between 0 and 100 indicating the max % the player can take up the full screen.

Regions:

All regions we map are available via the region API, customers will need to call the endpoint to get the available regions for the fixture.

The regions set is a list, but the list has two types of entries. Some entries are only the country code and other entries are the country and state/province code.

• When a province is in the list, the country will not appear alone.

Devices:

• 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
  
  

DRM and non DRM streams:

DRM: It means Digital Rights Management system. It is a protection technology applied by companies that distribute digital content, in our case, NFL has this DRM system due to its contractual agreement. It encrypts the video.

non DRM: All the content that is not NFL will work with non DRM, which means the video has no encryption.

Licensing of the content (packages)

Video Streaming comes in 9 potentially overlapping packages. These packages contain specific competitions of various sports which will make the booking of the streaming available in the Data Services console. In case a customer will like to acquire more packages, they should reach out their Account Manager.

Testing in UAT

Please note that in the UAT environment, most streams are automatically booked for you by default. This means you do not need to make any bookings through the UAT Data Services console for regular non-DRM and DRM continuous fixtures. However, for Betvision fixtures, you should still book the NFL GSIS Replay Manager events using the UAT console at https://dataservices.uat.betgenius.com.

Booking the streams in Production

Video Streaming Fixtures can be conveniently booked through our Data Services console by following this simple workflow:

1. Call the Video API: Begin by requesting the schedule list of all games that offer streaming.

2. Access the Booking Console: Navigate to the booking console (in the Production environment: https://dataservices.betgenius.com) and select the games you wish to book.

3. Retrieve the Streaming URL: Finally, call the API again to obtain the streaming URL. Please note that this URL will only be provided for fixtures that have been booked through the console. Attempting to request a URL for a game that has not been booked will result in an error.

You can find more detailed information on how to book the streams in the Streaming Booking Guide attached here:

If you have any questions regarding the streaming integration process, please feel free to reach out to our team via email, sbonboarding@geniussports.com, or Slack (a communication channel will be established for you). Once you are live with the Streaming product, our Support team will be more than happy to assist you further.