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": "drive_4c0859e1242cf39607d5896f6dae865c",
        "duration_sec": 2.92,
        "end_game_clock": 689.0,
        "end_he_frame": 1906,
        "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,
        "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,
        "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",
        "regions_entered": ["middle two", "key", "ra"],
        "start_game_clock": 692.0,
        "start_he_frame": 1731,
        "touch_start_type": "pass",
        "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.

`drive_id`

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.

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.

`touch_start_defender_id`

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_end_defender_id`

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.

`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.