← Event API
Live Data V2 — WebSocket
All live data is delivered over a WebSocket, a long-lived connection between the DDSports servers and your client. You must first obtain a subscription token by subscribing to the specific game (e.g. via the Game Subscription Token endpoint). Tokens are issued per game; use a new token to subscribe to another game or drill.
Connection URL
Connect to the WebSocket with your subscription token and optional query parameters. See Code examples → WebSocket connection URL for the full URL pattern.
Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| token | string | Yes | Subscription token (from Game Subscription Token endpoint). |
| source | string | No | Filter to specific data sources. Multiple source params supported, e.g. source=broadcastsummary&source=clock. If omitted, all client-accessible sources are sent. See Sources table below. |
| broadcast_summary_level | string | No | When using the broadcastsummary source, use `game_stats` to reduce response size and receive only game-level stats (no detailed breakdown). See Broadcast API stats / broadcast summary level options for other values. |
| last_seq | number | No | Sequence number for reconnection. Sequence-supported sources share one sequence; pass the last received seq when reconnecting to resume from that point. If omitted, streaming starts from the beginning of the event. Non-sequence sources always send latest or next value. |
Keep alives
Clients must send a ping no more than every 30 seconds when no other data is received, so the connection stays open. The server responds with a pong.
Sources
Use the source query parameter to subscribe to specific streams. Sequence-supported sources share a single sequence number for catch-up and reconnection.
| Source | Sequence | Description |
|---|---|---|
| marker | Yes | Game state markers (e.g. jersey colors, lineup status). |
| broadcastsummary | No | Broadcaster full summary (same shape as Broadcast API Game Stats JSON). |
| boxscorestatsv2 | Yes | Play-by-play box score stats for all players and team. |
| chart | Yes | Shot chart details for every shot. |
| possessions | Yes | Each team’s possessions; updated for each stat. |
| possessionstats | Yes | Advanced stat totals for grouped possessions. |
| lineupstats | Yes | Stat totals for grouped lineups. |
| location | No | Player and ball xyz locations. |
| clock | No | Game clock and shot clock ticks (2 Hz). |
Data payload shape by source
For each type: "data" message, the data object shape depends on source. Below are the main fields for each source.
marker
| Field | Type | Description |
|---|---|---|
| t | number | Timestamp (ms). |
| gameId | string | Game event ID. |
| status | string | Marker type (e.g. JERSEY_COLOR). |
| data | object | Payload depends on status; e.g. JERSEY_COLOR: facilityId, courtId, team1Id, team1JerseyColor, team2Id, team2JerseyColor (hex). |
broadcastsummary
| Field | Type | Description |
|---|---|---|
| at | number | Epoch timestamp of file (ms). |
| at_formatted | string | Human-readable timestamp for at. |
| period | string | Current or last period: PRE, H1, H2, Q1, Q2, Q3, Q4, HT, OT, END; COMPLETED when done; TP for test pattern. |
| reference | string | Internal ShotTracker tracking id. |
| game_stats | object | Full game totals; same format as half/quarter stats below. |
| half_1_stats | object | First half stats; always present with half_2_stats. |
| half_2_stats | object | Second half stats. |
| quarter_1_stats | object | First quarter; only when game is run as quarters. |
| quarter_2_stats | object | Second quarter stats. |
| quarter_3_stats | object | Third quarter stats. |
| quarter_4_stats | object | Fourth quarter stats. |
| ot_1_stats | object | First overtime stats. |
| *_stats.reference | string | Internal tracking id for that stats object. |
| *_stats.home | object | All team and player stats for the home team. |
| *_stats.away | object | All team and player stats for the away team; same shape as home (away.team, away.players with same fields as below). |
| home.team.team_id | number | ShotTracker internal team id (same for away.team). |
| home.team.consumer_code | string | Consumer-defined code for the team or ShotTracker team_id. |
| home.team.team_name | string | Team name defined in ShotTracker. |
| home.team.TWO_POINT_PCT_DISPLAY | string | (DEPRECATED) Percent of 2pt field goals only. |
| home.team.FG | number | Made field goals. |
| home.team.FGA | number | Attempted field goals. |
| home.team.FG_FRACTION | string | Fractional display of field goals. |
| home.team.FG_PCT_DISPLAY | string | Percent of field goals. |
| home.team.FG2 | number | Made 2pt field goals. |
| home.team.FGA2 | number | Attempted 2pt field goals. |
| home.team.FG2_FRACTION | string | Fractional display of 2pt field goals. |
| home.team.FG2_PCT_DISPLAY | string | Percent of 2pt field goals. |
| home.team.FG3 | number | Made 3pt field goals. |
| home.team.FGA3 | number | Attempted 3pt field goals. |
| home.team.FG3_FRACTION | string | Fractional display of 3pt field goals. |
| home.team.FG3_PCT_DISPLAY | string | Percent of 3pt field goals. |
| home.team.FT | number | Made free throws. |
| home.team.FTA | number | Attempted free throws. |
| home.team.FT_FRACTION | string | Fractional display of free throws. |
| home.team.FT_PCT_DISPLAY | string | Percent of free throws. |
| home.team.PTS | number | Team points. |
| home.team.REB | number | Team rebounds. |
| home.team.OFFENSIVE_REB | number | Team offensive rebounds. |
| home.team.DEFENSIVE_REB | number | Team defensive rebounds. |
| home.team.AST | number | Team assists. |
| home.team.STL | number | Team steals. |
| home.team.TO | number | Team turnovers. |
| home.team.LBTO | number | Team live ball turnovers. |
| home.team.DBTO | number | Team dead ball turnovers. |
| home.team.DIST | number | Total team distance in cm. |
| home.team.DIST_MILES | number | Total team distance in miles. |
| home.team.BLK | number | Team blocks. |
| home.team.FL | number | Team fouls. |
| home.team.FLDN | number | Team fouls drawn. |
| home.team.PPTS | number | Points in the paint. |
| home.team.AST_TO_RATE | number | Assist-to-turnover rate. |
| home.team.SECOND_CHANCE_POINTS | number | Points scored after an offensive rebound. |
| home.team.POINTS_OFF_TURNOVER | number | Points scored after a turnover. |
| home.team.shots | object[] | Team shots per ShotTracker 14-zone map; each zone: DISPLAY, PCT_DISPLAY, R, G, B (RGB). |
| home.team.shot_locations.make | array | Made shot locations (xy mm from hoop), peak ball height, entry angle, depth, velocity. |
| home.team.shot_locations.miss | array | Missed shot locations (same format as make). |
| home.team.cas_shots | object[] | Catch-and-shoot shots per zone map; each zone: DISPLAY, PCT_DISPLAY, R, G, B. |
| home.team.otd_shots | object[] | Off-the-dribble shots per zone map; each zone: DISPLAY, PCT_DISPLAY, R, G, B. |
| home.team.*_FG_VALUE | number | Per possession type (e.g. OVERALL, TRANSITION, PT0_BR0): total field goals. |
| home.team.*_FG | string | Per possession type: field goal percent. |
| home.team.*_FG_FRACTION | string | Per possession type: field goal fraction. |
| home.team.*_POSS | number | Per possession type: number of possessions. |
| home.team.*_PTS | number | Per possession type: points. |
| home.team.*_2PTM | number | Per possession type: 2pt makes. |
| home.team.*_2PTA | number | Per possession type: 2pt attempts. |
| home.team.*_3PTM | number | Per possession type: 3pt makes. |
| home.team.*_3PTA | number | Per possession type: 3pt attempts. |
| home.team.*_TO | number | Per possession type: turnovers. |
| home.team.*_PPP | number | Per possession type: points per possession. |
| home.team.*_FG_VALUE_ARROW | number | Per possession type: indicates which FG value is higher vs away team. |
| home.team.lineup_stats | object[] | Top 2 lineups; each: player_ids (array of 5), PLUS_MINUS, TOTAL_POINTS_SCORED, TOTAL_POINTS_ALLOWED. |
| home.players | object[] | Team and player stats; player_id 0 = team row (same for away.players). |
| home.players[].player_id | number | ShotTracker player id; 0 if team row. |
| home.players[].consumer_code | string | Consumer-defined code or ShotTracker player_id. |
| home.players[].jersey_number | number | Jersey number; -1 if team row. |
| home.players[].first_name | string | First name; null if team. |
| home.players[].last_name | string | Last name; null if team. |
| home.players[].position_abbr | string | C, G, F or null if team. |
| home.players[].sensor | number | Assigned sensor id; 0 if team. |
| home.players[].on_the_floor | boolean | True if currently on court. |
| home.players[].TWO_POINT_PCT_DISPLAY | string | (DEPRECATED) Percent of 2pt field goals only. |
| home.players[].FG | number | Made field goals. |
| home.players[].FGA | number | Attempted field goals. |
| home.players[].FG_FRACTION | string | Fractional display of field goals. |
| home.players[].FG_PCT_DISPLAY | string | Percent of field goals. |
| home.players[].FG2 | number | Made 2pt field goals. |
| home.players[].FGA2 | number | Attempted 2pt field goals. |
| home.players[].FG2_FRACTION | string | Fractional display of 2pt. |
| home.players[].FG2_PCT_DISPLAY | string | Percent of 2pt. |
| home.players[].FG3 | number | Made 3pt field goals. |
| home.players[].FGA3 | number | Attempted 3pt field goals. |
| home.players[].FG3_FRACTION | string | Fractional display of 3pt. |
| home.players[].FG3_PCT_DISPLAY | string | Percent of 3pt. |
| home.players[].FT | number | Made free throws. |
| home.players[].FTA | number | Attempted free throws. |
| home.players[].FT_FRACTION | string | Fractional display of FT. |
| home.players[].FT_PCT_DISPLAY | string | Percent of free throws. |
| home.players[].PLUS_MINUS | number | Plus/minus. |
| home.players[].PTS | number | Player points. |
| home.players[].REB | number | Rebounds. |
| home.players[].OFFENSIVE_REB | number | Offensive rebounds. |
| home.players[].DEFENSIVE_REB | number | Defensive rebounds. |
| home.players[].AST | number | Assists. |
| home.players[].STL | number | Steals. |
| home.players[].TO | number | Turnovers. |
| home.players[].LBTO | number | Live ball turnovers. |
| home.players[].DBTO | number | Dead ball turnovers. |
| home.players[].DIST | number | Distance in cm. |
| home.players[].DIST_MILES | number | Distance in miles. |
| home.players[].BLK | number | Blocks. |
| home.players[].FL | number | Fouls. |
| home.players[].FLDN | number | Fouls drawn. |
| home.players[].PPTS | number | Points in the paint. |
| home.players[].AST_TO_RATE | number | Assist-to-turnover rate. |
| home.players[].shots | object[] | Shots per 14-zone map; each zone: DISPLAY, PCT_DISPLAY, R, G, B. |
| home.players[].shot_locations.make | array | Made shot locations (xy mm, peak height, entry angle, depth, velocity). |
| home.players[].shot_locations.miss | array | Missed shot locations. |
| home.players[].cas_shots | object[] | Catch-and-shoot per zone; DISPLAY, PCT_DISPLAY, R, G, B. |
| home.players[].otd_shots | object[] | Off-the-dribble per zone; DISPLAY, PCT_DISPLAY, R, G, B. |
| home.players[].season_stats | object | Only with include_player_season; only under game_stats. FT, FTA, FT_FRACTION, FT_PCT_DISPLAY for season. |
boxscorestatsv2
| Field | Type | Description |
|---|---|---|
| classification | string | Stat classification (e.g. THREE_POINT_MAKE). |
| act | string | Actor type (e.g. PLAYER). |
| eid | string | Event ID. |
| tid | string | Team ID. |
| st | string | Session type (e.g. GAME_ROUND). |
| sid | string | Session ID. |
| t | number | Timestamp (ms). |
| gid | string | Game ID. |
| stats | object | Current stat values for this player (box score keys, e.g. FG, PTS, TEAM_SCORE). |
| totalStats | object | Cumulative stats after this event. |
| v | number | Version. |
| pid | string | Player ID. |
| prd | string | Period (e.g. Q1). |
| px | number | Player x (mm). |
| py | number | Player y (mm). |
| hex | number | Hoop x. |
| hey | number | Hoop y. |
chart
| Field | Type | Description |
|---|---|---|
| eid | string | Event ID. |
| t | number | Timestamp (ms). |
| pid | string | Shooter player ID. |
| tid | string | Team ID. |
| sid | string | Session ID. |
| gid | string | Game ID. |
| st | string | Shot result (MAKE / MISS). |
| is3 | boolean | True if 3-point shot. |
| pts | number | Points (0, 2, or 3). |
| px | number | Player x (mm). |
| py | number | Player y (mm). |
| pz | number | Player z. |
| hx | number | Hoop x. |
| hy | number | Hoop y. |
| hz | number | Hoop z. |
| s | string | Status (e.g. RECORDED). |
| z | number | Zone. |
| az | number | Advanced zone. |
| d | number | Shot distance (e.g. cm). |
| attributes | string[] | Shot attributes (e.g. CAS). |
| players | string[] | Player IDs on court. |
| shotDefenders | number[] | Player IDs of defenders. |
| prd | string | Period (e.g. Q1). |
possessions
| Field | Type | Description |
|---|---|---|
| state | string | e.g. SAVED. |
| possession | object | Current possession object. |
| possession.supervision | string | e.g. SYSTEM. |
| possession.startTimestamp | number | Start time (ms). |
| possession.teamId | string | Team ID. |
| possession.sessionId | string | Session ID. |
| possession.gameId | string | Game ID. |
| possession.lineupPlayers | string[] | Lineup player IDs. |
| possession.opponentLineupPlayers | string[] | Opponent lineup player IDs. |
| possession.possessions | array | Events in possession (possessionType, playerId, timestamp, etc.). |
| possession.stats | object | Possession stats (turnover, shotType, points, ballReversals, etc.). |
| possession.responseView | object | Simplified view (possessions[], period, events). |
possessionstats
| Field | Type | Description |
|---|---|---|
| t | number | Timestamp (ms). |
| scope | string | e.g. SESSION. |
| gid | string | Game ID. |
| sid | string | Session ID. |
| st | string | Session type (e.g. GAME_ROUND). |
| tid | string | Team ID. |
| summary | array | One object per group (type: OVERALL, PT0_BR0, etc.; POSS, POSS_PCT, PTS, PPP, 2PTM, 2PTA, 2PT_PCT, 3PTM, 3PTA, 3PT_PCT, TO, TO_PCT, EFG). |
lineupstats
| Field | Type | Description |
|---|---|---|
| tid | string | Team ID. |
| sid | string | Session ID. |
| gid | string | Game ID. |
| stats | object | FG_RATE, REB_RATE, TOTAL_POINTS_SCORED, TOTAL_TURNOVERS, PPP, OPPP, PLUS_MINUS, etc. |
| players | string[] | Player IDs in this lineup. |
location
| Field | Type | Description |
|---|---|---|
| gcms | number | Game clock milliseconds. |
| scms | number | Shot clock milliseconds. |
| cr | boolean | Clock running. |
| period | string | e.g. Q1. |
| facilityId | string | Facility ID. |
| courtId | string | Court ID. |
| sessionId | string | Session ID. |
| locations | array | Array of location objects. |
| locations[].t | number | Timestamp (ms). |
| locations[].type | string | PLAYER or BALL. |
| locations[].pid | number | Player ID (PLAYER). |
| locations[].bid | string | Ball ID (BALL). |
| locations[].tid | number | Team ID. |
| locations[].x | number | x (mm). |
| locations[].y | number | y (mm). |
| locations[].z | number | z (mm). |
| locations[].speed | number | Speed. |
| locations[].dist | number | Distance. |
| locations[].vx | number | Velocity x. |
| locations[].vy | number | Velocity y. |
| locations[].vz | number | Velocity z. |
clock
| Field | Type | Description |
|---|---|---|
| gid | string | Game ID. |
| period | string | e.g. Q1, OT. |
| type | string | e.g. GAME_SHOT_CLOCK. |
| state | string | e.g. STARTED. |
| source | string | e.g. OFFICIAL. |
| min | string | Minutes. |
| sec | string | Seconds. |
| subSec | string | Sub-seconds. |
| shotSec | string | null | Shot clock seconds (if applicable). |
| shotSubSec | string | null | Shot clock sub-seconds. |
| controllerId | string | null | Controller ID. |
Message shape
Each WebSocket message is JSON. Data messages include type, source, and optionally seq and data.
For full request/response examples and payload fields, see the Event API section Live Data V2 Games in the API Blueprint (live.apib) or the generated Aglio docs.