1 Introduction
2 Terminology
3 Technology Overview
4 Getting Started
5 Technical Details
- 5.1 Environments and Ably
- 5.2 API Changes and Versioning
- 5.3 Monitoring Feed Liveness and Data Reliability
  - 5.3.1 Monitoring your connection to Ably
- 5.4 Message Expiry
6 Technical Support
- 6.1 Support Contact Details
7 Frequently Asked Questions

Introduction

This document explains how to connect to Ably and receive “push feeds” where messages are sent by Genius Sports to clients as sporting actions occur. E.g. a message may describe a goal being scored or a sporting fixture starting.

A catalog of available feeds may be found in API Explorer for Genius Ably Push Feeds which describes the available data in detail.

Terminology

Ably Channel - Channels are the medium through which messages are distributed. Clients attach to channels to subscribe to messages, and every message published to a unique channel is broadcast by Ably to all subscribers. This messaging pattern is commonly called the Publish–subscribe pattern. You can read more about Ably Channels here.
Access Token - Ably’s authentication token required to establish a connection with Ably. You can learn more about this here.
Client Library - Ably’s public open-source SDKs provided to clients to simplify the software development work required by users of Ably. More information is available here.

Technology Overview

The API is implemented using the Ably platform. Ably acts as a high-performance communication hub between Genius Sports and clients of the API around the World.

Getting Started

The example code we show throughout this document is in C#. Ably supports many different programming languages and has documentation on the Ably Website including example code for each of them.

This section describes the steps needed to connect to Ably and receive messages.

The easiest way to consume messages from Ably is to download the Ably client-side library for your language of choice.

