The purpose of this guide is to show step-by-step how a piece of courtside software would make use of the warehouse livestream APIs.
This guide will make use of a sample basketball match. Please check the Live Stream API Documentation to find out what other pieces of data are possible.
This example assumes that the league being used is leagueId = 1 and that the streamKey being used (TEST0STREAM0KEY1234) has all the permissions required.
| Stream Key | Match Date | Home Team | Away Team | Venue |
|---|---|---|---|---|
| TEST0STREAM0KEY1234 | 25th April 2014 | Rotherberg Raiders | Sackville Hawks | Eastern Basketball Centre |
Before the match starts, a prematch call is made to retreive all the match information for setting up the courtside software.
{
"setup": {
"periods": {
"numberOfPeriods": "4",
"periodLength": "10",
"extraTime": "1",
"extraTimeLength": "5.00"
},
"foulsPersonal": 5,
"foulsTechnical": 5,
"shotClock" : "00:30:00",
"timeouts": {
"timeoutsStyle": "period",
"timeoutsPeriod1": "2",
"timeoutsPeriod2": "2",
"timeoutsPeriod3": "2",
"timeoutsPeriod4": "2",
"timeoutsExtraTime" : "1"
}
},
"matchInformation": {
"competition" : {
"competitionName" : "Test Competition",
"competitionAbbrev" : "Test",
"year" : "2014",
"gender" : "MALE",
"ageGroup" : "SENIOR",
"standard" : "TIER2",
"externalId" : "23"
},
"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": "Demo Basketball League",
"leagueAbbrev": "DBL",
"leagueId": 20,
"externalId": "2",
"geographicRegion": "NATIONAL",
"countryCode": "AU",
"countryCodeIOC": "AU",
"country": "Australia"
},
"match": {
"matchName": "Preliminary Final 3 v 4 ",
"matchTime": "2013-08-13 15:45:00",
"matchNumber": 45,
"phaseName": "Preliminary Round - A",
"poolName": "Finals",
"roundDescription": "Preliminary Finals",
"roundNumber": 4,
"matchType": "FINALS',
"twitterHashtag": "dblprelim',
"matchId": 2065,
"externalId": "243"
}
},
"teams": {
"teams": [
{
"teamNumber": 1,
"detail": {
"teamName": "Rotherberg Raiders",
"teamId": 28,
"externalId": "243",
"internationalReference": "T1234",
"teamNickname": "Raiders",
"teamCode": "RRD",
"countryCode": "AU",
"countryCodeIOC": "AU",
"country": "Australia",
"website": "http://www.rrd.com"
},
"players": [
{
"pno": 1,
"firstName": "John",
"familyName": "Smith",
"personId": 345,
"shirtNumber" : 45,
"playingPosition" : "FORWARD",
"dob" : "1977-10-26",
"gender" : "MALE",
"height": "177.00,
"isStarter" : 1,
"website": "http://www.johnsmith.com"
},
{
"pno": 2,
"firstName": "Aaron",
"familyName": "Person",
"shirtNumber" : 35,
"playingPosition" : "FORWARD",
"dob" : "1977-11-27",
"gender" : "MALE",
"isStarter" : 1,
"personId": 57564
}
],
"staff": [
{
"staffType": "COACH",
"subStaffType": "Head Coach",
"isCoach": "1",
"firstName": "John",
"familyName": "Smith",
"personId": 5764,
"externalId": "8"
}
},
{
"teamNumber": 2,
"detail": {
"teamName": "Sackville Hawks",
"teamId": 44,
"externalId": "248",
"internationalReference": "T1238",
"teamNickname": "Hawks",
"teamCode": "SVH",
"countryCode": "AU",
"countryCodeIOC": "AU",
"country": "Australia",
"website": "http://www.svh.com"
},
"players": [
{
"pno": 1,
"firstName": "Martin",
"familyName": "Mann",
"personId": 564
},
{
"pno": 2,
"firstName": "Archie",
"familyName": "Person",
"personId": 57544
}
],
"staff": [
{
"staffType": "COACH",
"subStaffType": "Defensive Coach",
"isCoach": "1",
"firstName": "John",
"familyName": "Richardson",
"personId": 57564,
"externalId": "98"
}
}
]
},
"officials": [
{
"staffType": "REFEREE",
"subStaffType": "",
"isCoach": "",
"isOfficial": "1",
"shirtNumber": "",
"firstName": "Timothy",
"familyName": "Sawtell",
"TVName": "",
"internationalFirstName": "",
"internationalFamilyName": "",
"namePronunciation": "",
"nickName": "",
"personId": "496",
"externalId": "1068331"
}
]
}
To see how to make the initial connection and when calls are to be made, please check the Live Stream Publish Document.
{
"message": {
"type": "status",
"period": {
"current": 1,
"periodType": "REGULAR"
},
"clock": "10:00:00",
"shotClock": "00:30:00",
"status": "INPROGRESS",
"clockRunning":1,
"periodstatus": "STARTED"
}
}
The boxscore total section needs to be sent after any match action that changes it, at the completition of a period, or end of the match (the entire boxscore needs to be sent).
An example of the actions that may trigger a boxscore send:
{
"message": {
"type": "boxscore",
"teams": [
{
"teamNumber": 1,
"total": {
"team": {
"sTurnovers": "10",
"sThreePointersAttempted": "50",
"sThreePointersMade": "10"
},
"players": [
{
"pno": 1,
"sMinutes": "2",
"sFoulsOn": "2",
"sBlocks": "3",
"sAssists": "2",
"sThreePointersAttempted": "10",
"sThreePointersMade": "3"
},
{
"pno": 2,
"sFoulsOn": "1",
"sBlocks": "6",
"sMinutes": "2",
"sAssists": "4",
"sThreePointersAttempted": "4",
"sThreePointersMade": "4"
}
]
},
{
"teamNumber": 2,
"total": {
"team": {
"sTurnovers": "9",
"sThreePointersAttempted": "49",
"sThreePointersMade": "9"
},
"players": [
{
"pno": 2,
"sFoulsOn": "1",
"sBlocks": "2",
"sMinutes": "2",
"sAssists": "1",
"sThreePointersAttempted": "9",
"sThreePointersMade": "2"
},
{
"pno": 3,
"sFoulsOn": "0",
"sMinutes": "2",
"sBlocks": "5",
"sAssists": "3",
"sThreePointersAttempted": "3",
"sThreePointersMade": "3"
}
]
},
}
]
}
}
The period-by-period (& totals) boxscore will need to be sent at the end of the match only.
{
"message": {
"type": "boxscore",
"teams": [
{
"teamNumber": 1,
"total": {
"team": {
"sTurnovers": "10",
"sThreePointersAttempted": "50",
"sThreePointersMade": "10"
},
"players": [
{
"pno": 1,
"sMinutes": "2",
"sFoulsOn": "2",
"sBlocks": "3",
"sAssists": "2",
"sThreePointersAttempted": "10",
"sThreePointersMade": "3"
},
{
"pno": 2,
"sFoulsOn": "1",
"sBlocks": "6",
"sMinutes": "2",
"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,
"total": {
"team": {
"sTurnovers": "9",
"sThreePointersAttempted": "49",
"sThreePointersMade": "9"
},
"players": [
{
"pno": 2,
"sFoulsOn": "1",
"sBlocks": "2",
"sMinutes": "2",
"sAssists": "1",
"sThreePointersAttempted": "9",
"sThreePointersMade": "2"
},
{
"pno": 3,
"sFoulsOn": "0",
"sMinutes": "2",
"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",
"sMinutes": "1",
"sBlocks": "2",
"sAssists": "1",
"sThreePointersAttempted": "7",
"sThreePointersMade": "2"
},
{
"pno": 3,
"sFoulsOn": "0",
"sBlocks": "1",
"sAssists": "2",
"sThreePointersAttempted": "0",
"sThreePointersMade": "0"
}
]
}
]
}
]
}
}
{
"message": {
"type": "action",
"actionNumber": 1,
"period": 1,
"periodType": "REGULAR",
"clock": "10:00:00",
"timeActual": "2013-08-13 15:56:22",
"shotClock": "00:30:00",
"teamNumber": 1,
"score1": "0",
"score2": "0",
"actionType": "jumpball",
"subType": "periodstart",
"players": {
"team1": [
"1",
"2",
"6",
"9",
"10"
],
"team2": [
"1",
"4",
"6",
"7",
"8"
]
}
"previousAction": 0
}
}
{
"message": {
"type": "action",
"actionNumber": 2,
"period": 1,
"periodType": "REGULAR",
"clock": "10:00:00",
"timeActual": "2013-08-13 15:56:22",
"shotClock": "00:30:00",
"teamNumber": 1,
"score1": "0",
"score2": "0",
"actionType": "game",
"subType": "start",
"players": {
"team1": [
"1",
"2",
"6",
"9",
"10"
],
"team2": [
"1",
"4",
"6",
"7",
"8"
]
}
"previousAction": 0
}
}
{
"message": {
"type": "action",
"actionNumber": 3,
"period": 1,
"periodType": "REGULAR",
"clock": "09:55:00",
"timeActual": "2013-08-13 15:56:22",
"shotClock": "00:25:00",
"teamNumber": 1,
"pno": 1,
"score1": "2",
"score2": "0",
"actionType": "2pt",
"subType": "dunk",
"qualifier": ["2ndchance","fastbreak"],
"x" : 200,
"y" : 200,
"side" : "left",
"area" : "inthepaint",
"previousAction": 0,
"success" : 1,
"players": {
"team1": [
"1",
"2",
"6",
"9",
"10"
],
"team2": [
"1",
"4",
"6",
"7",
"8"
]
}
}
},
{
"message": {
"type": "action",
"actionNumber": 4,
"period": 1,
"periodType": "REGULAR",
"clock": "09:55:00",
"timeActual": "2013-08-13 15:56:22",
"shotClock": "00:25:00",
"teamNumber": 1,
"pno": 1,
"score1": "2",
"score2": "0",
"actionType": "assist",
"previousAction": 3
"players": {
"team1": [
"1",
"2",
"6",
"9",
"10"
],
"team2": [
"1",
"4",
"6",
"7",
"8"
]
}
}
}
Called after any score, foul, timeout change or end of period/match.
{
"message": {
"type": "scoreboard",
"teams": [
{
"teamNumber": 1,
"score": "82",
"timeouts": 0,
"fouls": 1,
"periods": [
{
"period": 1,
"periodType": "REGULAR",
"score": "12"
},
{
"period": 2,
"periodType": "REGULAR",
"score": "22"
},
{
"period": 3,
"periodType": "REGULAR",
"score": "25"
},
{
"period": 4,
"periodType": "REGULAR",
"score": "80"
},
{
"period": 1,
"periodType": "OVERTIME",
"score": "82"
}
]
},
{
"teamNumber": 2,
"score": "83",
"timeouts": 2,
"fouls": 0,
"periods": [
{
"period": 1,
"periodType": "REGULAR",
"score": "2"
},
{
"period": 2,
"periodType": "REGULAR",
"score": "18"
},
{
"period": 3,
"periodType": "REGULAR",
"score": "23"
},
{
"period": 4,
"periodType": "REGULAR",
"score": "80"
},
{
"period": 1,
"periodType": "OVERTIME",
"score": "83"
}
]
}
]
}
}
{
"message" : {
"type": "action",
"actionNumber": 5,
"period": 1,
"periodType": "REGULAR",
"clock": "09:40:00",
"timeActual": "2013-08-13 15:56:22",
"shotClock": "00:18:00",
"teamNumber": 2,
"pno": 2,
"score1": "2",
"score2": "0",
"actionType": "steal",
"players": {
"team1": [
"1",
"2",
"6",
"9",
"10"
],
"team2": [
"1",
"4",
"6",
"7",
"8"
]
},
"previousAction": 0
}
"message": {
"type": "action",
"actionNumber": 6,
"period": 1,
"periodType": "REGULAR",
"clock": "09:40:00",
"timeActual": "2013-08-13 15:56:22",
"shotClock": "00:18:00",
"teamNumber": 1,
"pno": 1,
"score1": "2",
"score2": "0",
"actionType": "turnover",
"subType": "badpass",
"players": {
"team1": [
"1",
"2",
"6",
"9",
"10"
],
"team2": [
"1",
"4",
"6",
"7",
"8"
]
},
"previousAction": 5
},
}
{
"message": {
"type": "action",
"actionNumber": 7,
"period": 1,
"periodType": "REGULAR",
"clock": "09:30:00",
"timeActual": "2013-08-13 15:56:22",
"shotClock": "00:20:00",
"score1": "2",
"score2": "0",
"actionType": "clock",
"subType": "stop",
"previousAction": 0
},
"message": {
"type": "action",
"actionNumber": 8,
"period": 1,
"periodType": "REGULAR",
"clock": "09:30:00",
"timeActual": "2013-08-13 15:56:22",
"shotClock": "00:20:00",
"teamNumber": 1,
"pno": 1,
"score1": "2",
"score2": "0",
"actionType": "foul",
"subType": "personal",
"players": {
"team1": [
"1",
"2",
"6",
"9",
"10"
],
"team2": [
"1",
"4",
"6",
"7",
"8"
]
},
"previousAction": 0
},
"message": {
"type": "action",
"actionNumber": 9,
"period": 1,
"periodType": "REGULAR",
"clock": "09:30:00",
"timeActual": "2013-08-13 15:56:22",
"shotClock": "00:20:00",
"teamNumber": 2,
"pno": 2,
"score1": "2",
"score2": "0",
"actionType": "foulon",
"players": {
"team1": [
"1",
"2",
"6",
"9",
"10"
],
"team2": [
"1",
"4",
"6",
"7",
"8"
]
},
"previousAction": 8
}
}
{
"message": {
"type": "action",
"actionNumber": 10,
"period": 1,
"periodType": "REGULAR",
"clock": "09:30:00",
"timeActual": "2013-08-13 15:56:22",
"shotClock": "00:20:00",
"teamNumber": 1,
"score1": "2",
"score2": "0",
"actionType": "timeout",
"subType": "short",
"previousAction": 0
},
"message": {
"type": "action",
"actionNumber": 11,
"period": 1,
"periodType": "REGULAR",
"clock": "09:30:00",
"timeActual": "2013-08-13 15:56:22",
"shotClock": "00:20:00",
"teamNumber": 1,
"score1": "2",
"score2": "0",
"actionType": "clock",
"subType": "stop",
"previousAction": 0
},
}
{
"message": {
"type": "action",
"actionNumber": 12,
"period": 1,
"periodType": "REGULAR",
"clock": "09:30:00",
"timeActual": "2013-08-13 15:56:22",
"shotClock": "00:20:00",
"teamNumber": 1,
"pno": 2,
"score1": "2",
"score2": "0",
"actionType": "substitution",
"subType": "out,
"previousAction": 0
},
"message": {
"actionNumber": 13,
"period": 1,
"periodType": "REGULAR",
"clock": "09:30:00",
"timeActual": "2013-08-13 15:56:22",
"shotClock": "00:20:00",
"teamNumber": 1,
"pno": 11,
"score1": "2",
"score2": "0",
"actionType": "substitution",
"subType": "in",
"players": {
"team1": [
"1",
"11",
"6",
"9",
"10"
],
"team2": [
"1",
"4",
"6",
"7",
"8"
]
},
"previousAction": 0
}
}
{
"message": {
"type": "action",
"actionNumber": 14,
"period": 1,
"periodType": "REGULAR",
"clock": "09:30:00",
"timeActual": "2013-08-13 15:56:22",
"shotClock": "00:20:00",
"teamNumber": 1,
"pno": 1,
"score1": "2",
"score2": "0",
"actionType": "foul",
"subType": "personal",
"players": {
"team1": [
"1",
"2",
"6",
"9",
"10"
],
"team2": [
"1",
"4",
"6",
"7",
"8"
]
},
"previousAction": 0
},
"message": {
"type": "action",
"actionNumber": 15,
"period": 1,
"periodType": "REGULAR",
"clock": "09:30:00",
"timeActual": "2013-08-13 15:56:22",
"shotClock": "00:20:00",
"score1": "2",
"score2": "0",
"actionType": "clock",
"subType": "stop",
"players": {
"team1": [
"1",
"2",
"6",
"9",
"10"
],
"team2": [
"1",
"4",
"6",
"7",
"8"
]
},
"previousAction":14
},
"message": {
"type": "action",
"actionNumber": 16,
"period": 1,
"periodType": "REGULAR",
"clock": "09:30:00",
"timeActual": "2013-08-13 15:56:22",
"shotClock": "00:20:00",
"score1": "3",
"score2": "0",
"actionType": "freethrow",
"teamNumber": 1,
"subType": "1of2",
"pno": 1,
"success" : "1",
"players": {
"team1": [
"1",
"11",
"6",
"9",
"10"
],
"team2": [
"1",
"4",
"6",
"7",
"8"
]
},
"previousAction":0
},
"message": {
"type": "action",
"actionNumber": 17,
"period": 1,
"periodType": "REGULAR",
"clock": "09:30:00",
"timeActual": "2013-08-13 15:56:22",
"shotClock": "00:20:00",
"score1": "4",
"score2": "0",
"actionType": "freethrow",
"subType": "2of2",
"teamNumber": 1,
"pno": 1,
"success" : "1",
"players": {
"team1": [
"1",
"11",
"6",
"9",
"10"
],
"team2": [
"1",
"4",
"6",
"7",
"8"
]
},
"previousAction":16
},
}
The field possession shows which team (1 or 2) currently has possession, the possessionArrow shows who has the possession Arrow.
"message": {
"type": "status",
"period": {
"current": 1,
"periodType": "REGULAR"
},
"clock": "09:20:00",
"shotClock": "00:30:00",
"status": "INPROGRESS",
"clockRunning":1,
"periodstatus": "STARTED"
"possession" : 2,
"possessionArrow" : 2
}
}
The below example shows end of period 2.
{
"message": {
"type": "status",
"period": {
"current": 2,
"periodType": "REGULAR"
},
"clock": "00:00:00",
"shotClock": "00:00:00",
"status": "INPROGRESS",
"clockRunning":0,
"periodstatus": "ENDED"
}
"message": {
"type": "action",
"actionNumber": 15,
"period": 1,
"periodType": "REGULAR",
"clock": "09:30:00",
"timeActual": "2013-08-13 15:56:22",
"shotClock": "00:20:00",
"score1": "2",
"score2": "0",
"actionType": "period",
"subType": "end,
"previousAction": 0
}
}
The below example shows end of match.
{
"message": {
"type": "status",
"period": {
"current": 4,
"periodType": "REGULAR"
},
"clock": "00:00:00",
"shotClock": "00:00:00",
"status": "COMPLETED",
"clockRunning":0,
"periodstatus": "ENDED"
}
"message": {
"type": "action",
"actionNumber": 16,
"period": 4,
"periodType": "REGULAR",
"clock": "00:00:00",
"timeActual": "2013-08-13 15:56:22",
"score1": "2",
"score2": "0",
"actionType": "game",
"subType": "end,
"previousAction": 0
}
}