Possession Touches

The possession_touches section in the markings response contains an object for each individual player "possession touch" during the game.

Overview

A possession touch represents a continuous period where a single player has control of the ball, including dribbling. So they can take their hands off the ball during a possession touch, as long as nobody else touches it in between.

In other data sources these can be referred to simply as "touches", however we use the name "possession touch" to distinguish it from data that would indicate whether a player is touching the ball or not.

Sample Response

json

{
  "markings": {
    "possession_touches": [
      {
        "chance_id_ctg": "chance_4c33ded97f95174cc013b446c3981347",
        "drive_id_ctg": "drive_4c0859e1242cf39607d5896f6dae865c",
        "drive_id": "drive_4c0859e1242cf39607d5896f6dae865c",
        "duration_sec": 2.92,
        "end_game_clock": 689.0,
        "end_he_frame": 1906,
        "touch_end_defender_id_nba": 1627742,
        "touch_end_defender_id": 1627742,
        "end_loc_x": -474.27,
        "end_loc_y": 72.6,
        "end_wall_clock": "2025-12-23T01:11:06.221+00:00",
        "game_id_nba": "0022500404",
        "has_paint_touch_during_possession": true,
        "is_inbounds": false,
        "is_direct": true,
        "led_to_shot": true,
        "was_double_teamed_during_touch": false,
        "is_three_point_touch": false,
        "ball_handler_acceleration": 1.38,
        "ball_handler_feet_from_rim_at_touch": 27.42,
        "ball_handler_location_at_touch_end_x": -39.52,
        "ball_handler_location_at_touch_end_y": 5.67,
        "ball_handler_location_at_touch_start_x": -15.85,
        "ball_handler_location_at_touch_start_y": -11.36,
        "ball_handler_rim_movement_angle_after_touch": 18.2,
        "ball_handler_rim_movement_angle_before_touch": -12.45,
        "ball_handler_velocity_after_touch": 9.64,
        "ball_handler_velocity_before_touch": 8.26,
        "num_dribbles": 3,
        "num_close_teammates": 1,
        "linked_foul_id_ctg": "foul_b79c166c1d4f55c4ea866c515a86010e",
        "linked_foul_pbp_event_id": 9,
        "linked_pass_id_ctg": null,
        "linked_shot_id_ctg": "shot_bab5015a8c75579fc1cb24b82f3df764",
        "linked_shot_pbp_event_id": 9,
        "linked_turnover_id_ctg": null,
        "linked_turnover_pbp_event_id": null,
        "linked_violation_id_ctg": null,
        "linked_violation_pbp_event_id": null,
        "outcome_ctg_id": "shot_bab5015a8c75579fc1cb24b82f3df764",
        "outcome_game_clock_seconds": 688,
        "outcome_pbp_event_id": 9,
        "outcome_type": "shot",
        "period": 1,
        "player_id_nba": 1630180,
        "possession_touch_id_ctg": "possession_touch_71435614ec7ccbc094fe1f0bb3b8e98c",
        "previous_possession_touch_id_ctg": "possession_touch_8901ecbdad384037a07da551349797a2",
        "next_possession_touch_id_ctg": null,
        "possession_touch_number_in_chance": 4,
        "regions_entered": ["middle two", "key", "ra"],
        "start_game_clock": 692.0,
        "start_he_frame": 1731,
        "touch_start_type": "pass",
        "touch_start_defender_id_nba": 1627742,
        "touch_start_defender_id": 1627742,
        "start_loc_x": -190.18,
        "start_loc_y": -136.3,
        "start_wall_clock": "2025-12-23T01:11:03.305+00:00",
        "team_id_nba": 1610612740
      }
    ]
  }
}

Fields

Identifiers

`possession_touch_id_ctg`

Type: string

CTG-generated unique ID for this possession touch

`game_id_nba`

Type: string

NBA game ID

`team_id_nba`

Type: integer

NBA team ID of the player's team

`player_id_nba`

Type: integer

NBA player ID of the player with the ball

`chance_id_ctg`

Type: string

CTG-generated chance ID that this possession touch belongs to. null if the touch could not be associated with a chance.

