American Football Match State V1
- 1 Ably American Football Match State V1
- 2 Section Explanations
- 2.1 1. firstHalf
- 2.1.1 1.1 drives
- 2.1.2 1.1.1 plays
- 2.1.3 1.1.2 conversionPlays
- 2.1.4 1.1.3 score
- 2.1.5 1.1.4 scrimmageLocation
- 2.1.6 1.1.5 snap
- 2.1.7 1.1.6 period
- 2.1.8 1.1.7 actions
- 2.1.9 1.1.8 penalties
- 2.1.10 1.1.9 players
- 2.1.11 1.1.10 activeUnits
- 2.1.12 1.2 timeouts
- 2.1.13 1.3 timeoutsRemaining
- 2.1.14 1.4 coinToss
- 2.2 2. secondHalf
- 2.3 3. overtimePeriods
- 2.4 4. challenges
- 2.5 5. gameTime
- 2.6 6. matchStatus
- 2.7 7. score
- 2.8 8. homeTeam/awayTeam
- 2.9 comments
- 2.10 currentPossession
- 2.11 yardsToEndzone
- 2.12 risks
- 2.13 nextPlay
- 2.14 source
- 2.15 messageTimestampUtc
- 2.16 isReliable
- 2.17 isCoverageCancelled
- 2.18 reliabilityReasons
- 2.1 1. firstHalf
- 3 Schema definitions
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