NBA Game Distribution API - Stream - Multiple Games(Draft)
This API is designed to be used by external parties (as well as internal) to get information about one or many games. It is designed to return information relevant to the games at a specific time, it is not designed to be used to gather historical information about past games.
The API will be hosted in two separate locations:
Arena. The in arena endpoint will only support making calls about the game that is currently in progress at that specific arena.
Centrally The central endpoint will support making calls about any game.
The streaming API is provided over a WebSocket connection. The client establishes a websocket connection to the endpoint and is sent a series of messages. Each connection returns information about only one game.
| gameId string(10) |
Unique identifier for the game (Only required in single game mode) |
| format enum |
The format to return the data in.
|
| fromMessageId integer |
This parameter is used to reconnect to the API from where you left off, so that you don't have to re-handle messages you have previously received. By specifying a messageId with this parameter, messages with a messageId greater than (or equal to) the number specified here will be resent. 0 is valid and will resend all messages on connection. We strongly advise that you use this field to ensure reconnecting to the feed is quick and efficient, if for whatever reason your connection terminates during live games. Please note this only applies to messages that contain the messageId field, therefore only event and teams messages. Aggregated messages do not contain a messageId field so this will not apply to them. Only valid if |
| types string(100) |
A comma separated value of the message types to be sent through the feed. If not set, then the following value is assumed.
|
| language enum |
If any of the content is available in multiple languages (eg. the person's names) then this is the language is will be returned in. The language codes are IETF BCP 47 defined tags.
|
For each connection made you must send an authentication message to authorize your connection. This message must be sent within 5 seconds of connection.
{
"type": "authentication",
"apikey": "HDFJJ3839JL823J9238",
}
| type enum |
|
| apikey string;(50) |
The API key provided to you |
All data provided to these API functions is required to be in UTF-8 format.
All responses will be provided as UTF-8 strings.
Messages are sent in either JSON or XML depending on the format parameter used in starting the call.
Each message content differs depending on the type and category of the message, but will contain at least the following keys.
type
This field indicates the type of message. The valid types are each explained in more detail in this
documentation.
category
The messages can be broken down into a number of categories
raw-sport
Generated courtside these statistics are actions/events that have happened in the game.
raw-admin
Generated courtside these are administrative actions that do not directly aggregate to the end state of
the game. Examples include clock alterations.
aggregated
This category of messsages contain information that has been aggregated from a number of raw events.
Types such as box scores or play by play are examples of this type.
state
This category of messsages contains information related to the current state of the system and its
connections and timing.
distributionHost This key contains debugging information indicating from which distributionHost the
message is coming from. Clients should ignore this field when processing the data as the field value may change
per message.
{
"type": "action",
"category": "raw",
"distributionHost": "A389E9823",
...
...
}
From time to time new key values/structures will be added to this protocol. Any client consuming this data should ignore anything they do not understand. New fields/values/structures should not cause a failure or crash in the client system.
Not all keys will exist in all messages for all events. No value present for a key can be sent either as a value of
null or the key not being present in the data.
| type enum |
The type of the message
|
||
| category enum |
The category of the message
|
||
| gameId string(10) |
Unique identifier for the game |
||
| messageId integer |
Unique identifier of the message being sent |
||
| actionNumber integer |
Unique number for this event. Only present when category = |
||
| orderNumber integer |
Unique number identifiying the order of the action in the game. This number may not be sequential but will be unique. Sorting by this number will give the order of actions (and will account for edits and insertions). |
||
| clock string |
The current time on the clock. The format is ISO-8601, where mm represents the number of minutes, ss the number of seconds and cc the number of tenths of a second. Format is: PTmmMss.ccS |
||
| shotClock string |
The current time on the shot clock. The format is ISO-8601, where ss represents the number of seconds and cc the number of tenths of a second. If the time left on the shot clock is more than the game clock, then this field will be set to null. Format is: PTss.ccS |
||
| timeActual string |
The date/time when this event occurred in UTC Format is: YYYY-MM-DDTHH:MM:SS.sZ (ISO 8601) |
||
| period integer |
Sequence number of the period. OVERTIME periods are numbered after REGULAR periods. |
||
| periodType enum |
The type of period
|
||
| eventType enum |
A code representating the event taken. See Action Types for the list of options. |
||
| subType enum |
The subType of event occurring. See Action Types for the list of options. |
||
| descriptor enum |
A descriptor for the subType of the event occurring. See Action Types for the list of options. |
||
| qualifiers array |
An array of qualifiers to the event. See Action Types for the list of options. |
||
| |||
| success enum |
This event was completed successfully. Generally all events except shots are successful.
|
||
| flagged enum |
This event is flagged for review by the statistician
|
||
| system enum |
This event was automatically generated by the system and not explicitly performed by the user.
|
||
| value string(250) |
A text field. Some event types require a value. This is where that value will be placed. |
||
| previousAction integer |
The number of the previous action if it relates to this action |
||
| teamId integer |
Unique identifier for the team |
||
| personId integer |
The unique identifier for the person performing the event |
||
| x float |
X coordinate on the court as to where the action occurred. Defined in Court Definitions. |
||
| y float |
Y coordinate on the court as to where the action occurred. Defined in Court Definitions. |
||
| possession integer |
The teamId of the team that has offensive possession. If no team has possession then this field should be 0. eg. Shot made / missed => team taking the shot,
Rebound => team getting rebound,
Steal => team making steal,
Turnover => team making turnover,
Jumpball => 0,
Start Period => 0
|
||
| area string |
The area of the court where the action occurred. Defined in Court Definitions. |
||
| areaDetail string |
The area of the court where the action occurred. Defined in Court Definitions. |
||
| side enum |
Indicates which side of the court the player is shooting for.
|
||
| shotDistance float |
If a shot has been taken, this is the distance (in feet) of the shot. If not valid (eg. non shot event) then this key may not be present. |
||
| scoreHome string |
The current score of the home team. This field will always have the current score even if the action is an insert from earlier in the game. |
||
| scoreAway string |
The current score of the away team. This field will always have the current score even if the action is an insert from earlier in the game. |
||
| edited string |
If the action has been edited (after being initially sent) this field should contain the last time it was edited (in UTC). Format is: YYYY-MM-DDTHH:MM:SS.sZ (ISO 8601) |
||
| inserted string |
If the action has been inserted (added out of sequence) this field should contain the time it was inserted (in UTC). Format is: YYYY-MM-DDTHH:MM:SS.sZ (ISO 8601) |
||
| deleted string |
If the action has been deleted (after being initially sent) this field should contain the time it was deleted (in UTC). Format is: YYYY-MM-DDTHH:MM:SS.sZ (ISO 8601) |
||
| source enum |
The source location of where this event was captured.
|
||
| device enum |
The type of device that generated this event. Only visible if level=3 or above.
|
||
| officialId integer |
The unique identifier for the official who called the event. Only visible if level=2 or above. |
||
| statisticianId integer |
The unique identifier for the statistician who entered the event. Only visible if level=3 or above. |
||
| instance string(50) |
Unique identifier for the device which generated this event. Only visible if level=2 or above. |
||
raw-sport event typesFor a particular action an event can have 1 type, 1 subtype, 1 descriptor and any number of qualifiers
If qualifiers are able to be used for a particular action/subType, then any number of qualifiers may be applied to the action.
If the subType indicates (blank) this means that the action can be used without a subType.
| Type | SubType | Descriptor | Qualifiers |
|---|---|---|---|
game |
|||
start |
|||
end |
|||
period |
|||
start |
|||
end |
|||
2pt |
Applies to all 2pt subTypes:
|
||
| (blank) | |||
dunk |
|
||
layup |
|
||
hook |
|
||
jumpshot |
|
||
3pt |
Applies to all 3pt subTypes:
|
||
| (blank) | |||
jumpshot |
|
||
freethrow |
Applies to all freethrow subTypes:
|
Applies to all freethrow subTypes:
|
|
1of1 |
|
||
1of2 |
|
||
1of3 |
|||
2of2 |
|
||
2of3 |
|||
3of3 |
|||
1for1 |
|||
1for2 |
|||
1for3 |
|||
jumpball |
|||
| (blank) | |||
startperiod |
|||
lodgedball |
|||
heldball |
|||
doubleviolation |
|||
outofbounds |
|||
challenge |
|||
tap |
|||
unclearpass |
|||
doublefoul |
|||
won |
|||
lost |
|||
recovered |
team |
||
assist |
|||
block |
|||
received |
|||
rebound |
Applies to all subTypes:
|
||
defensive |
|||
offensive |
|||
foul |
Applies to all foul subTypes:
|
||
offensive |
Applies to offensive subType:
|
||
personal |
Applies to all personal foul subType:
|
||
technical |
Applies to technical subType:
|
team |
|
drawn |
|||
timeout |
mandatory |
||
full |
Mandatory qualifier only applies for full timeout | ||
short |
|||
officials |
|||
challenge |
|||
reset |
|||
steal |
|||
turnover |
|||
| (blank) | team |
||
toomanyplayers |
team |
||
excesstimeout |
team |
||
offensivefoul |
|||
basketfrombelow |
|||
swingingelbows |
|||
punchedball |
|||
oppositebasket |
|||
palming |
|||
jumpballviolation |
|||
laneviolation |
|||
inbound |
|||
discontinuedribble |
|||
lostball |
|||
offensivegoaltending |
|||
badpass |
|||
backcourt |
|||
doubledribble |
|||
outofbounds |
|
||
traveling |
|||
shotclock |
team |
||
3secviolation |
|||
5secviolation |
|||
8secviolation |
|||
5secinboundviolation |
team |
||
offensivekickedball |
|||
illegalassist |
|||
illegaloutofboundscreen |
|||
5secondbacktothebasket |
|||
10secondfreethrowshooter |
|||
substitution |
startperiod |
||
in |
|||
out |
|||
violation |
|||
| (blank) | |||
delayofgame |
|||
defensivegoaltending |
|||
defensive3second |
|||
lane |
|||
jumpball |
|||
kickedball |
|||
doublelane |
|||
ejection |
|||
| (blank) | |||
technical |
|||
secondtechnical |
|||
secondflagranttype1 |
|||
flagranttype2 |
|||
other |
|||
stoppage |
|||
| (blank) | |||
outofbounds |
|||
equipmentmalfunction |
|||
bloodrule |
|||
courtcleanup |
|||
injury |
|||
other |
|||
instantreplay |
|||
|
|
||
altercationrequest |
|||
memo |
The memo text should be in the value field |
raw-admin event typesFor a particular action an event can have 1 type, 1 subtype and 1 descriptor
If the subType indicates (blank) this means that the action can be used without a subType.
| Type | SubType | Descriptor | |
|---|---|---|---|
status |
|||
ready |
|||
warmup |
|||
pregame |
|||
anthem |
|||
oncourt |
|||
countdown |
|||
inprogress |
|||
periodbreak |
|||
interrupted |
|||
cancelled |
|||
finished |
|||
finalbox |
|||
protested |
|||
complete |
|||
rescheduled |
|||
delayed |
|||
suspended |
|||
periodstatus |
|||
pending |
|||
started |
|||
ended |
|||
confirmed |
|||
clock |
|||
start |
|||
stop |
|||
adjustment |
The number of seconds (use decimal places for fractions of a second) adjustment should be passed in the value field. Negative values are allowed | ||
shotclock |
|||
reset |
|||
adjustment |
The number of seconds (use decimal places for fractions of a second) adjustment should be passed in the value field. Negative values are allowed | ||
possessionchange |
|||
milestone |
|||
attendance |
The number of the attendees should be in the value field | ||
sellout |
|||
injury |
|||
available |
|||
notavailable |
|||
notreturning |
Court coordinates are dimensionless and are defined as percentage measurments of the total width and height of the basketball court. The origin (0,0) is the top left corner of the court meaning the bottom right point is (100,100).
Actual physical dimensions can be obtained by multiplying the x and y values by the width and height of the court respectively.
For example: x = 20,45 relates to (20*94/100), (45*50/100) = 18.8ft, 22.5 ft
The bottom of the court (x=0) is defined as the side where the score bench is located.
Each action comes through with two shot areas, area and areaDetail. These are defined by
ruleset, but they break the court up into a number of different zones. Each shot taken is assigned to one simple
zone and one detail zone depending on where the person was when the action was taken.
Each one of these zones is given a name which is returned in the data.
As the zones and their names change depending on configuration, they are not defined here, but can be obtained by contacting the NBA.
Example:
An example zone layout is shown, which each colour representing a different zone, which would return a different
name.
| type enum |
The type of the message
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| category enum |
The category of the message
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| messageId integer |
Unique identifier of the message being sent |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| gameId string(10) |
Unique identifier for the game |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| home object | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| away object | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| type enum |
The type of the message
|
| category enum |
The category of the message
|
| gameId string(10) |
Unique identifier for the game |
| periodType enum |
The type of period
|
| periodNumber integer |
The period number. Overtime periods start at 1. |
| period integer |
Sequence number of the period. OVERTIME periods are numbered after REGULAR periods. |
| clock string |
The current time on the clock. The format is ISO-8601, where mm represents the number of minutes, ss the number of seconds and cc the number of tenths of a second. Format is: PTmmMss.ccS |
| shotClock string |
The current time on the shot clock. The format is ISO-8601, where ss represents the number of seconds and cc the number of tenths of a second. If the time left on the shot clock is more than the game clock, then this field will be set to null. Format is: PTss.ccS |
| clockRunning enum |
Is the clock running?
|
| type enum |
The type of the message
|
| category enum |
The category of the message
|
| gameId string(10) |
Unique identifier for the game |
| status enum |
This status of the connection to the capture device
|
| source enum |
This source of the data
|
| instance string(50) |
Unique identifier for the device which generated this event. Only visible if level=2 or above. |
| type enum |
The type of the message
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| category enum |
The category of the message
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| gameId string(10) |
Unique identifier for the game |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| gameTimeLocal datetime |
The scheduled start date/time of the game in the timezone of the arena Format is: YYYY-MM-DDTHH:MM:SS.s (ISO 8601) |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| gameTimeUTC datetime |
The scheduled start date/time of the game in the UTC timezone Format is: YYYY-MM-DDTHH:MM:SS.sZ (ISO 8601) |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| gameTimeHome datetime |
The scheduled start date/time of the game in the timezone of the home team Format is: YYYY-MM-DDTHH:MM:SS.sZ (ISO 8601) |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| gameTimeAway datetime |
The scheduled start date/time of the game in the timezone of the away team Format is: YYYY-MM-DDTHH:MM:SS.sZ (ISO 8601) |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| homeTeamId integer |
Unique identifier for the team |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| awayTeamId integer |
Unique identifier for the team |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| arenaId integer |
The unique identifier for the arena |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| arenaName string(100) |
The name of the arena |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| arenaNickname string(50) |
A non-offical name of the arena |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| arenaCode string(50) |
Short Code of the arena |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| timezone string |
The timezone location as defined by the IANA time zone database. See http://en.wikipedia.org/wiki/List_of_tz_database_time_zones |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| ruleset object |
The ruleset that the game operates under |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| type enum |
The type of the message
|
||||||||||||||
| category enum |
The category of the message
|
||||||||||||||
| messageId integer |
Unique identifier of the message being sent |
||||||||||||||
| gameId string(10) |
Unique identifier for the game |
||||||||||||||
| officials array |
An array of officials |
||||||||||||||
| |||||||||||||||
| type enum |
The type of the message
|
||||||||||||||||||||||||
| category enum |
The category of the message
|
||||||||||||||||||||||||
| gameId string(10) |
Unique identifier for the game |
||||||||||||||||||||||||
| status enum |
The status of the match.
|
||||||||||||||||||||||||
| periodType enum |
The type of period
|
||||||||||||||||||||||||
| period integer |
Sequence number of the period. OVERTIME periods are numbered after REGULAR periods. |
||||||||||||||||||||||||
| periodNumber integer |
The period number. Overtime periods start at 1. |
||||||||||||||||||||||||
| periodStatus enum |
The status of the period.
|
||||||||||||||||||||||||
| clock string |
The current time on the clock. The format is ISO-8601, where mm represents the number of minutes, ss the number of seconds and cc the number of tenths of a second. Format is: PTmmMss.ccS |
||||||||||||||||||||||||
| shotClock string |
The current time on the shot clock. The format is ISO-8601, where ss represents the number of seconds and cc the number of tenths of a second. If the time left on the shot clock is more than the game clock, then this field will be set to null. Format is: PTss.ccS |
||||||||||||||||||||||||
| clockRunning enum |
Is the clock running?
|
||||||||||||||||||||||||
| homeTeam | |||||||||||||||||||||||||
| |||||||||||||||||||||||||
| awayTeam | |||||||||||||||||||||||||
| |||||||||||||||||||||||||
| attendance integer |
The attendance of the game |
||||||||||||||||||||||||
| sellout enum |
Is the game a sell out?
|
||||||||||||||||||||||||
| type enum |
The type of the message
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| category enum |
The category of the message
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| gameId string(10) |
Unique identifier for the game |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| actions array |
Array of play by play actions, sorted ascending |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||