Broadcast API Overview

Use Cases

The broadcast game day service is used to enhance the live viewing of games with in broadcast stats and high sample rate location data. Past integrations have been:

  • In venue graphics for display and video boards

  • Enhanced 3D broadcast video with location tracking; stats, distance, clocks, etc…

  • Enhanced 2D broadcast graphics with stats, shot charts, zone maps, etc…

Data Concepts

Locations XY Orientation

fullcourtxydirections

Zone Map Locations

Map of the 14 shot zones is represented as:

zonemap

Shot Chart Plotting

Team and player shot locations, supplied in the stats file, are plottable in the following orientation:

halfcourtxydirections

Authentication

An API key is required on all game data service endpoints. The API key identifies the calling stats data consumer and is passed either on the URL

?apikey=your api key

or as a HTTP header:

apikey: your api key

Please contact ShotTracker to obtain an API key.

Environment Connections

Production ShotTracker Cloud Service API

In-venue UDP Multicast

  • ip address: 239.251.101.6

  • port: 8668

Getting Started

When working with a realtime environment data consumption is first step; which we provide with a mock service. The goal of the mock service is to exercise the environment with a small subset of data that plays in a continous loop. Consumers of the mock service are able to quickly get up and running on ShotTrackers broadcast data concepts and delivery methods. Below are URL examples of the mock service.

Important Note Additional query parameters are used to invoke the mock environment and should be removed for production.

Mock JSON Endpoints

Schedule
https://api.shottracker.com/broadcast/v1/games/schedule?apikey=your_api_key&mock=true

SSE Stats
https://api.shottracker.com/broadcast/v1/stats/event-stream?apikey=your_api_key&schedule_id=mock-service&mock=true

REST Stats
https://api.shottracker.com/broadcast/v1/stats?apikey=your_api_key&schedule_id=mock-service&mock=true

REST Team/Player Attributes
https://api.shottracker.com/broadcast/v1/games/teams/?apikey=your_api_key&mock=true

Mock Displays

Schedule
https://api.shottracker.com/broadcast/schedule?apikey=your_api_key&mock=true
Stats
https://api.shottracker.com/broadcast/display?apikey=your_api_key&schedule_id=mock-service&mock=true

The mock service also exposes a locations feed. Those locations are delivered over TCP but consider, in production, the locations are obtained locally over UDP.

Mock Locations TCP

nc mocklive.shottracker.com 2000

Data Overview

The broadcast data collection is tailored to work with specific consumers needing access to very high sample rate sensor locations and full stats. The data is provided in 2 locations, sensor xy’s come from the ShotTracker local server installed at the facility and full stats from the ShotTracker cloud. Below represents the consumers connection diagram:

game_data

  1. The consumer resides on the same network as the ShotTracker local server where location data is emitted UDP via multicast. This data represents the exact location in xy of each ball and player sensor at the defined sample rate. See the Locations CSV Format section for a complete definition of each field.

  2. Full game stats is delivered from the ShotTracker cloud. This is delivered as a JSON file each time a stat occurs, half or quarter change, or a player sensor assignment is changed. See the Full Game Stats JSON Format for a complete description of each field.

Important Note The consumer must pull the players sensor assignments, either from the Attributes Endpoint or receive them directly from the Stats Endpoint, to know which sensor number in the CSV is what player.

Locations CSV Format

The ShotTracker server will always send a ping event which is used to inidicate the connection is alive. Ping messages will be sent every minute.

Ping

event_timestamp,event_structure_version,ping

event_timestamp = the time the event occurred in UTC ms
event_structure_version = the version of this event structure; will be 2
ping = the name of the event; will always be ping

When a game is active, the ShotTracker server will also send the player and ball locations with the following format. The version that will be sent is the most recent (greatest) version number unless pre-configured otherwise to support legacy consumers.

Player / Ball Locations v1

event_timestamp,event_structure_version,event_type,tag_serial_number,X,Y,Z

event_timestamp = the time the event occurred in UTC ms
event_structure_version = the version of the event structure; v1
event_type = player or ball location data
tag_serial_number = the unique serial number of the device.
X, Y, Z = mm location of the tag relative to the court coordinate system where the center of the court is 0,0

Sample: 
1611805439518,1,player,105645,-6113,-23444,1763
1611805439518,1,ball,2147583169,-1004,-23,455

Player / Ball Locations v2

event_timestamp,event_structure_version,event_type,game_clock,shot_clock,stop_flag,tag_serial_number,X,Y,Z

event_timestamp = the time the event occurred in UTC ms
event_structure_version = the version of the event structure; v2
event_type = player or ball location data
game_clock = MM:SS.T formatted clock data, MM = minute, SS = second, T = subsecond (depending on time subsecond might be missing)
shot_clock = SS.T formatted clock data, SS = second, T = subsecond (depending on time subsecond might be missing)
stop_flag = 0 if clock is running; 1 if clock is stopped
tag_serial_number = the unique serial number of the device.
X, Y, Z = mm location of the tag relative to the court coordinate system where the center of the court is 0,0

Sample:
1611805439518,2,player,19:59.0,30.0,1,105645,-6113,-23444,1763
1611805439518,2,ball,19:59.0,30.0,0,2147583169,-1004,-23,455

Note: if game/shot clock is not available these fields will be empty

Click here to download a full game example of the v2 player/ball locations.

