American Football Telemetry V1

1 Players
2 Balls
3 Objects
4 Coordinates Diagram:

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.

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).