Football Match State V1 (old)

1 Ably Football Match State V1
- 1.1 Introduction
- 1.2 Football Match State
2 Section Explanations
- 2.1 matchActions
  - 2.1.1 collections specific properties
  - 2.1.2 goals
  - 2.1.3 yellowCards
  - 2.1.4 secondYellowCards
  - 2.1.5 straightRedCards
  - 2.1.6 penalties
  - 2.1.7 penaltyRiskStateChanges
  - 2.1.8 substitutions
  - 2.1.9 shotsOnTarget
  - 2.1.10 shotsOffTarget
  - 2.1.11 shotsOffWoodwork
  - 2.1.12 blockedShots
  - 2.1.13 corners
  - 2.1.14 cornersV2
  - 2.1.15 penaltiesAwarded
  - 2.1.16 fouls
  - 2.1.17 offsides
  - 2.1.18 goalKicks
  - 2.1.19 missedPenalties
  - 2.1.20 savedPenalties
  - 2.1.21 throwIns
  - 2.1.22 possessionChanges
  - 2.1.23 stoppageTimeAnnouncements
  - 2.1.24 phaseChanges
  - 2.1.25 clockActions
  - 2.1.26 dangerStateChanges
  - 2.1.27 bookingStateChanges
  - 2.1.28 lineupUpdates
  - 2.1.29 systemMessages
  - 2.1.30 kickOffs
  - 2.1.31 varStateChanges
- 2.2 matchStatus
- 2.3 statistics
- 2.4 awayTeam
- 2.5 homeTeam
- 2.6 other
  - 2.6.1 source
  - 2.6.2 fixtureId
  - 2.6.3 sequence
  - 2.6.4 messageTimestampUtc
  - 2.6.5 isReliable
  - 2.6.6 isCoverageCancelled
  - 2.6.7 reliabilityReasons

Ably Football Match State V1

Introduction

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

Example API calls:
PullAPI: https://platform.matchstate.api.geniussports.com/api/v1/sources/GeniusSportsInPlay/sports/10/fixtures/10489892
Ably LiveAccess: https://platform.matchstate.api.geniussports.com/api/v1/sources/GeniusSportsInPlay/sports/10/fixtures/10489892/liveaccess

Football Match State

Section Explanations

matchActions

NOTE: All Match Actions includes the following additional fields (hence description is not copied in below actions).