Player Ball Possessions

The possession events indicate at an exact moment in time which player tag is possessing which ball. The events are broken into 2 separate events, got possession (or when the player got possession of the ball) and lost possesion (or when the player lost possession of the ball).

Got Possession

event_timestamp,event_structure_version,event_type,game_clock,shot_clock,stop_flag,player_tag_serial_number,X,Y,Z,ball_tag_serial_number

event_timestamp = the time the event occurred in UTC ms
event_structure_version = the version of the event structure; v2
event_type = gotpossession
game_clock = MM:SS.T formatted clock data, MM = minute, SS = second, T = subsecond (depending on time subsecond might be missing)
shot_clock = SS.T formatted clock data, SS = second, T = subsecond (depending on time subsecond might be missing)
stop_flag = 0 if clock is running; 1 if clock is stopped
player_tag_serial_number = the serial number of the players tag
X, Y, Z = mm location of the tag relative to the court coordinate system where the center of the court is 0,0
ball_tag_serial_number = the serial number of the ball the player tag is possessing

Sample: 
1611805439518,2,gotpossession,19:59.0,30.0,1,105645,-6113,-23444,1763,2147583169

Lost Possession

event_timestamp,event_structure_version,event_type,game_clock,shot_clock,stop_flag,player_tag_serial_number,X,Y,Z,ball_tag_serial_number,num_bounces

event_timestamp = the time the event occurred in UTC ms
event_structure_version = the version of the event structure; v2
event_type = lostpossession
game_clock = MM:SS.T formatted clock data, MM = minute, SS = second, T = subsecond (depending on time subsecond might be missing)
shot_clock = SS.T formatted clock data, SS = second, T = subsecond (depending on time subsecond might be missing)
stop_flag = 0 if clock is running; 1 if clock is stopped
player_tag_serial_number = the serial number of the players tag
X, Y, Z = mm location of the tag relative to the court coordinate system where the center of the court is 0,0
ball_tag_serial_number = the serial number of the ball the player tag is possessing
num_bounces = # of bounces counted while the player had possession

Sample: 
1611805439518,2,lostpossession,19:59.0,30.0,1,105645,-6113,-23444,1763,2147583169,8

Game Clock

event_timestamp,event_structure_version,scoreboard,source,clock,MM:SS.T,stop_flag

event_timestamp = the time the event occurred in UTC ms
event_structure_version = the version of this event structure; will be 1
scoreboard = indicates that this is a scoreboard message
source = details about the scoreboard type producing the message
clock = the name of the event; will always be clock
MM:SS.T = clock data, MM = minute, SS = second, T = subsecond (depending on time subsecond might be missing)
stop_flag = 0 if clock is running; 1 if clock is stopped

Shot Clock

event_timestamp,event_structure_version,scoreboard,source,shotclock,SS.T

event_timestamp = the time the event occurred in UTC ms
event_structure_version = the version of this event structure; will be 1
scoreboard = indicates that this is a scoreboard message
source = details about the scoreboard type producing the message
shotclock = the name of the event; will always be shotclock
SS.T = clock data, SS = second, T = subsecond (depending on time subsecond might be missing)

Period

event_timestamp,event_structure_version,scoreboard,source,period,current_period

event_timestamp = the time the event occurred in UTC ms
event_structure_version = the version of this event structure; will be 1
scoreboard = indicates that this is a scoreboard message
source = details about the scoreboard type producing the message
period = the name of the event; will always be period
current_period = The current period displayed on the scoreboard, e.g. 1, 2, 3, etc.

Score

event_timestamp,event_structure_version,scoreboard,source,score,home,guest

event_timestamp = the time the event occurred in UTC ms
event_structure_version = the version of this event structure; will be 1
scoreboard = indicates that this is a scoreboard message
source = details about the scoreboard type producing the message
score = the name of the event; will always be score
home = The current home team score displayed on the scoreboard
guest = The current guest team score displayed on the scoreboard
Note: home and guest scores may be empty until updated

Possession

event_timestamp,event_structure_version,scoreboard,source,poss,possession_team

event_timestamp = the time the event occurred in UTC ms
event_structure_version = the version of this event structure; will be 1
scoreboard = indicates that this is a scoreboard message
source = details about the scoreboard type producing the message
possession = the name of the event; will always be possession
possession_team = The current possession arrow, either HOME, or GUEST, as displayed on the scoreboard
Note: possession_team may be empty until updated

Fouls

event_timestamp,event_structure_version,scoreboard,source,fouls,home,guest

event_timestamp = the time the event occurred in UTC ms
event_structure_version = the version of this event structure; will be 1
scoreboard = indicates that this is a scoreboard message
source = details about the scoreboard type producing the message
fouls = the name of the event; will always be fouls
home = The current home team fouls displayed on the scoreboard
guest = The current guest team fouls displayed on the scoreboard
Note: home and guest fouls may be empty until updated
Note: This is may not be available on all scoreboards.

Bonus

event_timestamp,event_structure_version,scoreboard,source,bonus,home,guest

event_timestamp = the time the event occurred in UTC ms
event_structure_version = the version of this event structure; will be 1
scoreboard = indicates that this is a scoreboard message
source = details about the scoreboard type producing the message
bonus = the name of the event; will always be bonus
home = The current home team bonus indicator, either BONUS or blank, displayed on the scoreboard
guest = The current guest team bonus indicator, either BONUS or blank, displayed on the scoreboard
Note: This is may not be available on all scoreboards.

