Appearance
Passes
The passes section in the markings response contains an object for every pass that we detect in the game.
Overview
We attempt to detect both completed and incomplete passes. Incomplete passes can be difficult to differentiate from other situations where a player loses the ball, but we use a combination of ball trajectory and player position to make a best guess.
We also try to include controlled tips or "touch passes", where a player intentionally deflects the ball to a teammate. This includes rebound tip outs to teammates. But once again, this is an area that can be difficult to accurately differentiate from uncontrolled tips.
We filter out passes that occur after a made basket before the ball is inbounded, for example when one teammate collects the ball after it goes through the net and tosses it to a teammate to inbound.
Sample Response
json
{
"markings": {
"passes": [
{
"ball_end_loc_x": -28.36,
"ball_end_loc_y": -21.08,
"ball_hit_ground_during_completed_pass": false,
"ball_start_loc_x": -12.31,
"ball_start_loc_y": -16.95,
"catch_distance_forward_in": 29.8,
"catch_distance_from_mid_chest_in": 37.22,
"catch_distance_left_right_in": 2.72,
"catch_height_above_mid_hip_in": 34.4,
"catch_height_above_standing_hip_in": 23.25,
"catch_height_in": 63.6,
"chance_id_ctg": "chance_377f4e8d031acb0095eb520eb8ecec96",
"distance": 16.57,
"game_id_nba": "0022500404",
"intended_receiver_id_ctg": 202691,
"intended_receiver_id_nba": 202691,
"is_assist": false,
"is_backcourt": false,
"is_completed": true,
"is_direct": true,
"is_inbounds": false,
"is_jump_pass": false,
"is_one_handed_pass": false,
"is_potential_assist": true,
"is_secondary_assist": false,
"is_secondary_assister_the_shooter": false,
"is_turnover": false,
"led_to_shot": true,
"nba_game_id": "0022500404",
"num_dribbles_during_receiver_touch": 0,
"pass_handedness": "both",
"pass_id_ctg": "pass_0128a7fbcfa97b421d1877f843555263",
"pass_release_he_frame": 388571,
"pass_release_wall_clock": "2025-12-23T03:14:08.657+00:00",
"passer_id_ctg": 1630230,
"passer_id_nba": 1630230,
"passer_loc_x": -9.78,
"passer_loc_y": -16.27,
"passer_region": "far",
"pbp_event_id": null,
"receiver_jumped_for_touch": false,
"receiver_loc_x": -30.87,
"receiver_loc_y": -21.29,
"receiver_region": "left wing three",
"receiver_touch_time": 1.17,
"receiver_touch_start_he_frame": 388597,
"receiver_touch_start_wall_clock": "2025-12-23T03:14:09.09+00:00",
"receiver_touched_ball": true,
"is_reversal": false,
"turnover_receiver_loc_x": null,
"turnover_receiver_loc_y": null
}
]
}
}Fields
Identifiers
game_id_nba
Type: string
NBA game ID
nba_game_id deprecated
Type: string
NBA game ID
Deprecated
Use game_id_nba instead. This field will be removed in a future version.
pass_id_ctg
Type: string
CTG-generated unique pass ID.
chance_id_ctg
Type: string
CTG chance ID for the offensive opportunity this pass occurred in. null if no matching chance is found within 3 seconds of the pass (which may indicate a data error with a missing chance).
passer_id_nba
Type: integer
NBA player ID of the passer.
passer_id_ctg deprecated
Type: integer
NBA player ID of the passer
Deprecated
Use passer_id_nba instead. This field will be removed in a future version.
intended_receiver_id_nba
Type: integer
NBA player ID of the intended receiver. For a completed pass, this is the player who next touches the ball. For an incomplete pass, we use ball trajectory and player position data to make our best guess at who the pass was intended for.
intended_receiver_id_ctg deprecated
Type: integer
NBA player ID of the intended receiver
Deprecated
Use intended_receiver_id_nba instead. This field will be removed in a future version.
Pass Timing
pass_release_he_frame
Type: integer
Hawk-Eye frame when the pass left the passer's hands.
pass_release_wall_clock
Type: string
UTC timestamp corresponding to pass_release_he_frame.
receiver_touch_start_he_frame
Type: integer
Hawk-Eye frame when the intended receiver first touched the ball. null if the receiver never touched the ball (e.g. on an incomplete pass)
receiver_touch_start_wall_clock
Type: string
UTC timestamp corresponding to receiver_touch_start_he_frame. null if the receiver never touched the ball.
Pass Result
is_completed
Type: boolean
true if the pass was completed to a teammate after CTG's pass-result refinements. false when the pass is incomplete, including cases where a defender deflects the ball, the ball bounces multiple times after defensive contact, the defense gains immediate possession, or the play context indicates a turnover or stoppage rather than a controlled catch.
is_inbounds
Type: boolean
true if the pass was an inbounds pass. false otherwise.
is_turnover
Type: boolean
true if the pass resulted in a turnover. false otherwise.
is_direct
Type: boolean
true when the receiver’s touch after this pass ends in a shot, turnover, foul, or violation within a few seconds of catching the ball in the same period. false otherwise.
is_assist
Type: boolean
true if the NBA play-by-play credited this passer with an official assist on the receiver's shot. false otherwise.
pbp_event_id
Type: integer
The play-by-play event ID for the assisted shot when this pass was credited as an official assist. null if the pass was not credited as an official assist.
is_potential_assist
Type: boolean
true when the receiver's touch after this pass ends in a shot with no more than 3 dribbles and no more than 3.5 seconds of touch time. false otherwise.
NOTE
These thresholds were chosen by determining the values that best matched actual assists.
is_secondary_assist
Type: boolean
true if the receiver made a quick pass that was credited as an official assist without first dribbling. false otherwise.
is_secondary_assister_the_shooter
Type: boolean
true if this pass is a secondary assist where the passing player was also the shooter on the officially-assisted shot, such as a give-and-go. false otherwise.
led_to_shot
Type: boolean
true if the receiver shot the ball to end the possession touch immediately after this pass. false otherwise.
receiver_touch_time
Type: float | Unit: seconds
Duration of the receiver's possession touch after catching this pass. null if the pass was incomplete or the receiver touch could not be linked.
num_dribbles_during_receiver_touch
Type: integer
Number of dribbles during the receiver's possession touch after catching this pass. null if the pass was incomplete or the receiver touch could not be linked.
Pass Style
is_one_handed_pass
Type: boolean
true if the pass was thrown with only one hand on the ball for a meaningful portion of the throw. null if player pose data is unavailable for the passer at the time of the pass
pass_handedness
Type: string
Which hand primarily threw the pass:
rightleftbothnullif player pose data is unavailable for the passer at the time of the pass
NOTE
A pass that is not one-handed can still be primarily thrown with either the right or left hand if both hands are on the ball close to the release of the pass but one hand does the pushing.
is_jump_pass
Type: boolean
true if the passer was in the air when the ball was released. null if player pose data is unavailable for the passer at the time of the pass
is_reversal
Type: boolean
true if the pass moves the ball from an established strong side of the court to a receiver on the weak side. The receiver must be in the frontcourt and outside the middle of the floor. A pass is not counted as a reversal when the passer stays in the middle of the floor after multiple dribbles in the middle and passes to a receiver on the same side of the court. Incomplete passes can still be marked as reversals when the intended receiver's location is available. false otherwise.
is_backcourt
Type: boolean
true if the pass started in the offensive team's backcourt. false otherwise.
Pass Location
These fields use court coordinates in feet.
passer_loc_x
Type: float | Unit: feet
Passer's x-coordinate when the pass was released.
passer_loc_y
Type: float | Unit: feet
Passer's y-coordinate when the pass was released.
receiver_loc_x
Type: float | Unit: feet
Intended receiver's x-coordinate at the pass reception moment. For incomplete passes, this is the intended receiver's x-coordinate when the pass was released.
receiver_loc_y
Type: float | Unit: feet
Intended receiver's y-coordinate at the pass reception moment. For incomplete passes, this is the intended receiver's y-coordinate when the pass was released.
ball_start_loc_x
Type: float | Unit: feet
Ball x-coordinate when the pass was released.
ball_start_loc_y
Type: float | Unit: feet
Ball y-coordinate when the pass was released.
ball_end_loc_x
Type: float | Unit: feet
Ball x-coordinate at the end of the pass.
ball_end_loc_y
Type: float | Unit: feet
Ball y-coordinate at the end of the pass.
turnover_receiver_loc_x
Type: float | Unit: feet
X-coordinate of the defender credited with the steal on a live-ball turnover pass. When the defender credited with the steal is the first defender to gain possession of the ball, this uses that possession touch's start location. If the defender credited with the steal deflects the ball, this uses their last touch of the ball before their team gains possession; if that touch cannot be found, it falls back to the defender credited with the steal's location at the pass end frame. null if the pass was not a turnover or no steal was credited (e.g. an out-of-bounds or offensive-foul turnover).
turnover_receiver_loc_y
Type: float | Unit: feet
Y-coordinate of the defender credited with the steal on a live-ball turnover pass. When the defender credited with the steal is the first defender to gain possession of the ball, this uses that possession touch's start location. If the defender credited with the steal deflects the ball, this uses their last touch of the ball before their team gains possession; if that touch cannot be found, it falls back to the defender credited with the steal's location at the pass end frame. null if the pass was not a turnover or no steal was credited (e.g. an out-of-bounds or offensive-foul turnover).
passer_region
Type: string
Court region of the passer when the pass was released.
receiver_region
Type: string
Court region of the intended receiver at the pass reception moment. For incomplete passes, this is based on the intended receiver's location when the pass was released.
distance
Type: float | Unit: feet
Distance the ball traveled from the start of the pass to the end of the pass.
Reception Data
receiver_touched_ball
Type: boolean
true if the intended receiver touched the ball at any point near the end of the pass (including incomplete passes).
receiver_jumped_for_touch
Type: boolean
true if the receiver's first touch occurred while they were in the air. null if the receiver never touched the ball (e.g. on an incomplete pass)
ball_hit_ground_during_completed_pass
Type: boolean
true if the ball hit the ground between release and the receiver's first touch. null if the receiver never touched the ball (e.g. on an incomplete pass)
NOTE
Usually the ball hitting the ground on a completed pass is intentional, like a bounce pass, but because we can't easily infer intention from the tracking data this field is intentionally named to describe what we're measuring: whether the ball hit the ground between release and the receiver's first touch, not whether it was a bounce pass.
Catch Location
These fields measure where the receiver caught the ball relative to their body.
catch_height_in
Type: float | Unit: inches
Ball height above the floor at the receiver's first touch. null if the receiver never touched the ball (e.g. on an incomplete pass)
catch_height_above_mid_hip_in
Type: float | Unit: inches
Ball height above the receiver's mid hip at first touch. null if the receiver never touched the ball (e.g. on an incomplete pass)
catch_height_above_standing_hip_in
Type: float | Unit: inches
Ball height above the receiver's estimated standing hip height at first touch. This helps adjust for receivers bending down to catch low passes. null if the receiver never touched the ball (e.g. on an incomplete pass)
catch_distance_from_mid_chest_in
Type: float | Unit: inches
Distance from the ball center to the receiver's mid-chest point at first touch. We compute the mid-chest as the midpoint between the mid hip and neck. null if the receiver never touched the ball (e.g. on an incomplete pass)
catch_distance_left_right_in
Type: float | Unit: inches
How many inches to the left/right the center of the ball is from the center of the player’s chest (based on which way the shoulders are facing). This is an absolute value, i.e. it does not indicate direction only the magnitude. A value close to 0 would indicate the ball is caught in the middle of the player’s body, while a high value would indicate it is way off to the side of the player (again, based on which way the player’s shoulders are facing when the ball is first touched). null if the receiver never touched the ball (e.g. on an incomplete pass)
catch_distance_forward_in
Type: float | Unit: inches
How many inches in front of the player the center of the ball is when it is first touched. A value close to 0 would indicate the ball is first touched very close to the player’s body, while a high value would indicate it is touched far out in front of a player’s body. null if the receiver never touched the ball (e.g. on an incomplete pass)