NBA FAQs

What format are date fields presented in?

When we present date only values we present these in the ISO 8601 standard format.
ex: 2013-04-03
We use these for attributes that have date and no time (such as birthdate). For more information: https://en.wikipedia.org/wiki/ISO_8601

What format are the date/time fields presented in?

All of our Date/Time attributes are in UTC, presented in the ISO 8601 standard format.
ex: 2013-04-03T18:15:00+00:00
For more information: https://en.wikipedia.org/wiki/ISO_8601

How do I locate the TTL (Time to Live)/cache on an API endpoint?

The cache (in seconds) can be accessed in the returned header information on each RESTful API call, under cache-control.
ex. cache-control: max-age=1, public, s-maxage=1 or
cache-control: public, must-revalidate, max-age=120

Note that, for select game-centric endpoints, the TTL may adjust when an event is live. This information is available for each endpoint on our developer portal.

What game statuses can I expect to see in the feeds and what are their definitions?

Here is a list of the valid game statuses you can expect to see, and their definitions.

scheduled - The game is scheduled to occur.
created – The game has been created and we have begun logging information.
inprogress – The game is in progress.
halftime - The game is currently at halftime.
complete – The game is over, but stat validation is not complete.
closed – The game is over and the stats have been validated.
cancelled – The game has been cancelled. No makeup game will be played as a result.
delayed – The start of the game is currently delayed or the game has gone from in progress to delayed for some reason.
postponed – The game has been postponed, to be made up at another day and time. Once the makeup game is announced, a new game and ID will be created and scheduled on the announced makeup date.
time-tbd – The game has been scheduled, but a time has yet to be announced.
if-necessary – The game will be scheduled if it is required.
unnecessary – The series game was scheduled to occur, but will not take place due to one team clinching the series early.

What series statuses can I expect to see in the feeds and what are their definitions?

Here is a list of the valid series statuses you can expect to see, and their definitions.

scheduled – The series is scheduled to occur.
inprogress – The series is in progress.
closed – The series is over.

What player positions can I expect to see in the feeds?

Here is a list of the valid player positions you can expect to see.

What player primary positions can I expect to see in the feeds?

Here is a list of the valid player primary positions you can expect to see.

What player statuses can I expect to see in the feeds?

Here is a list of the valid player statuses you can expect to see.

ACT – The player is on the team’s active roster
SUS – The player is suspended
IR – The player is on injured reserve
TWO-WAY - The player is on a two-way contract
NWT – The player is no longer with the team
FA – Free Agent
RET – Retired
DUP – Duplicate
M-LEAGUE – Sent to minor league team
TEN-DAY – The player is on a 10-day contract

What player injury statuses can I expect to see in the feeds?

Here is a list of the valid player injury statuses you can expect to see.

Unknown
Day to Day
Out
Out for Season
Out Indefinitely

What shot type descriptions can I expect to see in the feeds?

Here is a list of the valid shot types with the descriptions you can expect to see for each shot type.

Jump Shot (This is the only shot type for 3-point attempts)

bank
driving
driving bank
driving floating
driving floating bank
turnaround
turnaround bank
turnaround fadeaway
turnaround fadeaway bank
floating
fadeaway
fadeaway bank
stepback
stepback bank
pullup
pullup bank
running
running pullup

Layup

alley-oop
cutting
cutting finger roll
driving
driving reverse
driving finger roll
finger roll
putback
reverse
running
running reverse
running finger roll
running alley-oop
tip

Dunk

alley-oop
tip
driving
driving reverse
putback
running
reverse
running reverse
running alley-oop
cutting

Tip Shot

Hook

bank
driving
driving bank
turnaround
turnaround bank

What are the valid turnover type descriptions I can expect to see in the feeds?

Here is a list of the valid turnover types you can expect to see.

Traveling
Bad Pass
Lost Ball
Carrying
Palming
Out of Bounds

Lost Ball
Step
Bad Pass

Double Dribble
Offensive Goaltending
3-second violation
5-second violation
8-second violation
10-second violation
Back Court Violation
Shot Clock Violation
Lane Violation
Illegal Assist
Illegal Screen
Turnover
Too Many Players
Excess Timeout
Basket from Below
Swinging Elbows
Offensive Foul
Punched Ball
Opposite Basket
Jump Ball Violation
Inbound
Discontinue Dribble
5-second Violation Inbound
Kicked ball Violation
5-second Violation Back to the Basket

