Appearance
Ball Screen Instances
The ball_screen_instances section contains one row for each "screening instance" during a Ball Screen.
Overview
If a screener adjusts the angle of their screen or re-screens, we often want to view these as separate "instances" of a ball screen. These are all still part of the same ball screen action but the directions and coverages can differ between each of these instances of a screen.
Because of this, we have created the notion of a "screening instance", where a given ball screen can have more than one screening instance. Notably, we require all 4 players in the ball screen to remain the same for it to count as a screening instance. So a case where a screener screens, the defenders switch, the screener turns and re-screens would not be viewed as a new instance. Ideally this would be a separate ball screen action.
This data set gives the Hawk-Eye frame for each instance linked to a ball_screen_id_ctg.
For ball screens without a re-screen or angle adjustment, they will have one screening instance that will match the screening_he_frame of the ball screen.
Each row has the player IDs, the instance frame and clocks, and the screener and ballhandler locations at that frame. It also has fields that show which instance is the first one and which frame is the current ball-screen frame.
Sample Response
json
{
"markings": {
"ball_screen_instances": [
{
"attacking_positive_x_basket": false,
"ball_defender_id_nba": 1630230,
"ball_handler_id_nba": 1630180,
"ball_handler_loc_x": -156.78,
"ball_handler_loc_y": -102.65,
"ball_screen_id_ctg": "ball_screen_790295edbb16a587380cd3d49f5063ef",
"ball_screen_screening_he_frame": 1747,
"chance_id_ctg": "chance_4c33ded97f95174cc013b446c3981347",
"double_screen_screener_id_nba": null,
"game_id_nba": "0022500404",
"instance_count": 2,
"instance_number": 1,
"instance_screening_he_frame": 1747,
"is_current_screening_frame": true,
"is_dribble_handoff": true,
"is_handoff": true,
"is_initial_screening_instance": true,
"period": 1,
"possession_id_ctg": "possession_90461f431f3586f0ba39f25f0cefdec7",
"screener_defender_id_nba": 203076,
"screener_id_nba": 1642852,
"screener_loc_x": -182.64,
"screener_loc_y": -54.05,
"screening_game_clock": 692.0,
"screening_shot_clock": 10.0,
"screening_wall_clock": "2025-12-23T01:11:03.571+00:00"
}
]
}
}The sample values show the response shape. They do not describe a current game record.
Fields
Identifiers
ball_screen_id_ctg
Type: string
CTG ID of the parent row in Ball Screens. Join this field with ball_screen_id_ctg in that data set.
game_id_nba
Type: string
NBA game ID.
chance_id_ctg
Type: string | Nullable
CTG ID of the related chance, when available.
possession_id_ctg
Type: string | Nullable
CTG ID of the related possession, when available.
Players
ball_handler_id_nba
Type: integer | Nullable
NBA player ID of the ballhandler.
screener_id_nba
Type: integer | Nullable
NBA player ID of the screener.
double_screen_screener_id_nba
Type: integer | Nullable
NBA player ID of the other screener in a double screen, when available.
ball_defender_id_nba
Type: integer | Nullable
NBA player ID of the defender assigned to the ballhandler.
screener_defender_id_nba
Type: integer | Nullable
NBA player ID of the defender assigned to the screener.
Instance
instance_number
Type: integer | Nullable
Chronological order of this instance within its parent ball screen. Numbering starts at 1 and has no gaps.
instance_count
Type: integer | Nullable
Total number of instances linked to the parent ball screen. All rows for that parent have the same value.
instance_screening_he_frame
Type: integer
Hawk-Eye frame number for this screening instance.
ball_screen_screening_he_frame
Type: integer | Nullable
Hawk-Eye frame number for the parent ball screen's recorded screening frame.
is_initial_screening_instance
Type: boolean | Nullable
true when this is the first screening instance linked to the parent ball screen.
is_current_screening_frame
Type: boolean | Nullable
true when this frame matches the parent ball screen's recorded screening frame.
is_handoff
Type: boolean | Nullable
true when CTG classifies the parent ball screen as a handoff.
is_dribble_handoff
Type: boolean
true when CTG classifies the parent ball screen as a dribble handoff.
Timing
period
Type: integer | Nullable
Period number. Values 1–4 are regulation periods. Values 5 and higher are overtime periods.
screening_game_clock
Type: float | Unit: seconds | Nullable
Game clock time remaining in the period at instance_screening_he_frame.
screening_shot_clock
Type: float | Unit: seconds | Nullable
Shot clock time at instance_screening_he_frame. 0 when the shot clock is off.
screening_wall_clock
Type: string | Nullable
UTC wall-clock time at instance_screening_he_frame, in ISO-8601 format.
Location
attacking_positive_x_basket
Type: boolean | Nullable
true when the offense attacks the basket on the positive-x side of the court.
screener_loc_x
Type: float | Unit: inches | Nullable
X coordinate of the screener at instance_screening_he_frame.
screener_loc_y
Type: float | Unit: inches | Nullable
Y coordinate of the screener at instance_screening_he_frame.
ball_handler_loc_x
Type: float | Unit: inches | Nullable
X coordinate of the ballhandler at instance_screening_he_frame.
ball_handler_loc_y
Type: float | Unit: inches | Nullable
Y coordinate of the ballhandler at instance_screening_he_frame.