American Football Match EventsV2
- Martin Kuks
- Iryna Antonova
- Stoyan Stoyanov
- Matt Williams
- 1 Feed Match Event
- 2 Feed Match Action
- 3 Actions
- 3.1 Fumble
- 3.2 PassAttempt (called Pass in v1)
- 3.3 IncompletePass
- 3.4 CompletePass
- 3.5 Interception
- 3.6 FieldGoal
- 3.7 FieldGoalAttempt
- 3.8 FieldGoalBlocked
- 3.9 TimeoutsRemaining
- 3.10 Timeout
- 3.11 Snap
- 3.12 Touchdown
- 3.13 Single
- 3.14 Run
- 3.15 RunAfterCatch
- 3.16 Kneel
- 3.17 Tackle
- 3.18 Comment
- 3.19 NextPlay
- 3.20 Safety
- 3.21 OnePointSafety
- 3.22 ClockSet
- 3.23 ClockStarted
- 3.24 ClockStopped
- 3.25 CoinToss
- 3.26 ConversionAttempt
- 3.27 OnePointConversion
- 3.28 TwoPointsConversion
- 3.29 OutOfBounds
- 3.30 Touchback
- 3.31 Penalty
- 3.32 Return
- 3.33 Down
- 3.34 Sack
- 3.35 KickOff
- 3.36 Possession
- 3.37 YardsToEndzone
- 3.38 MatchStatusChanged
- 3.39 PeriodChanged
- 3.40 Punt
- 3.41 Risks
- 3.42 FairCatch
- 3.43 Challenge
- 3.44 Lateral
- 4 Other Match Events
- 4.1 Reliability
- 4.2 CurrentLineup
- 4.3 Muff
- 4.4 Recovery
- 5 Players
Feed Match Event
American Football Match Events
Example Ably LiveAccess URL: https://platform.matchstate.api.geniussports.com/api/v1/sources/GeniusPremium/sports/17/fixtures/10173048/liveaccess/matchevents?sportApiVersion=v2
{
"sportId": 17,
"fixtureId": "91143158",
"source": "GeniusPremiumReplay",
"sequenceId": 1606,
"actionId": 839,
"insertedBeforeActionId": null,
"isCancelled": false,
"isConfirmed": false,
"isModified": true,
"action": {},
"messageTimestampUtc": "2022-05-19T10:31:24.0121616Z"
}Element | Type | Description |
|---|---|---|
| Integer | Sport Identifier (17 for American Football) |
| String | Unique fixture identifier |
| String | Feed Provider information |
| Integer | Sequence Id of feed match events |
| Integer | Unique match action identifier |
| Integer | Identifier used to specify before which action Id this specific action was inserted (in case this insertion is done before previously published match events) |
| boolean | Indicates whether the action is cancelled |
| boolean | Indicates whether the action is confirmed |
| boolean | Indicates whether the action is modified |
| Match action array | Consists of Match Action data properties |
| String($date-time) | Timestamp of the message |
Feed Match Action
NOTE: All Feed Match Actions includes the following additional fields (hence it’s not copy-pasted to every action described below).
{
"team": "Home",
"gameTime": "00:10:00",
"period": {
"number": 1,
"progressStatus": "NotStarted",
"type": "Regular"
},
"utcTimestamp": "2023-09-24T18:19:09.5924521Z"
}Element | Type | Description |
|---|---|---|
| string($x-extensible-enum) [ None, Home, Away ] | Team data |
| string($date-span) | Game time data |
| Period array | Period in the game data |
| integer($int32) | Period number |
| string($x-extensible-enum) [ NotStarted, InProgress, Complete ] | Period progress status |
| string($x-extensible-enum) [ Regular, Overtime ] | Period type data |
| string($date-time) | Timestamp of the message |
Actions
NOTE: All Feed Match Actions consist of Feed Match Event + Feed Match Action + Action data properties
Fumble
{
"$type": "GeniusSports.Sports.AmericanFootball.Contracts.V2.MatchEvents.Fumble, GeniusSports.Sports.AmericanFootball.Contracts.V2.MatchEvents",
"subtype": "FumbledHandoff",
"yards": 45,
"yardLine": {
"yards": 45,
"sideOfPitch": "Away"
},
"teamInPossession": "None",
"isNullified": false,
"players": [
{
"id": "999739",
"type": "Fumbled"
}
]
}Element | Type | Description |
|---|---|---|
| string |
|
| Player array | Player data |
| string($x-extensible-enum) | Indicates second level of action description |
| Yardlines array | Indicates enforcement and placement yardlines of the penalty if both available |
| integer($int32) | Unique player Id |
| string | Type of action performed by the player |
| integer($int32) | Yards where the ball was recovered/fumbled |
| string($x-extensible-enum) | Team in possession |
| string($x-extensible-enum) [ None, Home, Away ] | Indicates the side of the pitch if it’s home or away |
| boolean | Indicates whether this action is nullified |
PassAttempt (called Pass in v1)
Element | Type | Description |
|---|---|---|
| string |
|
| Players array | Player data |
| boolean | Indicates whether this action is nullified |
| integer($int32) | Unique player Id |
| string | Type of the player? |
IncompletePass
Element | Type | Description |
|---|---|---|
| string |
|
| Players array | Player data |
| boolean | Indicates whether this action is nullified |
| Yardlines array | Indicates enforcement and placement yardlines of the penalty if both available |
|
|
|
| integer($int32) | Unique player Id |
| string | Type of the player? |
CompletePass
Element | Type | Description |
|---|---|---|
| string |
|
| Players array | Player data |
| boolean | Indicates whether this action is nullified |
| Yardlines array |
|
| integer($int32) | Indicates Air Yards + Yards after catch |
| integer($int32) | Unique player Id |
| string | Type of the player? |
Interception
Element | Type | Description |
|---|---|---|
| string |
|
| boolean | Indicates whether this action is nullified |
| Yardlines array |
|
| Players array | Player data |
| integer($int32) | Unique player Id |
| string | Type of the player? |
FieldGoal
Element | Type | Description |
|---|---|---|
| string |
|
| boolean | Indicates whether FG was made |
| boolean | Indicates whether this action is nullified |
| integer($int32) | Indicates yards from there the FG was taken |
| Yardlines array |
|
| Players array | Player data |
| integer($int32) | Unique player Id |
| string | Type of the player? |
FieldGoalAttempt
Element | Type | Description |
|---|---|---|
| string |
|
| Players array | Player data |
| integer($int32) | Unique player Id |
| string | Type of the player? |
| boolean | Indicates whether this action was nullified |
| Yardlines array |
|
FieldGoalBlocked
Element | Type | Description |
|---|---|---|
| Players array | Player data |
| boolean | Indicates whether this action was nullified |
TimeoutsRemaining
Element | Type | Description |
|---|---|---|
| string |
|
| integer($int32) | Number of timeouts remaining for away team |
| integer($int32) | Number of timeouts remaining for home team |
Timeout
No player or yards data. Just an event to record a timeout fact.
Element | Type | Description |
|---|---|---|
| string |
|
Snap
Element | Type | Description |
|---|---|---|
| string |
|
| boolean | Indicates if it is confirmed or not |
Touchdown
Element | Type | Description |
|---|---|---|
| string |
|
| boolean | Indicates whether this action was nullified |
| Players array | Player data |
| integer($int32) | Unique player Id |
| string | Type of the player? |
Single
Element | Type | Description |
|---|---|---|
| boolean | Indicates whether this action was nullified |
| Player data array | Kicker player data |
| integer($int32) | Unique kicker Id |
| string | two possible values: “Kicker” or null |
Run
Element | Type | Description |
|---|---|---|
| string |
|
| integer($int32) | Indicates how many yards a player rushed |
| boolean | Indicates whether this action was nullified |
| Players array | Player data |
| integer($int32) | Unique player Id |
| string | Type of the player? |
RunAfterCatch
Element | Type | Description |
|---|---|---|
| string |
|
| integer($int32) | Indicates how many yards a player rushed |
| boolean | Indicates whether this action was nullified |
| Players array | Player data |
| integer($int32) | Unique player Id |
| string | Type of the player? |
Kneel
Element | Type | Description |
|---|---|---|
| string |
|
| integer($int32) | Indicates how many yards a player rushed |
| boolean | Indicates whether this action was nullified |
| Yardlines array |
|
| Players array | Player data |
| integer($int32) | Unique player Id |
| string | Type of the player? |
Tackle
Element | Type | Description |
|---|---|---|
| string |
|
| Yardlines array |
|
| string($x-extensible-enum) [ None, Home, Away ] | Indicates the side of the pitch if it’s home or away |
| boolean | Indicates whether this action was nullified |
| Players array | Player data |
| integer($int32) | Unique player Id |
| string | Type of the player? |
| integer($int32) | Indicates where the tackle happened |
Comment
Element | Type | Description |
|---|---|---|
| string |
|
| string | Comments provided by Feed Prodiver |
NextPlay
Element | Type | Description |
|---|---|---|
| string |
|
| string($x-extensible-enum) [ Snap, Kickoff, Pat ] | Next Play Type |
| LOS data array | LOS data |
| integer($int32) | Scrimmage Yard Line |
| string($x-extensible-enum) [ None, Home, Away ] | Indicates the side of the pitch if it’s home or away |
| integer($int32) | Number of the next Down |
| integer($int32) | Yards to go for successful |
| boolean | Indicates if it is confirmed or not |
| string($x-extensible-enum) [ None, Home, Away ] | Team data |
Safety
Element | Type | Description |
|---|---|---|
| boolean | Indicates whether this action was nullified |
| Players array | Player data |
OnePointSafety
Element | Type | Description |
|---|---|---|
| boolean | Indicates whether this action was nullified |
| Players array | Player data |
ClockSet
No player or yards data. Just an event to record a clock set fact.
ClockStarted
No player or yards data. Just an event to record a clock start fact.
Element | Type | Description |
|---|---|---|
| string |
|
ClockStopped
No player or yards data. Just an event to record a clock stop fact.
Element | Type | Description |
|---|---|---|
| string |
|
CoinToss
Element | Type | Description |
|---|---|---|
| string |
|
| integer($int32) | team Id |
| boolean | Indicates whether choice deferred or not |
| string($x-extensible-enum) [ Kick, Receive, EndZone, NorthEndZone, EastEndZone, SouthEndZone, WestEndZone ] | Indicates the away team choice from the available options. |
| string($x-extensible-enum) [ Kick, Receive, EndZone, NorthEndZone, EastEndZone, SouthEndZone, WestEndZone ] | Indicates the home team choice from the available options. |
ConversionAttempt
Element | Type | Description |
|---|---|---|
| string |
|
| string($x-extensible-enum) [ Unknown, OnePoint, TwoPoints ] | Indicated the type of conversion attempt play |
| boolean | Indicates whether this action was nullified |
| Yardlines array |
|
| Players array | Player data |
| integer($int32) | Unique player Id |
| string | Type of the player? |
OnePointConversion
Element | Type | Description |
|---|---|---|
| string |
|
| boolean | Indicates whether this action was made or not |
| boolean | Indicates whether this action was nullified |
| Players array | Player data |
| integer($int32) | Unique player Id |
| string | Type of the player? |
TwoPointsConversion
Element | Type | Description |
|---|---|---|
| string |
|
| boolean | Indicates whether this action was made or not |
| Players array | Player data |
| boolean | Indicates whether this action was nullified |
| integer($int32) | Unique player Id |
| string | Type of the player? |
OutOfBounds
Element | Type | Description |
|---|---|---|
| string [GeniusSports.Sports.AmericanFootball.Contracts.V2.MatchEvents.OutOfBounds, GeniusSports.Sports.AmericanFootball.Contracts.V2.MatchEvents] |
|
| integer($int32) | Indicates the yard line where out of bounds happened |
| Players array | Player data |
Touchback
Element | Type | Description |
|---|---|---|
| string |
|
| boolean | Indicates whether this action was nullified |
| Players array | Player data |
Penalty
Element | Type | Description |
|---|---|---|
| string |
|
| string($x-extensible-enum) Unknown, BlockBelowWaist, BlockingOutOfBounds, ChopBlock, Clipping, ContactingTheKicker, CutBlocking, Defensive12OnField, DefensiveDelayOfGame, DefensiveHolding, DefensiveOffside, DefensivePassInterference, DefensiveTooManyMenOnField, DelayOfGame, DelayOfKickoff, DisconcertingSignals, Disqualification, Encroachment, EquipmentViolation, FaceMask, FairCatchInterference, FalseStart, Fighting, Holding, HoldingReturn, HorseCollarTackle, Hurdling, IllegalBat, IllegalBlindsideBlock, IllegalBlock, IllegalBlockAboveTheWaist, IllegalBlockAboveWaist, IllegalBlockAfterFcSignal, IllegalBlockInBack, IllegalBlockOnReturn, IllegalContact, IllegalContactWithSnapper, IllegalCrackback, IllegalCut, IllegalDoubleTeamBlock, IllegalDownfieldOnKick, IllegalFormation, IllegalForwardPass, IllegalInterferenceCover, IllegalInterferenceOnLooseBall, IllegalKickoff, IllegallyKickingBall, IllegalMotion, IllegalParticipation, IllegalPeelback, IllegalPunt, IllegalShift, IllegalSnap, IllegalSubstitution, IllegalTouchKick, IllegalTouchOfKick, IllegalTouchPass, IllegalUseOfHands, IllegalWedge, IneligibleDownfieldKick, IneligibleDownfieldOnPass, IneligibleDownfieldPass, IneligibleReceiver, IntentionalGrounding, InterferenceWithOpportunityToCatch, InvalidFairCatchSignal, KickCatchInterference, KickoffOutOfBounds, Leaping, Leverage, LowBlock, LoweringHeadToInitiateContact, NeutralZoneInfraction, NoYards15, NoYards5, ObjectionableConduct, Offensive12OnField, OffensiveHolding, OffensiveOffside, OffensivePassInterference, OffensiveTooManyMenOnField, Offside, OffsideOnFreeKick, PassInterference, PersonalFoul, PhysicalAbuseOnOfficial, PilingOn, PlayerOutOfBoundsOnKick, PlayerOutOfBoundsOnPunt, ProcedureGeneral, ProcedureIllegalFormation, ProcedureNoEnd, PushBlocking, Pyramiding, ReturnFromOutOfBounds, RoughingHolder, RoughingTheKicker, RoughingThePasser, RoughPlay, RunningIntoHolder, RunningIntoTheKicker, ShortFreeKick, SidelineInterference, Spearing, Targeting, Taunting, TimeCountAfter3MinuteWarningIntentional, TimeCountAfter3MinuteWarningLoss10Yards, TimeCountAfter3MinuteWarningLossDown, TimeCountAfter3MinuteWarningUnintentional, TimeCountBefore3MinuteWarning, TooManyPlayers, Tripping, UnnecessaryRoughness, UnnecessaryRoughnessMajorGrade2, UnsportsmanlikeConduct | Penalty type |
| integer($int32) | Indicates the amount of yards team was penalized based on the penalty type |
| string($x-extensible-enum) Unknown, Accepted, Declined, Offsetting, Superseded | Outcome of the penalty |
| Yardlines array | Indicates enforcement and placement yardlines of the penalty if both available |
|
|
|
| string($x-extensible-enum) [ None, Home, Away ] | Indicates the side of the pitch if it’s home or away |
| string($x-extensible-enum) Unknown, Accepted, Declined, Offsetting, Superseded | Indicates where the penalty is enforced from. Available options: [Unknown, DeadBall, OtherSpot, PreviousSpot, SuccedingSpot] |
| string($x-extensible-enum) Unknown, Accepted, Declined, Offsetting, Superseded | Indicates if penalty results in firstDown, LossOfDown or down Repeats. Available options: [Unknown, First, Repeats, LossOfDown] |
| Players array | Player data |
| integer($int32) | Unique player Id |
| string | Type of the player? |
Return
Element | Type | Description |
|---|---|---|
| string |
|
| integer($int32) | Indicates the yards gained |
| Yardlines array |
|
| string($x-extensible-enum) [ None, Home, Away ] | Indicates the side of the pitch if it’s home or away |
|
|
|
| boolean | Indicates whether this action was nullified |
| Players array | Player data |
| integer($int32) | Unique player Id |
| string | Type of the player? |
Down
Element | Type | Description |
|---|---|---|
| string |
|
| integer($int32) | Number of the Down in a Play |
| integer($int32) | Indicates yards to go for a successful down |
| integer($int32) | Scrimmage Yard line |
| string($date-span) | game clock data |
| string($date-span) | time of the day |
| string | Description by Feed Provider |
Sack
Element | Type | Description |
|---|---|---|
| string |
|
|
|
|
| integer($int32) | Indicates yards behind the Scrimmage Line |
| boolean | Indicates whether this action was nullified |
| Yardlines array |
|
| Players array | Player data |
| integer($int32) | Unique player Id |
| string | Type of the player? |
KickOff
Element | Type | Description |
|---|---|---|
| string |
|
|
|
|
| integer($int32) | Indicates yards behind the Scrimmage Line |
| boolean | Indicates whether this action was nullified |
| Players array | Player data |
| integer($int32) | Unique player Id |
| string | Type of the player? |
Possession
No player or yards data. Just an event to record a possession of the ball fact.
Element | Type | Description |
|---|---|---|
| string |
|
YardsToEndzone
Element | Type | Description |
|---|---|---|
| string |
|
| integer($int32) | Indicates yards to End Zone |
MatchStatusChanged
Element | Type | Description |
|---|---|---|
| string |
|
| string($x-extensible-enum) [ Unknown, NotStarted, Warmup, InProgress, Postponed, Finished, Interrupted, CoverageStopped, Abandoned, Cancelled, Delayed ] | Indicates match status |
PeriodChanged
No player or yards data. Just an event to record a period change fact.
Element | Type | Description |
|---|---|---|
| string |
|
Punt
Element | Type | Description |
|---|---|---|
| string |
|
| integer($int32) | yards gained |
| boolean | Indicates whether this action was nullified |
| Players array | Player data |
| integer($int32) | Unique player Id |
| string | Type of the player? |
Risks
Element | Type | Description |
|---|---|---|
| string |
|
| string($x-extensible-enum) [ Unknown, Active, NonActive ] | Touchdown risk |
| string($x-extensible-enum) [ Unknown, Active, NonActive ] | Onside Kick risk |
| string($x-extensible-enum) [ Unknown, Active, NonActive ] | Field Goal risk |
| string($x-extensible-enum) [ Unknown, Active, NonActive ] | Fourth Down risk |
| string($x-extensible-enum) [ Unknown, Active, NonActive ] | Safety risk |
| string($x-extensible-enum) [ Unknown, Active, NonActive ] | Challenge risk |
| string($x-extensible-enum) [ Unknown, Active, NonActive ] | Penalty risk |
| string($x-extensible-enum) [ Unknown, Active, NonActive ] | VideoReview risk |
| string($x-extensible-enum) [ Unknown, Active, NonActive ] | Turnover risk |
| string($x-extensible-enum) [ Unknown, Active, NonActive ] | Indicates that the play is about to start (teams are lining up to begin the play). |
| string($x-extensible-enum) [ Unknown, Active, NonActive ] | Other risk |
|
|
|
|
|
|
|
|
|
FairCatch
Element | Type | Description |
|---|---|---|
| string |
|
| integer($int32) | yard line |
| boolean | Indicates whether this action was nullified |
| Yardlines array |
|
| string($x-extensible-enum) [ None, Home, Away ] | Indicates the side of the pitch if it’s home or away |
| Players array | Player data |
| integer($int32) | Unique player Id |
| string | Type of the player? |
Challenge
Element | Type | Description |
|---|---|---|
| string($x-extensible-enum) [ Unknown, Won, Lost ] | Result of the challenge |
Lateral
Element | Type | Description |
|---|---|---|
| integer($int32) | Indicates how many yards was the lateral. |
| Players array | Player data, indicates who lateraled (passer) and who received the lateral (receiver) |
| boolean | Indicates whether this action was nullified |
| integer($int32) |
|
| string |
|
Other Match Events
Reliability
Element | Type | Description |
|---|---|---|
| string |
|
| string($date-time) | Timestamp of the message |
| boolean | Indicates whether the current match events are reliable or not |
| string | Reason |
CurrentLineup
Element | Type | Description |
|---|---|---|
| string |
|
| string | Type of the team players are assigned to |
| Array Of Lineup Player | Lineup players array |
|
|
|
| string | Indicates an Unique id of the player |
| string | Indicates the position of the player. Available options: [Unknown, Kicker, Punter, Returner, RunningBack, Fullback, WideReceiver, TightEnd, Tackle, Guard, Quarterback, Center, End, Linebacker, Cornerback, Safety, Holder, LongSnapper, DefensiveBack, OffensiveLineman, DefensiveLineman] |
| string | Indicates the side of the player. Available options: [Unknown, Right, Middle, Left] |
| string | Indicates the status of the player during the game. Available options: |
Muff
Element | Type | Description |
|---|---|---|
| string |
|
| Players array | Player data |
| integer($int32) | yard line |
| boolean | Indicates whether this action was nullified |
| Yardlines array |
|
| string($x-extensible-enum) [ None, Home, Away ] | Indicates the side of the pitch if it’s home or away |
| integer($int32) | Unique player Id |
| string | Type of the player? |
Recovery
Element | Type | Description |
|---|---|---|
| string |
|
| integer($int32) | Indicates the amount of yards from the point where opponents recovered the ball to the point where the play finished |
| Yardlines array |
|
| string($x-extensible-enum) [ None, Home, Away ] | Indicates the side of the pitch if it’s home or away |
| boolean | Indicates whether this action was nullified |
| Players array | Player data |
| integer($int32) | Unique player Id |
| string | Type of the player? |
Players
Player type | Valid action types | Explanation |
|---|---|---|
|
| This action type is currently used in penalties |
|
| The player that was tackled |
|
| The player who tackled, in case of |
|
| The player who assisted tackling in the tackle (secondary tackler). Tackle can have two tackle assisters and no tackler |
|
| The player who scored the points |
|
| The player who is the intended receiver for a pass or fair catch. In case of conversions, only when pass is attempted |
|
| The player who passed the ball. In case of conversions, only when pass is attempted |
|
| The player who fumbled the ball |
|
| The player who recovered the ball |
|
| The play who kicked the ball. |
|
| The player who runs with the ball. In case of conversions, only when it is rushed |
|
| The player who attempts to make a return with the ball |
|
| The player who intercepts the pass |
|
| The player who blocks the kick |
|
| The player/s who hit the quarterback to the ground |
|
| The player/s who earn pass defended on incomplete pass |
|
| The player who muffs the catch |