Livestream - READ - FAQs

The purpose of this guide is to answer some of the Frequently Asked Questions we get in regards to how a user can implement the livestream READ feed.

The specific calls this FAQ will cover can be found in v2 READ documentation. Please check the Live Stream READ Documentation for more information.

Type of Connection

Most importantly, a long running socket connection MUST be used in order to digest the data from the READ stream. See below for code examples.

Frequently Asked Questions

When should I connect?

Connection should be made before the match in question is scheduled to take place. Please check the Available Matches Documentation for more information. You should not connect more than 30min prior to the scheduled start of the match.

If the capture device at the venue has not yet connected then you will receive the following connection message.

            {"type":"connection","instance":"","status":"NOTCONNECTED"}
            

Once connected, the connection will send a message indicating that the courtside device is connected.

            {"type":"connection","instance":"786f42af45a89bbe10bd0e5350e09ba3","status":"CONNECTED"}
            

The status messages (type=st) will also contain the status of the match. For example inprogress.

How do I connect to the feed

A long running socket connection must be used to digest the data from the v2 READ feed.

The example below provides some sample code in PHP to process the read feed. It connects to the feed, process the data into messages and coverts the data into a PHP data structure. It then calls a callback function to deal with the data.

$url = "https://live.test.wh.sportingpulseinternational.com/v2/basketball/read/12345?ak=SAMPLE_API_KEY";
$r   = new ReaderExample();
$r->run($url, 'processdata');


// Callback function to process the data
function processdata($data)
{
    // Do whatever you need to do with the data
    var_dump($data);
}


class ReaderExample
{
    protected $msg_buffer = '';
    protected $callback = '';

    const MAX_LENGTH = 1000000;
    const EOL_SEPARATOR = "\r\n";

    public function run($url, $callbackfunction)
    {
        $this->callback = $callbackfunction;
        $curlURL        = $url;
        $ch             = curl_init();
        curl_setopt($ch, CURLOPT_URL, $url);
        curl_setopt($ch, CURLOPT_WRITEFUNCTION, array(
            $this,
            'on_Read'
        ));
        curl_exec($ch);
        curl_close($ch);
        return 1;
    }

    protected function on_Read($ch, $str)
    {
        $this->msg_buffer .= $str;
        while (($p = strrpos($this->msg_buffer, self::EOL_SEPARATOR)) !== false) {
            $msgs             = explode(self::EOL_SEPARATOR, substr($this->msg_buffer, 0, $p));
            $this->msg_buffer = substr($this->msg_buffer, $p + strlen(self::EOL_SEPARATOR));
            foreach ($msgs as $msg)
                $this->on_Read_Message(rtrim($msg, self::EOL_SEPARATOR) . self::EOL_SEPARATOR);
        }

        if (strlen($this->msg_buffer) > self::MAX_LENGTH) {
            $this->on_Read_Message($this->msg_buffer);
            $this->msg_buffer = "";
        }
        return strlen($str);
    }

    public function on_Read_Message($msgIn)
    {
        $msg = json_decode($msgIn, true);
        if (!$msg) {
            error_log("INVALID MESSAGE $msgIn");
            return false;
        }
        call_user_func($this->callback, $msg);
        return true;
    }

}
            

How long should I connect for

The connection should continue from pre-game until the type=st status of complete is received.

Excluding network drop-outs you should only connect once per match. Many connections of short durations will result in your access to the match being revoked automatically by the system.

How do I get prematch player lists?

If players have been selected to play in the match before match time, then they will be available in the Match Players call in the Data Warehouse REST API. If they have not been pre-selected, then the players for the match will appear in the team messages as they are selected.

What do I receive on connection/re-connection?

When you connect to the READ stream you will immediately receive any relevant data. What this data is depends on the state of the game and the parameters you set on connection.

On each connection you will receive a connection message indicating whether the venue application is currently connected. If it is currently connected the value will be CONNECTED, if they are yet to connect it will be NOTCONNECTED. If the application has been connected for this match, but is not currently, the value will be LOST.

If the match is in progress (or there is data available) you will receive that latest version of the following messages: (depending on your types setting)

When any event happens in the game that causes this data to change, then you will receive updated versions of these messages.

If you have chosen to receive message of type action the data you are sent on connection depends on the fromMessageId parameter. When you connect by default you will not receive any action messages that have occurred in the past (they will still be part of the playbyplay), you will only receive new actions. If you want to receive actions generated previously you specify the messageId of the last action you received in the fromMessageId parameter and all the messages sent after that messageId will be resent. To resend all message from the start of the game set the fromMessageId parameter to 0.

This API is a streaming API, you are expected to connect once at the start of the game and consume the actions as they happen. Treating this API as a RESTful call and making multiple short calls to get the current list of actions will NOT be tolerated and your access will be revoked.

What happens when a match finishes?

When a match finishes the status message type will contain a message.status of complete.

Once a match is complete, you should disconnect.

Once the match reaches a status of 'complete' the data is processed and saved into the Data Warehouse. The processing can take a couple of minutes to occur, but after it is complete the data will be available using the standard Data Warehouse API calls (API Calls Documentation).

After the match is complete you should not reconnect to the stream.