Bonus 1

event_timestamp,event_structure_version,scoreboard,source,bonus1,home,guest

event_timestamp = the time the event occurred in UTC ms
event_structure_version = the version of this event structure; will be 1
scoreboard = indicates that this is a scoreboard message
source = details about the scoreboard type producing the message
bonus1 = the name of the event; will always be bonus1
home = The current home team 1st bonus indicator, either BONUS or blank, displayed on the scoreboard
guest = The current guest team 1st bonus indicator, either BONUS or blank, displayed on the scoreboard
Note: This is may not be available on all scoreboards.

Bonus 2

event_timestamp,event_structure_version,scoreboard,source,bonus2,home,guest

event_timestamp = the time the event occurred in UTC ms
event_structure_version = the version of this event structure; will be 1
scoreboard = indicates that this is a scoreboard message
source = details about the scoreboard type producing the message
bonus2 = the name of the event; will always be bonus2
home = The current home team 2nd bonus indicator, either BONUS or blank, displayed on the scoreboard
guest = The current guest team 2nd bonus indicator, either BONUS or blank, displayed on the scoreboard
Note: This is may not be available on all scoreboards.

Timeouts

event_timestamp,event_structure_version,scoreboard,source,timeouts,home,guest

event_timestamp = the time the event occurred in UTC ms
event_structure_version = the version of this event structure; will be 1
scoreboard = indicates that this is a scoreboard message
source = details about the scoreboard type producing the message
timeouts = the name of the event; will always be timeouts
home = The current home team timeouts remining displayed on the scoreboard
guest = The current guest team timeouts remaining displayed on the scoreboard
Note: This is may not be available on all scoreboards.

Timeouts Full

event_timestamp,event_structure_version,scoreboard,source,timeouts_full,home,guest

event_timestamp = the time the event occurred in UTC ms
event_structure_version = the version of this event structure; will be 1
scoreboard = indicates that this is a scoreboard message
source = details about the scoreboard type producing the message
timeouts_full = the name of the event; will always be timeouts_full
home = The current home team timeouts full remining displayed on the scoreboard
guest = The current guest team timeouts full remaining displayed on the scoreboard
Note: This is may not be available on all scoreboards.

Timeouts Partial

event_timestamp,event_structure_version,scoreboard,source,timeouts_partial,home,guest

event_timestamp = the time the event occurred in UTC ms
event_structure_version = the version of this event structure; will be 1
scoreboard = indicates that this is a scoreboard message
source = details about the scoreboard type producing the message
timeouts_partial = the name of the event; will always be timeouts_partial
home = The current home team timeouts partial remining displayed on the scoreboard
guest = The current guest team timeouts partial remaining displayed on the scoreboard
Note: This is may not be available on all scoreboards.

Game Stats JSON Data Format

The json file contains stats at the following levels:
- Full game stats (game_stats object)
- First half stats (half_1_stats object)
- Second half stats (half_2_stats object)
- First quarter stats (quarter_1_stats object)
- Second quarter stats (quarter_2_stats object)
- Third quarter stats (quarter_3_stats object)
- Fourth quarter stats (quarter_4_stats object)
- Overtime stats (ot_1_stats object)

The quarter_n_stats objects are only included when the game is ran as quarters. All games, regardless if ran as quarters or halves, include the game_stats and half_n_stats objects.

at (number) - epoch timestamp of file
at_formatted (string) - human readable timestamp represent by the at field
period (string) - the current or last period of the game (PRE, H1, H2, Q1, Q2, Q3, Q4, HT, OT, END)

Each game, half and quarter stats object has the same format and contains the following fields:

reference (string) - the internal value to represent the ShotTracker internal tracking id
home (object) - all team and player stats for the home team
away (object) - all team and player stats for the away team

Each home and away objects contains the same fields; those are:

team (object) - contains all team level stats
team,team_id (number) - the ShotTracker internal team id
team,team_name (string) - the name of the team defined in ShotTracker
team,TWO_POINT_PCT_DISPLAY (string) - (DEPRECATED) the percent of only 2pt field goals
team,FG (number) - the number of made field goals
team,FGA (number) - the number of attempted field goals
team,FG_FRACTION (string) - the fractional display of field goals
team,FG_PCT_DISPLAY (string) - the percent of field goals
team,FG2 (number) - the number of made 2pt field goals
team,FGA2 (number) - the number of attempted 2pt field goals
team,FG2_FRACTION (string) - the fractional display of 2pt field goals
team,FG2_PCT_DISPLAY (string) - the percent of 2pt field goals
team,FG3 (number) - the number of made 3pt field goals
team,FGA3 (number) - the number of attempted 3pt field goals
team,FG3_FRACTION (string) - the fractional display of 3pt field goals
team,FG3_PCT_DISPLAY (string) - the percent of 3pt field goals
team,FT (number) - the number of made free throws
team,FTA (number) - the number of attempted free throws
team,FT_FRACTION (string) - the fractional display of free throws
team,FT_PCT_DISPLAY (string) - the percent of free throws
team,PTS (number) - number of team points
team,REB (number) - number of team rebounds
team,OFFENSIVE_REB (number) - number of team offensive rebounds
team,DEFENSIVE_REB (number) - number of team defensive rebounds
team,AST (number) - number of team assists
team,STL (number) - number of team steals
team,TO (number) - number of team turnovers
team,DIST (number) - total team distance in cm
team,DIST_MILES (number) - total team distance in miles
team,BLK (number) - number of team blocks
team,FL (number) - number of team fouls
team,PPTS (number) - number of points in the paint
team,AST_TO_RATE (number) - the rate of assist to turnovers
team,SECOND_CHANCE_POINTS (number) - number of points scored after an offensive rebound
team,POINTS_OFF_TURNOVER (number) - number of points scored after a turnover

