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.
Differences between v1 read call and v2 read call
GET /v2/{sport}/read/{matchId}
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
|
||||||||||||||||||||||
types |
string |
A comma separated value of the message types to be sent through the feed. Message types are explained in detail below.
If not specified the following string is assumed
|
||||||||||||||||||||||
playbyplayOnConnect |
integer |
If this parameter is set to 1, then the playbyplay section will only be sent at the start of the connection not on every action. If the types parameter is used and pbp or pbc is not specified then this parameter has no effect as the playbyplay will not be sent at all. |
||||||||||||||||||||||
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 actions occurring in the game will not be sent, only new actions. By specifying a messageId with this parameter, actions occurring after the messageId specified here will be resent. 0 is valid and will resend all actions on connection. |
Do not supply a request body with this method.
The body of the response is a series of messages (defined below). Each message is delimited by a carriage return/line-feed \r\n
series of characters (in hex, 0x0D 0x0A).
This message type has the current status of the connection. This message type is always sent regardless of the values of the types
URL parameter. 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.
|
|||
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. |
{ "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 } } } }
This message type has the current status of the match.
message |
|||
type |
status |
||
clock |
The current time on the clock. Format MM:SS:ff (Minutes:Seconds:Hundredths) | ||
shotClock |
The current time on the shot clock. Format MM:SS:ff (Minutes:Seconds:Hundredths) | ||
clockRunning |
Is the clock currently running? 1 = yes, 0 = no | ||
possession |
The number of the team in the match, 1 or 2 that currently has possession. 0 is valid. | ||
possessionArrow |
The number of the team in the match, 1 or 2 to which the possession Arrow is currently pointing. 0 is valid. | ||
period |
|||
current |
The current period number. Overtime periods start at 1 | ||
periodType |
The type of the current period.
|
||
status |
The current status of the match
|
||
periodStatus |
The current status of the period
|
||
scores |
An array of team records | ||
teamNumber |
The number of the team in the match, 1 or 2. | ||
score |
The total score for that team in the match |
{ "message": { "type": "status", "period": { "current": "1", "periodType": "REGULAR" }, "clock": "10:00:00", "clockRunning": 1, "shotClock": "00:10:00", "status": "inprogress", "periodStatus": "started" "scores": [ { "teamNumber":1, "score":5 }, { "teamNumber":2, "score":22 } ] } }
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 | ||
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 |
{ "message": { "type": "setup", "messageId" : 6, "periods": { "number":2, "length" : 20, "extraTimeLength" : 5, "breakPeriod" : 2, "breakHalftime" : 2, "extraTime: 1 }, "maxFoulsPersonal": "5", "maxFoulsTechnical": "5", "shotClock": "25", "timeouts" : { "style": "period", "half1": "2", "half2": "3", "period1": "2", "period2": "2", "period3": "2", "period4": "2", "extraTime": "1" } } }
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 |
|||
suburb |
|||
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 |
"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": "AUS", "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": "AUS", "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" } }
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 |
{ "message": { "type": "teams", "messageId" : 6, "teams": [ { "teamNumber": 1, "detail": { "teamName": "Rotherberg Raiders", "teamId": 2065, "externalId": "243", "internationalReference": "T1234", "teamNickname": "Raiders", "teamCode": "RRD", "countryCode": "AU", "countryCodeIOC": "AUS", "country": "Australia", "website": "http://www.rrd.com", "logoURL": "http:/www.rrd.com/logo.jpg" }, "players": [ { "pno": 1, "firstName": "John", "familyName": "Smith", "personId": 3456, "website": "http://www.johnsmith.com", "profileURL": "http://www.rrd.com/players/johnsmith.html", "captain": 1, "active": 1, "starter": 1 }, { "pno": 2, "firstName": "Aaron", "familyName": "Person", "personId": 57564, "profileURL": "http://www.rrd.com/players/aaronperson.html", "captain": 0, "active": 1, "starter": 0 } ], "coach": { "firstName": "John", "familyName": "Richardson", "personId": 57564, "externalId": "98" } }, { "teamNumber": 2, "detail": { "teamName": "Sackville Hawks", "teamId": 2066, "externalId": "248", "internationalReference": "T1238", "teamNickname": "Hawks", "teamCode": "SVH", "countryCode": "AU", "countryCodeIOC": "AUS", "country": "Australia", "website": "http://www.svh.com", "logoURL": "http:/www.svh.com/logo.jpg" }, "players": [ { "pno": 1, "firstName": "Martin", "familyName": "Mann", "personId": 3458, "profileURL": "http://www.svh.com/players/mm.html", "captain": 1, "active": 1, "starter": 1 }, { "pno": 2, "firstName": "Archie", "familyName": "Person", "personId": 57544, "profileURL": "http://www.svh.com/players/ap.html", "captain": 0, "active": 1, "starter": 0 } ], "coach": { "firstName": "Marsha", "familyName": "Bradley", "personId": 564, "externalId": "28" }, "assistcoach1": { "firstName": "Greg", "familyName": "Martin", "personId": 567, "externalId": "29" } } ] } }
This message type contains the information about the match officials assigned to the match.
message |
|||
type |
officials |
||
messageId |
Unique message identifier (see main description) | ||
commissioner |
|||
firstName |
|||
familyName |
|||
firstNameTV |
|||
familyNameTV |
|||
nickName |
|||
personId |
|||
externalId |
|||
referee1 |
|||
firstName |
|||
familyName |
|||
firstNameTV |
|||
familyNameTV |
|||
nickName |
|||
personId |
|||
externalId |
|||
referee2 |
|||
firstName |
|||
familyName |
|||
firstNameTV |
|||
familyNameTV |
|||
nickName |
|||
personId |
|||
externalId |
|||
referee3 |
|||
firstName |
|||
familyName |
|||
firstNameTV |
|||
familyNameTV |
|||
nickName |
|||
personId |
|||
externalId |
{ "message": { "type": "officials", "messageId": 9, "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" } } }
This message type contains the values for the box score (team and player statistics).
The periods
key (and everything below it) is only included in the message if the bxa
types parameter has been used.
message |
|||||
type |
boxscore |
||||
teams |
An array of teams | ||||
teamNumber |
The number of the team in the match, 1 or 2. | ||||
total |
|||||
team |
|||||
statname |
This section can contain any number of team match statistics columns appropriate for the sport. | ||||
players |
An array of 1 to many players | ||||
pno |
The number of the player in the match. This is a sequence number not a jumper number. | ||||
statname |
This section can contain any number of person match statistics columns appropriate for the sport. | ||||
periods |
Optional depending on types parameter |
||||
period |
The period number. Overtime periods start at 1 | ||||
periodType |
The type of period.
|
||||
team |
|||||
statname |
This section can contain any number of person match statistics columns appropriate for the sport. | ||||
players |
An array of 1 to many players | ||||
pno |
The number of the player in the match. This is a sequence number not a jumper number. | ||||
statname |
This section can contain any number of person match statistics columns appropriate for the sport. |
{ "message": { "type": "boxscore", "teams": [ { "teamNumber": 1, "total": { "team": { "sTurnovers": "10", "sThreePointersAttempted": "50", "sThreePointersMade": "10" }, "players": [ { "pno": 1, "sFoulsOn": "2", "sBlocks": "3", "sAssists": "2", "sThreePointersAttempted": "10", "sThreePointersMade": "3" }, { "pno": 2, "sFoulsOn": "1", "sBlocks": "6", "sAssists": "4", "sThreePointersAttempted": "4", "sThreePointersMade": "4" } ] }, "periods": [ { "period": 1, "periodType": "REGULAR", "team": { "sTurnovers": "5", "sThreePointersAttempted": "30", "sThreePointersMade": "3" }, "players": [ { "pno": 1, "sFoulsOn": "1", "sBlocks": "2", "sAssists": "0", "sThreePointersAttempted": "5", "sThreePointersMade": "0" }, { "pno": 2, "sFoulsOn": "1", "sBlocks": "0", "sAssists": "2", "sThreePointersAttempted": "2", "sThreePointersMade": "2" } ] }, { "period": 2, "periodType": "REGULAR", "team": { "sTurnovers": "5", "sThreePointersAttempted": "20", "sThreePointersMade": "7" }, "players": [ { "pno": 1, "sFoulsOn": "1", "sBlocks": "1", "sAssists": "2", "sThreePointersAttempted": "5", "sThreePointersMade": "3" }, { "pno": 2, "sFoulsOn": "0", "sBlocks": "6", "sAssists": "2", "sThreePointersAttempted": "2", "sThreePointersMade": "2" } ] } ] }, { "teamNumber": 2, "totals": { "team": { "sTurnovers": "9", "sThreePointersAttempted": "49", "sThreePointersMade": "9" }, "players": [ { "pno": 2, "sFoulsOn": "1", "sBlocks": "2", "sAssists": "1", "sThreePointersAttempted": "9", "sThreePointersMade": "2" }, { "pno": 3, "sFoulsOn": "0", "sBlocks": "5", "sAssists": "3", "sThreePointersAttempted": "3", "sThreePointersMade": "3" } ] }, "periods": [ { "period": 1, "periodType": "REGULAR", "team": { "sTurnovers": "2", "sThreePointersAttempted": "45", "sThreePointersMade": "8" }, "players": [ { "pno": 2, "sFoulsOn": "0", "sBlocks": "0", "sAssists": "0", "sThreePointersAttempted": "2", "sThreePointersMade": "0" }, { "pno": 3, "sFoulsOn": "0", "sBlocks": "4", "sAssists": "1", "sThreePointersAttempted": "3", "sThreePointersMade": "3" } ] }, { "period": 2, "periodType": "REGULAR", "team": { "sTurnovers": "7", "sThreePointersAttempted": "4", "sThreePointersMade": "1" }, "players": [ { "pno": 2, "sFoulsOn": "1", "sBlocks": "2", "sAssists": "1", "sThreePointersAttempted": "7", "sThreePointersMade": "2" }, { "pno": 3, "sFoulsOn": "0", "sBlocks": "1", "sAssists": "2", "sThreePointersAttempted": "0", "sThreePointersMade": "0" } ] } ] } ] } }
This message type contains a list of all the actions in the match.
message |
||||
type |
playbyplay |
|||
actions |
A list of actions | |||
actionNumber |
The unique sequence number given to this action | |||
messageId |
Unique message identifier | |||
origMessageId |
If this action is a delete/update then this field contains the messageId of the original message |
|||
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.
|
|||
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: | |||
score1 |
The score for team number 1 after the result of this action | |||
score2 |
The score for team number 2 after the result of this action | |||
officialId |
The unique identifier for the official that called this action. | |||
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. | |||
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. | |||
value |
A text field. Some action types require a value. This is where that value needs to be placed. | |||
players |
||||
team1 |
A list of the pnos of the players that were active for team number 1 at the time of the action. | |||
team2 |
A list of the pnos of the players that were active for team number 1 at the time of the action. | |||
edited |
If the action has been edited (after being initially sent) this field contains the last time it was edited (in UTC). The time is 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 present. | |||
inserted |
If the action has been inserted (added out of sequence) this field contains the time it was inserted(in UTC). The time is in the following format (in UTC). Format YYYY-MM-DD HH:MM:SS. If the action has not been inserted, then this field is not present. | |||
deleted |
If the action has been deleted (after being initially sent) this field contains the time it was deleted (in UTC). The time is 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 present. | |||
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. |
{ "message": { "type": "playbyplay", "actions": [ { "actionNumber": 1, "period": 1, "periodType": "REGULAR", "clock": "10:00:00", "timeActual": "2013-08-13 15:56:00", "shotClock": "00:20:00", "teamNumber": 1, "pno": 1, "score1": "0", "score2": "0", "actionType": "sub", "subType": "in", "previousAction": 0 }, { "actionNumber": 2, "period": 1, "periodType": "REGULAR", "clock": "09:56:00", "timeActual": "2013-08-13 15:56:00", "shotClock": "00:15:00", "teamNumber": 1, "pno": 1, "score1": "1", "score2": "2", "actionType": "2pt", "subType": "dunk", "qualifiers": ["2ndchance","fastbreak"], "x" : "300", "y" : "400", "side" : "left", "area" : "inthepaint", "previousAction": 0, "success" : 1, "players": { "team1": [ "1", "2", "6", "9", "10" ], "team2": [ "1", "4", "6", "7", "8" ] } }, { "actionNumber": 1, "period": 1, "periodType": "REGULAR", "clock": "09:56:00", "timeActual": "2013-08-13 15:56:00", "shotClock": "00:23:00", "teamNumber": 1, "pno": 1, "score1": "1", "score2": "2", "actionType": "freethrow", "subType": "1of2", "qualifiers": ["turnover"], "x" : "200", "y" : "200", "side" : "left", "area" : "insidecenter", "previousAction": 0, "success" : 1, "players": { "team1": [ 1, 2, 6, 9, 1 ], "team2": [ 1, 4, 6, 7, 8 ] } } ] } }
This message type contains one specific action in the match.
This contains a singular action in the same format as a playbyplay action.
Note:In the singular action message, the fields score1
and score2
have slightly different behaviour than in the playbyplay
message. They contain the current score, not the score after the result of the action. This means that even if the edit of a period 2 action was made in period 4, then the scores are the current score as of period 4 - with any result of the edit taken into account.
{ "message": { "type": "action", "actionNumber": 1, "period": 1, "periodType": "REGULAR", "clock": "10:00:00", "timeActual": "2013-08-13 15:56:00", "shotClock": "00:20:00", "teamNumber": 1, "pno": 1, "score1": "0", "score2": "0", "actionType": "sub", "subType": "in", "previousAction": 0 } }
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 |
{ "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 } }