Introduction

Statistics Platform delivers Live Match Statistics to any interested customer via Ably. The Statistics are being generated from Match State Events, based on rules configuration.

V2 Documentation and Swagger: https://statistics.api.geniussports.com/docs/openapi

Delivery

Statistics are being delivered through Ably. You can find the Ably integration guide here.
Consumers should subscribe to Fixture and Source specific channel. Channel names follow the pattern "live-statistics:{sportName}:{versionNumber}:{fixtureId}:{sourceId}" (e.g. "live-statistics:AmericanFootball:v1:456789:GeniusPremium"). All consumers that have a token for that channel will receive Live Match Statistics via that channel.
Currently V1 is not available on UAT, but V2 is available on both environments.

Contract

JSON Schema

Example

{
  "metadata": {
    "version": "1.0.0",
    "generatedFromEvent": "1ec6a1ed-d035-4534-abd1-82d5d15aa3b1",
    "updatedAtUtc": "2021-05-26T09:41:20Z",
    "heartbeatExpiresAtUtc": "2021-05-26T09:41:20Z",
  },
  "source": {
    "id": 56,
    "name": "NFL",
    "version": "123.456.756",
    "href": "coverages.api.geniussports.com/v1/sources/56",
  },
  "fixture": {
    "id": 999999,
    "href": "fixtures.api.geniussports.com/v1/fixtures/999999",
  },
  "competitors": [
    {
      "id": 101,
      "href": "fixtures.api.geniussports.com/v1/competitors/101",
      "statistics": {
        "fieldGoalsAttempted": 15,
        "fieldGoalsMade": 5,
        "fieldGoalsPercentage": 0.33333,
        "fouledOutPlayers": 2,
        ...
      },
      "participants": [
        {
          "id": 987987,
          "href": "fixtures.api.geniussports.com/v1/players/987987",
          "statistics": {
            "fieldGoalsAttempted": 1,
            "fieldGoalsMade": 1,
            "fieldGoalsPercentage": 1.00000,
            "fouledOut": false,
          },
        },
        {
          "id": 123456,
          "href": "fixtures.api.geniussports.com/v1/players/123456",
          "statistics": {
            "fieldGoalsAttempted": 10,
            "fieldGoalsMade": 1,
            "fieldGoalsPercentage": 0.10000,
            "fouledOut": true,
          },
        },
        ...
      ],
    }, {
      "id": 404,
      "href": "fixtures.api.geniussports.com/v1/competitors/404",
      "statistics": {
        "fieldGoalsAttempted": 10,
        "fieldGoalsMade": 5,
        "fieldGoalsPercentage": 0.50000,
        "fouledOutPlayers": 0,
        ...
      },
      "participants": [],
    }
  ],
}

Section Explanations

metadata

The metadata section contains information about the message itself.

{
  "version": "1.0.0",
  "generatedFromEvent": "125367489-45678-3246587-1357"
  "updatedAtUtc": "2021-05-26T09:41:20Z",
  "heartbeatExpiresAtUtc": "2021-05-26T09:41:30Z",
}

version	string	The version of the Statistics Contract.
generatedFromEvent	string - UUID	The UUID of the last event in Match State that affected the statistics.
updatedAtUtc	ISO 8601 timestamp	The timestamp when the statistics were updated.
heartbeatExpiresAtUtc	ISO 8601 timestamp	The timestamp by when you should expect another message.

source

The source section contains information about the source, that is providing Match Events.

{
  "id": 56,
  "name": "LiveStats",
  "version": "123.456.756",
  "href": "coverages.api.geniussports.com/v1/sources/56",
}

id	int	The id of the Match Events Source
name	string	The name of the Match Events Source
version	string	The version of the Match Events Source
href	string - url	The link to the Match Events Source details

fixture

The fixture section contains minimal information about the Match.

id	int	The id of the Fixture
href	string - url	The link to the Fixture details

competitors

The competitors array contains competitor objects, that contain minimal information about the competitors within the match, a list of competitor participants, and competitor statistics.

This is usually used to represent Teams in Team-based sports and Players in 1-v-1 sports.

id	int	The id of the Competitor
href	string - url	The link to the Competitor details
statistics	object	The statistics object for the Competitor

participants

The participants array contains participant objects, that contain minimal information about the participant in a competitor and participant statistics.

This is usually used to represent Players/Coaches in Team-based sports.

id	int	The id of the Participant
href	string - url	The link to the Participant details
statistics	object	The statistics object for the Participant

statistics

The statistics object contains the list of statistics for the entity that it is presented in.

Missing statistics are omitted, and statistics with a value of 0 mean that the value of the statistic is 0.

Swagger

You can use the Statistics API Swagger to try out the calls and investigate the schema files.

Statistics API Swagger

UAT Statistics API Swagger