team,shots (object array) - total team shots locations per ShotTrackers 14 zone map
team,shots,zone# (object) - specific ShotTracker zone
team,shots,zone#,DISPLAY (string) - the fractional display of zone shots
team,shots,zone#,PCT_DISPLAY (string) - the percent of the zone shots
team,shots,zone#,R (number) - red color value in RGB
team,shots,zone#,G (number) - green color value in RGB
team,shots,zone#,B (number) - blue color value in RGB
team,shot_locations,make (array) - array of xy made shot locations in millimeters, 0,0 starts at the hoop where positive y runs from the hoop out to center court and positive x runs from the hoop to the right of the positive y; see Shot Chart Plotting for this visual
team,shot_locations,miss (array) - array of xy missed shot locations in millimeters, 0,0 starts at the hoop where positive y runs from the hoop out to center court and positive x runs from the hoop to the right of the positive y; see Shot Chart Plotting for this visual
team,cas_shots (object array) - total team catch and shoot shots locations per ShotTrackers 14 zone map
team,cas_shots,zone# (object) - specific ShotTracker zone
team,cas_shots,zone#,DISPLAY (string) - the fractional display of zone shots
team,cas_shots,zone#,PCT_DISPLAY (string) - the percent of the zone shots
team,cas_shots,zone#,R (number) - red color value in RGB
team,cas_shots,zone#,G (number) - green color value in RGB
team,cas_shots,zone#,B (number) - blue color value in RGB
team,otd_shots (object array) - total team off the dribble shots locations per ShotTrackers 14 zone map
team,otd_shots,zone# (object) - specific ShotTracker zone
team,otd_shots,zone#,DISPLAY (string) - the fractional display of zone shots
team,otd_shots,zone#,PCT_DISPLAY (string) - the percent of the zone shots
team,otd_shots,zone#,R (number) - red color value in RGB
team,otd_shots,zone#,G (number) - green color value in RGB
team,otd_shots,zone#,B (number) - blue color value in RGB

The team section also contains the following possession type stats. All of the possession types below are a subset of the OVERALL type with the exception of TRANSITION. Paint Touch (PT) occurs when a player possesses the basketball and their location is in the paint. A Ball Reversal (BR) occurs when the ball travels from one wing to the other. This can happen in 1 pass, a player dribbling the ball from one side to the other, or a series of passes. 

Below are the possession type prefixes:

TRANSITION - a possession that remains in live ball, either after a turnover, a made shot, or a defensive rebound, that is either turned over or a shot is taken within 10 seconds
OVERALL - all half court possessions
PT0_BR0 - a possession with no paint touch or ball reversal
PT1_BR0 - a possession that only has at least one paint touch
PT0_BR1 - a possession that only has one ball reversal
PT0_BR2 - a possession that only has two or more ball reversals
PT1_BR1 - a possession that has at least one paint touch combined with only one ball reversal
PT1_BR2 - a possession that has a least one paint touch combined with two or more ball reversals
PASS0_2 - a possession with zero passes, one pass or two passes in the possession
PASS3_5 - a possession with 3 passes, four passes or five passes in the possession
PASS6 - a possession that has 6 or more passes in the possession
BS0 - a possession with no ball screens
BS1 - a possession with only 1 ball screen
BS2 - a possession with only 2 ball screens
BS3 - a possession with 3 or more ball screens
BS_ALL - a sum of BS1 + BS2 + BS3
BS_LW - ball screen possessions on the left wing
BS_MW - ball screen possessions on the middle wing
BS_RW - ball screen possessions on the right wing
BS_PNP - pick and pop ball screen possessions 
BS_PNR - pick and roll ball screen possessions
BS_PNSR - pick and short roll ball screen possessions
BS_SS - screened shot ball screen possessions
BS_HANDOFF - handoff ball screen possessions
BS_DRAG - drag ball screen possessions

team,<possession type prefix>_VALUE (number) - total field goals
team,<possession type prefix>_FG (string) - total field goals percent
team,<possession type prefix>_FG_FRACTION (string) - total field goals fraction
team,<possession type prefix>_POSS (number) - number of possessions
team,<possession type prefix>_PTS (number) - number of points in possession type
team,<possession type prefix>_2PTM (number) - 2pt makes
team,<possession type prefix>_2PTA(number) - 2pt attempts
team,<possession type prefix>_3PTM (number) - 3pt makes
team,<possession type prefix>_3PTA (number) - 3pt attempts
team,<possession type prefix>_TO (number) - turnovers
team,<possession type prefix>_PPP (number) - number of points per possession
team,<possession type prefix>_FG_VALUE_ARROW - indicates which field goal value is higher when compared between home and away teams

