Appearance
Jump Shot Contests
The jump_shot_contests section in the markings response contains defensive contest information for every jump shot.
Overview
For each jump shot, we track every defender who was within 8 feet of the shooter's centroid at the moment of release. This includes:
- Defender positioning relative to the shooter
- Hand placement and distance to the ball at multiple checkpoints
- Jump timing relative to the shooter
If a shot has multiple contesters, there will be multiple records—one for each contester.
All of the fields below refer to the contester on the shot.
Sample Response
json
{
"markings": {
"jump_shot_contests": [
{
"angle_relative_to_shooter_at_ball_in_hands": -37.37,
"angle_relative_to_shooter_at_min_hips": -32.14,
"angle_relative_to_shooter_at_release": -6.64,
"angle_relative_to_shooter_at_shooter_jump_start": -25.08,
"closest_hand_above_head_at_ball_in_hands": false,
"closest_hand_above_head_at_min_hips": false,
"closest_hand_above_head_at_release": true,
"closest_hand_above_head_at_shooter_jump_start": true,
"closest_hand_at_release": "left",
"closest_hand_ball_dist_at_ball_in_hands_in": 51.72,
"closest_hand_ball_dist_at_min_hips_in": 27.9,
"closest_hand_ball_dist_at_release_in": 22.36,
"closest_hand_ball_dist_at_shooter_jump_start_in": 29.06,
"closest_hand_ball_height_diff_at_ball_in_hands_in": 2.25,
"closest_hand_ball_height_diff_at_min_hips_in": -2.24,
"closest_hand_ball_height_diff_at_release_in": -17.14,
"closest_hand_ball_height_diff_at_shooter_jump_start_in": 6.82,
"closest_hand_ball_hoop_angle_at_ball_in_hands": -33.0,
"closest_hand_ball_hoop_angle_at_min_hips": -51.05,
"closest_hand_ball_hoop_angle_at_release": 11.95,
"closest_hand_ball_hoop_angle_at_shooter_jump_start": -18.42,
"closest_hand_ball_vertical_angle_at_ball_in_hands": 2.49,
"closest_hand_ball_vertical_angle_at_min_hips": -4.6,
"closest_hand_ball_vertical_angle_at_release": -50.07,
"closest_hand_ball_vertical_angle_at_shooter_jump_start": 13.57,
"contester_ball_dist_at_first_both_hands_on_ball_in": 59.47,
"contester_id_nba": 1642852,
"event_pbp_id": 13,
"game_id_nba": "0022500404",
"jump_shot_contest_id_ctg": "jump_shot_contest_5ff88862f1463a8d7e418d8a591093e7",
"jump_timing": "before_shot_release",
"left_hand_above_head_at_ball_in_hands": false,
"left_hand_above_head_at_min_hips": false,
"left_hand_above_head_at_release": true,
"left_hand_above_head_at_shooter_jump_start": true,
"left_hand_ball_dist_at_ball_in_hands_in": 55.63,
"left_hand_ball_dist_at_min_hips_in": 27.9,
"left_hand_ball_dist_at_release_in": 22.36,
"left_hand_ball_dist_at_shooter_jump_start_in": 29.06,
"left_hand_ball_height_diff_at_ball_in_hands_in": 3.13,
"left_hand_ball_height_diff_at_min_hips_in": -2.24,
"left_hand_ball_height_diff_at_release_in": -17.14,
"left_hand_ball_height_diff_at_shooter_jump_start_in": 6.82,
"left_hand_ball_hoop_angle_at_ball_in_hands": -57.16,
"left_hand_ball_hoop_angle_at_min_hips": -51.05,
"left_hand_ball_hoop_angle_at_release": 11.95,
"left_hand_ball_hoop_angle_at_shooter_jump_start": -18.42,
"left_hand_ball_vertical_angle_at_ball_in_hands": 3.22,
"left_hand_ball_vertical_angle_at_min_hips": -4.6,
"left_hand_ball_vertical_angle_at_release": -50.07,
"left_hand_ball_vertical_angle_at_shooter_jump_start": 13.57,
"min_left_hand_to_ball_dist_after_release_he_frame": 5584,
"min_left_hand_to_ball_dist_after_release_in": 31.46,
"min_left_hand_to_ball_dist_after_release_wall_clock": "2025-12-23T01:12:07.534+00:00",
"min_right_hand_to_ball_dist_after_release_he_frame": 5587,
"min_right_hand_to_ball_dist_after_release_in": 82.52,
"min_right_hand_to_ball_dist_after_release_wall_clock": "2025-12-23T01:12:07.584+00:00",
"pbp_event_id": 13,
"position_relative_to_shooter_at_ball_in_hands": "front",
"position_relative_to_shooter_at_min_hips": "front",
"position_relative_to_shooter_at_release": "front",
"position_relative_to_shooter_at_shooter_jump_start": "front",
"right_hand_above_head_at_ball_in_hands": false,
"right_hand_above_head_at_min_hips": false,
"right_hand_above_head_at_release": false,
"right_hand_above_head_at_shooter_jump_start": true,
"right_hand_ball_dist_at_ball_in_hands_in": 51.72,
"right_hand_ball_dist_at_min_hips_in": 31.14,
"right_hand_ball_dist_at_release_in": 85.93,
"right_hand_ball_dist_at_shooter_jump_start_in": 58.94,
"right_hand_ball_height_diff_at_ball_in_hands_in": 2.25,
"right_hand_ball_height_diff_at_min_hips_in": -1.18,
"right_hand_ball_height_diff_at_release_in": -52.17,
"right_hand_ball_height_diff_at_shooter_jump_start_in": 9.4,
"right_hand_ball_hoop_angle_at_ball_in_hands": -33.0,
"right_hand_ball_hoop_angle_at_min_hips": -28.51,
"right_hand_ball_hoop_angle_at_release": -25.92,
"right_hand_ball_hoop_angle_at_shooter_jump_start": -7.88,
"right_hand_ball_vertical_angle_at_ball_in_hands": 2.49,
"right_hand_ball_vertical_angle_at_min_hips": -2.16,
"right_hand_ball_vertical_angle_at_release": -37.38,
"right_hand_ball_vertical_angle_at_shooter_jump_start": 9.18,
"shooter_id_nba": 203076,
"shot_id_ctg": "shot_c02d176b015b05088e75b098632da86c"
}
]
}
}Fields
Identifiers
jump_shot_contest_id_ctg
Type: string
CTG-generated unique identifier for this jump shot contest event
game_id_nba
Type: string
NBA game ID
shot_id_ctg
Type: string
CTG-generated shot ID (join with shots and jump_shots)
shooter_id_nba
Type: integer
NBA player ID of the shooter
contester_id_nba
Type: integer
NBA player ID of the defender
pbp_event_id
Type: integer
Play-by-play event ID (i.e. NGSS ID) for this shot
event_pbp_id deprecated
Type: integer
Play-by-play event ID (i.e. NGSS ID) for this shot
Deprecated
Use pbp_event_id instead. This field will be removed in a future version.
Checkpoints
Contest data is captured at four checkpoints during the shooting motion:
| Checkpoint | Description |
|---|---|
release | 3 frames before the ball leaves the shooter's hands |
shooter_jump_start | 1 frame after the shooter's feet leave the floor |
ball_in_hands | When shooter first has both hands on the ball |
min_hips | When shooter's hips are at their lowest point before the shot |
Note on ball_in_hands Checkpoint
Be aware that this checkpoint may be well before the actual shooting motion if the player holds the ball for a while before shooting (e.g., catch, jab a few times, then shoot).
Defender Position
Angle Relative to Shooter
The 2D angle (viewed from overhead) formed by the contester's mid hip, the shooter's mid hip, and the rim. Positive = left of shooter (from behind), negative = right.
angle_relative_to_shooter_at_release
Type: float | Unit: degrees
Defender angle at release
angle_relative_to_shooter_at_shooter_jump_start
Type: float | Unit: degrees
Defender angle at shooter's jump start
angle_relative_to_shooter_at_ball_in_hands
Type: float | Unit: degrees
Defender angle when ball first in hands
angle_relative_to_shooter_at_min_hips
Type: float | Unit: degrees
Defender angle at min hips
Position Relative to Shooter
Uses the angle to categorize the defender's position relative to the shooter-to-rim line (i.e. as viewed from behind the shooter, looking at the basket):
position_relative_to_shooter_at_release
Type: string
front, back, left, or right
position_relative_to_shooter_at_shooter_jump_start
Type: string
Position at jump start
position_relative_to_shooter_at_ball_in_hands
Type: string
Position at ball in hands
position_relative_to_shooter_at_min_hips
Type: string
Position at min hips
Defender Distance from Ball
contester_ball_dist_at_first_both_hands_on_ball_in
Type: float | Unit: inches
2D distance from defender's mid hip to ball when shooter first touches it
Jump Timing
jump_timing
Type: string
When the defender jumped relative to the shooter:
before_shooter_jump: Defender leaves ground before shooterbefore_shot_release: Defender leaves ground after shooter but before releaseafter_shot_release: Defender leaves ground after ball is releasedno_jump: Defender doesn't jump
Hand Position Data
Hand position is measured as the midpoint between thumb and pinky (since we don't currently have joint data for any other parts of the hand). Data is provided for left hand, right hand, and the closest hand to the ball at each checkpoint.
Which Hand is Closest
closest_hand_at_release
Type: string
left or right — which hand was closest to ball at release
Hand-to-Ball Distance
left_hand_ball_dist_at_release_in
Type: float | Unit: inches
Left hand distance to ball at release
right_hand_ball_dist_at_release_in
Type: float | Unit: inches
Right hand distance to ball at release
closest_hand_ball_dist_at_release_in
Type: float | Unit: inches
Closest hand distance to ball at release
left_hand_ball_dist_at_shooter_jump_start_in
Type: float | Unit: inches
Left hand distance at jump start
right_hand_ball_dist_at_shooter_jump_start_in
Type: float | Unit: inches
Right hand distance at jump start
closest_hand_ball_dist_at_shooter_jump_start_in
Type: float | Unit: inches
Closest hand distance at jump start
left_hand_ball_dist_at_ball_in_hands_in
Type: float | Unit: inches
Left hand distance at ball in hands
right_hand_ball_dist_at_ball_in_hands_in
Type: float | Unit: inches
Right hand distance at ball in hands
closest_hand_ball_dist_at_ball_in_hands_in
Type: float | Unit: inches
Closest hand distance at ball in hands
left_hand_ball_dist_at_min_hips_in
Type: float | Unit: inches
Left hand distance at min hips
right_hand_ball_dist_at_min_hips_in
Type: float | Unit: inches
Right hand distance at min hips
closest_hand_ball_dist_at_min_hips_in
Type: float | Unit: inches
Closest hand distance at min hips
Hand Above Head
true if hand is at least 4 inches above the defender's eye on that side.
left_hand_above_head_at_release
Type: boolean
Left hand above head at release
right_hand_above_head_at_release
Type: boolean
Right hand above head at release
closest_hand_above_head_at_release
Type: boolean
Closest hand above head at release
left_hand_above_head_at_shooter_jump_start
Type: boolean
Left hand above head at jump start
right_hand_above_head_at_shooter_jump_start
Type: boolean
Right hand above head at jump start
closest_hand_above_head_at_shooter_jump_start
Type: boolean
Closest hand above head at jump start
left_hand_above_head_at_ball_in_hands
Type: boolean
Left hand above head at ball in hands
right_hand_above_head_at_ball_in_hands
Type: boolean
Right hand above head at ball in hands
closest_hand_above_head_at_ball_in_hands
Type: boolean
Closest hand above head at ball in hands
left_hand_above_head_at_min_hips
Type: boolean
Left hand above head at min hips
right_hand_above_head_at_min_hips
Type: boolean
Right hand above head at min hips
closest_hand_above_head_at_min_hips
Type: boolean
Closest hand above head at min hips
Hand-to-Ball Vertical Angle
The vertical angle from hand to ball. Higher values mean the shooter would need to shoot at a higher angle to get over the defender's hand. Positive = hand above ball center, negative = below.
left_hand_ball_vertical_angle_at_release
Type: float | Unit: degrees
Left hand vertical angle at release
right_hand_ball_vertical_angle_at_release
Type: float | Unit: degrees
Right hand vertical angle at release
closest_hand_ball_vertical_angle_at_release
Type: float | Unit: degrees
Closest hand vertical angle at release
left_hand_ball_vertical_angle_at_shooter_jump_start
Type: float | Unit: degrees
Left hand vertical angle at jump start
right_hand_ball_vertical_angle_at_shooter_jump_start
Type: float | Unit: degrees
Right hand vertical angle at jump start
closest_hand_ball_vertical_angle_at_shooter_jump_start
Type: float | Unit: degrees
Closest hand vertical angle at jump start
left_hand_ball_vertical_angle_at_ball_in_hands
Type: float | Unit: degrees
Left hand vertical angle at ball in hands
right_hand_ball_vertical_angle_at_ball_in_hands
Type: float | Unit: degrees
Right hand vertical angle at ball in hands
closest_hand_ball_vertical_angle_at_ball_in_hands
Type: float | Unit: degrees
Closest hand vertical angle at ball in hands
left_hand_ball_vertical_angle_at_min_hips
Type: float | Unit: degrees
Left hand vertical angle at min hips
right_hand_ball_vertical_angle_at_min_hips
Type: float | Unit: degrees
Right hand vertical angle at min hips
closest_hand_ball_vertical_angle_at_min_hips
Type: float | Unit: degrees
Closest hand vertical angle at min hips
Hand-to-Ball Height Difference
Height difference between hand and ball center. Positive = hand higher than ball.
left_hand_ball_height_diff_at_release_in
Type: float | Unit: inches
Left hand height diff at release
right_hand_ball_height_diff_at_release_in
Type: float | Unit: inches
Right hand height diff at release
closest_hand_ball_height_diff_at_release_in
Type: float | Unit: inches
Closest hand height diff at release
left_hand_ball_height_diff_at_shooter_jump_start_in
Type: float | Unit: inches
Left hand height diff at jump start
right_hand_ball_height_diff_at_shooter_jump_start_in
Type: float | Unit: inches
Right hand height diff at jump start
closest_hand_ball_height_diff_at_shooter_jump_start_in
Type: float | Unit: inches
Closest hand height diff at jump start
left_hand_ball_height_diff_at_ball_in_hands_in
Type: float | Unit: inches
Left hand height diff at ball in hands
right_hand_ball_height_diff_at_ball_in_hands_in
Type: float | Unit: inches
Right hand height diff at ball in hands
closest_hand_ball_height_diff_at_ball_in_hands_in
Type: float | Unit: inches
Closest hand height diff at ball in hands
left_hand_ball_height_diff_at_min_hips_in
Type: float | Unit: inches
Left hand height diff at min hips
right_hand_ball_height_diff_at_min_hips_in
Type: float | Unit: inches
Right hand height diff at min hips
closest_hand_ball_height_diff_at_min_hips_in
Type: float | Unit: inches
Closest hand height diff at min hips
Hand-to-Ball Horizontal Angle (relative to hoop)
The 2D angle (as if looking from overhead) formed by the hand, the ball, and the rim. Positive = left of shooter, negative = right. 180° = directly behind ball.
left_hand_ball_hoop_angle_at_release
Type: float | Unit: degrees
Left hand horizontal angle at release
right_hand_ball_hoop_angle_at_release
Type: float | Unit: degrees
Right hand horizontal angle at release
closest_hand_ball_hoop_angle_at_release
Type: float | Unit: degrees
Closest hand horizontal angle at release
left_hand_ball_hoop_angle_at_shooter_jump_start
Type: float | Unit: degrees
Left hand horizontal angle at jump start
right_hand_ball_hoop_angle_at_shooter_jump_start
Type: float | Unit: degrees
Right hand horizontal angle at jump start
closest_hand_ball_hoop_angle_at_shooter_jump_start
Type: float | Unit: degrees
Closest hand horizontal angle at jump start
left_hand_ball_hoop_angle_at_ball_in_hands
Type: float | Unit: degrees
Left hand horizontal angle at ball in hands
right_hand_ball_hoop_angle_at_ball_in_hands
Type: float | Unit: degrees
Right hand horizontal angle at ball in hands
closest_hand_ball_hoop_angle_at_ball_in_hands
Type: float | Unit: degrees
Closest hand horizontal angle at ball in hands
left_hand_ball_hoop_angle_at_min_hips
Type: float | Unit: degrees
Left hand horizontal angle at min hips
right_hand_ball_hoop_angle_at_min_hips
Type: float | Unit: degrees
Right hand horizontal angle at min hips
closest_hand_ball_hoop_angle_at_min_hips
Type: float | Unit: degrees
Closest hand horizontal angle at min hips
Hand to Ball Distance After Release
This can help identify contests where the hand gets very close to blocking the ball but it's after the ball is already out of the shooter's hand.
min_right_hand_to_ball_dist_after_release_he_frame
Type: integer
Frame when right hand was closest to ball after release
min_right_hand_to_ball_dist_after_release_wall_clock
Type: string
UTC timestamp corresponding to min_right_hand_to_ball_dist_after_release_he_frame.
min_left_hand_to_ball_dist_after_release_he_frame
Type: integer
Frame when left hand was closest to ball after release
min_left_hand_to_ball_dist_after_release_wall_clock
Type: string
UTC timestamp corresponding to min_left_hand_to_ball_dist_after_release_he_frame.
min_right_hand_to_ball_dist_after_release_in
Type: float
Minimum distance (inches) from right hand to ball after release
min_left_hand_to_ball_dist_after_release_in
Type: float
Minimum distance (inches) from left hand to ball after release