What are the valid stoppage reasons I can expect to see in the feeds?

Here is a list of the valid stoppage reasons you can expect to see.

Out of Bounds
Equipment Malfunction
Blood Rule
Court Cleanup
Injury
Other

What are the valid jump ball reasons I can expect to see in the feeds?

Here is a list of the valid jump ball reasons you can expect to see.

Lodged Ball
Held Ball
Double Violation
Unclear Pass
Double Foul

What are the valid foul type descriptions I can expect to see in the feeds?

Here is a list of the valid foul type descriptions you can expect to see.

Charge
Off the Ball
Block
Take
Double
Shooting
Clear Path
Loose Ball
Blocking
Player Control
Shooting block
Elbowing
Punching
Flagrant One
Flagrant Two
Away from Play
Unsportsmanlike Conduct
Rim Hanging
Delay of Game
Taunting
Indirect
Excess Timeout
Too Many Players
Inbound
Defensive Three Second
Flopping

What are the valid free throw types I can expect to see in the feeds?

Here is a list of the valid free throw types you can expect to see.

Regular
Technical
Flagrant
Clear Path

What ejection types can I expect to see in the feeds?

Here is a list of the valid ejection types you can expect to see.

Technical
Second Technical
Second Flagrant Type 1
Flagrant Type 2
Other

Are there cases when not all game data is available?

Yes, in cases when Sportradar is unable to receive data from the venue, Sportradar's in-house operators will take over coverage of the game. In these cases, the following data points will not be available or will not update during the game.

Defensive Points per Possession
Defensive Rating
Defensive Rebounds Percentage
Fast Break Attempts
Fast Break Made
Fast Break Percentage
Minus
Offensive Points per Possession
Offensive Rating
Offensive Rebounds Percentage
Opponent Possessions
Plus
Rebounds Percentage
Second Chance Attempts
Second Chance Made
Second Chance Percentage
Team Defensive Rebounds
Team Offensive Rebounds
Time Spent Leading
Turnovers Percentage

After the game, when on-venue data can be received again, these fields will be updated.

What is the scale of the X Y coordinates?

The court we use is 1128 by 600. The scale is in inches.

What x/y vertices define action areas in the x/y coordinate graph?

A list of areas is included below. Note that these vertices are for the left side of the court. For the right side, we use the following calculation, where length=1128 and width=600:

right-court-point = (length - x, width - y)
left_basket=[63, 300]
right_basket=[1065, 300]

Areas:

underbasket: [ 48, 252 ], [ 77, 258 ], [ 111, 300 ], [ 77, 342 ], [ 48, 348 ]
inthepaint: [ 0, 204 ], [ 228, 204 ], [ 228, 396 ], [ 0, 396 ]
insiderightwing: [ 0, 36 ], [ 115, 36 ], [ 77, 204 ], [ 0, 204 ]
insideright: [ 115, 36 ], [ 225, 87 ], [ 294, 161 ], [ 225, 204 ], [ 77, 204 ]
insidecenter: [ 225, 204 ], [ 294, 161 ], [ 324, 218 ], [ 337, 300 ], [ 324, 382 ], [ 294, 439 ], [ 225, 396 ]
insideleft: [ 115, 564 ], [ 225, 513 ], [ 294, 439 ], [ 225, 396 ], [ 77, 396 ]
insideleftwing: [ 0, 564 ], [ 115, 564 ], [ 77, 396 ], [ 0, 396 ]
outsiderightwing: [ 0, 0 ], [ 122, 0 ], [ 115, 36 ], [ 0, 36 ]
outsideright: [ 122, 0 ], [ 492, 0 ], [ 492, 69 ], [ 324, 218 ], [ 294, 161 ], [ 225, 87 ], [ 115, 36 ]
outsidecenter: [ 324, 216 ], [ 492, 69 ], [ 492, 531 ], [ 324, 382 ], [ 337, 300 ]
outsideleft: [ 122, 600 ], [ 492, 600 ], [ 492, 531 ], [ 324, 382 ], [ 294, 439 ], [ 225, 513 ], [ 115, 564 ]
outsideleftwing: [ 0, 600 ], [ 122, 600 ], [ 115, 564 ], [ 0, 564 ]
backcourt: [ 492, 0 ], [ 564, 0 ], [ 564, 600 ], [ 492, 600 ]

