Docs
Coverage MatrixDocumentationRelease LogLog InContact Us

Frequently asked questions for NBA v5.

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.

  • NA
  • C
  • C-F
  • F
  • F-C
  • F-G
  • G
  • G-F

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.

  • NA
  • C
  • PF
  • PG
  • SF
  • SG

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

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 playoff statuses and their definitions?

Here is a list of the valid playoff statuses 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.

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


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.