American Football Telemetry V1

Example Ably LiveAccess URL: https://platform.matchstate.api.geniussports.com/api/v1/sources/GeniusPremium/sports/17/fixtures/10173048/liveaccess/telemetry


Players

{ "type": "players", "utcTimestamp": "2022-05-30T08:28:29.425Z", "units": { "distance": "Yards", "time": "Seconds" }, "splitType": "Time", "chunks": [{ "identifier": "2022-06-09T16:00:58.5100763Z", "telemetries": [ { "playerId": "31051", "teamId": "35168", "speed": 1.13, "signedAcceleration": -0.28, "unsignedAcceleration": 0.43, "distance": 0.11, "orientation": 321.36, "dirLoad": -0.01, "latLoad": 0.01, "direction": 329.48, "isOnField": true, "x": 12.63, "y": 24.97, "z": 0.0, "dataQualityIndex": 98.58 }, ... ] }] }

Element

Type

Description

Element

Type

Description

type

string

Object identifier

utcTimestamp

String($date-time)

Timestamp of the message

units.distance

string($x-extensible-enum)

[ Meters, Yards ]

Unit used for space

units.time

string($x-extensible-enum)

[ Seconds ]

Unit used for time

splitType

string($x-extensible-enum)

[ Time, Frame]

How data are stored in the chunks

chunks.identifier

String

Identifier used for each chunk, it could be the frameId or the time in utc format according to the splitType 

playerId

String

Player Genius Id

teamId

String

Team Genius Id

speed

Float

Speed of the player (in yards)

signedAcceleration

Float

The signed acceleration value. it it can have negative values and not directional.

unsignedAcceleration

Float

Acceleration of the player

distance

Float

Distance since last timestamp (in yards)

orientation

Float

Orientation of the player

dirLoad

Float

Load acting coincident with the direction of travel

latLoad

Float

Load acting orthogonal to the direction of travel

direction

Float

Direction of the player

isOnField

Boolean

Indicates if the player is on the field

dataQualityIndex

Float

Quality of the tracking from 0 (bad) to 200 (exceptional)

x

Float

x-coordinate of the player

y

Float

y-coordinate of the player

z

Float

z-coordinate of the player

Balls

{ "type": "balls", "utcTimestamp": "2022-05-30T08:28:29.425Z", "units": { "distance": "Yards", "time": "Seconds" }, "splitType": "Time", "chunks": [{ "identifier": "2022-06-09T16:00:58.5100763Z", "telemetries": [ { "ballId": "abcd", "speed": 10.1, "signedAcceleration": 10.1, "unsignedAcceleration": 10.1, "distance": 10.1, "isActiveInThePlay": false, "isOnField": true, "x": 10.1, "y": 10.1, "z": 10.1, "dataQualityIndex": 0.0 }, ... ] }] }

Element

Type

Description

Element

Type

Description

type

string

Object identifier

utcTimestamp

String($date-time)

Timestamp of the message

units.distance

string($x-extensible-enum)

[ Meters, Yards ]

Unit used for space

units.time

string($x-extensible-enum)

[ Seconds ]

Unit used for time

splitType

string($x-extensible-enum)

[ Time, Frame]

How data are stored in the chunks

chunks.identifier

String

Identifier used for each chunk, it could be the frameId or the time in UTC format according to the splitType 

ballId

String

Ball Id

speed

Float

Speed of the player (in yards)

signedAcceleration

Float

The signed acceleration value. it it can have negative values and not directional.

unsignedAcceleration

Float

Acceleration of the player

distance

Float

Distance since last timestamp (in yards)

isActiveInThePlay

Boolean

Indicates if it's the active ball

isOnField

Boolean

Indicates if the balls on the field

dataQualityIndex

Float

Quality of the tracking from 0 (bad) to 200 (exceptional)

x

Float

x-coordinate of the ball

y

Float

y-coordinate of the ball

z

Float

z-coordinate of the ball

Objects

{ "type": "objects", "utcTimestamp": "2022-05-30T08:28:29.425Z", "units": { "distance": "Yards", "time": "Seconds" }, "splitType": "Time", "chunks": [{ "identifier": "2022-06-09T16:00:58.5100763Z", "telemetries": [ { "objectType": "CHAIN_UNIT_2", "x": 60.0, "y": 70.0, "z": 80.0, "dataQualityIndex": 90.0 }, ... ] }] }

Element

Type

Description

Element

Type

Description

type

string

Object identifier

utcTimestamp

String($date-time)

Timestamp of the message

units.distance

string($x-extensible-enum)

[ Meters, Yards ]

Unit used for space

units.time

string($x-extensible-enum)

[ Seconds ]

Unit used for time

splitType

string($x-extensible-enum)

[ Time, Frame]

How data are stored in the chunks

chunks.identifier

String

Identifier used for each chunk, it could be the frameId or the time in UTC format according to the splitType 

objectType

string($x-extensible-enum)

[ OFFICIAL_DOWN_INDICATOR_1, BACKUP_OFFICIAL_DOWN_INDICATOR_1, OFFICIAL_DOWN_INDICATOR_2, BACKUP_OFFICIAL_DOWN_INDICATOR_2, SECOND_BACKUP_OFFICIAL_DOWN_INDICATOR_2, BULLS_EYE, BACKUP_BULLS_EYE, CHAIN_UNIT_1, BACKUP_CHAIN_UNIT_1, CHAIN_UNIT_2, BACKUP_CHAIN_UNIT_2, DRIVE_START_MARKER, BACKUP_DRIVE_START_MARKER, PYLON_1, PYLON_2, PYLON_3, PYLON_4, PYLON_5, PYLON_6, PYLON_7, PYLON_8]

Type of object

dataQualityIndex

Float

Quality of the tracking from 0 (bad) to 200 (exceptional)

x

Float

x-coordinate of the object

y

Float

y-coordinate of the object

z

Float

z-coordinate of the object

Coordinates Diagram:

The diagram helps visualize the coordinates and orientation of objects on an NFL football field, which ties into the telemetry data described in this documentation.

image (99).png



  • Coordinates (x, y, z): The diagram shows a field with increasing X and Y axes, which correspond to the X and Y coordinates provided in the telemetry data for players, balls, and objects. These values help locate a player, ball, or object’s position on the field at a given time.

  • Orientation and direction: The orientation and direction of the football in the diagram show how direction is measured (with 0 degrees pointing toward the top of the field and increasing clockwise). This connects to the "orientation" and "direction" fields in the telemetry data, which provide details on the direction a player or object is facing and moving.

  • Field Zones and Sides: The diagram clearly marks the "Home" and "Visitor" sidelines and endzones. This spatial information is helpful for understanding how telemetry coordinates map to the actual field space, which can be relevant for understanding player positions (e.g., which side of the field they are on).