Read log

Read a stream of live game events.

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

This call returns the actions as sent by the capture device. It does not calculate play by play or box scores and it does not return game status messages, it is purely a stream of setup and action messages.

HTTP Request

GET /v2/{sport}/readlog/{matchId}

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

Parameters

Parameter Name Value Description
Required Parameters
sport string The sport for which you are making the request
ak string The API key given to you
matchId string The unique matchId for the match
Optional Parameters
format string The format the data is to be received in. Options are
  • json (Default)
  • xml
latency integer If this parameter is set to 1, then extra timing information will be included in the data returned.
fromMessageId integer When connecting to the service, previous messages occurring in the game will not be sent, only new messages. By specifying a messageId with this paramter, messages with a messageId greater than (or equal to) the number specified here will be resent. 0 is valid and will resend all messages on connection.

Request Body

Do not supply a request body with this method.

Response

The body of the response is a series of messages (defined below). Each message is delimted by a carriage return/line-feed \r\n series of characters (in hex, 0x0D 0x0A).

Message Types

connection

This message type has the current status of the connection. If no other message is available, this message type will be sent every 5 seconds to maintain the connection.

message
  type     connection
  instance     The unique identifier of the controlling instance for this match.
  status     The current status of the connection to the match data capture device.
  • NOTCONNECTED The device has not yet connected
  • CONNECTED The device is currently connected
  • LOST The device has lost connection
  • COMPLETED The device has completed its collection
  latency     Only provided if latency=1 parameter is set.
    total    
      1m The average latency (over the last 1 minute) in seconds between the capture device and the data being available.
      5m The average latency (over the last 5 minutes) in seconds between the capture device and the data being available.
      15m The average latency (over the last 15 minutes) in seconds between the capture device and the data being available.
    process    
      1m The average latency (over the last 1 minute) in seconds between the data being received from the capture devie and being available.
      5m The average latency (over the last 5 minutes) in seconds between the data being received from the capture devie and being available.
      15m The average latency (over the last 15 minutes) in seconds between the data being received from the capture devie and being available.
    capture    
      1m The average latency (over the last 1 minute) in seconds between the capture device and the system.
      5m The average latency (over the last 5 minutes) in seconds between the capture device and the system.
      15m The average latency (over the last 15 minutes) in seconds between the capture device and the system.
Example 
        {
          "message": {
            "type": "connection",
            "status" : "CONNECTED"
            "instance" : "1234"
            "latency" : {
                "total" : {
                    "1m" : 1.2,
                    "5m" : 1.41,
                    "15m" : 1.3
                },
                "capture" : {
                    "1m" : 0.4,
                    "5m" : 0.7,
                    "15m" : 0.6
                },
                "process" : {
                    "1m" : 0.8,
                    "5m" : 0.71,
                    "15m" : 0.7
                }
            }
          }
        }

setup

This message type has information about the how the match will be run.

message
  type   setup
  messageId   Unique message identifier
  periods    
    number The number of periods
    length The length of the periods
    extraTime Is extra time available
    extraTimeLength The length of the extra time periods
    breakPeriod The length (in minutes) between periods
    breakHalftime The length (in minutes) at half time
  shotClock   The length of time (in seconds) for the shotClock
  foulsPersonal   The maximum number of fouls (personal) allowed
  foulsTechnical   The maximum number of fouls (technical) allowed
  foulsBeforeBonus   The number of fouls allowed before a bonus is given
  timeouts    
    style How are timeouts counted, by period or half
    period1 The maximum number of timeouts allowed in period 1
    period2 The maximum number of timeouts allowed in period 2
    period3 The maximum number of timeouts allowed in period 3
    period4 The maximum number of timeouts allowed in period 4
    half1 The maximum number of timeouts allowed in the first half
    half2 The maximum number of timeouts allowed in the second half
    extraTime The maximum number of timeouts allowed in extraTime
Example 
        {
          "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"
            }
          }
        }

matchInformation

This message type has information about the match.

