Publish v 2.0

Publish a match to the system action by action as the match is in progress.

This method instantiates a long running call, which will remain open as long as data is being sent.

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

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.

Parameters

            POST /v2/basketball/publish?streamKey=TESTSTREAMKEY&timestamp=1412987153 HTTP/1.1
            Host: localhost:8000
            Connection: keep-alive

        

            /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.

        {
          "message": {
            "type": "master",
            "format": "json"
          }
        }
        

        {
          "compressedMessage": "q1YqqSxIVbJSyk0sLkktUtJRSssvyk0sAYpkFefnKdUCAA=="
        }
        

Connection time-outs

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.

MessageId

Each message from the message category 'match' must include a messageId parameter. 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.

When to send Messages

Messages should be sent as soon as possible after some kind of action occurs.

For example these are the sections you would send for particular events:

• Foul: action (Foul), action (PossessionChange)
• Successful shot: action(3pt)
• Substitution In: action(substitution in)
• Start of Match: status (inprogress), periodstatus (started), game (start), period (start), clock (start)
• Start of Period: periodstatus (started), period (start), clock (start)

Message Types - Sending

For detailed information about the size and types of the field values, please check the corresponding resource description in the Warehouse API documentation.

setupMessage Category : Match

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.

The fields for this message type differ by sport. The fields are listed below, by sport.

Basketball:

3x3 Basketball:

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

teamsMessage Category : Match

This message type defines the teams and players for the match.

It is compulsory to send at least one of these messages.

            {
              "message": {
                "type": "teams",
                "messageId" : 6,
                "teams": [
                  {
                    "teamNumber": 1,
                    "detail": {
                      "teamName": "Rotherberg Raiders",
                      "teamId": 2065,
                      "teamNickname": "Raiders",
                      "teamCode": "RRD"
                    },
                    "players": [
                      {
                        "pno": 1,
                        "firstName": "John",
                        "familyName": "Smith",
                        "personId": 3456,
                        "captain": 1,
                        "active": 1,
                        "starter": 1
                      },
                      {
                        "pno": 2,
                        "firstName": "Aaron",
                        "familyName": "Person",
                        "personId": 57564,
                        "captain": 0,
                        "active": 1,
                        "starter": 0
                      }
                    ],
                    "coach": {
                      "personId": 57564
                    }
                  },
                  {
                    "teamNumber": 2,
                    "detail": {
                      "teamName": "Sackville Hawks",
                      "teamId": 2066,
                      "teamNickname": "Hawks",
                      "teamCode": "SVH"
                    },
                    "players": [
                      {
                        "pno": 1,
                        "firstName": "Martin",
                        "familyName": "Mann",
                        "personId": 3458,
                        "captain": 1,
                        "active": 1,
                        "starter": 1
                      },
                      {
                        "pno": 2,
                        "firstName": "Archie",
                        "familyName": "Person",
                        "personId": 57544,
                        "captain": 0,
                        "active": 1,
                        "starter": 0
                      }
                    ],
                    "coach": {
                      "personId": 564
                    }
                  }
                ]
              }
            }
        

officialsMessage Category : Match

This message type contains the 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.

        {
          "message": {
            "type": "officials",
            "messageId" : 3,
            "commissioner" : {
                "personId" : 2345,
                "firstName" : "John",
                "familyName" : "Smith",
                "externalId" : "HY3434"
            },
            "referee1" : {
                "personId" : 34,
                "firstName" : "Angus",
                "familyName" : "Smythe",
                "externalId" : "56"
            },
            "referee2" : {
                "personId" : 987,
                "firstName" : "Mary",
                "familyName" : "Richardson",
                "externalId" : "MR8"
            }
          }
        }
        

actionMessage Category : Match

This message type contains one specific action in the match.

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.

{
  "message": {
    "type": "action",
    "messageId": 5,
    "actionNumber": 1,
    "period": 1,
    "periodType": "REGULAR",
    "clock": "10:00:00",
    "timeActual": "2013-08-13 15:56:00",
    "shotClock": "00:20",
    "teamNumber": 1,
    "pno": 1,
    "score1": "0",
    "score2": "0",
    "actionType": "substitution",
    "subType": "in",
    "previousAction": 0
  }
}
        

summaryMessage Category : Match

This message type has information about the how the match was run.

This message type is optional, but if sent, it must be sent before the match status is sent as completed.

        {
          "message": {
            "type": "summary",
            "messageId" : 456,
            "timeActual": "2015-06-04 18:00:00",
            "timeEndActual": "2015-06-04 21:04:00",
            "durationActual": 184,
            "temperature": 25,
            "attendance": 250,
            "duration": 48
          }
        }
        

master Message Category : Connection

This message type changes the mode of the connection from backup to master. Any other master connections will be disconnected.

This message type is only required if the client is making multiple simultaneous connections to the server.

        {
          "message": {
            "type": "master",
            "format": "json"
          }
        }
        

keepaliveMessage Category : Connection

This message type is sent to keep the connection to the server alive. This message is not required, but may be used to maintain an open connection. It is the only message type that does not require a messageId

        {
          "message": {
            "type": "keepalive"
          }
        }
        

latencyresponseMessage Category : Connection

The client should send this message type in response to a latencyrequest message.

            {
              "message": {
                "type": "latencyresponse",
                "number": 1394569858.9497
              }
            }
        

disconnectMessage Category : Connection

The client should send this message to the server when it ends its connection.

            {
              "message": {
                "type": "disconnect",
                "reason": "USER_INITIATED",
                "description" : "User pressed disconnect"
              }
            }
        

Message Types - Receiving

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.

authenticated

The message type is returned from the warehouse on successful authentication. Included in this message is the messageId 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.

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

error

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

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

latencyrequest

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

ack

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

The message contains the messageId of the sent message and actionNumber (if sent).

            {
              "message": {
                "type": "ack",
                "acktype": "action",
                "actionNumber": 783,
                "messageId": 1041
              }
            }
        

sendaction

In some circumstances the server will send an action message to the client. The client should interpret this message and action it as if the user had requested this action. It should then be sent back to the server as a normal action. If this is the case the server will send the action message with a messageId of 0.