For example if using Visual Studio and .Net (C#) you can install the library using the following command in Visual Studio’s Package Manager Console:

Install-Package ably.io

The example .Net code below requires the following Ably namespaces:

using IO.Ably;
using IO.Ably.Realtime;

It is also possible to connect directly without using Ably’s own libraries and more information about that is available here.

Before you can start using the code below you will need to get the following secrets from Genius Sports Support Team:

Client ID
Client Secret
API Key

To access uat environment, add .uat to the URLs documented in the section below:
https://uat.auth.api.geniussports.com/oauth2/token
https://platform.uat.matchstate.api.geniussports.com/api/v1

1. Obtaining an Access Token for the Match State Platform API

First, you will need to get an access token for the Match State Platform API.

var url = "https://auth.api.geniussports.com/oauth2/token";
var body = new Dictionary<string, string> {
	{"grant_type", "client_credentials"},
	{"client_id", "CLIENT_ID"},
	{"client_secret", "CLIENT_SECRET"}
};

var httpClient = new HttpClient();
var response = await httpClient.PostAsync(url, new FormUrlEncodedContent(body));
var responseBody = await response.Content.ReadAsStringAsync();

var tokenEnvelope = JsonConvert.DeserializeObject<JObject>(responseBody);
var accessToken = tokenEnvelope["access_token"].ToString();

Please refer to Authenticating against Genius Sports APIs for more information about authenticating against our API’s in both the User Acceptance Testing and Production environments.

2. Consuming the Fixture Schedule

To be able to connect to Ably channel you will need to know the Fixture ID. You can get the fixtures with available feeds using the Match State Platform Schedule API.

var sourceId = "GeniusPremium";
var sportId = 17; // American Football
var from = DateTime.UtcNow.ToString("s");
var to = DateTime.UtcNow.AddDays(2).ToString("s");
var baseUrl = "https://platform.matchstate.api.geniussports.com/api/v1";
var url = $"{baseUrl}/sources/{sourceId}/sports/{sportId}/schedule?from={from}&to={to}";

var httpClient = new HttpClient();
httpClient.DefaultRequestHeaders.Add("Authorization", "{ACCESS_TOKEN}");
httpClient.DefaultRequestHeaders.Add("x-api-key", "{API_KEY}");

var response = await httpClient.GetAsync(url);
var responseBody = await response.Content.ReadAsStringAsync();

var schedule = JsonConvert.DeserializeObject<JArray>(responseBody);
var fixtureId = schedule[0]["fixtureId"].ToString();

2.5. Obtaining competitor information:

You can retrieve competitor information, as well as other information such as competitions, venues, etc, from our FixtureAPI. Please note that the client credentials for the Fixture API are different from those of the Ably APIs.
Fixture API

3. Obtaining an Ably Access Token and a Channel Name

Now when you have a {FIXTURE_ID} you will need to call the appropriate endpoint as described in Match State Platform Access Control API to get the Ably Channel Name and Ably Access Token.

Important: The FIXTURE_ID should be scheduled in a period of between 5 days in the past and 2 days in the future, by the Match State Platform Schedule API in order for the Access Control API to return a channel & token.

async Task<(string channelName, string accessToken)> GetAblyFeed()
{
    var sourceId = "GeniusPremium";
    var sportId = 17; // American Football
    var fixtureId = "{FIXTURE_ID}";
    var baseUrl = "https://platform.matchstate.api.geniussports.com/api/v1";
    var url = $"{baseUrl}/sources/{sourceId}/sports/{sportId}/fixtures/{fixtureId}/liveaccess";
    
    var httpClient = new HttpClient();
    httpClient.DefaultRequestHeaders.Add("Authorization", "{ACCESS_TOKEN}");
    httpClient.DefaultRequestHeaders.Add("x-api-key", "{API_KEY}");
    
    var response = await httpClient.GetAsync(url);
    var responseBody = await response.Content.ReadAsStringAsync();
    
    var ablyFeed = JsonConvert.DeserializeObject<JObject>(responseBody);
    var ablyChannelName = ablyFeed["channelName"].ToString();
    var ablyAccessToken = ablyFeed["accessToken"].ToString();
    return (ablyChannelName, ablyAccessToken);
}

4. Refreshing an Ably Access Token

An Ably Access Token will normally expire after some time. To handle that problem you will need to implement the method that Ably Client will call to refresh the token:

5. Connecting to Ably and Subscribing to a Channel

Now everything is ready to start listening for the Match State.

See API Explorer for Genius Ably Push Feeds for information about the available channels, their names, and message formats.

More information and examples of how to subscribe to channels can be found in the official ReadMe files in Ably’s GitHub account for the downloaded SDK.

Technical Details

Environments and Ably

Genius Sports provides the following Ably environments for customer use:

Production
UAT

Which Ably environment a client connects to is determined by the Access Token so please take care to use the correct key for each environment.

API Changes and Versioning

From time to time Genius Sports may make changes to the format of the data provided through its API. Where possible these changes will be made in a non-breaking additive manner. Clients of the contract should be notified, and if they are not interested in the new fields they can simply ignore them.

On rare occasions, a breaking change to the contract may be required. This will be done in a rolling update manner with the older and newer version of the contract published simultaneously in different Ably channels for a pre-defined period in order to provide users of the contract time to upgrade before the old contract channel is turned off.

Monitoring Feed Liveness and Data Reliability

Monitoring your connection to Ably

The AblyRealtime object that is returned when connecting to Ably exposes a property Connection. The Connection exposes an On method that allows the client to subscribe to channel events such as: Initialized, Connecting, Connected, Disconnected, Suspended, Closing, Closed, Failed

The Connection exposes another property State, having one of the following values: Initialized, Connecting, Connected, Disconnected, Suspended, Closing, Closed, Failed.

Any other state than Connected means that the connection to Ably is lost. This property is constantly updated by the client-side library.

For more details consult Ably’s documentation.

Message Expiry

By default, a message will be available to be consumed from a channel for two minutes from publication. This means consumers experiencing brief connection drops will not miss any messages. If a consumer is offline for more than two minutes they can either:

Simply wait for the next message to be published if the messages they are consuming are complete in themselves, rather than being event-based
Request the latest information from the appropriate REST API i.e. essentially using the REST API as a bootstrap mechanism.

Technical Support

Support Contact Details

To get a Client Id, Client Secret and API Key please contact: apikey@geniussports.com

For technical support for an integrating customer please contact customerintegrations@geniussports.com. For live customers please contact, Genius Sports Support Team at the following address: support@geniussports.com.

Frequently Asked Questions

Why did Genius Sports select Ably as the technology to deliver a Push API for clients?

Ably provides market-leading technology for worldwide, low latency, highly resilient message delivery. Ably supports many different programming languages through its client libraries and also supports direct access through Web Sockets for customers who prefer to write their own access logic.

How do I obtain a client library to connect to Ably?

Following the Ably documentation the users can download the client-side library for the language of their choice from here.

For example, Genius Sports uses the following client-side library itself for .Net GitHub - ably/ably-dotnet: .NET, MAUI, Xamarin, Mono and Unity client library SDK for Ably realtime messaging service version 1.2

What Operating Systems and Languages does Ably support?

Any OS that supports the client-side libraries. In our case, these are all major OPs - Windows, Linux, Macintosh. The Ably Realtime client library is available in the most popular languages and platforms including JavaScript, iOS, Android, Java, .NET, Node.js, Ruby, and more.

Are there any limitations around the number of open Ably connections?

Ably Realtime instance represents a single connection to Ably. Currently an Ably token which is issued by Genius APIs, only allows subscribing to a single channel and thus consuming data for a single fixture. Looking forward, this limitation would be mitigated by issuing tokens that allow access to multiple channels but until then, there is no customer specific limit for the number of connections that can be established. There is a hard limit of inbound messages per connection which is 100 messages per second.

Are there any limitations around the number of channel subscriptions per connection?

Yes. There is a hard limit of a maximum of 200 channels per connection.

When should I open the channel subscription?

We do not recommend subscribing to a channel too much before fixture start time. We suggest 3 hours before the kickoff should be a sensible interval of time to create your subscription. Creating a subscription to channel with no publisher will not result in an error. Please keep in mind that each Ably access token has expiration time and needs to be refreshed so if you create a subscription too early, you will have to refresh the token multiple times.

Genius Sports Integration Documents

Genius Sports Live Sports Data Push API via Ably