Appearance
Drives
The drives section in the markings response contains data for offensive drives toward the basket.
Overview
A drive is defined as when a player takes at least one dribble in an effort to get closer to the rim. This is a reasonably loose definition of drives that may capture some situations that don't immediately seem like the classic concept of a drive. But we feel it is better to be very inclusive in this category and then provide you with the details of the drive that you can use to filter down if you would like.
We follow the following guidelines to help identify these drives:
- The player must start outside the paint and beyond 10 feet from the rim
- The player must get closer to the rim
- The player must get inside around three-point line distance during their drive
- A player who catches a pass on the move in transition headed toward the rim at high speed would not be counted as driving
Sample Response
json
{
"markings": {
"drives": [
{
"ball_handler_defender_id_nba": 1630230,
"ballhandler_movement_side": "right",
"ballhandler_outcome": "shot",
"ballhandler_possession_touch_id_ctg": "possession_touch_71435614ec7ccbc094fe1f0bb3b8e98c",
"ballhandler_possession_touch_id": "possession_touch_71435614ec7ccbc094fe1f0bb3b8e98c",
"ballhandler_possession_touch_outcome_id_ctg": "shot_bab5015a8c75579fc1cb24b82f3df764",
"ballhandler_possession_touch_outcome_id": "shot_bab5015a8c75579fc1cb24b82f3df764",
"chance_id_ctg": "chance_4c33ded97f95174cc013b446c3981347",
"defensive_weak_side_player_count": 2,
"drive_id_ctg": "drive_4c0859e1242cf39607d5896f6dae865c",
"drive_context": "pick",
"drive_initial_direction": "right",
"ball_hoop_distance_min": 5.52,
"drive_outcome": "interior_shot",
"end_distance_to_hoop_in": 75.24,
"end_game_clock": 689.0,
"end_he_frame": 1908,
"end_loc_x": -474.27,
"end_loc_y": 72.6,
"end_region": "ra",
"end_shot_clock": 7.0,
"end_wall_clock": "2025-12-23T01:11:06.255+00:00",
"game_id_nba": "0022500404",
"has_offensive_off_ball_player_moving_at_play_start": true,
"is_direct": true,
"max_ballhandler_speed_in_per_sec": 237.67,
"offensive_weak_side_player_count": 2,
"period": 1,
"player_id_nba": 1630180,
"attacking_positive_x_basket": true,
"start_distance_to_hoop_in": 356.77,
"start_game_clock": 691.0,
"start_he_frame": 1776,
"start_loc_x": -321.42,
"start_loc_y": 86.34,
"start_region": "middle two",
"start_shot_clock": 10.0,
"start_wall_clock": "2025-12-23T01:11:04.055+00:00",
"team_id_nba": 1610612740
}
]
}
}Fields
Identifiers
game_id_nba
Type: string
NBA game ID
drive_id_ctg
Type: string
CTG-generated unique drive ID
chance_id_ctg
Type: string
CTG-generated identifier for the chance during which this drive occurred. This field is null if the drive could not be associated with a chance due to upstream data error.
player_id_nba
Type: integer
NBA player ID of the driver
team_id_nba
Type: integer
NBA team ID of the driving team
ball_handler_defender_id_nba
Type: integer
NBA player ID of the primary defender on the ball handler. null when there is an upstream error that causes bad chance data which prevents us from identifying the defender.
Timing
Period
period
Type: integer
Period in which the drive occurred
Start
The start of the drive is estimated to be when the player first starts to attack the basket.
start_game_clock
Type: float
Game clock when drive began
start_shot_clock
Type: float
Shot clock when drive began
start_he_frame
Type: integer
Hawk-Eye frame when drive began
start_wall_clock
Type: string
UTC timestamp when drive began
End
The end of the drive is estimated to be when:
- The player stops their dribbling toward the rim for a significant period of time (e.g. retreats back out, dribbles under the rim and pulls the ball out, picks up the ball and stops). Note that if the player retreats for a little but then attacks again, we keep this as part of the same drive unless the retreat is significant.
- The ball leaves the player's hands (via pass or shot or turnover).
- The whistle is blown and play stops due to a foul/violation.
end_game_clock
Type: float
Game clock when drive ended
end_shot_clock
Type: float
Shot clock when drive ended
end_he_frame
Type: integer
Hawk-Eye frame when drive ended
end_wall_clock
Type: string
UTC timestamp when drive ended
Drive Metrics
start_distance_to_hoop_in
Type: float | Unit: inches
Distance from driver to hoop at drive start
end_distance_to_hoop_in
Type: float | Unit: inches
Distance from driver to hoop at drive end
ball_hoop_distance_min
Type: float | Unit: feet
Minimum distance from the ball to the hoop during the drive.
start_loc_x
Type: float | Unit: inches
X coordinate of the driver's centroid at the start of the drive.
start_loc_y
Type: float | Unit: inches
Y coordinate of the driver's centroid at the start of the drive.
start_region
Type: string
Court region of the driver's centroid at the start of the drive.
drive_context
Type: string
How the drive started. One of: 1v1, pick, handoff, off_ball_screen, closeout, ball_screen_screener, transition, other.
If more than one action is detected for the drive, we use the following precedence order: 1v1, pick, handoff, off_ball_screen, closeout, ball_screen_screener, transition, other.
So ball_screen_screener is for situations where the driver was previously a screener in a ball screen action and then attacked but without the drive matching any of the prior categories in the priority order. A pick and pop with a closeout will be closeout, but a half roll into a drive with no closeout would be ball_screen_screener.
drive_initial_direction
Type: string | Nullable
The driver's first meaningful attack direction relative to the basket. One of: left, right, straight.
This field describes the start of the drive. It does not describe all movement during the drive. Sometimes the exact placement of the start of the drive can be ambiguous, or what counts as an initial movement one direction is hard to determine. For example, should a hard dribble left before crossing back right and attacking count as initially going left? In these cases we have tried our best to count a meaningful amount of movement one direction as the initial direction the driver went, but this probably needs more sharpening to make sure it is consistent across situations and is easy to interpret.
This field is null when the direction cannot be determined due to upstream data issues.
end_loc_x
Type: float | Unit: inches
X coordinate of the driver's centroid at the end of the drive.
end_loc_y
Type: float | Unit: inches
Y coordinate of the driver's centroid at the end of the drive.
end_region
Type: string
Court region of the driver's centroid at the end of the drive.
attacking_positive_x_basket
Type: boolean
true if the offensive team is attacking the basket on the positive-x side of the court (i.e., the basket with positive x coordinates).
max_ballhandler_speed_in_per_sec
Type: float | Unit: inches/second
Maximum ball handler speed reached during the drive.
is_direct
Type: boolean
true when the drive ends in a direct scoring outcome: the ballhandler shoots, is fouled and goes to the free throw line, or turns the ball over — or the driver makes a pass near the end of the drive and the receiver shoots within one dribble of catching it (in the same chance, with no further passes before the shot). false otherwise.
drive_outcome
Type: string | Nullable
Possible options for the outcome of the drive:
dribble_out: The driver keeps their dribble alive and takes at least two dribbles after the drive, where at least one of those dribbles goes to the perimeter and is further from the rim than the drive end location.pass_to_perimeter: The driver passes to a teammate who catches at least 15 feet from the rim. If the pass is a turnover, it is still included in this category, and the location of the intended receiver is used.pass_to_interior: The driver passes to a teammate who catches within 15 feet of the rim. If the pass is a turnover, it is still included in this category, and the location of the intended receiver is used.jump_shot: The driver's possession touch ends with a shot that has a shot type ofjumperwithout them having dribbled out first.interior_shot: The driver's possession touch ends with a shot that does not have a shot type ofjumperwithout them having dribbled out first.turnover: The driver commits a non-passing turnover.stoppage: The drive ends because play stops for a foul, violation, or other stoppage.
This field is null when the drive end could not be classified due to upstream data issues.
Off-ball context fields
defensive_weak_side_player_count
Type: integer | Nullable
How many of the four defensive off-ball players were on the weak side at the start of the drive. For drives, the weak side is defined as follows: draw a line from the ball handler at drive start to the center of the rim, then determine which way the ball handler is moving (to the right or left relative to that line). The weak side is the opposite side of the line from the way the ball handler is moving, so if they are moving to their right, anyone to the left of the line is on the weak side.
offensive_weak_side_player_count
Type: integer | Nullable
How many offensive off-ball players were on the weak side at the start of the drive. For drives, the weak side is defined as follows: draw a line from the ball handler at drive start to the center of the rim, then determine which way the ball handler is moving (to the right or left relative to that line). The weak side is the opposite side of the line from the way the ball handler is moving, so if they are moving to their right, anyone to the left of the line is on the weak side.
ballhandler_movement_side
Type: string | Nullable
Direction the ballhandler moved during the full drive (left or right). This field differs from drive_initial_direction, which describes only the start. null if the movement side could not be determined.
ballhandler_outcome
Type: string | Nullable
How the driver's linked possession touch ended. One of: shot, pass, turnover, foul, violation, stoppage, unknown.
ballhandler_possession_touch_id_ctg
Type: string | Nullable
CTG-generated possession touch ID for the driver touch linked to this drive.
ballhandler_possession_touch_id deprecated
Type: string | Nullable
Compatibility alias for ballhandler_possession_touch_id_ctg. Both fields contain the same value, including null.
Deprecated
Use ballhandler_possession_touch_id_ctg instead. This field will be removed in a future version.
ballhandler_possession_touch_outcome_id_ctg
Type: string | Nullable
CTG-generated event ID for how the linked driver possession touch ended. This can be null when the outcome does not have a specific CTG event ID.
ballhandler_possession_touch_outcome_id deprecated
Type: string | Nullable
Compatibility alias for ballhandler_possession_touch_outcome_id_ctg. Both fields contain the same value, including null.
Deprecated
Use ballhandler_possession_touch_outcome_id_ctg instead. This field will be removed in a future version.
has_offensive_off_ball_player_moving_at_play_start
Type: boolean | Nullable
true if at least one offensive off-ball player is moving at a reasonably fast speed when the drive starts.