`previous_possession_touch_id_ctg`

Type: string | Nullable

CTG-generated ID for the prior possession touch in the same chance. null for the first touch in the chance.

`next_possession_touch_id_ctg`

Type: string | Nullable

CTG-generated ID for the next possession touch in the same chance. null for the last touch in the chance.

`possession_touch_number_in_chance`

Type: integer | Nullable

Chronological position of this possession touch within its chance. The first touch has value 1. null when the touch has no associated chance.

`drive_id_ctg`

Type: string | Nullable

CTG-generated drive ID for the earliest drive by this player that overlaps the possession touch. null if no such drive is identified.

`drive_id` deprecated

Type: string | Nullable

Compatibility alias for drive_id_ctg. Both fields contain the same value, including null.

Deprecated

Use drive_id_ctg instead. This field will be removed in a future version.

Timing

`period`

Type: integer

Period in which the possession touch occurred. Overtime would be period 5, double overtime period 6, etc.

`start_he_frame`

Type: integer

Hawk-Eye frame when the possession touch began.

`end_he_frame`

Type: integer

Hawk-Eye frame when the possession touch ended.

`start_wall_clock`

Type: string

UTC timestamp when the possession touch began.

`end_wall_clock`

Type: string

UTC timestamp when the possession touch ended.

`start_game_clock`

Type: float

Game clock (in seconds remaining in the period) when the possession touch began.

`end_game_clock`

Type: float

Game clock (in seconds remaining in the period) when the possession touch ended.

`duration_sec`

Type: float

Duration of the possession touch in seconds.

Context

`is_inbounds`

Type: boolean

true if this possession touch involves the player making an inbounds pass.

`num_dribbles`

Type: integer

Number of dribbles the player took during this possession touch. null if dribble count could not be determined.

`has_paint_touch_during_possession`

Type: boolean

true if the ballhandler had a paint touch during this possession touch. A qualifying paint touch is counted if the ball and both feet are in the paint during the touch or shortly after it ends (to capture in air passes or fouls while driving).

`touch_start_type`

Type: string

Type of event that led to the player's possession touch. Typical values include pass, orb, drb, inbounder, and other.

`regions_entered`

Type: array[string]

Court regions the ballhandler entered during the possession touch.

`led_to_shot`

Type: boolean

true if this possession touch ended with a shot attempt.

`is_direct`

Type: boolean

true when the possession touch directly leads to the outcome of the chance: the ballhandler shoots, is fouled, turns the ball over, commits a violation, or makes a quick completed pass and the receiver shoots soon after in the same chance. false otherwise.

`was_double_teamed_during_touch`

Type: boolean

true when a double team occurs during this possession touch.

`touch_start_defender_id_nba`

Type: integer | Nullable

NBA player ID of the defender who had the ballhandler as their last clear matchup at the start of the possession touch. null if no matchup is available at that frame. This can happen for inbound touches because the touch boundary may fall before matchup coverage is available.

`touch_start_defender_id` deprecated

Type: integer | Nullable

Compatibility alias for touch_start_defender_id_nba. Both fields contain the same value, including null.

Deprecated

Use touch_start_defender_id_nba instead. This field will be removed in a future version.

`touch_end_defender_id_nba`

Type: integer | Nullable

NBA player ID of the defender who had the ballhandler as their last clear matchup at the end of the possession touch. null if no matchup is available at that frame. This can happen for inbound touches because the touch boundary may fall before matchup coverage is available.

`touch_end_defender_id` deprecated

Type: integer | Nullable

Compatibility alias for touch_end_defender_id_nba. Both fields contain the same value, including null.

Deprecated

Use touch_end_defender_id_nba instead. This field will be removed in a future version.

`start_loc_x`

Type: float | Unit: inches

X coordinate of the player's centroid at the start of the touch. Positive X is toward one basket, negative X toward the other.

`start_loc_y`

Type: float | Unit: inches

Y coordinate of the player's centroid at the start of the touch. Positive Y is toward one sideline, negative Y toward the other.

`end_loc_x`

Type: float | Unit: inches