"matchActions": [
        {
            "id": 0,
            "sequenceId": 0,
            "phase": "PreMatch",
            "timeElapsedInPhase": "string",
            "team": "Home",
            "playerInternalId": "string",
            "isConfirmed": true,
            "timestampUtc": "2022-10-19T14:16:10.998Z"
        }

`id`	A unique identifier of the action
`sequenceId`	Within the scope of the action collection, the sequence of the action
`phase`	Enum that describes the phase at which the action occurred: PreMatch, FirstHalf, HalfTime, SecondHalf, PostMatch, FullTimeNormalTime, ExtraTimeFirstHalf, ExtraTimeHalfTime, ExtraTimeSecondHalf, Penalties
`timeElapsedInPhase`	The time in seconds in the phase that the action occured
`team`	Indicates which team made that action
`playerInternalId`	The player id that the action was awarded to
`isConfirmed`	Indicates whether the action is confirmed
`timestampUtc`	The Utc timestamp of the action

collections specific properties

NOTE: All Match Actions collections can include the following additional fields.

{
    "isCollected": true,
    "isReliable": true,
    "timestampUtc": "2022-10-19T14:16:10.999Z"
}

`isCollected`	True if this data type is being collected for this fixture, False otherwise
`isReliable`	Indicates whether the current match collection is reliable or not
`timestampUtc`	The Utc timestamp of the collection

goals

The collection of goals scored in a match.

"goals": {
    "goals": [
        {
            "id": 0,
            "sequenceId": 0,
            "phase": "PreMatch",
            "timeElapsedInPhase": "string",
            "team": "Home",
            "scoredByInternalId": "string",
            "assistByInternalId": "string",
            "isOwnGoal": true,
            "wasScoredFromPenalty": true,
            "isConfirmed": true,
            "timestampUtc": "2022-10-19T14:16:10.998Z"
        }
    ]

`scoredByInternalId`	The player that scored the goal
`assistByInternalId`	The player assisted in the scoring of the goal
`isOwnGoal`	True if this was an own goal, False otherwise. Will be null if it is not known whether goal was an own goal
`wasScoredFromPenalty`	True if this goal was scored from a penalty, False otherwise. Will be null if it is not known whether goal was scored from a penalty

yellowCards

The collection of yellow cards awarded.

secondYellowCards

The collection of second yellow cards awarded.

straightRedCards

The collection of straight red cards awarded.

penalties

The collection contains information about the given penalty.

penaltyOutcome

The penalty outcome with one of the following properties: NotTaken, Retaken, Missed, Scored

penaltyRiskStateChanges

The collection of penalty risk changes will include “Start” and “Stop” of penalty risk actions.

penaltyRiskState

The risk state of a penalty with the following properties : Home/AwayDanger,Home/AwaySafe

substitutions

The collection lists all the player substitutions that occur in a match.

`playerOnInternalId`	The player id coming onto the pitch
`playerOffInternalId`	The player id coming off the pitch

shotsOnTarget

The collection of on-target shots by each team

`savedByInternalId`	The player id that saved the shot
`ballReturnedToPlay`	If the ball was returned to play

shotsOffTarget

The collection of off-target shots by each team

shotsOffWoodwork

The collection of times each team has hit the woodwork

ballReturnedToPlay

If the ball was returned to play

blockedShots

The collection of times each team has had an on-target shot blocked

corners

The collection of corners awarded to each team

cornersV2

The new collection of corners awarded to each team

`awarded`	Object contains corner awarded properties: `isConfirmed, timestampUtc, timeElapsedInPhase`
`taken`	Object contains corner taken properties: `isConfirmed, timestampUtc, timeElapsedInPhase`

penaltiesAwarded

The collection of awarded penalties

fouls

The collection of fouls committed by each team

`foulingTeam`	The team that made the foul
`fouledPlayerInternalId`	The player id that was fouled
`fouledByInternalId`	The player id that cause the foul

offsides

The collection of offsides by each team

goalKicks

The collection of goal kicks by each team

missedPenalties

The collection of missed penalties by each team

savedPenalties

The collection of saved penalties by each team

throwIns

The collection of throw Ins by each team

possessionChanges

The collection of possession data changes by each team

stoppageTimeAnnouncements

The collection of stoppage announcement time by each team

addedMinutes

Game’s stoppage time

phaseChanges

The collection of match phase changes in order by each team

`previousPhase`	Enum that describes the previous phase of the match
`currentPhase`	Enum that describes the current phase of the match
`currentPhaseStartTime`	The start time of the current phase

clockActions

The collection of clock actions

`activityType`	An Enum describing the clock activity. Possible values are: `Start, Stop, Adjustment`
`isClockRunning`	True if the clock is running, False otherwise

dangerStateChanges

The collection of danger state changes

dangerState

Enum of danger state data: Unknown, Safe, Attack, DangerousAttack

bookingStateChanges

The collection of booking state changes

bookingState

An Enum that describes the current booking state. Possible values: Safe, YellowCardDanger, RedCardDanger

lineupUpdates

The collection of all the changes in lineups

`updates`	An array of changes to the lineups
`newLineup`	A lineup
`startingOnPitch`	An array of Player objects listing players who will start the match on the pitch: `internalId` : An unique identifier for the player (internal) `sourceId` : An unique identifier for the player (source) `sourceName` : The player's name `shirtNumber` : The player's shirt number `playerPosition` : The player's possition
`startingBench`	An array of Player objects listing players who will start the match on the bench

`formation`	The formation for the team

systemMessages

The collection of any system messages sent regarding the match

`messageId`	Message identifier
`message`	The actual message

kickOffs

The collection of kickoffs by each team

varStateChanges

The collection of var state changes

`varState`	An Enum that describes the current Video Assistant Referee state. Possible values: `Safe, InProgress, Danger`
`varReason`	Enum that describes the reason for the var: `NotSet, HomeGoal, HomePenalty, HomeRedCard, HomeMistakenIdentity, AwayGoal, AwayPenalty, AwayRedCard, AwayMistakenIdentity, Goal, Penalty, RedCard, MistakenIdentity, HomeUnknown, AwayUnknown, Unknown, PenaltyRetake, HomePenaltyRetake, AwayPenaltyRetake`
`varOutcome`	Enum that describes the outcome of the var: NotSet, HomeNoGoal, AwayNoGoal, NoGoal, HomeGoalAwarded, AwayGoalAwarded, GoalAwarded, HomeNoPenalty, AwayNoPenalty, NoPenalty, HomePenaltyAwarded, AwayPenaltyAwarded, PenaltyAwarded, HomeNoRedCard, AwayNoRedCard, NoRedCard, HomeRedCardGiven, AwayRedCardGiven, RedCardGiven, HomePlayerNotChanged, AwayPlayerNotChanged, PlayerNotChanged, HomePlayerChanged, AwayPlayerChanged, PlayerChanged, HomeNoAction, AwayNoAction, NoAction, HomeUnknown, AwayUnknown, Unknown, HomePenaltyWillBeRetaken, AwayPenaltyWillBeRetaken, HomeNoPenaltyRetake, AwayNoPenaltyRetake, PenaltyWillBeRetaken, NoPenaltyRetake
`varReasonV2`	(V2) An Enum that describes the current Video Assistant Referee outcome. Possible values: NotSet (Default), HomeNoGoal, AwayNoGoal, NoGoal, HomeGoalAwarded, AwayGoalAwarded, GoalAwarded, HomeNoPenalty, AwayNoPenalty, NoPenalty, HomePenaltyAwarded, AwayPenaltyAwarded, PenaltyAwarded, HomeNoRedCard, AwayNoRedCard, NoRedCard, HomeRedCardGiven, AwayRedCardGiven, RedCardGiven, HomePlayerNotChanged, AwayPlayerNotChanged, PlayerNotChanged, HomePlayerChanged, AwayPlayerChanged, PlayerChanged, HomeNoAction, AwayNoAction, NoAction, HomeUnknown, AwayUnknown, Unknown, PenaltyRetake, HomePenaltyRetake, AwayPenaltyRetake
`varOutcomeV2`	(V2) An Enum that describes the current Video Assistant Referee outcome. Possible values: NotSet (Default), HomeNoGoal, AwayNoGoal, NoGoal, HomeGoalAwarded, AwayGoalAwarded, GoalAwarded, HomeNoPenalty, AwayNoPenalty, NoPenalty, HomePenaltyAwarded, AwayPenaltyAwarded, PenaltyAwarded, HomeNoRedCard, AwayNoRedCard, NoRedCard, HomeRedCardGiven, AwayRedCardGiven, RedCardGiven, HomePlayerNotChanged, AwayPlayerNotChanged, PlayerNotChanged, HomePlayerChanged, AwayPlayerChanged, PlayerChanged, HomeNoAction, AwayNoAction, NoAction, HomeUnknown, AwayUnknown, Unknown, HomePenaltyWillBeRetaken, AwayPenaltyWillBeRetaken, HomeNoPenaltyRetake, AwayNoPenaltyRetake, PenaltyWillBeRetaken, NoPenaltyRetake

matchStatus

The matchStatus property reflects the current match status.

"matchStatus": "Finished"

matchStatus

Enum that describes the current match status: Unknown, NotStarted, Warmup, InProgress, Postponed, Finished, Interrupted, CoverageStopped, CoverageResumed, Abandoned, Cancelled, Delayed

statistics

Statistics for the match

awayTeam

Indicates the away team details

sourceId

Away team Id

sourceName

Away team name

strip

Describes strip details.

color1: Describes the teams primary color

color2: Describes the teams secondary color

pantsColor: Describes the teams pants color

socksColor: Describes the teams socks color

*All colors are RGB scale

jerseyDesign: Describes the jersey design, possible values are: Unknown, Plain, StripedHorizontal, StripedVertical, BarHorizontal, BarVertical

homeTeam

Indicates the away team details

sourceId

Home team Id

sourceName

Home team name

strip

Describes strip details.

color1: Describes the teams primary color

color2: Describes the teams secondary color

pantsColor: Describes the teams pants color

socksColor: Describes the teams socks color

*All colors are RGB scale

jerseyDesign: Describes the jersey design, possible values are: Unknown, Plain, StripedHorizontal, StripedVertical, BarHorizontal, BarVertical

other

Overview of the game data

source

The source property describes the source that is providing the feed for Match State

fixtureId

The fixtureId property indicates the id of the mapped source fixture to Genius Sports fixture

Use case: Id of this fixture (match).

sequence

The sequence property indicates

Use case: Sequence of the latest feed match event.

messageTimestampUtc

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

Use case: Time when match state was last updated.

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.

Reliability is used to indicate that some of the information within the message may be inaccurate and it should not be relied on for purposes where message accuracy is critical.

Use case: Current match state is reliable.

isCoverageCancelled

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

Use case: Coverage for this match has not been canceled.

reliabilityReasons

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

Use case: The heartbeat for the current match state has been lost, the feed is considered reliable and the coverage is unknown.

`coverageCancelledAt`	The time that coverage was cancelled
`currentVarState`	An Enum that describes the current Video Assistant Referee state. Possible values: `Safe, InProgress, Danger`
`varReason`	An Enum that describes the current Video Assistant Referee reason. Possible values: `NotSet (Default), HomeGoal, HomePenalty, HomeRedCard, HomeMistakenIdentity, AwayGoal, AwayPenalty, AwayRedCard, AwayMistakenIdentity, Goal, Penalty, RedCard, MistakenIdentity, HomeUnknown, AwayUnknown, Unknown`
`varOutcome`	An Enum that describes the current Video Assistant Referee outcome. Possible values: `NotSet (Default), HomeNoGoal, AwayNoGoal, NoGoal, HomeGoalAwarded, AwayGoalAwarded, GoalAwarded, HomeNoPenalty, AwayNoPenalty, NoPenalty, HomePenaltyAwarded, AwayPenaltyAwarded, PenaltyAwarded, HomeNoRedCard, AwayNoRedCard, NoRedCard, HomeRedCardGiven, AwayRedCardGiven, RedCardGiven, HomePlayerNotChanged, AwayPlayerNotChanged, PlayerNotChanged, HomePlayerChanged, AwayPlayerChanged, PlayerChanged, HomeNoAction, AwayNoAction, NoAction, HomeUnknown, AwayUnknown, Unknown`
`varReasonV2`	(V2) An Enum that describes the current Video Assistant Referee outcome. Possible values: NotSet (Default), HomeNoGoal, AwayNoGoal, NoGoal, HomeGoalAwarded, AwayGoalAwarded, GoalAwarded, HomeNoPenalty, AwayNoPenalty, NoPenalty, HomePenaltyAwarded, AwayPenaltyAwarded, PenaltyAwarded, HomeNoRedCard, AwayNoRedCard, NoRedCard, HomeRedCardGiven, AwayRedCardGiven, RedCardGiven, HomePlayerNotChanged, AwayPlayerNotChanged, PlayerNotChanged, HomePlayerChanged, AwayPlayerChanged, PlayerChanged, HomeNoAction, AwayNoAction, NoAction, HomeUnknown, AwayUnknown, Unknown, PenaltyRetake, HomePenaltyRetake, AwayPenaltyRetake
`varOutcomeV2`	(V2) An Enum that describes the current Video Assistant Referee outcome. Possible values: NotSet (Default), HomeNoGoal, AwayNoGoal, NoGoal, HomeGoalAwarded, AwayGoalAwarded, GoalAwarded, HomeNoPenalty, AwayNoPenalty, NoPenalty, HomePenaltyAwarded, AwayPenaltyAwarded, PenaltyAwarded, HomeNoRedCard, AwayNoRedCard, NoRedCard, HomeRedCardGiven, AwayRedCardGiven, RedCardGiven, HomePlayerNotChanged, AwayPlayerNotChanged, PlayerNotChanged, HomePlayerChanged, AwayPlayerChanged, PlayerChanged, HomeNoAction, AwayNoAction, NoAction, HomeUnknown, AwayUnknown, Unknown, HomePenaltyWillBeRetaken, AwayPenaltyWillBeRetaken, HomeNoPenaltyRetake, AwayNoPenaltyRetake, PenaltyWillBeRetaken, NoPenaltyRetake
`isSecondLeg`	Boolean: True if this is the second leg of a two match fixture
`firstLegScore`	The score from the first leg of a two-leg fixture. Populated only if IsSecondLeg is True
`normalTimeHalfDuration`	The expected duration of the first and second halves
`extraTimeHalfDuration`	The expected duration of the first and second halves of extra time if match can go to extra time
`canGoToExtraTime`	True if the match will go to extra time if normal time ends in a draw
`canGoStraightToPenaltiesAfterNormalTime`	True if the match will go straight to penalties if normal time ends in a draw
`canGoToPenalties`	True if the match will go to penalties if extra time ends in a draw
`source`	Indicates the source of this match state.
`fixtureId`	Indicates the mapped Genius Sports fixture id
`sequence`	Indicates the sequence number of the feed match events
`messageTimestampUtc`	Timestamp of the latest update to match state (UTC)
`isReliable`	Indicates whether the current match state is reliable or not
`isCoverageCancelled`	Indicates whether the coverage for this particular match has been cancelled or not
`reliabilityReasons`	`Heartbeat` : Short description of heartbeat status `FeedReliability` : Short description of feed reliability status `Coverage` : Short description of the coverage for this match