team,lineup_stats (object array) - the top 2 lineups for each team
team,lineup_stats,#,player_ids (array) - the 5 player ids for the given lineup stats
team,lineup_stats,#,PLUS_MINUS (number) - the lineup's plus/minus
team,lineup_stats,#,TOTAL_POINTS_SCORED (number) - the lineups total points scored
team,lineup_stats,#,TOTAL_POINTS_ALLOWED (number) - the lineups total points allowed

players (object array) - all team and player stats; team stats will be identified by a player_id of 0
players,#,player_id (number) - the ShotTracker internal player id or will be 0 if team
players,#,jersey_number (number) - player team jersey number or -1 if team
players,#,first_name (string) - players first name or null if team
players,#,last_name (string) - players last name or null if team
players,#,position_abbr (string) - player position abbreviation, C center, G guard, F forward or null if team
players,#,sensor (number) - current player assigned sensor or 0 if team
players,#,on_the_floor (boolean) - true if currently on the court in lineup
players,#,TWO_POINT_PCT_DISPLAY (string) - (DEPRECATED) the percent of only 2pt field goals
players,#,FG (number) - the number of made field goals
players,#,FGA (number) - the number of attempted field goals
players,#,FG_FRACTION (string) - the fractional display of field goals
players,#,FG_PCT_DISPLAY (string) - the percent of field goals
players,#,FG2 (number) - the number of made 2pt field goals
players,#,FGA2 (number) - the number of attempted 2pt field goals
players,#,FG2_FRACTION (string) - the fractional display of 2pt field goals
players,#,FG2_PCT_DISPLAY (string) - the percent of 2pt field goals
players,#,FG3 (number) - the number of made 3pt field goals
players,#,FGA3 (number) - the number of attempted 3pt field goals
players,#,FG3_FRACTION (string) - the fractional display of 3pt field goals
players,#,FG3_PCT_DISPLAY (string) - the percent of 3pt field goals
players,#,FT (number) - the number of made free throws
players,#,FTA (number) - the number of attempted free throws
players,#,FT_FRACTION (string) - the fractional display of free throws
players,#,FT_PCT_DISPLAY (string) - the percent of free throws
players,#,PLUS_MINUS (number) - the player's plus/minus
players,#,PTS (number) - number of player points
players,#,REB (number) - number of player rebounds
players,#,OFFENSIVE_REB (number) - number of player offensive rebounds
players,#,DEFENSIVE_REB (number) - number of player defensive rebounds
players,#,AST (number) - number of player assists
players,#,STL (number) - number of player steals
players,#,TO (number) - number of player turnovers
players,#,DIST (number) - total player distance in cm
players,#,DIST_MILES (number) - total player distance in miles
players,#,BLK (number) - number of player blocks
players,#,FL (number) - number of player fouls
players,#,PPTS (number) - number of points in the paint
players,#,AST_TO_RATE (number) - the rate of assists to turnovers

players,#,shots (object array) - total player shots locations per ShotTrackers 14 zone map
players,#,shots,zone# (object) - specific ShotTracker zone
players,#,shots,zone#,DISPLAY (string) - the fractional display of zone shots
players,#,shots,zone#,PCT_DISPLAY (string) - the percent of the zone shots
players,#,shots,zone#,R (number) - red color value in RGB
players,#,shots,zone#,G (number) - green color value in RGB
players,#,shots,zone#,B (number) - blue color value in RGB

players,#,shot_locations,make (array) - array of xy made shot locations in millimeters, 0,0 starts at the hoop where positive y runs from the hoop out to center court and positive x runs from the hoop to the right of the positive y; see Shot Chart Plotting for this visual
players,#,shot_locations,miss (array) - array of xy missed shot locations in millimeters, 0,0 starts at the hoop where positive y runs from the hoop out to center court and positive x runs from the hoop to the right of the positive y; see Shot Chart Plotting for this visual

players,#,cas_shots (object array) - total player catch and shoot shots locations per ShotTrackers 14 zone map
players,#,cas_shots,zone# (object) - specific ShotTracker zone
players,#,cas_shots,zone#,DISPLAY (string) - the fractional display of zone shots
players,#,cas_shots,zone#,PCT_DISPLAY (string) - the percent of the zone shots
players,#,cas_shots,zone#,R (number) - red color value in RGB
players,#,cas_shots,zone#,G (number) - green color value in RGB
players,#,cas_shots,zone#,B (number) - blue color value in RGB

players,#,otd_shots (object array) - total player off the dribble shots locations per ShotTrackers 14 zone map
players,#,otd_shots,zone# (object) - specific ShotTracker zone
players,#,otd_shots,zone#,DISPLAY (string) - the fractional display of zone shots
players,#,otd_shots,zone#,PCT_DISPLAY (string) - the percent of the zone shots
players,#,otd_shots,zone#,R (number) - red color value in RGB
players,#,otd_shots,zone#,G (number) - green color value in RGB
players,#,otd_shots,zone#,B (number) - blue color value in RGB

Broadcast Game Endpoints

Schedule

Schedule
GET/broadcast/v1/games/schedule{?from,to,apikey}

Requests the ShotTracker game schedule. If from and to are not provided it will return all games at the time of the request to all into the future. If from and to are provided will return only the games during the timeframe. The intention of a from/to search would be in the future as the broadcast service is live and upcoming scheduled games.

Example URI

