The rules of football can be found here:
- The Football Association: http://www.thefa.com/football-rules-governance
Note: not all data elements are available for all matches due to differing information availability and coverage methods.
This document describes the V3 football match state contract.
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
StartTime
Contains the start times of each phase of play. Values will be null if the phase has not yet started.
{
"FirstHalf":"2015-10-01T15:00:22.889Z",
"SecondHalf":null,
"ExtraTimeFirstHalf":null,
"ExtraTimeSecondHalf":null,
"Penalties":null
},
Element | Type | Description |
|---|---|---|
FirstHalf | DateTime (optional) | The start time in UTC of the first half |
SecondHalf | DateTime (optional) | The start time in UTC of the second half |
ExtraTimeFirstHalf | DateTime (optional) | The start time in UTC of the first half of extra time |
ExtraTimeSecondHalf | DateTime (optional) | The start time in UTC of the second half of extra time |
Penalties | DateTime (optional) | The start time in UTC of the penalty shootout |
StoppageTimes
Contains the amount of stoppage time to be played after each phase of normal time.
{
"FirstHalf":null,
"SecondHalf":null,
"ExtraTimeFirstHalf":null,
"ExtraTimeSecondHalf":null
},
Element | Type | Description |
|---|---|---|
FirstHalf | TimeSpan (optional) | The amount of stoppage time to be played in the first half |
SecondHalf | TimeSpan (optional) | The amount of stoppage time to be played in the second half |
ExtraTimeFirstHalf | TimeSpan (optional) | The amount of stoppage time to be played in the first half of extra time |
ExtraTimeSecondHalf | TimeSpan (optional) | The amount of stoppage time to be played in the second half of extra time |
ScoreSummary
An object that describes a piece of TeamA/TeamB information such as the current score in goals.
{
"Score":{},
"IsCollected":true,
"IsReliable":true
}
Element | Type | Description |
|---|---|---|
Score | Score | A Score object |
IsCollected | Boolean | True if this data type is being collected for this fixture, False otherwise |
IsReliable | Boolean | True if the data values are reliable, False otherwise |
Score
An object that holds a head-to-head score for a particular data type.
{
"Home":0,
"Away":2
}
Element | Type | Description |
|---|---|---|
Home | Integer | The Home team's score |
Away | Integer | The Away team's score |
...
The detail message lists every action that has happened in a football match. This allows a complete timeline of the match to be constructed at any point.
{
"CustomerId":6444,
"FixtureId":"3415011",
"MatchActions":{},
"AwayTeam":{},
"HomeTeam":{},
"IsSecondLeg":false,
"FirstLegScore":null,
"NormalTimeHalfDuration":"00:40:00",
"ExtraTimeHalfDuration":"00:10:00",
"CanGoToExtraTime":false,
"CanGoStraightToPenaltiesAfterNormalTime":false,
"CanGoToPenalties":false,
"MessageTimestampUtc":"2015-10-01T15:15:44.9551641Z"
}
Element | Type | Description |
|---|---|---|
CustomerId | Integer | An immutable identifier for the customer |
FixtureId | String | An immutable identifier for the event |
MatchActions | MatchActions | A collection of actions that has occurred so far |
AwayTeam | Team | An object that describes the away team |
HomeTeam | Team | An object that describes the home team |
IsSecondLeg | Boolean | Boolean: True if this is the second leg of a two match fixture |
FirstLegScore | Score | The score from the first leg of a two leg fixture. Populated only if IsSecondLeg is True |
NormalTimeHalfDuration | TimeSpan | The expected duration of the first and second halves |
ExtraTimeHalfDuration | TimeSpan | The expected duration of the first and second halves of extra time if match can go to extra time |
CanGoToExtraTime | Boolean | True if the match will go to extra time if normal time ends in a draw |
CanGoStraightToPenaltiesAfterNormalTime | Boolean | 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 |
MessageTimestampUtc | DateTime | The time that the message is sent, UTC |
MatchActions
A collection of objects detailing every action that has happened so far in a match.
{
"Goals":{},
"YellowCards":{},
"SecondYellowCards":{},
"StraightRedCards":{},
"Substitutions":{},
"ShotsOnTarget":{},
"ShotsOffTarget":{},
"ShotsOffWoodwork":{},
"BlockedShots":{},
"Corners":{},
"PenaltiesAwarded":{},
"Fouls":{},
"Offsides":{},
"GoalKicks":{},
"MissedPenalties":{},
"ThrowIns":{},
"StoppageTimeAnnouncements":{},
"PhaseChanges":{},
"DangerStateChanges":{},
"LineupUpdates":{},
"SystemMessages":{},
"ClockActions":{},
"BookingStateChanges":{},
}
Element | Type | Description |
|---|---|---|
Goals | GoalCollection | Goals scored |
YellowCards | MatchActionCollection | Yellow cards awarded |
SecondYellowCards | MatchActionCollection | Second yellow cards awarded |
SraightRedCards | MatchActionCollection | Straight red cards awarded |
Substitutions | SubstitutionCollection | Substitutions made |
ShotsOnTarget | MatchActionCollection | Shots on target |
ShotsOffTarget | MatchActionCollection | Shots off target |
ShotsOffWoodwork |
| Shots that hit the woodwork |
BlockedShots | MatchActionCollection | Shots that are blocked |
Corners | MatchActionCollection | Corners awarded |
PenaltiesAwarded | MatchActionCollection | Penalties awarded |
Fouls |
| Fouls conceded |
Offsides | MatchActionCollection | Offsides committed |
GoalKicks | MatchActionCollection | Goal kicks awarded |
MissedPenalties | MatchActionCollection | Penalties missed by each team |
ThrowIns | MatchActionCollection | Throw-ins taken |
StoppageTimeAnnouncements | StoppageTimeAnnouncementCollection | Announcements of stoppage time |
PhaseChanges | PhaseChangeCollection | Changes to match phase |
DangerStateChanges | DangerStateChangeCollection | Changes to danger state |
LineupUpdates | LineupUpdatedCollection | Changes to lineup |
SystemMessages | SystemMessageCollection | System messages |
ClockActions | ClockActionCollection | Clock actions or corrections |
BookingStateChanges | BookingStateChangeCollection | Changes to booking state |
GoalCollection
Details of all goals scored in a match.
{
"Goals":[],
"IsCollected":true,
"IsReliable":true
}
Element | Type | Description |
|---|---|---|
Goals | Goal | An array of goals scored |
IsCollected | Boolean | True if this data type is being collected for this fixture, False otherwise |
IsReliable | Boolean | True if the data values are reliable, False otherwise |
Goal
A goal scored in a football match.
{
"Phase":"FirstHalf",
"TimeElapsedInPhase":"00:06:57.8570000",
"Team":"Away",
"ScoredByPlayerId":null,
"IsOwnGoal":null,
"WasScoredFromPenalty":null,
"IsConfirmed":true
}
Element | Type | Description |
|---|---|---|
Phase | Phase | An Enum that describes the current phase of the match (see Match Summary Message above). |
TimeElapsedInPhase | TimeSpan |
|
Team | TeamSide | Attributes an action to a team |
ScoredByPlayerId | Int, nullable | Attributes an action to a player. The value will correspond to the team details in the Fixture message. Null if the scoring player is not known. |
IsOwnGoal | Boolean, nullable | True if this was an own goal, False otherwise. Will be null if it is not known whether goal was an own goal. |
WasScoredFromPenalty | Boolean, nullable | 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. |
IsConfirmed | Boolean | True if this goal has been confirmed, False otherwise |
TeamSide
Some actions or scores are attributed to an individual team. TeamSide is an Enum that details the team to which its parent element applies. It can take the following values:
Value | Name | Description |
0 | Home | The home team |
1 | Away | The away team |
MatchActionCollection
MatchActionCollection lists all the match actions of a particular type that occur in a match.
{
"MatchActions":[],
"IsCollected":true,
"IsReliable":true
}
...
Element
...
Type
...
Description
...
MatchActions
...
MatchAction
...
...
StartTimes
...
The start time of each phase of play in UTC
...
StoppageTimes
...
StoppageTimes
...
The amount of stoppage time to be played in each phase of the match
...
Goals
...
ScoreSummary
...
The number of goals awarded to each team
...
YellowCards
...
ScoreSummary
...
The number of yellow cards awarded to each team
...
SecondYellowCards
...
ScoreSummary
...
The number of second yellow cards awarded to each team
...
StraightRedCards
...
ScoreSummary
...
The number of straight red cards awarded to each team
...
Substitutions
...
ScoreSummary
...
The number of substitutions made by each team
...
ShotsOnTarget
...
ScoreSummary
...
The number of on-target shots by each team
...
ShotsOffTarget
...
ScoreSummary
...
The number of off-target shots by each team
...
ShotsOffWoodwork
...
ScoreSummary
...
The number of times each team has hit the woodwork
...
BlockedShots
...
ScoreSummary
...
The number of times each team has had an on-target shot blocked
...
Corners
...
ScoreSummary
...
The number of corners awarded to each team
...
PenaltiesAwarded
...
ScoreSummary
...
The number of penalties awarded to each team
...
Fouls
...
ScoreSummary
...
The number of fouls committed by each team
...
Offsides
...
ScoreSummary
...
The number of offsides committed by each team
...
GoalKicks
...
ScoreSummary
...
The number of goal kicks taken by each team
...
MissedPenalties
...
ScoreSummary
...
The number of penalties missed by each team
...
SavedPenalties
...
ScoreSummary
...
The number of penalties saved by each team
...
ThrowIns
...
ScoreSummary
...
The number of throw-ins awarded to each team
...
IsSecondLeg
...
Boolean
...
Boolean: True if this is the second leg of a two match fixture
...
FirstLegScore
...
Score
...
The score from the first leg of a two leg fixture. Populated only if IsSecondLeg is True
...
NormalTimeHalfDuration
...
TimeSpan
...
The expected duration of the first and second halves
...
ExtraTimeHalfDuration
...
TimeSpan
...
The expected duration of the first and second halves of extra time if match can go to extra time
...
CanGoToExtraTime
...
Boolean
...
True if the match will go to extra time if normal time ends in a draw
...
CanGoStraightToPenaltiesAfterNormalTime
...
Boolean
...
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
...
MessageTimestampUtc
...
DateTime
...
The time that the message is sent, UTC
MatchAction
...
...
...
...
...
...
...
...
...
...
TimeElapsedInPhase
...
TimeSpan
...
...
Team
...
TeamSide
...
Attributes an action to a team
...
PlayerId
...
Int, nullable
...
Attributes an action to a player. The value will correspond to the team details in the Fixture message. Null if the player details are not known.
...
IsConfirmed
...
Boolean
...
True if this action has been confirmed, False otherwise
SubstitutionCollection
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
OnPlayerId
...
Int, nullable
...
The player coming onto the pitch. Null if the player is not known.
...
OffPlayerId
...
Int, nullable
...
FoulCollection
...
...
...
...
...
Description
...
Fouls
...
Foul
...
An array of fouls
...
IsCollected
...
Boolean
...
True if this data type is being collected for this fixture, False otherwise
...
IsReliable
...
Boolean
...
True if the data values are reliable, False otherwise
Foul
...
...
...
Phase
...
Phase
...
An Enum that describes the current phase of the match (see Match Summary Message above).
...
TimeElapsedInPhase
...
TimeSpan
...
...
FoulingTeam
...
TeamSide
...
Attributes an action to a team
...
IsConfirmed
...
Boolean
...
True if this action has been confirmed, False otherwise
StoppageTimeAnnouncementCollection
...
...
...
...
...
...
...
StoppageTimeAnnouncement
...
...
...
...
...
...
AddedMinutes
...
Integer
...
PhaseChangeCollection
...
...
...
...
...
...
...
...
...
...
...
Element | Type | Description |
|---|---|---|
PreviousPhase | Phase | An Enum that describes the previous phase of the match (see Match Summary Message above). |
CurrentPhase | Phase | An Enum that describes the current phase of the match (see Match Summary Message above). |
CurrentPhaseStartTime | DateTime |
|
IsConfirmed | Boolean | True if this action has been confirmed, False otherwise |
MessageId | Int | This field is currently not in use |
Message | String | This field is currently not in use |
Football Match Phase
At the end of a football match the phase will change to PostMatch to indicate that the match has ended. In a small number of matches, where a period of extra time play might be allowed within the rules (depending on the score after normal time and from any earlier leg), the phase may change first to FullTimeNormalTime before moving to PostMatch.
DangerStateChangeCollection
...
...
...
...
...
...
...
...
...
...
...
DangerState
...
DangerState
...
The danger state of the match.
...
IsConfirmed
...
Boolean
...
True if this action has been confirmed, False otherwise
DangerState
...
LineupUpdatedCollection
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
NewLineup
...
Lineup
...
A lineup
...
Team
...
TeamSide
...
Lineup
...
...
...
Player
An object describing a player taking part in a football match.
{
"Id":38753,
"Name":"Rooney, W",
"ShirtNumber":8
}
Element | Type | Description |
|---|---|---|
Id | Int | A unique identifier for the player |
Name | String | The player's name |
ShirtNumber | Integer | The player's shirt number |
SystemMessageCollection
...
...
Player
...
An array of Player objects listing players who will start the match on the pitch
...
StartingOnBench
...
Player
...
An array of Player objects listing players who will start the match on the bench
...
...
SystemMessage
...
An array of system messages
...
...
...
Boolean
...
True if the data values are reliable, False otherwise
SystemMessage
A system message describing something that affects a football match.
{
"Phase":"FirstHalf",
"TimeElapsedInPhase":"00:17:16.1270000",
"Message":"A message about a football match",
"IsConfirmed":true
}
...
Element
...
Type
...
Description
...
Phase
...
TimeElapsedInPhase
...
TimeSpan
...
...
Message
...
String
...
A message
...
IsConfirmed
...
Boolean
...
True if this action has been confirmed, False otherwise
ClockActionCollection
ClockActionCollection lists all the changes made to the clock during a match.
{
"ClockActions":[],
"IsCollected":true,
"IsReliable":true
}
Element | Type | Description |
|---|---|---|
ClockActions | ClockAction | An array of changes to the clock |
IsCollected | Boolean | True if this data type is being collected for this fixture, False otherwise |
IsReliable | Boolean | True if the data values are reliable, False otherwise |
ClockAction
A change to the clock in a football match.
{
"Phase":"FirstHalf",
"TimeElapsedInPhase":"00:18:17.1270000",
"TimestampUtc":"2015-10-09T10:12:11.001Z",
"ActivityType":"Home",
"IsClockRunning":true,
"IsConfirmed":true
}
Element | Type | Description |
|---|---|---|
Phase | Phase | An Enum that describes the current phase of the match (see Match Summary Message above). |
TimeElapsedInPhase | TimeSpan |
|
TimestampUtc | DateTime |
|
ActivityType | ClockActivityTypeDto | An Enum describing the clock activity. Possible values are: |
IcClockRunning | Boolean | True if the clock is running, False otherwise |
IsConfirmed | Boolean | True if this action has been confirmed, False otherwise |
BookingStateChangeCollection
BookingStateChangeCollection lists any changes to the booking states that occur during the match.
{
"BookingStateChanges":[],
"IsCollected":true,
"IsReliable":true
}
Element | Type | Description |
|---|---|---|
BookingStateChanges | BookingStateChange | An array of changes to the booking state |
IsCollected | Boolean | True if this data type is being collected for this fixture, False otherwise |
IsReliable | Boolean | True if the data values are reliable, False otherwise |
BookingStateChanges
A change to the booking state of a football match.
{
"Phase":"FirstHalf",
"TimeElapsedInPhase":"00:19:18.1270000",
"BookingState":"",
"IsConfirmed":true
}
...
Element
...
Type
...
Description
...
Phase
...
Phase
...
An Enum that describes the current phase of the match (see Match Summary Message above).
...
TimeElapsedInPhase
...
TimeSpan
...
The time that has elapsed in the current phase.
...
BookingState
...
BookingState
...
An Enum describing the booking state. Possible values are:
Safe,
YellowCardDanger,
RedCardDanger
...
IsConfirmed
...
Boolean
...