X coordinate of the player's centroid at the end of the touch.

`end_loc_y`

Type: float | Unit: inches

Y coordinate of the player's centroid at the end of the touch.

`is_three_point_touch`

Type: boolean | Nullable

true if the ballhandler's touch started in a three-point court region.

Location And Movement

`ball_handler_location_at_touch_start_x`

Type: float | Unit: feet | Nullable

Ballhandler x coordinate at the start of the touch.

`ball_handler_location_at_touch_start_y`

Type: float | Unit: feet | Nullable

Ballhandler y coordinate at the start of the touch.

`ball_handler_location_at_touch_end_x`

Type: float | Unit: feet | Nullable

Ballhandler x coordinate at the end of the touch.

`ball_handler_location_at_touch_end_y`

Type: float | Unit: feet | Nullable

Ballhandler y coordinate at the end of the touch.

`ball_handler_feet_from_rim_at_touch`

Type: float | Unit: feet | Nullable

Ballhandler distance from the rim at the start of the touch.

`ball_handler_velocity_before_touch`

Type: float | Unit: feet/sec | Nullable

Ballhandler speed before the touch start.

`ball_handler_velocity_after_touch`

Type: float | Unit: feet/sec | Nullable

Ballhandler speed after the touch start.

`ball_handler_acceleration`

Type: float | Unit: feet/sec | Nullable

Change from the ballhandler's speed before the touch start to their speed after the touch start.

`ball_handler_rim_movement_angle_before_touch`

Type: float | Unit: degrees | Nullable

Ballhandler movement angle relative to the rim before the touch start.

`ball_handler_rim_movement_angle_after_touch`

Type: float | Unit: degrees | Nullable

Ballhandler movement angle relative to the rim after the touch start.

`num_close_teammates`

Type: integer | Nullable

Number of teammates near the ballhandler at the touch start.

Outcome

These fields describe how the possession touch ended - what event concluded this player's time with the ball.

`outcome_type`

Type: string

The type of event that ended this possession touch. Possible values:

shot - Touch ended with a shot attempt
pass - Touch ended with a pass to another player
turnover - Touch ended with a turnover
foul - Touch ended due to a foul
violation - Touch ended due to a violation
stoppage - Touch ended due to a game stoppage
unknown - Could not determine how the touch ended

`outcome_game_clock_seconds`

Type: float

Game clock (in seconds remaining in the period) when the outcome event is recorded as occurring. null if the outcome type is unknown.

`outcome_pbp_event_id`

Type: integer

NBA Play-by-Play event ID associated with the outcome event. null if no PBP event is associated.

`outcome_ctg_id`

Type: string

CTG ID of the related event (for example, a shot, pass, or violation ID). Use this value to join to the data set for the related event. The value is null when the outcome has no applicable CTG event or is unknown.

Linked Events

These fields link any matched event. The Outcome fields (e.g. outcome_type) choose just one type of outcome based on a system that prioritizes shot over foul, for example. But a touch can link to more than one event type. For example, a passing turnover links both a pass and a turnover. These fields make all of the linked events accessible.

`linked_pass_id_ctg`

Type: string | Nullable

CTG pass ID linked to this touch.

`linked_shot_id_ctg`

Type: string | Nullable

CTG shot ID linked to this touch.

`linked_shot_pbp_event_id`

Type: integer | Nullable

NBA Play-by-Play event ID for the linked shot.

`linked_turnover_id_ctg`

Type: string | Nullable

CTG turnover ID linked to this touch.

`linked_turnover_pbp_event_id`

Type: integer | Nullable

NBA Play-by-Play event ID for the linked turnover.

`linked_foul_id_ctg`

Type: string | Nullable

CTG foul ID linked to this touch.

`linked_foul_pbp_event_id`

Type: integer | Nullable

NBA Play-by-Play event ID for the linked foul.

`linked_violation_id_ctg`

Type: string | Nullable

CTG violation ID linked to this touch.

`linked_violation_pbp_event_id`

Type: integer | Nullable

NBA Play-by-Play event ID for the linked violation.

Possession Touches ​

Overview ​

Sample Response ​