GET /broadcast/v1/games/schedule?from=&to=&apikey=
URI Parameters
HideShow
from
number (optional) 

The starting epoch timestamp (in milliseconds); in UTC

to
number (optional) 

The ending epoch timestamp (in milliseconds); in UTC

apikey
string (required) 

The authentication key

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "games": [
    {
      "schedule_id": "1a4118d4-2e50-11e6-b4a4-deecc6e6f111",
      "event_id": "1a4118d4-2e50-11e6-b4a4-deecc6e6f111",
      "location": "Test Location",
      "tournament": "N/A",
      "tipoff_at": 1549587600000,
      "expected_duration_ms": 7200000,
      "name": "TestTeam at BWB",
      "gender": "MEN",
      "status": "SCHEDULED",
      "home_team_id": 461,
      "away_team_id": 493,
      "_link": "/broadcast/display?schedule_id=1a4118d4-2e50-11e6-b4a4-deecc6e6f111",
      "_home_team_link": "/broadcast/v1/games/teams/461?testing=true",
      "_home_team_images": "/broadcast/v1/games/teams/461/images?testing=true",
      "_away_team_link": "/broadcast/v1/games/teams/493?testing=true",
      "_away_team_images": "/broadcast/v1/games/teams/493/images?testing=true",
      "_sse_stats_link": "/broadcast/v1/stats/event-stream?schedule_id=1a4118d4-2e50-11e6-b4a4-deecc6e6f111",
      "_stats_link": "/broadcast/v1/stats?schedule_id=1a4118d4-2e50-11e6-b4a4-deecc6e6f111",
      "udp_multicast_ip": "127.0.0.1",
      "udp_multicast_port": 8765
    }
  ]
}

Teams

Teams
GET/broadcast/v1/games/teams{?apikey}

Returns all ShotTracker teams.

Example URI

GET /broadcast/v1/games/teams?apikey=
URI Parameters
HideShow
apikey
string (required) 

The authentication key

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "teams": [
    {
      "id": 461,
      "name": "TestTeam"
    },
    {
      "id": 493,
      "name": "BWB"
    },
    {
      "id": 481,
      "name": "ShotTrackerW"
    }
  ]
}

Team And Player Attributes

Team And Player Attributes
GET/broadcast/v1/games/teams/{team_id}{?apikey,game_event_id}

The current active players on the team. The endpoint also returns the players current assigned sensor which can change during a game. The game_event_id parameter can be used to look up all of the players on the team at the time of a game. With this query parameter an additional field is return ‘sensor_assignments_history’ which indicates the sensor assignments during the game. This field is the same response from the Event API Sensor Assignments History Players who are no longer on the team will have an ‘is_active’ false.

Example URI

GET /broadcast/v1/games/teams/team_id?apikey=&game_event_id=
URI Parameters
HideShow
team_id
number (required) 

ID of the team

game_event_id
string (optional) 

ID of the game

apikey
string (required) 

The authentication key

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": 493,
  "name": "BWB",
  "abbr": "BB",
  "city": "Kansas City",
  "state": "MO",
  "color_rgb": "0066CC",
  "players": [
    {
      "id": 3531,
      "first_name": "Shelden",
      "last_name": "Williams",
      "jersey_number": 4,
      "position_abbr": "C",
      "sensor": 100630
    },
    {
      "id": 3541,
      "first_name": "Casey",
      "last_name": "Jacobsen",
      "jersey_number": 3,
      "position_abbr": "F",
      "sensor": 100520
    },
    {
      "id": 3548,
      "first_name": "Mateen",
      "last_name": "Cleaves",
      "jersey_number": 2,
      "position_abbr": "G",
      "sensor": 100539
    },
    {
      "id": 3532,
      "first_name": "Alando",
      "last_name": "Tucker",
      "jersey_number": 6,
      "position_abbr": "F",
      "sensor": null
    }
  ]
}

Team And Player Images

Team And Player Images
GET/broadcast/v1/games/teams/{team_id}/images{?apikey}

Returns the team and player image links.

Example URI

GET /broadcast/v1/games/teams/team_id/images?apikey=
URI Parameters
HideShow
team_id
number (required) 

ID of the team

apikey
string (required) 

The authentication key

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "team_image_url": "https://shottracker.com/pimg/bc1b6e06-3a44-11e6-857c-06a15c73f3c3",
  "players": [
    {
      "id": 2907,
      "image_url": "https://shottracker.com/pimg/bc1b6e06-3a44-11e6-857c-06a15c73f3c3"
    },
    {
      "id": 2908,
      "image_url": "https://shottracker.com/pimg/bc1b6e06-3a44-11e6-857c-06a15c73f3c3"
    },
    {
      "id": 2909,
      "image_url": "https://shottracker.com/pimg/bc1b6e06-3a44-11e6-857c-06a15c73f3c3"
    },
    {
      "id": 2910,
      "image_url": "https://shottracker.com/pimg/bc1b6e06-3a44-11e6-857c-06a15c73f3c3"
    },
    {
      "id": 2911,
      "image_url": "https://shottracker.com/pimg/bc1b6e06-3a44-11e6-857c-06a15c73f3c3"
    }
  ]
}

Active Game Colors

Active Game Colors
GET/broadcast/v1/games/active/{schedule_id}/colors{?apikey}