Why does the team_basket attribution in the play-by-play feed not match the basket orientation (left vs. right) in the broadcast or game tracking that I'm viewing?

Our team_basket attribution is set to match the orientation of the local television broadcast, which is on the opposite side of the scorer's table. The team_basket attribution may not match the orientation used by the particular broadcast or game tracker that you are viewing.

If you want to provide a perspective from the scorer's table, you will have to map the coordinates so that the coordinates attributed to left side of the court are attributed to the right side of the court on your end (and vice versa).

What are the valid events types tracked in the play by play feed?

Here is a list of the valid event types you can expect to see.

challengereview - Instant replay (challenge: <outcome>)
challengetimeout - <team name> challenge timeout
clearpathfoul - <charged_to> clear path foul (<drawn_by> draws the foul)
deadball - <given_to> rebound (deadball)
defaultviolation - <charged_to> violation
defensivegoaltending - <charged_to> defensive goaltending violation
delay - <charged_to> delay of game violation
doublelane - <charged_to> double lane violation
ejection - <given_to> ejected from the game (<ejection_type>)
endperiod - End of <nth period/half>
flagrantone - <charged_to> flagrant 1 (<drawn_by> draws the foul)
flagranttwo - <charged_to> flagrant 2 (<drawn_by> draws the foul)
freethrowmade - <taken_by> makes <free_throw_type> free throw <attempt>
freethrowmiss - <taken_by> misses <free_throw_type> free throw <attempt> (<charged_to> lane_violation)
jumpball - Jump ball <reason>. <possessor> vs <challenger> (<possession> gains possession)
jumpballviolation - <charged_to> jump ball violation
kickball - <charged_to> kicked ball violation
lane - <charged_to> lane violation
lineupchange - <team_name> lineup change (<players>)
offensivefoul - <charged_to> offensive foul (<foul_type_desc>) (<drawn_by> draws the foul)
officialtimeout - Official timeout
openinbound - Open inbound <team_name>
opentip - <home> vs <away> (<possession> gains possession)
personalfoul - <charged_to> personal foul (<foul_type_desc>) (<drawn_by> draws the foul)
possession - <possession> gain possession
rebound - <given_to> <offensive/defensive> rebound
requestreview - Instant replay (request)
review - Play review (<reason>, <outcome>)
shootingfoul - <charged_to> shooting foul (<drawn_by> draws the foul)
stoppage - Stoppage (<reason>)
teamtimeout - <team_name> <duration> second timeout
technicalfoul - <charged_to> technical foul (<foul_type_desc>)
technicalfoulnonunsportsmanlike - <charged_to> technical foul (<foul_type_desc>)
threepointmade - <taken_by> makes three point <shot_type_desc> <shot_type> (<assisted_by> assists)
threepointmiss - <taken_by> misses three point <shot_type_desc> <shot_type> or <blocked_by> blocks <taken_by> three point <shot_type_desc> <shot_type>
turnover - <charged_to> turnover (turnover_type_desc>)
tvtimeout - TV Timeout
twopointmade - <taken_by> makes two point <shot_type_desc> <shot_type> (<assisted_by> assists)
twopointmiss - <taken_by> misses two point <shot_type_desc> <shot_type> or <blocked_by> blocks <taken_by> two point <shot_type_desc> <shot_type>

What are the valid `clinched` playoff values for a team in the Rankings endpoint?

Here is a list of the clinched values and their definitions:

conference – The team has clinched the best record home court advantage for the playoffs
division – The team has clinched the division
eliminated – The team has been eliminated from playoff contention
playoff_berth – The team has clinched a playoff berth
play_in_berth – The team has clinched at least the play-in game