Fields ​

Identifiers ​

possession_touch_id_ctg ​

game_id_nba ​

team_id_nba ​

player_id_nba ​

chance_id_ctg ​

previous_possession_touch_id_ctg ​

next_possession_touch_id_ctg ​

possession_touch_number_in_chance ​

drive_id_ctg ​

drive_id deprecated ​

Timing ​

period ​

start_he_frame ​

end_he_frame ​

start_wall_clock ​

end_wall_clock ​

start_game_clock ​

end_game_clock ​

duration_sec ​

Context ​

is_inbounds ​

num_dribbles ​

has_paint_touch_during_possession ​

touch_start_type ​

regions_entered ​

led_to_shot ​

is_direct ​

was_double_teamed_during_touch ​

touch_start_defender_id_nba ​

touch_start_defender_id deprecated ​

touch_end_defender_id_nba ​

touch_end_defender_id deprecated ​

start_loc_x ​

start_loc_y ​

end_loc_x ​

end_loc_y ​

is_three_point_touch ​

Location And Movement ​

ball_handler_location_at_touch_start_x ​

ball_handler_location_at_touch_start_y ​

ball_handler_location_at_touch_end_x ​

ball_handler_location_at_touch_end_y ​

ball_handler_feet_from_rim_at_touch ​

ball_handler_velocity_before_touch ​

ball_handler_velocity_after_touch ​

ball_handler_acceleration ​

ball_handler_rim_movement_angle_before_touch ​

ball_handler_rim_movement_angle_after_touch ​

num_close_teammates ​

Outcome ​

outcome_type ​

outcome_game_clock_seconds ​

outcome_pbp_event_id ​

outcome_ctg_id ​

Linked Events ​

linked_pass_id_ctg ​

linked_shot_id_ctg ​

linked_shot_pbp_event_id ​

linked_turnover_id_ctg ​

linked_turnover_pbp_event_id ​

linked_foul_id_ctg ​

linked_foul_pbp_event_id ​

linked_violation_id_ctg ​

linked_violation_pbp_event_id ​

Possession Touches

Overview

Sample Response

Fields

Identifiers

`possession_touch_id_ctg`

`game_id_nba`

`team_id_nba`

`player_id_nba`

`chance_id_ctg`

`previous_possession_touch_id_ctg`

`next_possession_touch_id_ctg`

`possession_touch_number_in_chance`

`drive_id_ctg`

`drive_id` deprecated

Timing

`period`

`start_he_frame`

`end_he_frame`

`start_wall_clock`

`end_wall_clock`

`start_game_clock`

`end_game_clock`

`duration_sec`

Context

`is_inbounds`

`num_dribbles`

`has_paint_touch_during_possession`

`touch_start_type`

`regions_entered`

`led_to_shot`

`is_direct`

`was_double_teamed_during_touch`

`touch_start_defender_id_nba`

`touch_start_defender_id` deprecated

`touch_end_defender_id_nba`

`touch_end_defender_id` deprecated

`start_loc_x`

`start_loc_y`

`end_loc_x`

`end_loc_y`

`is_three_point_touch`

Location And Movement

`ball_handler_location_at_touch_start_x`

`ball_handler_location_at_touch_start_y`

`ball_handler_location_at_touch_end_x`

`ball_handler_location_at_touch_end_y`

`ball_handler_feet_from_rim_at_touch`

`ball_handler_velocity_before_touch`

`ball_handler_velocity_after_touch`

`ball_handler_acceleration`

`ball_handler_rim_movement_angle_before_touch`

`ball_handler_rim_movement_angle_after_touch`

`num_close_teammates`

Outcome

`outcome_type`

`outcome_game_clock_seconds`

`outcome_pbp_event_id`

`outcome_ctg_id`

Linked Events

`linked_pass_id_ctg`

`linked_shot_id_ctg`

`linked_shot_pbp_event_id`

`linked_turnover_id_ctg`

`linked_turnover_pbp_event_id`

`linked_foul_id_ctg`

`linked_foul_pbp_event_id`

`linked_violation_id_ctg`

`linked_violation_pbp_event_id`