Returns the team colors for the active game. This endpoint only works with games in an ACTIVE status. It is possible to subscribe to a game before it is active which means once a game marker message is received this endpoint could be called to get the current colors set by ShotTracker game success group. The base team color (color_rgb) is returned under the teams endpoint and can be used to represent the team color however this endpoint represents the exact jersey color each team is wearing at the time of the active game.

Example URI

GET /broadcast/v1/games/active/schedule_id/colors?apikey=
URI Parameters
HideShow
schedule_id
string (required) 

ID of the scheduled game

apikey
string (required) 

The authentication key

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "teams": [
    {
      "id": 469,
      "color": "00FF80"
    },
    {
      "id": 470,
      "color": "0080FF"
    }
  ]
}

Full Game Stats SSE

Full Game Stats SSE
GET/broadcast/v1/stats/event-stream{?schedule_id,format,apikey}

Opens a Server Sent Events (SSE) connection that will remain open as long as the connection persists. This endpoint will push updated live game stats to the consumer as they occur. The schedule_id from the Schedule endpoint is required. If the connection drops during the game, after reconnecting, the latest game stats file will be pushed. See the Full Game Stats JSON Format for a complete description of each field.

Note: This endpoint only works with active or upcoming scheduled games. Ended games remain retrievable on this endpoint for 12 hours from the end of the game.

Example connecting to the SSE endpoint using javascript:

var EventSource = require("eventsource");
var fs = require('fs');

const SCHEDULE_ID = '<schedule id>';
const API_KEY = '<your api key>';

var es = new EventSource(`https://api.shottracker.com/broadcast/v1/stats/event-stream?schedule_id=${SCHEDULE_ID}&apikey=${API_KEY}`);

var listener = function (event) {
    var type = event.type;
    if (type === 'message') {
        var data = event.data;
        console.log(data);

        fs.writeFile("./sse_data.json", data, function(err) {
            if(err) {
                return console.log(err);
            }

            console.log("The file was saved!");
        });
    }
};

es.addEventListener('open', listener);
es.addEventListener('message', listener);
es.addEventListener('error', listener);

Example connection to the SSE endpoint using golang (download tool):

package main

import (
  "bufio"
  "fmt"
  "io"
  "net/http"
  "os"
  "strings"
  "time"
)

const CONNECTED_STATUS = "CONNECTED"
const DISCONNECTED_STATUS = "DISCONNECTED"

var timer *time.Timer

func main() {
  reader := bufio.NewReader(os.Stdin)
  fmt.Println("ShotTracker SSE Download Utility")
  fmt.Println("--------------------------------")
  fmt.Println("Enter Event Stream URL")
  fmt.Print("> ")
  url, _ := reader.ReadString('\n')
  fmt.Println("Enter Output File Name")
  fmt.Print("> ")
  fileName, _ := reader.ReadString('\n')
  fmt.Println("================================")

  run(strings.TrimSpace(url), strings.TrimSpace(fileName))
}

func run(url string, fileName string) {
  for {
    response, _ := getResponse(nil, url)

    if response == nil {
      time.Sleep(5000 * time.Millisecond)
      continue
    }

    logToConsole(CONNECTED_STATUS, "waiting for data ...")
    read(response, fileName)

    response.Body.Close()
  }
}

func getResponse(body io.Reader, url string) (*http.Response, error) {
  request, requestErr := http.NewRequest(http.MethodGet, url, body)
  if requestErr != nil {
    panic(fmt.Sprintf("Error occurred creating new request: %s", requestErr))
  }
  request.Header.Add("Accept", "text/event-stream")

  httpClient := http.Client{}

  response, err := httpClient.Do(request)
  if err != nil {
    logToConsole(DISCONNECTED_STATUS, fmt.Sprintf("error occurred connecting to %s: %s", url, err))
    return nil, err
  }
  if response.StatusCode != http.StatusOK {
    panic(fmt.Sprintf("Expected a %d status code; got a %d", http.StatusOK, response.StatusCode))
  }
  return response, err
}

func read(response *http.Response, fileName string) {
  handleHeartbeat(response)

  dataChannel := make(chan string)
  cancelChannel := make(chan struct{})
  go func() {
    for {
      select {
      case data := <-dataChannel:
        {
          dataHandler(fileName, data, response)
        }
      case <-cancelChannel:
        return
      }
    }
  }()

  defer close(cancelChannel)

  reader := bufio.NewReader(response.Body)
  for {
    data, err := reader.ReadString('\n')
    if err != nil && err != io.EOF {
      fmt.Fprintf(os.Stderr, "Error reading response: %s\n", err)
      break
    }

    dataChannel <- data
  }
}

func dataHandler(fileName string, data string, response *http.Response) {
  if data == "\n" {
    return
  }

  if data == ":\n" {
    logToConsole(CONNECTED_STATUS, "server heartbeat received")
    handleHeartbeat(response)
  }

  if strings.HasPrefix(data, "data:") {
    logToConsole(CONNECTED_STATUS, "data received, updating "+fileName)
    writeToFile(fileName, strings.TrimSpace(data[6:]))
  }
}

func handleHeartbeat(response *http.Response) {
  if timer != nil {
    timer.Stop()
  }
  timer = time.NewTimer(30 * time.Second)
  go func() {
    <-timer.C
    logToConsole(DISCONNECTED_STATUS, "no heartbeat received in 30 seconds; reconnecting...")
    response.Body.Close()
  }()
  return
}