<division id="582d6502-9a93-4a8d-8785-69374d732875" name="Atlantic" alias="ATLANTIC">
  <team id="583eccfa-fb46-11e1-82cb-f4ce4684ea4c" name="Celtics" market="Boston" sr_id="sr:team:3422" reference="1610612738">
    <rank conference="1" division="1" clinched="conference"/>
  </team>
  <team id="583ec70e-fb46-11e1-82cb-f4ce4684ea4c" name="Knicks" market="New York" sr_id="sr:team:3421" reference="1610612752">
    <rank conference="2" division="2" clinched="playoff_berth"/>
  </team>
  <team id="583ec87d-fb46-11e1-82cb-f4ce4684ea4c" name="76ers" market="Philadelphia" sr_id="sr:team:3420" reference="1610612755">
    <rank conference="7" division="3" clinched="playoff_berth"/>
  </team>
  <team id="583ec9d6-fb46-11e1-82cb-f4ce4684ea4c" name="Nets" market="Brooklyn" sr_id="sr:team:3436" reference="1610612751">
    <rank conference="11" division="4" clinched="eliminated"/>
  </team>
  <team id="583ecda6-fb46-11e1-82cb-f4ce4684ea4c" name="Raptors" market="Toronto" sr_id="sr:team:3433" reference="1610612761">
    <rank conference="12" division="5" clinched="eliminated"/>
  </team>
</division>

{
  "id": "582d6502-9a93-4a8d-8785-69374d732875",
    "name": "Atlantic",
      "alias": "ATLANTIC",
        "teams": [
          {
            "id": "583eccfa-fb46-11e1-82cb-f4ce4684ea4c",
            "name": "Celtics",
            "market": "Boston",
            "sr_id": "sr:team:3422",
            "reference": "1610612738",
            "rank": {
              "conference": 1,
              "division": 1,
              "clinched": "conference"
            }
          },
          {
            "id": "583ec70e-fb46-11e1-82cb-f4ce4684ea4c",
            "name": "Knicks",
            "market": "New York",
            "sr_id": "sr:team:3421",
            "reference": "1610612752",
            "rank": {
              "conference": 2,
              "division": 2,
              "clinched": "playoff_berth"
            }
          },
          {
            "id": "583ec87d-fb46-11e1-82cb-f4ce4684ea4c",
            "name": "76ers",
            "market": "Philadelphia",
            "sr_id": "sr:team:3420",
            "reference": "1610612755",
            "rank": {
              "conference": 7,
              "division": 3,
              "clinched": "playoff_berth"
            }
          },
          {
            "id": "583ec9d6-fb46-11e1-82cb-f4ce4684ea4c",
            "name": "Nets",
            "market": "Brooklyn",
            "sr_id": "sr:team:3436",
            "reference": "1610612751",
            "rank": {
              "conference": 11,
              "division": 4,
              "clinched": "eliminated"
            }
          },
          {
            "id": "583ecda6-fb46-11e1-82cb-f4ce4684ea4c",
            "name": "Raptors",
            "market": "Toronto",
            "sr_id": "sr:team:3433",
            "reference": "1610612761",
            "rank": {
              "conference": 12,
              "division": 5,
              "clinched": "eliminated"
            }
          }
        ]
},

What are the valid qualifier names?

Here is a list of the valid qualifier names:

2ndchance
fastbreak
fromturnover
defensivegoaltending
pointsinthepaint
fastbreak
fromturnover
team
deadball
1freethrow
2freethrow
mandatory

When are scores added to the schedule feeds?

Final scores are added to the schedule feeds when the game status changes to completed.

Do you provide your feeds in any languages other than English?

Currently, we provide our feeds in 4 languages: Brazilian Portuguese, English, French, Russian, Simplified Chinese, and Spanish. The codes are as follows:

Brazilian Portuguese: br
English: eu
French: fr
Russian: ru
Simplified Chinese: zh
Spanish: es

Please note, our translated feeds include translated teams, players, and play-by-play descriptions. The feeds themselves are in English, but the content of the attributes has been translated.

What are the possible values for event category used in the Push Events feed?

Here is a list of the valid event categories you can expect to see.

freethrow
freethrow,score
foul
foul,flagrant
foul,warning
lineupchange
period,stoppage
period,stoppage,possession
possession
shot
shot,score
stoppage
timeout,stoppage
turnover
violation

What are the possible values for statistics type used in the Push Events feed?

Here is a list of the valid statistics types you can expect to see.

