Skip to content

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:

CheckpointDescription
release3 frames before the ball leaves the shooter's hands
shooter_jump_start1 frame after the shooter's feet leave the floor
ball_in_handsWhen shooter first has both hands on the ball
min_hipsWhen 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 shooter
  • before_shot_release: Defender leaves ground after shooter but before release
  • after_shot_release: Defender leaves ground after ball is released
  • no_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