func writeToFile(filename string, data string) {
  file, err := os.Create(filename)
  if err != nil {
    fmt.Fprintf(os.Stderr, "Error creating file: %s\n", err)
  }

  defer file.Close()

  _, err = io.WriteString(file, data)
  if err != nil {
    fmt.Fprintf(os.Stderr, "Error writing to file: %s\n", err)
  }

  file.Sync()
}

func logToConsole(status string, value string) {
  dateTime := time.Now().Format("2006.01.02 15:04:05")

  fmt.Printf("\r%s [%s] %s", status, dateTime, value)
}

Example URI

GET /broadcast/v1/stats/event-stream?schedule_id=&format=&apikey=
URI Parameters
HideShow
schedule_id
string (required) 

ID of the scheduled game

format
string (optional) 

indicates the response format; values are json or xml; if no value is given the default format is json

apikey
string (required) 

The authentication key

Response  200
HideShow
Headers
Content-Type: text/event-stream
Body
See "Game Stats JSON Format"

Full Game Stats

Full Game Stats
GET/broadcast/v1/stats{?schedule_id,format,apikey}

This endpoint will return the latest updated game stats. To receive updates as they happen consumers should use the Full Game Stats SSE. See the Full Game Stats JSON Format for a complete description of each field.

Example URI

GET /broadcast/v1/stats?schedule_id=&format=&apikey=
URI Parameters
HideShow
schedule_id
string (required) 

ID of the scheduled game

format
string (optional) 

indicates the response format; values are json or xml; if no value is given the default format is json

apikey
string (required) 

The authentication key

Response  200
HideShow
Headers
Content-Type: application/json
Body
See "Game Stats JSON Format"

Tournament Stats

Tournament Stats
GET/broadcast/v1/tournament/stats{?schedule_id,team_id,player_id,apikey}

Requests either team or player basic stats over the course of a tournament. The request is made within the context of an active game schedule_id that is part of a tournament. If only the team_id is given, the stats are rolled up to the team level over the tournament. If both the team_id and player_id are given, the stats are at the player level over the tournament. The stats returned from this endpoint DO NOT contain the stats for the active game (schedule_id); the stats only reflect the completed games in the same tournament.

The following stats are returned from this endpoint.

Stat Name Type Description
TWO_POINT_PCT_DISPLAY string (DEPRECATED) the percent of only 2pt field goals
FG number the number of made field goals
FGA number the number of attempted field goals
FG_FRACTION string the fractional display of field goals
FG_PCT_DISPLAY string the percent of field goals
FG2 number the number of made 2pt field goals
FGA2 number the number of attempted 2pt field goals
FG2_FRACTION string the fractional display of 2pt field goals
FG2_PCT_DISPLAY string the percent of 2pt field goals
FG3 number the number of made 3pt field goals
FGA3 number the number of attempted 3pt field goals
FG3_FRACTION string the fractional display of 3pt field goals
FG3_PCT_DISPLAY string the percent of 3pt field goals
FT number the number of made free throws
FTA number the number of attempted free throws
FT_FRACTION string the fractional display of free throws
FT_PCT_DISPLAY string the percent of free throws
PLUS_MINUS number the player’s plus/minus
PTS number number of points
REB number number of rebounds
OFFENSIVE_REB number number of offensive rebounds
DEFENSIVE_REB number number of defensive rebounds
AST number number of assists
STL number number of steals
TO number number of turnovers
DIST number total distance in cm
DIST_MILES number total distance in miles
BLK number number of blocks
FL number number of fouls
AST_TO_RATE number the rate of assist to turnovers
SECOND_CHANCE_POINTS number number of points scored after an offensive rebound
POINTS_OFF_TURNOVER number number of points scored after a turnover

Example URI

GET /broadcast/v1/tournament/stats?schedule_id=&team_id=&player_id=&apikey=
URI Parameters
HideShow
schedule_id
string (required) 

ID of the scheduled game

team_id
number (required) 

ID of the team

player_id
number (optional) 

ID of the player

apikey
string (required) 

The authentication key

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "TWO_POINT_PCT_DISPLAY": "57%",
  "FG": 38,
  "FGA": 61,
  "FG_FRACTION": "38/61",
  "FG_PCT_DISPLAY": "62%",
  "FG2": 27,
  "FGA2": 51,
  "FG2_FRACTION": "27/51",
  "FG2_PCT_DISPLAY": "53%",
  "FG3": 9,
  "FGA3": 10,
  "FG3_FRACTION": "9/10",
  "FG3_PCT_DISPLAY": "90%",
  "FT": 2,
  "FTA": 3,
  "FT_FRACTION": "2/3",
  "FT_PCT_DISPLAY": "67%",
  "PTS": 87,
  "REB": 24,
  "OFFENSIVE_REB": 24,
  "DEFENSIVE_REB": 0,
  "AST": 2,
  "STL": 2,
  "TO": 0,
  "DIST": 16915,
  "DIST_MILES": 0.11,
  "BLK": 0,
  "FL": 0,
  "AST_TO_RATE": 0,
  "SECOND_CHANCE_POINTS": 12,
  "POINTS_OFF_TURNOVER": 0
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Game not found"
}
Response  412
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "team_id is required"
}
Response  422
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Game not within a tournament"
}