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

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.

1: Default

periods associativearray

numberOfPeriods integer	The number of periods in a match, not including any over/extra time
periodLength integer	The length of each period (in minutes)
numberOfTimeoutsAllowed integer	How many timeouts can be taken in a Game Set.
numberOfSubstitutionsAllowed integer	Number of substitutions allowed in single Game Set.

pointsForWin integer

Points needed to win a Game Set.

pointsForWinTieBreak integer

Points needed to win a Tiebreak Game Set.

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 Statistics. 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.
colorCode string(7)	Team kit color in RGB format (e.g. '#FFFFFF')

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. `UNIVERSAL` Universal `LIBERO` Libero `OUTSIDEHITTER` Outside Hitter `OPPOSITE` Opposite `MIDDLEBLOCKER` Middle Blocker `SETTER` Setter `DS-L` Libero / Defensive specialist `DS` Defensive specialist `MH` Middle Hitter `RS` Right Side
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

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