Warehouse - Publish Stream API Documentation - American Football

Introduction

This API call is to send real time data to the Warehouse/Statistics Engine. It is accomplished by sending a stream of messages over a long running socket. Pending network problems the connection should remain open for the length of the match.

Connection

There are two different ways to establish a publish connection to the system a HTTP method or a RAW method. These two different ways exists to enable the client to potentially work around any port or proxy problems present at in venue areas. Connections can also be sent over one of two different ports, 80 or 5522

The same data, parameters and format is used in both methods, only the startup of the connection differs.

Note: This call makes use of the streaming API endpoint which differs from the standard API endpoint.

HTTP Request

POST /v2/{sport}/publish

RAW

In the RAW method, a socket is opened to the streaming API endpoint and the request string is sent, followed by two carriage returns (\n\n) or two carriage return line feeds (\r\n\r\n). To initiate RAW mode the nohttp parameter must be present and set in the request string.

/v2/{sport}/publish
  streamKey string(30)

The unique authorisation key that allows the streaming of the match
  timestamp integer

The UNIX timestamp for the current date and time indicating the number of seconds since January 1st 1970 at UTC. The client timestamp must be within 60 seconds of the correct time or else the connection will be refused.
  appVersion string(64)

Application name and version that is sending the data.
nohttp enum

If set to 1 then the connection will operate in RAW mode. If this parameter is not present or not set to the value of 1, then the connection will operate in HTTP mode regardless of what connection string is sent.

0
No (Default)
1
Yes
mode enum

The mode of the connection

master
Master - The data being sent is distributed to any outputs (Default)
backup
Backup - The data being sent is processed but not distributed to any outputs
format enum

The format the data is being sent in.

json
JSON (Default)
xml
XML
sendAcks enum

If set to 1, then each message received will generate an acknowledgement message.

0
No (Default)
1
Yes
Example - HTTP 
POST /v2/basketball/publish?streamKey=TESTSTREAMKEY&timestamp=1412987153 HTTP/1.1
Host: localhost:8000
Connection: keep-alive
Example - RAW 
/v2/basketball/publish?nohttp=1&streamKey=TESTSTREAMKEY&timestamp=1412987153

Request Body

The body of the request should be a series of messages (defined below). Each message must be delimited by a carriage return/line-feed \r\n series of characters (in hex, 0x0D 0x0A). Consequently this series of characters must not appear in any message content.

Message Compression

