Match State Platform Access Control API
- Martin Kuks
- Dimitar Atanasov
Overview
This document explains how to use Match State Platform Access Control API to request access to Genius Sports Ably Push Feeds programmatically.
See Using the Genius Sports Ably Push API for an introduction to Ably.
Obtaining an Ably API Token and Channel Name
In order to request an Ably accessToken and channelName you need to query corresponding /liveaccess endpoint:
Authenticating against Genius Sports APIs
In order to access Genius Sports Match State Platform APIs or Match Statistics API, see Authenticating against Genius Sports APIs.
Ably Access Retrieval
The Access Control API exposes separate endpoints for retrieval of accessToken for match state, match events and telemetry related channels.
The response is JSON with accessToken, channelName, and expiresAtUtc.
{
"accessToken": "FdwyHQ.FF3SGUfCt0xBp78NUshy80g5eTKKBmZ0Sqn_ZJWwW_ACBkGsTPjNxDIWZ700ZCpQR4h0KhMzeZS4dSKK1kHFV586PYbna2XUE7zSgUdzKmyNXZpWWljghJW6k7pj_Wd1PVrlwzGQyH1aEa3hF4xpeVcXWDJ9jflQvAqQE1kwjY-w",
"channelName": "match-state:AmericanFootball:v1:10324:GeniusPremium",
"expiresAtUtc": "2021-06-04T13:12:52.537Z"
}The accessToken and the channelName are used to subscribe to provided Ably channel and consume the data published to that channel.
The access token is valid until the specified timestamp. Once it expires clients have two options to get access to the feed again.
Call again the /liveaccess endpoint and get the new token
Using Ably client of their choice provide an AuthCallback, which is called automatically before the token expires, and renews it. For more info, see Connecting to Ably and Subscribing to a Channel.
NOTE: The format of a channel name should not be considered to be fixed and might change in the future.
Match State Access Retrieval
This example uses the Production Match State API URL for a particular NFL Fixture.
curl -H 'x-api-key: YOUR-API-KEY' -H 'Authorization: YOUR-ACCESS-TOKEN' https://platform.matchstate.api.geniussports.com/api/v1/sources/GeniusPremium/sports/17/fixtures/10324/liveaccessImportant: The fixture that one needs feed for (in our case 10324) should be scheduled in a period of up to 2 days in the future, by the Schedule API.
Match Events Access Retrieval
This example uses the Production Match State API URL for a particular NFL Fixture.
curl -H 'x-api-key: YOUR-API-KEY' -H 'Authorization: YOUR-ACCESS-TOKEN' https://platform.matchstate.api.geniussports.com/api/v1/sources/GeniusPremium/sports/17/fixtures/10324/liveaccess/matcheventsTelemetry Access Retrieval
This example uses the Production Match State API URL for a particular NFL Fixture.
Explicit Sport REST API Version
Each endpoint supports an optional query parameter sportApiVersion for specifying the sport REST API version, i.e.
The default value for sportApiVersion is v1.
Ably Access Revocation (Access Control API v2 Only)
The Access Control v2 API introduces the option to revoke access for a specific resource - the combination of feed (e.g. match state), source, sport, fixture and sportApiVersion.
Revocation can be requested with the same URL you used to request access by adding /revoke and using the HTTP POST method.
Revoking access to a resource will revoke all access tokens for that specific resource for your credentials.
Revocation will block new tokens for the same resource for 1 hour. It is recommended to only use this if access to the resource is not going to be needed.
Revocation is only allowed for fixtures in the future. If a fixture has already started, attempting to revoke access will result in a 400 (Bad Request) response.
Example revocation of match state:
Technical Support
Support Team Contact Details
To get an 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.