American Football Match State V1

Ably American Football Match State V1

Introduction

The document describes the American Football V1 Match state contract and provides examples of using it.

American Football Match State

Section Explanations

1. firstHalf

The firstHalf section contains information about the coin toss results, all drives of the half, timeouts taken by the teams during this half and remaining timeouts for each team.

{ "drives": [{}], "timeouts": [{}], "timeoutsRemaining": {}, "coinToss": {} }

Use case:

1.1 drives

The drives array contains drive objects that contain information about team who was in possession of that drive, indication was it a kickoff drive or not, list of all plays and conversion plays happened during the drive as well as basic information about the scores and indication if it is a finished drive or not.

{ "teamInPossession": "Home", "isKickOff": true, "plays": [{}], "conversionPlays": [{}], "score": [{}], "isFinished": true }

1.1.1 plays

The plays array contains play objects that contain general information about the play as well as list of all play actions and list of penalties associated with the play.

{ "sequence": 2, "downNumber": 1, "yardsToGo": 10, "scrimmageLocation": {}, "snap": {}, "isVoid": false, "isConfirmed": true, "isFinished": false, "period": {}, "actions": [{}], "penalties": [{}], "startedAtGameTime": "00:12:43", "endedAtGameTime": "00:12:11", "startedAtUtc": "2021-06-02T20:31:36.955Z", "endedAtUtc": "2021-06-02T20:31:36.955Z", "description": "(12:43) K.Cousins pass deep left to A.Thielen to HST 49 for 18 yards (E.Murray)." }

1.1.2 conversionPlays

The conversionPlays array contains conversionPlay objects that contain similar information to regular play object, but is used either for one point or two point conversions.

1.1.3 score

The score array contains score object that contains information about how the score was gained, which team scored, how many points and period when it happened.

1.1.4 scrimmageLocation

The scrimmageLocation section contains basic information about the line of scrimmage.

1.1.5 snap

The snap section contains basic information about the snap action - time when it happened and whether it’s confirmed.

1.1.6 period

The period section contains basic information about the period number and if it’s a regular period or an overtime.

1.1.6 periodWithStatus

The period section contains basic information about the period number and if it’s a regular period or an overtime and its status

1.1.7 actions

The actions array contains action objects that contain information about specific action of the play - which team made the action, what kind of action was it, players involved.

1.1.8 penalties

The penalties array contains penalty objects that contain information about the given penalty - which team got the penalty, which player, what kind of penalty and penalty yards.

1.1.9 players

The players array contains player object that contains basic information about the player.

1.1.10 activeUnits

The activeUnits section contains information about what kind of players were involved on the field - defense, offense or special team.

1.2 timeouts

The timeouts array contains timeout objects that contain general information about each timeout taken during the half of the match.

1.3 timeoutsRemaining

The timeoutsRemaining section contains basic information - how many timeouts are remaining for each team.

1.4 coinToss

The coinToss section contains information about the outcome of coin toss in the beginning of each half.

2. secondHalf

The secondHalf section is identical to the firstHalf section structure described above.

3. overtimePeriods

The overtimePeriods array contains overtimePeriod objects that contain information about each overtime. It has identical structure to halfs with one exception - in addition it has “period” property.

4. challenges

The challenges array contains challenge objects that contain general information about challenge - which team challenged, when and what was the result.

5. gameTime

The gameTime section contains information about the game clock - what’s the clock value, when was it last updated and is it running at the moment.

6. matchStatus

The matchStatus property reflects the current match status.

6.1 periodWithStatus

The periodWithStatus property describes the current period and its status.

7. score

The score section contains information about the latest score of the match.

8. homeTeam/awayTeam

The homeTeam and awayTeam sections contain list of players who are playing as part of offensive, defensive or special teams in the match.

8.1 offensive/defensive/special

The offensive/defensive/special array contain lineupPlayer object that contains information about the players (lineup) - player id, name, position he is playing and side.

comments

The comments section contains comment objects that contain the text of comment and time when it was entered.

currentPossession

The currentPossession section contains information about the team which is in possession and time when it was last updated.

yardsToEndzone

The yardsToEndzone section contains information about how many yards are from team’s endzone and when this information was last updated.

risks

The risks section contains a list of risks that are important to consider (significant events) for betting purposes.

nextPlay

Describes precise enough details of what would be the characteristics of the next play, before it is actually created

source

The source property describes the source that is providing the feed for Match State. For NFL the following options will be available - GeniusPremium, GeniusPremiumReplay,

messageTimestampUtc

The messageTimestampUtc property indicates the exact time of this match state message.

isReliable

The isReliable property is used to note whether the given match state is reliable or not. This property is a result of the reliabilityReasons statuses.

isCoverageCancelled

The isCoverageCancelled property is used to note whether the coverage of this match has been cancelled or not.

reliabilityReasons

The reliabilityReasons section contains a list of items considered in order to make an automatic decision whether the match state is reliable or not.

Schema definitions