message
  type matchInformation
  competition    
    competitionName
    competitionAbbrev
    competitionNameInternational
    competitionAbbrevInternational
    standard
    competitionId
    externalId
    twitter
    gender
    year
    ageGroup
    logo The files sub-structure from the Upload Resource. Only present if this competition has a logo that has been uploaded.
  venue    
    venueName
    venueCode
    venueNickname
    venueId
    venueNameInternational
    venueCodeInternational
    venueNicknameInternational
    venueId
    externalId
    countryCode
    countryCodeIOC
    country
    latitude
    longitude
    surfaceName
    seatingCapacity
    timezone
  league    
    leagueName
    leagueAbbrev
    leagueNameInternational
    leagueAbbrevInternational
    leagueId
    geographicRegion
    externalId
    countryCode
    countryCodeIOC
    country
    logo The files sub-structure from the Upload Resource. Only present if this league has a logo that has been uploaded.
  match    
    matchTime
    matchName
    matchNumber
    phaseName
    poolNumber
    roundDescription
    roundNumber
    matchType
    twitterHashtag
    matchId
    externalId
  pool    
    poolName
    poolNumber
    externalId
Example 
        "matchInformation" : {
            "competition": {
              "competitionName": "National Basketball League 2014",
              "competitionAbbrev": "NBL2014",
              "standard": "ELITE",
              "competitionId": 2045,
              "externalId": "23",
              "twitter": "nbl",
              "gender": "MALE",
              "year": 2014,
              "ageGroup": "SENIOR"
            },
            "venue": {
              "venueName": "Maximum Stadium",
              "venueCode": "MAX",
              "locationName": "National Sports Complex",
              "venueId": 2045,
              "externalId": "23",
              "countryCode": "AU",
              "countryCodeIOC": "AU",
              "country": "Australia",
              "latitude": "-34.567",
              "longitude": "-30.347",
              "surfaceName": "Court 1",
              "venueNickname": "MAXIS",
              "seatingCapacity": 90000,
              "timeZone": "Australia/Melbourne"
            },
            "league": {
              "leagueName": "National Basketball League",
              "leagueNabbrev": "NBL",
              "leagueId": 20,
              "externalId": "2",
              "geographicRegion": "NATIONAL",
              "countryCode": "AU",
              "countryCodeIOC": "AU",
              "country": "Australia"
            },
            "match": {
              "matchName": "Preliminary Final 3 v 4 ",
              "matchTime": "2013-06-07 19:30:00",
              "matchNumber": 45,
              "phaseName": "Preliminary Round - A",
              "poolNumber": 1,
              "roundName": "Preliminary Finals",
              "roundNumber": 4,
              "matchType": "FINALS',
              "twitterhashtag": "nbl14m45',
              "matchId": 2065,
              "externalId": "243"
            }
            "pool": {
              "poolNumber": 1,
              "poolName": "Pool 1",
              "externalId": "23"
            }
        }

teams

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

message
  type     teams
  messageId     Unique message identifier
  teams     An array of team records
    teamNumber   The number of the team in the match, 1 or 2.
    detail    
      teamName  
      teamNameInternational  
      teamId  
      externalId  
      internationalReference  
      teamNickname  
      teamCode  
      teamCodeInternational  
      teamNicknameInternational  
      countryCode  
      countryCodeIOC  
      country  
      website  
      logo The files sub-structure from the Upload Resource. Only present if this team has a logo that has been uploaded.
    players   A list of players
      pno The number of the player in the match. This is a sequence number not a jumper number.
      firstName  
      familyName  
      firstNameTV  
      familyNameTV  
      nickName  
      internationalFirstName  
      internationalFamilyName  
      scoreboardName  
      personId  
      externalId  
      internationalReference  
      nationality  
      nationalityCode  
      nationalityCodeIOC  
      website  
      photo The files sub-structure from the Upload Resource. Only present if this person has a photo that has been uploaded.
      shirtNumber  
      playingPosition  
      dob  
      height  
      active Is this player currently active? 1 = yes, 0 = no
      captain Is this player the captain? 1 = yes, 0 = no
      starter Is this player a starter? 1 = yes, 0 = no
    coach    
      firstName  
      familyName  
      firstNameTV  
      familyNameTV  
      nickName  
      internationalFirstName  
      internationalFamilyName  
      scoreboardName  
      personId  
      externalId  
    assistcoach1    
      firstName  
      familyName  
      firstNameTV  
      nickName  
      internationalFirstName  
      internationalFamilyName  
      scoreboardName  
      personId  
      externalId  
    assistcoach2    
      firstName  
      familyName  
      firstNameTV  
      familyNameTV  
      nickName  
      internationalFirstName  
      internationalFamilyName  
      scoreboardName  
      personId  
      externalId  
Example 
            {
              "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
                    }
                  }
                ]
              }
            }

