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": "possession_touch_71435614ec7ccbc094fe1f0bb3b8e98c",
"ballhandler_possession_touch_outcome_id": "shot_bab5015a8c75579fc1cb24b82f3df764",
"chance_id_ctg": "chance_4c33ded97f95174cc013b446c3981347",
"defensive_weak_side_player_count": 2,
"drive_id_ctg": "drive_4c0859e1242cf39607d5896f6dae865c",
"end_distance_to_hoop_in": 75.24,
"end_game_clock": 689.0,
"end_he_frame": 1908,
"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,
"start_distance_to_hoop_in": 356.77,
"start_game_clock": 691.0,
"start_he_frame": 1776,
"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
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.
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 drive (left or right). 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
Type: string | Nullable
CTG-generated possession touch ID for the driver touch linked to this drive.
ballhandler_possession_touch_outcome_id
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.
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.