The content if each message may be sent in a compressed format to reduce the size of the data being transferred. The message data should be compressed using a gzip/deflate algorithm (http://www.faqs.org/rfcs/rfc1951.html)and then Base64 encoded. Instead of the normal data being the value of the message key, the compressed data should be the value of a compressedMessage key.

Example - Uncompressed 
{
  "message": {
    "type": "master",
    "format": "json"
  }
}
Example - Compressed 
{
  "compressedMessage": "q1YqqSxIVbJSyk0sLkktUtJRSssvyk0sAYpkFefnKdUCAA=="
}

Connection Timeouts

To maintain the open connection at least one message must be sent every 20 seconds. A keepalive message may be sent if no other message needs to be sent.

The session will be closed automatically if it has been open for more than 4 hours, whether data is being sent or not.

Master/Slave

For redundancy purposes the system supports multiple connections for the same match from different clients. There can only be one connection in master mode, all the others must be in backup mode. If a second connection is made in master mode, or a connection changed to master mode then the first master connection is disconnected.

Connection Latency

To monitor the latency of the entire streaming process as well as the connection between the client and the warehouse the latency of the connection is measured. This process involves the sending of a latencyrequest message from the warehouse to the client. The client should immediately respond with a latencyresponse message containing the information sent by the warehouse.

Message Ids

For messages that require a messageId, the messageId MUST be a unique and sequential integer. Numbers cannot be skipped. If the system detects that a messageId has been skipped then an error will be generated indicating which messageId is missing. The client should interpret this message and resend all messages from (and including) the missing Id. Processing will not be resumed until the missing message is processed.

messageId vs actionNumber It can sometimes be confusing to tell the difference between these two fields. It may be easier to think of them as the primary keys to two database tables. actionNumber is the primary key for the list (table) of actions that occur during the match. An actionNumber uniquely identifies that action, and doesn't change even if details about that action are changed. messageId can be thought of as the primary key of the list (table) of messages that have been sent. A messageId unqiuely identifies a message that has been sent. Any edit of an existing actionNumber would require a new message be sent (a new messageId), but the same actionNumber.

Character Set

All data provided to these API functions is required to be in UTF-8 format.

All responses will be provided as UTF-8 strings.

Player participation tracking

Players are marked as participated if any of these conditions are met

  • Player is marked as starter in teams message
  • Player is mentioned in substitution message
  • Any action message contains person number in pno field
  • Player is mentioned in any action at qualifiers field containing players list

Message Types Received

While the publish call is primarily about streaming data to the warehouse, the connection is bi-directional and messages will also be sent from the warehouse.

This is a list of all the message types that can be sent from the Statistics Engine to the cli ent.

authenticated
The message type is returned from the warehouse on successful authentication. The field lastMessageId contains the id of the last successfully processed message. If the connection is a reconnection then the client should sent all messages with an Id after this one.
type enum

The type of the message

authenticated
lastMessageId integer

The last messageId successfully processed for this match.

Example

{
  "message": {
    "type": "authenticated",
    "lastMessageId": 45
  }
}

error
The message type is returned from the warehouse on any type of error.
type enum

The type of the message

error
error string

A string description of the error

Example

{
  "message": {
    "type": "error",
    "error": "[message.clockRunning] is missing and it is required"
  }
}

latencyrequest
This message type is sent from the warehouse to measure latency for the connection. The client should immediately respond with a lantencyresponse message.
type enum

The type of the message

latencyrequest
number integer

A unique number. This should be immediately returned by the client in a latencyresponse message.

Example

{
    "message": {
        "type": "latencyrequest",
        "number": 1492625489.6728
    }
}

ack
The message type is sent in response to a message from the client. Only sent when the sendAcks parameter is set on connection.
type enum

The type of the message

ack
acktype string

The type of the message being acknowledged.
  messageId integer

The messageId of the message being acknowledged.
actionNumber integer

The actionNumber (if present) of the message being acknowledged.

Example

{
    "message": {
        "type": "ack",
        "acktype": "action",
        "actionNumber": 712,
        "messageId": 925
    }
}
Message Types Sent

This is a list of all the message types that can be sent to the Statistics Engine from the client.

setup
This message type has information about the how the match will be run. This message type must be sent at least once before the beginning of the match.
  type enum

The type of the message

setup
  messageId integer

Unique identifier of the message being sent
inConference enum

Is this an in conference match. If this differs from prematch match data – a notification will be generated for League Manager.

0
No
1
Yes
atNeutralVenue enum

Is this match played at a neutral venue. If this differs from prematch match data – a notification will be generated for League Manager.

0
No
1
Yes
courtType enum

Court type of the match.
periods associativearray

numberOfPeriods integer

The number of periods played per game.

4
(Default)
halfTimeBreak integer

The length of the break between halves, in minutes.

15
(Default)
timeouts associativearray

timeoutsPerHalf integer

The number of timeouts allowed per half of the game.

3
(Default)
timeoutsOvertime integer

The number of timeouts allowed per overtime.

1
(Default)
allowOvertime integer

Allow overtime.

1
Yes (Default)
0
No
numberOfPlayers integer

The default number of players on field per team.

0
Unlimited (Default)
minimumAbandonTime integer

Minimum required time for the match to count as officially complete if it is abandoned.

70
(Default)
customEfficiencyFormula string(10000)

A string giving the formula to calculate a custom efficiency value. The formula can use simple mathematical constructs * + - / () and contain a number of variables. Each variable must be the name of a valid Team Match Statistic. For a complete list of allowed statistic names and further formula check the person match statistics.

Example

{
    "message": {
        "timeouts": {
            "extratime": 1,
            "period4": 2,
            "period3": 2,
            "period2": 2,
            "period1": 2,
            "half2": 3,
            "half1": 2,
            "style": "period"
        },
        "periods": {
            "breakPeriod": 2,
            "breakHalftime": 2,
            "length": 10,
            "overtime": 1,
            "number": 4,
            "lengthOvertime": 5
        },
        "messageId": 1,
        "maxFoulsTechnical": 5,
        "shotClock": 25,
        "type": "setup",
        "customEfficiencyFormula": "",
        "foulsBeforeBonus": 4,
        "maxFoulsPersonal": 5
    }
}

teams
This message type defines the teams and players for the match. It is compulsory to send at least one of these messages.
  type enum

The type of the message

teams
  messageId integer

Unique identifier of the message being sent
teams array

An array of team records
  teamNumber integer

The number of the team in the match, 1 or 2.
competitionStatistics associativearray

sWins integer

Overall wins of the team. Compared with prematch [matchInformation][teams][teams][competitionStatistics][sWins]. If different sends notification to se support system to league manager.
sDraws integer

Overall draws of the team. Compared with prematch [matchInformation][teams][teams][competitionStatistics][sDraws]. If different sends notification to se support system to league manager.
sLosses integer

Overall losses of the team. Compared with prematch [matchInformation][teams][teams][competitionStatistics][sLosses]. If different sends notification to se support system to league manager.
conferenceStatistics associativearray

sWins integer

Conference wins of the team. Compared with prematch [matchInformation][teams][teams][conferenceStatistics][sWins]. If different sends notification to se support system to league manager.
sDraws integer

Overall draws of the team. Compared with prematch [matchInformation][teams][teams][conferenceStatistics][sDraws]. If different sends notification to se support system to league manager.
sLosses integer

Conference losses of the team. Compared with prematch [matchInformation][teams][teams][conferenceStatistics][sLosses]. If different sends notification to se support system to league manager.
detail associativearray

  teamName string(100)

The name of the team
isHomeCompetitor enum

Is this a 'home' match for this competitor.

0
No
1
Yes
  teamId integer

Unique identifier for the team
teamNickname string(50)

A non-offical name of the team
teamCode string(3)

A three letter code for this team
isExhibition enum

Is this competitor playing an exhibition game? Note - exhibition games are always excluded from competition/conference statistics.

0
No (Default)
1
Yes
sportClass string(64)

Total team sport class value used for para-sports.
players array

  pno integer

The number of the player in the match. This is a sequence number not a jersey number.
personId integer

Unique identifier for the person
  familyName string(50)

The family name of the person
  firstName string(50)

The first name of the person
height double

The height of the person, in cms
sportClass string(64)

A value used to describe the Sport Class for para-sports.
shirtNumber string

Player's shirt Number for the match.
playingPosition enum

Player's playing position for the match.

QB
Quarterback
RB
Running Back
FB
Full Back
OL
Offensive Line
OT
Offensive Tackle
OG
Offensive Guard
OC
Offensive Center
WR
Wide Receiver
TE
Tight End
DL
Defensive Line
DE
Defensive End
DT
Defensive Tackle
LB
Linebacker
DB
Defensive Back
CB
Cornerback
S
Safety
K
Kicker
P
Punter
LS
Long Snapper
starter enum

Is the person a starter?

1
Yes
0
No (Default)
captain enum

Is the person the captain?

1
Yes
0
No (Default)
active enum

Is the person currently active/on the field of play?

1
Yes
0
No (Default)
coach associativearray

DEPRECATED. Use teamOfficials instead.
personId integer

Unique identifier for the person
familyName string(50)

The family name of the person
firstName string(50)

The first name of the person
assistcoach1 associativearray

DEPRECATED. Use teamOfficials instead.
personId integer

Unique identifier for the person
familyName string(50)

The family name of the person
firstName string(50)

The first name of the person
assistcoach2 associativearray

DEPRECATED. Use teamOfficials instead.
personId integer

Unique identifier for the person
familyName string(50)

The family name of the person
firstName string(50)

The first name of the person
teamOfficials array

A list of team officials
personId integer

Unique identifier for the person
firstName string(100)

The first name of the official
familyName string(100)

The family name of the official
shirtNumber string(30)

Shirt number
  officialType enum

CAPTAIN
Captain
VICE_CAPTAIN
Vice Captain
HEAD_COACH
Head Coach
COACH
Coach
ASSISTANT_COACH
Assistant Coach
UMPIRE
Umpire
externalId string(50)

A unique ID for this person set by the owner of this league.

Example

{
    "message": {
        "messageId": 29,
        "teams": [{
            "players": [{
                "active": 1,
                "pno": 1,
                "firstName": "Brandon",
                "personId": 424206,
                "shirtNumber": "3",
                "playingPosition": "G",
                "height": 0,
                "familyName": "Clark",
                "starter": 1,
                "captain": 0
            }, {
                "active": 1,
                "pno": 2,
                "firstName": "Tyler",
                "personId": 8775,
                "shirtNumber": "4",
                "playingPosition": "G",
                "height": 0,
                "familyName": "Bernardini",
                "starter": 1,
                "captain": 1
            }, {
                "active": 0,
                "pno": 3,
                "firstName": "William",
                "personId": 94332,
                "shirtNumber": "5",
                "playingPosition": "F\/C",
                "height": 0,
                "familyName": "Maynard",
                "starter": 0,
                "captain": 0
            }, {
                "active": 1,
                "pno": 4,
                "firstName": "Shane",
                "personId": 248176,
                "shirtNumber": "7",
                "playingPosition": "F",
                "height": 0,
                "familyName": "Walker",
                "starter": 1,
                "captain": 0
            }, {
                "active": 0,
                "pno": 5,
                "firstName": "Andrew",
                "personId": 6678,
                "shirtNumber": "8",
                "playingPosition": "F",
                "height": 0,
                "familyName": "Sullivan",
                "starter": 0,
                "captain": 0
            }, {
                "active": 0,
                "pno": 20,
                "firstName": "Sesan",
                "personId": 309075,
                "shirtNumber": "9",
                "playingPosition": "",
                "height": 0,
                "familyName": "Russell",
                "starter": 0,
                "captain": 0
            }, {
                "active": 0,
                "pno": 6,
                "firstName": "Josh",
                "personId": 562587,
                "shirtNumber": "10",
                "playingPosition": "G",
                "height": 0,
                "familyName": "Ward-Hibbert",
                "starter": 0,
                "captain": 0
            }, {
                "active": 0,
                "pno": 8,
                "firstName": "Harrison",
                "personId": 8540,
                "shirtNumber": "12",
                "playingPosition": "F",
                "height": 0,
                "familyName": "Gamble",
                "starter": 0,
                "captain": 0
            }, {
                "active": 0,
                "pno": 9,
                "firstName": "Conner",
                "personId": 6813,
                "shirtNumber": "13",
                "playingPosition": "PG",
                "height": 0,
                "familyName": "Washington",
                "starter": 0,
                "captain": 0
            }, {
                "active": 1,
                "pno": 11,
                "firstName": "Pierre",
                "personId": 54481,
                "shirtNumber": "15",
                "playingPosition": "F",
                "height": 0,
                "familyName": "Hampton",
                "starter": 1,
                "captain": 0
            }, {
                "active": 0,
                "pno": 12,
                "firstName": "Eric",
                "personId": 424208,
                "shirtNumber": "22",
                "playingPosition": "G",
                "height": 0,
                "familyName": "Robertson",
                "starter": 0,
                "captain": 0
            }, {
                "active": 0,
                "pno": 13,
                "firstName": "Andrew",
                "personId": 6695,
                "shirtNumber": "31",
                "playingPosition": "F",
                "height": 0,
                "familyName": "Thomson",
                "starter": 0,
                "captain": 0
            }, {
                "active": 1,
                "pno": 14,
                "firstName": "Taylor",
                "personId": 40287,
                "shirtNumber": "33",
                "playingPosition": "F",
                "height": 0,
                "familyName": "King",
                "starter": 1,
                "captain": 0
            }],
            "assistcoach2": {
                "firstName": "Mark",
                "personId": 8514,
                "familyName": "Jarram"
            },
            "assistcoach1": {
                "firstName": "Philip",
                "personId": 6756,
                "familyName": "Gleadell"
            },
            "teamNumber": 1,
            "coach": {
                "firstName": "Rob",
                "personId": 6670,
                "familyName": "Paternostro"
            },
            "detail": {
                "teamName": "Leicester Riders",
                "teamCode": "LEI",
                "teamNickname": "Riders",
                "teamId": 1081
            }
        }, {
            "players": [{
                "active": 0,
                "pno": 1,
                "firstName": "Christian",
                "personId": 248173,
                "shirtNumber": "1",
                "playingPosition": "F",
                "height": 0,
                "familyName": "Behrens",
                "starter": 0,
                "captain": 0
            }, {
                "active": 0,
                "pno": 2,
                "firstName": "Joe",
                "personId": 480493,
                "shirtNumber": "3",
                "playingPosition": "",
                "height": 0,
                "familyName": "Hart",
                "starter": 0,
                "captain": 0
            }, {
                "active": 1,
                "pno": 3,
                "firstName": "Deandre",
                "personId": 424212,
                "shirtNumber": "6",
                "playingPosition": "G",
                "height": 0,
                "familyName": "Parks",
                "starter": 1,
                "captain": 0
            }, {
                "active": 0,
                "pno": 4,
                "firstName": "Danny",
                "personId": 94329,
                "shirtNumber": "8",
                "playingPosition": "G",
                "height": 0,
                "familyName": "Horta-Darrington",
                "starter": 0,
                "captain": 0
            }, {
                "active": 1,
                "pno": 5,
                "firstName": "Darius",
                "personId": 6690,
                "shirtNumber": "13",
                "playingPosition": "C",
                "height": 0,
                "familyName": "Defoe",
                "starter": 1,
                "captain": 0
            }, {
                "active": 1,
                "pno": 6,
                "firstName": "Scott",
                "personId": 8570,
                "shirtNumber": "14",
                "playingPosition": "F",
                "height": 0,
                "familyName": "Martin",
                "starter": 1,
                "captain": 0
            }, {
                "active": 1,
                "pno": 7,
                "firstName": "Fabulous",
                "personId": 6692,
                "shirtNumber": "20",
                "playingPosition": "G",
                "height": 0,
                "familyName": "Flournoy",
                "starter": 1,
                "captain": 0
            }, {
                "active": 0,
                "pno": 8,
                "firstName": "Andrew",
                "personId": 6808,
                "shirtNumber": "21",
                "playingPosition": "SG",
                "height": 0,
                "familyName": "Lasker",
                "starter": 0,
                "captain": 0
            }, {
                "active": 0,
                "pno": 9,
                "firstName": "Orlan",
                "personId": 263652,
                "shirtNumber": "23",
                "playingPosition": "F",
                "height": 0,
                "familyName": "Jackman",
                "starter": 0,
                "captain": 0
            }, {
                "active": 1,
                "pno": 10,
                "firstName": "Rahmon",
                "personId": 8653,
                "shirtNumber": "44",
                "playingPosition": "PG",
                "height": 0,
                "familyName": "Fletcher",
                "starter": 1,
                "captain": 1
            }],
            "assistcoach2": {
                "firstName": "Ian",
                "personId": 8724,
                "familyName": "Macleod"
            },
            "assistcoach1": {
                "firstName": "David",
                "personId": 6759,
                "familyName": "Forrester"
            },
            "teamNumber": 2,
            "coach": {
                "firstName": "Fabulous",
                "personId": 6692,
                "familyName": "Flournoy"
            },
            "detail": {
                "teamName": "Esh Group Eagles Newcastle",
                "teamCode": "NEW",
                "teamNickname": "Eagles",
                "teamId": 1084
            }
        }],
        "type": "teams"
    }
}

officials
This message type contains information about the match officials assigned to the match. This message type is only needed it there is information about match officials that needs to be sent.
  type enum

The type of the message

officials
  messageId integer

Unique identifier of the message being sent
commissioner associativearray

DEPRECATED. Use matchOfficials property instead
personId integer

Unique identifier for the person
familyName string(50)

The family name of the person
firstName string(50)

The first name of the person
externalId string(50)

A unique ID for this person set by the owner of this league.
referee1 associativearray

DEPRECATED. Use matchOfficials property instead
personId integer

Unique identifier for the person
familyName string(50)

The family name of the person
firstName string(50)

The first name of the person
externalId string(50)

A unique ID for this person set by the owner of this league.
referee2 associativearray

DEPRECATED. Use matchOfficials property instead
personId integer

Unique identifier for the person
familyName string(50)

The family name of the person
firstName string(50)

The first name of the person
externalId string(50)

A unique ID for this person set by the owner of this league.
referee3 associativearray

DEPRECATED. Use matchOfficials property instead
personId integer

Unique identifier for the person
familyName string(50)

The family name of the person
firstName string(50)

The first name of the person
externalId string(50)

A unique ID for this person set by the owner of this league.
technicaldelegate associativearray

DEPRECATED. Use matchOfficials property instead
personId integer

Unique identifier for the person
familyName string(50)

The family name of the person
firstName string(50)

The first name of the person
externalId string(50)

A unique ID for this person set by the owner of this league.
matchOfficials array

A list of match officials
firstName string(100)

The first name of the official
familyName string(100)

The family name of the official
shirtNumber string(30)

Shirt number
personId integer

Unique id of the person
externalId string(50)

A unique ID for this person set by the owner of this league.
  officialType enum

Official Type

CAPTAIN
Captain
VICE_CAPTAIN
Vice Captain
HEAD_COACH
Head Coach
COACH
Coach
ASSISTANT_COACH
Assistant Coach
REFEREE
Referee
ASSISTANT_REFEREE
Assistant Referee
RESERVE_REFEREE
Reserve Referee
RESERVE_ASSISTANT_REFEREE
Reserve Assistant Referee
TEAM
Team
MEDICAL_STAFF
Medical Staff
MATCH_OFFICIAL
Match Official
COMMISSIONER
Commissioner
STATISTICIAN
Statistician
SCOREKEEPER
Scorekeeper
ASSISTANT_SCOREKEEPER
Assistant Scorekeeper
TIMEKEEPER
Timekeeper
VIDEO_OPERATOR
Video Operator
UMPIRE
Umpire
HEAD_LINESMAN
Head Linesman
LINE_JUDGE
Line Judge
FIELD_JUDGE
Field Judge
SIDE_JUDGE
Side Judge
BACK_JUDGE
Back Judge
CENTER_JUDGE
Center Judge
REPLAY_OFFICIAL
Replay Official
statisticians array

An array of statisticians
firstName string(100)

The first name of the statistician
familyName string(100)

The family name of the statistician
statisticianId integer

The unique id given to this statistician
statisticianType enum

The job the statistician is performing for this match

OPERATOR
The person entering the statistics
CALLER
The person calling the statistics

Example

{
    "message": {
        "messageId": 3,
        "referee2": {
            "firstName": "John",
            "personId": 1244,
            "familyName": "Smith",
            "name": "John Smith"
        },
        "referee1": {
            "firstName": "Mary",
            "personId": 4252,
            "familyName": "Johnson",
            "name": "Mary Johnson"
        },
        "statisticians": [{
            "firstName": "GERALDINE",
            "familyName": "FRENCH",
            "statisticianId": 393492,
            "statisticianType": "OPERATOR"
        }],
        "type": "officials"
    }
}

action

This message type contains an individual game action.

Actions come in two types, adminstrative or sport. A sport type action is related to the sport aspect of the match, eg substitution or foul. An administrative type action is related to the process or publishing the game eg. period confirmed. Only sport type actions are given an actionNumber. The action number is a sequential integer that should uniquely refer to that action. The actionNumber is repeated to indicate an edit or delete on the original action.

  type enum

The type of the message

action
  messageId integer

Unique identifier of the message being sent
actionNumber integer

Unique sequence number for this action
teamNumber integer

The number of the team in the match, 1 or 2.
pno integer

The number of the player in the match. This is a sequence number not a jersey number.
  clock string

The time on the clock when this action occurred.

Format is: MM:SS:CC
  timeActual datetime

The date/time when this action occurred in UTC.

Format is: YYYY-MM-DD HH:MM:SS
  period integer

What period of the match is this statistic related to. 0 is valid and represents the value for the total match. Overtime periods should start at 1.
  periodType enum

The type of period

REGULAR
(Default)
OVERTIME
  actionType string(20)

A code representating the action type. See Action Types for the list of options.
success enum

Was this action completed successfully? Generally all actions except scoring actions are successful.

1
Yes (Default)
0
No
subType string(20)

The subordinate type of the action. Used to further define the action. See Action Types for the list of options.
qualifiers array

An array of qualifiers to the action. See Action Types for the list of options. If the qualfier has a value that is being sent, then the qualifier name and value are separated by ':'. eg. ["from:head","freekick","goalmouth:lowleft"]
value string(1000)

A text field. Some action types require a value. This is where that value will be placed. See Action Types for the list of actions that require this field.
previousAction integer

The actionNumber of the base/primary action if this action relates to another action. eg. For a freethrow/freekick, this may be the actionNumber of the original foul.
officialId integer

The unique identifier for the official calling the action
x float

X coordinate on the playing surface where the action occurred. Defined in Playing Surface Definition.
y float

Y coordinate on the playing surface where the action occurred. Defined in Playing Surface Definition.
area string

The area of the playing surface where the action occurred. Defined in Playing Surface Definition.
side enum

Indicates which side of the playing surface the player's/team's goal is.

(blank)
left
Team's goal is to the left
right
Team's goal is to the right
  score1 string

This field represents the current score for team number 1 after the completion of this action. Even if this action is an edit for a previous period, this should be the current score.
  score2 string

This field represents the current score for team number 2 after the completion of this action. Even if this action is an edit for a previous period, this should be the current score.
edited datetime

If the action has been edited (after being initially sent) this field contains the last time it was edited (in UTC). If the action has not been edited, then this field is not present.

Format is: YYYY-MM-DD HH:MM:SS
inserted datetime

If the action has been missed previously and inserted (added out of sequence) later this field contains the time it was inserted (in UTC). If the action has not been inserted or added out of sequence during active workflow then this field is not present.

Format is: YYYY-MM-DD HH:MM:SS
deleted datetime

If the action has been deleted (after being initially sent) this field contains the time it was deleted (in UTC). If the action has not been deleted, then this field is not present.

Format is: YYYY-MM-DD HH:MM:SS
sendDelay float

Optional field. May be added from the capture device to indicate a delay (in seconds) before the message was sent.
completionDelay float

Optional field. May be added from the capture device to indicate the time taken (in seconds) to complete the entering of the action.
system enum

If this value is set to 1 then it indicates that this action was automatically generated by the system and not explicitly performed by the user (value = 0). eg. A start period automatically creating a start clock action.

0
No (Default)
1
Yes
underReview enum

The action is not official as yet, it is being review by match officials or the organisation. This may occur in disputed actions or actions being checked by some kind of video.

0
No (Default)
1
Yes
orderNumber integer

Optional. A unique number identifiying the order of the action in the game. This number may not be sequential but will be unique. Sorting by this number will give the order of actions (and will account for edits and insertions). When assigning this number initially you should leave gaps (eg 100,200,300) to allow you to enter any inserted actions in their correct orderNumber sequence.
drive integer

Drive number
play integer

Play number
yardline object

Current yardline
teamNumber integer

yardline integer

playOverall integer

Play number overal in a game
possible enum

Optional field. May be added to indicate the action is not confirmed yet and do not affect any statistics. Require permission to retrieve possible actions from Streaming API.

0
No (Default)
1
Yes
text string

Play summary text.

Example

{
    "message": {
        "pno": 8,
        "period": 4,
        "actionNumber": 703,
        "sendDelay": 0.084,
        "success": 0,
        "previousAction": 0,
        "messageId": 910,
        "periodType": "REGULAR",
        "score2": "79",
        "score1": "85",
        "y": 9.524,
        "x": 21.494,
        "subType": "",
        "qualifiers": [],
        "timeActual": "2017-04-19 20:16:33",
        "completionDelay": 1.317,
        "shotClock": "00:00:00",
        "edited": "2017-04-19 20:16:35",
        "teamNumber": 2,
        "type": "action",
        "side": "left",
        "clock": "00:15:36",
        "area": "outsideleft",
        "actionType": "3pt",
        "system": 1
    }
}

drive summary

This message type contains summary information about individual drive state

This message may be sent at the start and/or at the end of the drive. If properties of two messages overlap - the property of the latter message will be set as final. Drive summary is updated based on its drive number.

  type enum

The type of the message

drivesummary
  messageId integer

Unique identifier of the message being sent
  driveNumber integer

Unique sequence number for this drive
  teamNumber

The number of the team in the match that is in possesion when the drive starts, 1 or 2.

1
2
top string

Time spent during the particular drive

Format is: MM:SS
yards integer

Yards won/lost during the particular drive
plays integer

How many plays made during the particular drive
isHomeTeam integer

Whether the team has started the drive is Home or Visitor

1
Yes
0
No (Default)
startType enum

How the particular drive started

KICKOFF
PUNT
INTERCEPTION
FUMBLE
DOWNS
UNKNOWN
startQuarter integer

During which quarter the drive started
startTime string

Time of the start of the drive

Format is: MM:SS
startLine integer

The yard line where the drive started
startSideTeamId string

The team ID on which field side the drive stopped
stopType enum

How the particular drive ended

TOUCHDOWN
FIELDGOAL
SAFETY
PUNT
INTERCEPTION
FUMBLE
ENDOFHALF
DOWNS
UNKNOWN
stopQuarter integer

During which quarter the drive ended
stopTime string

Time of the end of the drive

Format is: MM:SS
stopLine integer

The yard line where the drive ended
stopSideTeamId string

The team ID on which field side the drive stopped

summary
This message type has information about the how the match was run. Usually it will only be sent once at the end of the match.
  type enum

The type of the message

summary
  messageId integer

Unique identifier of the message being sent
  timeActual datetime

The actual start date/time of the match in the UTC timezone

Format is: YYYY-MM-DD HH:MM:SS
  timeEndActual datetime

The actual end date/time of the match in the UTC timezone

Format is: YYYY-MM-DD HH:MM:SS or Unfinished
duration integer

The duration (in minutes) of the match, excluding any pregame activities
durationActual integer

The actual duration of the match (mins) including timeouts, stoppages and period breaks.
temperature integer

The temperature during the match (degrees Celsius)
hasFlaggedActions enum

Indication if match has game actions that need to be fixed

0
No (Default)
1
Yes
attendance integer

The number of people who attended the match

Example

{
    "durationActual": 97,
    "timeEndActual": "2017-03-05 14:38:01",
    "messageId": 923,
    "timeActual": "2017-03-05 13:01:11",
    "duration": 40,
    "attendance": 250,
    "temperature": 25,
    "hasFlaggedActions": 0,
    "type": "summary"
}

disconnect
The client should send this message to the server to notify it that it is explicitly ending its connection.
  type enum

The type of the message

disconnect
  reason enum

The reason for the disconnection

USER_INITIATED
The user initiated the disconnection (eg. pressing a disconnect button)
MATCH_COMPLETE
The match is complete
NO_HEARTBEAT
There was no heartbeat response from the server
OTHER
Another reason
description string

A description of the reason for the disconnection

Example

{
    "messageId": 923,
    "type": "disconnect",
    "reason": "USER_INITIATED",
    "description" : "User pressed disconnect"
}
Definitions

Action Types

For a particular action an event can have 1 type, 1 subtype and any number of qualifiers

If qualifiers are able to be used for a particular action/subType, then any number of qualifiers may be applied to the action.

If the subType indicates (blank) this means that the action can be used without a subType.

Sport Action Types
type subType qualifiers
game      
  start    
  end
  • confirmed
  
period      
  start    
  end
  • confirmed
  
cointoss (empty) Applies to all subTypes:
  • looserchoice
    • kickoff
    • receive
    • endzone
  • nullified
  • winnerchoice
    • kickoff
    • receive
    • endzone
    • winnerteam
  •  
overtime Applies to overtime subType:
  • defense
  • offense
secondhalf
startofgame Applies to startofgame subType:
  • defer
drive Applies to all subTypes:
  • drivetime
  • nullified
  • redzone
  • redzonedown
  • redzonefieldgoalmissed
  • redzonefumblelost
  • redzonegameend
  • redzonehalfend
  • redzoneinterception
  • redzonelostbydowns
  • status
    • started
    • ended
  • timeofpossession
  •  
  • drivetime: Drive time
  • timeofpossession: Time of possession
endofplay (empty) Applies to all subTypes:
  • nullified
  •  
extrapoint (empty) Applies to all subTypes:
  • nullified
  • pointsafterturnover
  • redzone
  •  
blocked Applies to blocked subType:
  • blockedby
nullifiedbypenalty
fieldgoal (empty) Applies to all subTypes:
  • firstandgoal
  • nullified
  • pointsafterturnover
  • redzone
  • yards
  •  
  • yards: Exact field goal yards
blocked Applies to blocked subType:
  • blockedby
nullifiedbypenalty
teamblocked
fumble (empty) Applies to all subTypes:
  • forcedby
  • nullified
  •  
lost Applies to lost subType:
  • recoveredafterlossby
recovered Applies to recovered subType:
  • recoveredby
team Applies to team subType:
  • loss
kickoff (empty) Applies to all subTypes:
  • grossyards
  • kickoffonside
  • kickoffonsideattempt
  • netyards
  • nullified
  •  
  • grossyards: Gross kickoff yards (actual kickoff distance)
  • netyards: Net Kickoff Yards (with Fair Catch and Touchback yards pre-applied)
faircatch
muffed
outofbounds Applies to outofbounds subType:
  • 5yardandrekick
  • 5yardfromoutofbounds
  • takeatthespot
return Applies to return subType:
  • muffed
touchback
outofbounds (empty) Applies to all subTypes:
  • nullified
  •  
kickoff Applies to kickoff subType:
  • penalty
  • penaltyyards
pass (empty) Applies to all subTypes:
  • left
  • middle
  • nullified
  • passbreakupby
  • pat
  • patconverted
  • quarterbackhurriedby
  • quarterbackhurriedbysecondary
  • redzone
  • right
  • target
  • touchdown
  • yards
  •  
  • passbreakupby: Player who broke up pass
  • quarterbackhurriedby: Player who hurried QB
  • quarterbackhurriedbysecondary: Second Player who hurried QB
  • yards: Pass yards
completed
incompleted Applies to incompleted subType:
  • dropped
intercepted Applies to intercepted subType:
  • interceptedby
sacked Applies to sacked subType:
  • fumble
  • rushingyards
spike
penalty (empty) Applies to all subTypes:
  • enforcementspot
    • succeeding
    • previous
    • spotofthefoul
    • deadball
  • nullified
  • reason
    • offside
    • delayofgame
    • illegalforwardpass
    • passinterference
    • holding
    • encroachment
    • falsestart
    • ineligibledownfieldonpass
    • illegalformation
    • illegalmotion
    • illegalsubstitution
    • illegalshift
    • illegalsnap
    • runningintoholder
    • runningintothekicker
    • returnfromoutofbounds
    • intentionalgrounding
    • illegalbat
    • illegalblockinback
    • blockbelowwaist
    • chopblock
    • clipping
    • fighting
    • facemask
    • illegalblockafterfcsignal
    • illegalwedge
    • tripping
    • unnecessaryroughness
    • unsportsmanlikeconduct
    • illegaluseofhands
    • personalfoul
    • horsecollartackle
    • disconcertingsignals
    • blockingoutofbounds
    • equipmentviolation
    • hurdling
    • illegalcontactwithsnapper
    • illegaltouchofkick
    • illegaltouchpass
    • leaping
    • leverage
    • roughingholder
    • roughingthepasser
    • roughingthekicker
    • targeting
    • kickcatchinterference
  •  
  • reason: Penalty reason
accepted Applies to accepted subType:
  • penaltyyards
declined
  • yardLine
offset
play Applies to all subTypes:
  • conversion
    • 0
    • 1
  • conversionattempt
    • 0
    • 1
  • down
    • first
    • second
    • third
    • fourth
  • firstdown
    • rushing
    • passing
    • penalty
    • rushingandpenalty
    • passingandpenalty
  • lateralplay
  • nullified
  • opponenttimeofpossession
  • redzonedown
  • scored
  • status
    • started
    • ended
  • timeofpossession
  • togo
  • type
    • snap
    • kickoff
    • pat
  • yardLine
  •  
  • opponenttimeofpossession: Time of possession for opponent team in case of first kickoff in game
  • timeofpossession: Time of possession for team in case of kickoff
  • togo: how many yards to the first down
  • yardLine: line of scrimmage
punt (empty) Applies to all subTypes:
  • grossyards
  • insidetwenty
  • netyards
  • nullified
  •  
  • grossyards: Gross punt yards (actual kickoff distance)
  • netyards: Net punt yards (with Fair Catch and Touchback yards pre-applied)
blocked Applies to blocked subType:
  • blockedby
downed
faircatch
muffed
outofbounds
return
teamblocked
touchback
reception (empty) Applies to all subTypes:
  • afterlateral
  • afterrecovery
  • nullified
  • reception
  • receptionyards
  • yardsaftercatch
  •  
  • receptionyards: Reception distance in yards
  • yardsaftercatch: Yards gained after pass was caught
recovery
fumble Applies to fumble subType:
  • lostby
return Applies to all subTypes:
  • afterlateral
  • afterrecovery
  • attempt
  • nullified
  • pat
  • yards
  •  
  • yards: Return yards
fieldgoal
fumble
interception
kickoff
punt
teamkickoff
teampunt
rush (empty) Applies to all subTypes:
  • afterlateral
  • afterrecovery
  • attempt
  • left
  • middle
  • nullified
  • pat
  • right
  • yardsgained
  • yardslost
  •  
  • yardsgained: Yards gained by rushing
  • yardslost: Yards lost by rushing
quarterbackkneel
quarterbackscramble
sack (empty) Applies to all subTypes:
  • nullified
  • quarterback
  • sackyards
  •  
  • quarterback: player number of opposing team's quarterback who will get negative rushing yards
  • sackyards: Yards lost due to sack
assisted Applies to assisted subType:
  • assistedby
  • assistedsackyards
unassisted Applies to unassisted subType:
  • fumble
timeout (empty)
other
team
safety (empty) Applies to all subTypes:
  • nullified
  • pointsafterturnover
  •  
nullifiedbypenalty
onepoint Applies to onepoint subType:
  • defensive
teamtwopoint
twopoint
snap (empty) Applies to all subTypes:
  • ballsnapped
  • huddle
  • miscfumble
  • nohuddle
  • nullified
  •  
fieldgoal
punt
shotgun
undercenter
tackle (empty) Applies to all subTypes:
  • assistedby
  • forcedfumble
  • fumble
  • interception
  • kickoff
  • kickoffreturn
  • nullified
  • pass
  • punt
  • puntreturn
  • rush
  • tackleforlossyards
  •  
  • assistedby: Tackle assisted by player
  • tackleforlossyards: Tackle for loss distance in yards
assisted
assistedtackleforloss Applies to assistedtackleforloss subType:
  • assistedtackleforlossyards
unassisted
unassistedtackleforloss
touchdown (empty) Applies to all subTypes:
  • firstandgoal
  • fumblereturn
  • interception
  • kickreturn
  • nullified
  • pointsafterturnover
  • puntreturn
  • reception
  • redzonereception
  • redzonerush
  • rush
  •  
nullifiedbypenalty
twopointconversion (empty) Applies to all subTypes:
  • nullified
  • pointsafterturnover
  • reception
  • redzone
  • rushing
  •  
defensiveconversion Applies to defensiveconversion subType:
  • fumbleconversion
  • interceptionconversion
  • kickconversion
nullifiedbypenalty
participated (empty) Applies to all subTypes:
  • players
  • players: comma-separated list of player numbers

Administrative Action Types
type subType qualifiers  
status     Indicates a change in the status of the match
  delayed
  • prevgame
  • teamlate
  • early
 The start time of the match has been changed. The delay in minutes should be passed in the value field. Negative delays are allowed (to indicate early start).
  loaded   The match has been loaded in the software
  ready   The match is ready to proceed in the software and the teams have been loaded
  inprogress   The match is currently in progress
  periodbreak   The match is currently in progress, but in a break between periods
  interrupted
  • equipment
  • venue
  • weather
  • spectator
  • medical
 The match has been stopped temporarily and will resume after a delay. The delay in minutes should be passed in the value field. The qualifiers can be used to give a reason for the delay.
  cancelled   The match will not be started
  abandoned   The match has been stopped and will not restart
  rescheduled   The match has been stopped (or has not started) and will not start/restart. It will be played again at another time.
  finished   The match has come to the end
  protested   The match has come to the end, but the result has been protested
  complete   The match is complete, all scores have been confirmed and result is official
periodstatus     Indicates a change in the period status
  pending   Indicates the period is about to start
  started   Indicates the period has started
  ended   Indicates the period has ended
  confirmed   Indicates that scores have been confirmed for the period
capturestatus      
  unreliable   Indicates that the state of the game being sent by the software differs significantly from the actual situation.
  reliable   Indicates that the state of the game being sent by the software now matches the actual situation.
clock      
  start    
  stop    
  adjustment   The number of seconds adjustment should be passed in the value field. Negative values are allowed
risk (empty)
  • goal
  • cardyellow
  • var
  • cardred
  • penalty