officials

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   Unique message identifier (see main description)
  commissioner    
    personId Unique identifier for the person acting as Commissioner (generated by the warehouse system)
    firstName First name of person acting as Commissioner
    familyName Family name of person acting as Commissioner
    externalId ExternalId of person acting as Commissioner
  referee1    
    personId Unique identifier for the person acting as Referee 1 (generated by the warehouse system)
    firstName First name of person acting as Referee 1
    familyName Family name of person acting as Referee 1
    externalId ExternalId of person acting as Referee 1
  referee2    
    personId Unique identifier for the person acting as Referee 2 (generated by the warehouse system)
    firstName First name of person acting as Referee 2
    familyName Family name of person acting as Referee 2
    externalId ExternalId of person acting as Referee 2
  referee3    
    personId Unique identifier for the person acting as Referee 3 (generated by the warehouse system)
    firstName First name of person acting as Referee 3
    familyName Family name of person acting as Referee 3
    externalId ExternalId of person acting as Referee 3
Example 
        {
          "message": {
            "type": "officials",
            "messageId" : 3,
            "commissioner" : {
                "personId" : 2345,
                "name" : "John Smith",
                "externalId" : "HY3434"
            },
            "referee1" : {
                "personId" : 34,
                "name" : "Angus Smythe",
                "externalId" : "56"
            },
            "referee2" : {
                "personId" : 987,
                "name" : "Mary Richardson",
                "externalId" : "MR8"
            }
          }
        }

action

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     Unique message identifier (see main description)
  origMessageId     If this action is a delete/update then this field contains the messageId of the original message
  actionNumber     The unique sequence number given to this action. See above
  clock     The current time on the clock. Format MM:SS:CC
  shotClock     The current time on the shot clock. Format MM:SS:CC
  timeActual     The actual time for this action in UTC. Format YYYY-MM-DD HH:MM:SS
  period     The period number. Overtime periods start at 1
  periodType     The type of period.
  • REGULAR
  • OVERTIME
  teamNumber     The team this action relates to. 1 or 2. 0 for not team related actions, eg start gane
  pno     The player this action relates to. The player's number inside the team, not their playing number
  actionType     A code representating the action taken. Defined by sport:
  subType     The subType of action occurring. Defined by sport:
  qualifiers     An semi-colon ';' delimited string of qualifiers to the action. Defined by sport:
  value     A text field. Some action types require a value. This is where that value needs to be placed. Defined by sport:
  score1     The current score for team number 1. Even if this action is an edit for a previous period, this should be the current score.
  score2     The current score for team number 2. Even if this action is an edit for a previous period, this should be the current score.
  previousAction     If this action is the result of another action. This field should hold the number of the previous action.
  success     This action was completed successfully. 1 = yes, 0 = no. Generally all actions except shots are successful.
  officialId     The unique identifier for the official that called this action.
  area     The area on the playing surface where the action occurred. Defined in Playing Surface Definition.
  x     The x coordinate for where the action occurred on the playing surface. Defined in Playing Surface Definition.
  y     The y coordinate for where the action occurred on the playing surface. Defined in Playing Surface Definition.
  side     The side of the playing surface, left or right. Defined in Playing Surface Definition.
  edited     If the action has been edited (after being initially sent) this field should contain the last time it was edited (in UTC). The time should be in the following format (in UTC). Format YYYY-MM-DD HH:MM:SS. If the action has not been edited, then this field is not required.
  inserted     If the action has been inserted (added out of sequence) this field should contain the time it was inserted (in UTC). The time should be in the following format (in UTC). Format YYYY-MM-DD HH:MM:SS. If the action has not been inserted, then this field should not be present.
  deleted     If the action has been deleted (after being initially sent) this field should contain the time it was deleted (in UTC). The time should be in the following format (in UTC). Format YYYY-MM-DD HH:MM:SS. If the action has not been deleted, then this field is not required.
  system     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.
  underReview     1 = yes, 0 = no. 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.
  sendDelay     Optional. If present, this floating point number represents the number of seconds that have elapsed (at the time of sending the message) since the action occurred.
Example 
{
  "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
  }
}

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.

message
  type   summary
  messageId   Unique message identifier (see main description)
  timeActual   The actual start time of the match YYYY-MM-DD HH:MM:SS (local time)
  timeEndActual   The actual end time of the match YYYY-MM-DD HH:MM:SS (local time)
  durationActual   The actual duration of the match (mins) including timeouts and period breaks
  temperature   The temperature during the match (Degrees Celsius)
  attendance   Attendance of the match
  duration   The duration (in minutes) of the match - including overtime - excluding breaks and timeouts
Example 
        {
          "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
          }
        }