fieldgoal
assist
block
attemptblocked
rebound
freethrow
turnover
steal
personalfoul
flagrantfoul
technicalfoul
ejection
fouldrawn
offensivefoul

What formulas are used to calculate efficiency and efficiency game score?

Here are the formulas we use:

Efficiency: (Points + Rebounds + Assists + Steals + Blocks − Missed Field Goal Attempts − Missed Free Throw Attempts - Turnovers)

Efficiency Game Score: (Points) + (0.4*Field Goals Made) - (0.7*Field Goals Attempted) - (0.4*Free Throws Missed) + (0.7*Offensive Rebounds) + (0.3*Defensive Rebounds) + (Steals) + (0.7*Assists) + (0.7*Blocks) – (0.4*Personal Fouls) – (Turnovers)

Note: For this team efficiency calculations, statistics attributed to the team rather than a player are not counted (i.e. team rebounds, team turnovers, team fouls, etc.).

What types of splits do you provide?

Our splits are broken down into the following categories based on feed endpoint:

Game:

home
loss
opponent
over_500
road
under_500
venue
win

Hierarchy:

conference
division

In-game:

higher_fg_pct
less_personal_fouls
less_rebounds
less_turnovers
lower_fg_pct
more_personal_fouls
more_rebounds
more_turnovers
over_100_against
over_100_for
same_personal_fouls
same_rebounds
same_turnovers
under_100_against
under_100_for

Schedule:

days_of_rest
day_of_week
last_5
last_10
month
week

What are the possible values for player – not_playing_reason?

Here is a list of the valid not playing reasons you can expect to see, and their descriptions.

DNP - Coaches Decision
DNP - Injury/Illness
DNP - Personal
DNP - Rest
DNP - Trade Pending
DNP - League Suspension
DNP - Team Suspension
DNP - Return to Competition Reconditioning
DNP - Ineligible to Play
DNP - Health and Safety Protocols
DND - Coaches Decision
DND - Injury/Illness
DND - Personal
DND - Rest
DND - Trade Pending
DND - League Suspension
DND - Team Suspension
DND - Return to Competition Reconditioning
DND - Ineligible to Play
DND - Health and Safety Protocols
NWT - Coaches Decision
NWT - Injury/Illness
NWT - Personal
NWT - Rest
NWT - Trade Pending
NWT - League Suspension
NWT - Team Suspension
NWT - Return to Competition Reconditioning
NWT - Ineligible to Play
NWT - Health and Safety Protocols
NWT - Not With Team
Inactive - Injury/Illness
Inactive - Personal
Inactive - Rest
Inactive - Suspended
Inactive - Trade Pending
Inactive - Coaches Decision
Inactive - G League Team
Inactive - G League - On Assignment
Inactive - G League - Two-Way
Inactive - Not With Team
Inactive - Team Suspension
Inactive - League Suspension
Inactive - Health and Safety Protocols
Inactive - Return to Competition Reconditioning
Inactive - NWT Return to Competition Reconditioning
Inactive - Ineligible to Play

What are the valid transaction_code and transaction_type values?

Here is a list of the valid transaction codes and types:

ACT - Activated
MIN - Assigned to Minors
CL - Claimed
CEXP - Contract Expired
CEXT - Contract Extension
DEC - Deceased
FA - Declared Free Agency
DRA - Drafted
SUS - League Suspension
ABS - Leave of Absence
NWT - Not With Team
TRAN - Other Transaction
INACT - Placed on Inactive List
RSGN - Re-Signed
REC - Recalled from Minors
RSUS - Reinstated from Suspension
REL - Released
RET - Retired
EDRA - Selected in Expansion Draft
SGN - Signed
10D - Signed to 10-Day Contract
10D2- Signed to Second 10-Day Contract
TSUS - Team Suspension
TRD - Traded
WA - Waived

When should I expect to see prospect data in the Prospects endpoint?

College prospects will appear after the NCAA Early-Entrant withdrawal deadline has passed. International prospects will appear after the the NBA Early-Entrant withdrawal deadline has passed.

When should I expect pre-draft trades to be reflected in Trades and Draft Summary endpoints?

The trades and draft summary endpoints will reflect pre-draft trades after the NBA Draft Lottery has occurred.