===== BEGIN PAGE: Home ===== --- layout: home hero: name: "CTG Pro Data Feed" text: "Documentation" actions: - theme: brand text: Getting the Data link: /getting-the-data/ - theme: alt text: View Data Sets link: /data-sets/ ===== END PAGE: Home ===== ===== BEGIN PAGE: Getting the Data ===== # Getting the Data --- title: Getting the Data --- # Getting the Data ## API Host & Endpoints API requests should be made to: ``` https://api.cleaningtheglass.com/pro/ ``` The API provides two endpoints: | Endpoint | Description | |----------|-------------| | `GET /game_status` | Check the processing status of games | | `GET /markings` | Retrieve the markings data for a specific game | ## Authentication API requests require authentication via an API key which we will provide to you. Include your key in the `X-API-KEY` header of every request: ```bash curl --request GET \ --url 'https://api.cleaningtheglass.com/pro/game_status' \ --header 'X-API-KEY: YOUR_API_KEY' ``` ### Authentication Errors | Scenario | Response | HTTP Status | |----------|----------|-------------| | Missing API key | `"Authorization Required. Please include your API key in the X-API-KEY header."` | `403` | | Invalid API key | `"Authorization Error: invalid API key."` | `403` | | Insufficient permissions | `"Authorization Error: API key does not have access to processed data."` | `403` | ## Game Status Endpoint ``` GET /game_status ``` Retrieve the processing status of games in the CTG system. Use this to discover which games have data available and their current processing state. ::: tip NOTE This only includes games that have been processed already or games that are currently being processed. Games that will happen in the future are not available at this endpoint. ::: ### Parameters | Parameter | Required | Type | Description | |-----------|----------|------|-------------| | `nba_game_id` | No | string | Filter to a specific game (e.g., `0022500241`) | | `stream_type` | No | string | `delayed` (i.e. live) or `processed`. Default: `delayed` | | `only_in_progress` | No | boolean | If `true`, only return games currently being processed | ### Example Request ::: code-group ```bash [cURL] curl --request GET \ --url 'https://api.cleaningtheglass.com/pro/game_status?stream_type=processed' \ --header 'X-API-KEY: YOUR_API_KEY' ``` ```python [Python] import requests response = requests.get( "https://api.cleaningtheglass.com/pro/game_status", headers={"X-API-KEY": "YOUR_API_KEY"}, params={"stream_type": "processed"} ) games = response.json()["games"] ``` ```javascript [JavaScript] const response = await fetch( "https://api.cleaningtheglass.com/pro/game_status?stream_type=processed", { headers: { "X-API-KEY": "YOUR_API_KEY" } } ); const { games } = await response.json(); ``` ::: ### Example Response ```json { "games": [ { "nba_game_id": "0022500241", "game_status": "completed", "tracking_stream": "processed.pose.clean", "ctg_last_updated": "2025-11-15T04:23:15.123456+00:00" }, { "nba_game_id": "0022500242", "game_status": "in_progress", "tracking_stream": "delayed.pose.clean", "ctg_last_updated": "2025-11-15T20:48:01.326940+00:00" } ] } ``` ### Response Fields #### `nba_game_id` **Type:** `string` The NBA game ID (e.g., `"0022500241"`). #### `game_status` **Type:** `string` The CTG processing status of this game: | Status | Description | |--------|-------------| | `in_progress` | Game is currently being live-processed by CTG | | `partial` | Game was processed, but some data is missing | | `completed` | The complete game was processed | #### `tracking_stream` **Type:** `string` The tracking stream used when generating the CTG markings: | Value | Description | |-------|-------------| | `delayed.pose.clean` | Live/in-progress data stream | | `processed.pose.clean` | Postgame processed data stream | #### `ctg_last_updated` **Type:** `string` (ISO 8601 timestamp) The last time this game's data was updated by CTG (e.g., `"2025-11-15T04:23:15.123456+00:00"`). ## Markings Endpoint ``` GET /markings ``` Retrieve the markings data for a specific game. ### Parameters | Parameter | Required | Type | Description | |-----------|----------|------|-------------| | `nba_game_id` | **Yes** | string | The NBA game ID (e.g., `0022500241`) | | `stream_type` | No | string | `delayed` or `processed`. Default: `delayed` | | `marking_types` | No | string | Comma-separated list of marking types to return. If not specified, all available types are returned. A list of available marking types is provided below. | ::: tip We include the `marking_types` parameter as an option so that you can fetch a specific marking type that you are interested in without having to download the entire set of markings for a given game, since the size of this data can be quite large. ::: ### Example — Filtered Markings ::: code-group ```bash [cURL] curl --request GET \ --url 'https://api.cleaningtheglass.com/pro/markings?nba_game_id=0022500241&stream_type=processed&marking_types=shots,jump_shots,passes' \ --header 'Accept-Encoding: gzip,deflate' \ --header 'X-API-KEY: YOUR_API_KEY' ``` ```python [Python] import requests response = requests.get( "https://api.cleaningtheglass.com/pro/markings", headers={"X-API-KEY": "YOUR_API_KEY"}, params={ "nba_game_id": "0022500241", "stream_type": "processed", "marking_types": "shots,jump_shots,passes" } ) markings = response.json()["markings"] ``` ```javascript [JavaScript] const params = new URLSearchParams({ nba_game_id: "0022500241", stream_type: "processed", marking_types: "shots,jump_shots,passes" }); const response = await fetch( `https://api.cleaningtheglass.com/pro/markings?${params}`, { headers: { "X-API-KEY": "YOUR_API_KEY" } } ); const { markings } = await response.json(); ``` ::: ::: tip NOTE In the example above, we include the `Accept-Encoding: gzip,deflate` header on the request to reduce the response size significantly. We strongly recommend that as a best practice since the volume of this data can get to be quite large! ::: ### Stream Types | Value | Internal Stream | Description | |-------|-----------------|-------------| | `delayed` | `delayed.pose.clean` | Live/in-progress game data | | `processed` | `processed.pose.clean` | Postgame processed data | ### Request Errors | Scenario | Response | HTTP Status | |----------|----------|-------------| | Missing `nba_game_id` | `"nba_game_id is required"` | `400` | | Invalid `stream_type` | `"Invalid stream_type 'invalid'. Valid options: delayed, processed"` | `400` | | Invalid `marking_types` | `"Invalid marking types for delayed stream: closeouts, drives..."` | `400` | | Game not found | `"No markings found for nba_game_id='0022500999'..."` | `404` | ### Response Structure The `/markings` endpoint returns a JSON object with metadata and a `markings` object containing arrays for each marking type: ```json { "nba_game_id": "0022500241", "stream_type": "processed", "markings": { "shots": [...], "jump_shots": [...], "interior_shots": [...], "jump_shot_contests": [...], "interior_shot_contests": [...], "free_throws": [...], "passes": [...], "dribbles": [...], "jumps": [...], "rebounds": [...], "deflections": [...], "closeouts": [...], "drives": [...], "falls": [...], "fouls": [...], "turnovers": [...], "chances": [...], "possessions": [...], "possession_touches": [...], "contested_rebound_touches": [...], "anthro_measurements": [...] } } ``` ::: warning We often update the data by adding new fields or new markings. We do not want to break your ingestion pipelines when we deploy new data, so please design your ingestion system to be resilient to the addition of new fields. We will not remove or change fields without significant advanced notice. ::: ### Marking Types by Stream All marking types you see here and in the [Data Sets](/data-sets/) section are available in the postgame (processed) data. Live (delayed) data contains only a subset of these marking types (temporarily). - `shots` - `jump_shots` - `interior_shots` - `free_throws` - `jump_shot_contests` - `interior_shot_contests` - `passes` - `dribbles` - `jumps` - `falls` - `deflections` - `rebounds` - `contested_rebound_touches` - `chances` - `possessions` - `turnovers` - `fouls` - `anthro_measurements` - `closeouts` - `drives` - `possession_touches` Only the following marking types are currently available in the live (delayed) stream: - `anthro_measurements` - `chances` - `contested_rebound_touches` - `deflections` - `dribbles` - `falls` - `fouls` - `free_throws` - `interior_shot_contests` - `interior_shots` - `jump_shot_contests` - `jump_shots` - `jumps` - `passes` - `possessions` - `rebounds` - `shots` - `turnovers` Full descriptions and field definitions for each of these marking types are available in the [Data Sets](/data-sets/) section. ## Quick Start Here's a minimal example to retrieve markings for a game: ::: code-group ```bash [cURL] curl --request GET \ --url 'https://api.cleaningtheglass.com/pro/markings?nba_game_id=0022500241&stream_type=processed' \ --header 'Accept-Encoding: gzip,deflate' \ --header 'X-API-KEY: YOUR_API_KEY' ``` ```python [Python] import requests response = requests.get( "https://api.cleaningtheglass.com/pro/markings", headers={"X-API-KEY": "YOUR_API_KEY"}, params={ "nba_game_id": "0022500241", "stream_type": "processed" } ) data = response.json() # Access different marking types shots = data["markings"]["shots"] jump_shots = data["markings"]["jump_shots"] passes = data["markings"]["passes"] ``` ```javascript [JavaScript] const response = await fetch( "https://api.cleaningtheglass.com/pro/markings?nba_game_id=0022500241&stream_type=processed", { headers: { "X-API-KEY": "YOUR_API_KEY" } } ); const data = await response.json(); // Access different marking types const shots = data.markings.shots; const jumpShots = data.markings.jump_shots; const passes = data.markings.passes; ``` ::: ### Verifying It Worked A successful response will return a JSON object containing the game metadata and a `markings` object with arrays for each marking type: ```json { "nba_game_id": "0022500241", "stream_type": "processed", "markings": { "shots": [...], "jump_shots": [...], "passes": [...], ... } } ``` If you see this structure, you're all set! Each array contains individual events from the game. ### Next Steps - **Explore the data**: Check out the [Data Sets](/data-sets/) section for detailed field definitions - **Understand key concepts**: Read [Key Concepts](/concepts/) to learn about coordinate systems, timestamps, and entity IDs - **Filter your requests**: Use the `marking_types` parameter to fetch only the data you need ## LLM & Tooling Support For teams using LLMs, we expose a few machine-readable helper files alongside this documentation: - **[`/fields.json`](/fields.json)**: A machine-readable catalog of data-set fields (by marking type), including type, units, and descriptions. This is the recommended starting point for code generation or schema validation. - **[`/llms.txt`](/llms.txt)**: A short, high-level guide that explains the CTG Pro Markings API, key endpoints, and where the rest of the docs live. - **[`/llms-full.txt`](/llms-full.txt)**: A single large text file that concatenates the main documentation pages and appends the full field catalog. Useful if your tooling prefers ingesting one big document. These files are regenerated automatically from these docs so they should always stay in sync with the documentation. ===== END PAGE: Getting the Data ===== ===== BEGIN PAGE: Concepts ===== # Concepts # Concepts ## Season Coverage The CTG Pro Data Feed is based on the data in the "Hawk-Eye era", i.e. from the 2023-24 season and onward when pose data for all players first became available. We sometimes call this the "3D data" because it involves being able to analyze player movement in three dimensions, which was not previously possible in prior eras of tracking data. Equivalent markings for the "2D era" (2013-14 through 2022-23) do not yet exist in the CTG Pro Data Feed. During the alpha testing, only data from the 2025-26 season will be backfilled and updated with changes. When we move onto beta testing, the data will be backfilled for the entire 3D era. ## Feed Types The CTG Pro Data Feed provides two feed types: live and postgame. The live data is built off of Hawk-Eye's **delayed** data stream, and the postgame data is built off of their **processed** stream. The delayed stream is available in-game with minimal delays, but is less accurate than the processed stream. ### Checking Stream Availability You can use the `/game_status` endpoint to check which games have data available for a given feed, as detailed in the [Game Status Endpoint](../getting-the-data/#game-status-endpoint) section. ## Entity IDs The CTG Pro Data Feed uses official NBA identifiers for games, players, and teams. - Every game has a unique 10-digit NBA game ID that identifies the specific matchup, e.g. `0042400101` or `0022500241` - Each player has a unique integer identifier assigned by the NBA, e.g. `201939` or `1641705` - Each teams is identified by an integer IDs assigned by the NBA, e.g. `1610612747` ## CTG Internal IDs CTG generates unique identifiers for most markings. This ID is designed to be easy to read and work with so that you can know at a glance what marking type it refers to, for example: | Field Name | Format | Example | |---------------|--------|-------------| | `shot_id_ctg` | `shot_` | `shot_53c414a581512a05b591899e94225dea` | | `pass_id_ctg` | `pass_` | `pass_9afbfea254c6d47a1f0f74e53ba3fab3` | | `chance_id_ctg` | `chance_` | `chance_878aba9051e5f93a16c5b27c495e1c3d` | ::: warning These IDs are designed to be stable across changes in the data *only if the underlying defining characterstics of the data do not change*. That is, the shot ID is keyed to some identifying characteristics like the shooter and estimated release frame. If the release frame changes in the underlying data, the ID of the given shot will change. **You should not rely on these IDs to be stable across time, then.** We do have an attempted solution to try to produce stable IDs which we may expose at some point, but until then you will need to engineer systems that assume these IDs could change across backfills. ::: ## Coordinate Systems The CTG Pro Data Feed uses Hawk-Eye's coordinate system for all fields that reference specific x and y coordinates, in their unit of choice (inches). Most fields will also reference the units in the field or field definition (e.g. inches vs. feet), but if not specified you can assume the defaults are inches for distance and degrees for angle measurements. ### Court Layout Here is the diagram of the coordinate system as taken from Hawk-Eye's documentation:
Hawk-Eye NBA Court Coordinate System
As you can see, the origin (0, 0, 0) is the center of the jump circle in the middle of the court right on the floor. ### Attacking Direction Where necessary, our data includes an `attacking_positive_x` flag (similar to what Hawk-Eye does) to indicate which basket the offensive team is attacking: | Value | Meaning | |-------|---------| | `true` | Offense is attacking the basket at X = +41.75 feet (right side of court when looking from broadcast angle) | | `false` | Offense is attacking the basket at X = -41.75 feet (left side of court when looking from broadcast angle) | ::: tip NOTE We do not take the `attacking_positive_x` flag directly from Hawk-Eye's data, as we have found it is not always reliable. We calculate it ourselves, and thus there may be differences if compared directly to Hawk-Eye's version. ::: ### Court Regions Sometimes our data includes a court region for easy grouping into standard regions: | Region | Description | |--------|-------------| | `ra` | Restricted Area (near the rim) | | `key` | The paint/key area | | `left corner two` / `right corner two` | Corner 2-point zones | | `left corner three` / `right corner three` | Corner 3-point zones | | `left wing two` / `right wing two` | Wing 2-point zones | | `left wing three` / `right wing three` | Wing 3-point zones | | `middle two` / `middle three` | Top of key zones | | `left dunker` / `right dunker` | Dunker spots (offensive) | | `far` | Beyond the 3-point arc on offensive half | | `backcourt` | Defensive half of the court | Here is a diagram showing our definitions of the various zones (coordinates in the diagram are in feet):
Court Region Diagram
## Frames & Timestamps The CTG Pro Data Feed uses both the Hawk-Eye frame numbers and the wall clock timestamps to precisely identify moments during a game that apply to the markings. ### Hawk-Eye Frame Numbers Hawk-Eye frame numbers reference the frame number assigned by Hawk-Eye for the given feed type. Their tracking data is currently delivered at 60 frames per second (FPS). Fields ending in `_he_frame` contain Hawk-Eye frame numbers, for example: | Field | Description | |-------|-------------| | `first_ball_in_hands_he_frame` | When player first touches ball | | `last_ball_in_hands_he_frame` | When ball is released | | `last_either_foot_on_floor_he_frame` | Last frame where either foot is on the floor (right before becoming airborne) | ### Wall Clock Timestamps Recognizing that not everything can be tied to the Hawk-Eye data, and that many teams have not ingested frame level Hawk-Eye data, we also deliver the wall clock timestamp of the frame anywhere there is a frame number. They appear in fields that are named `*_wall_clock`. This allows you to tie marking data to specific points in time for other uses apart from matching to Hawk-Eye frame data. Wall clocks are delivered in UTC using ISO 8601 format, for example: ``` 2025-11-18T02:20:39.402+00:00 ``` ===== END PAGE: Concepts ===== ===== BEGIN PAGE: Data Sets Overview ===== # Data Sets Overview # Data Sets Overview The CTG Pro Data Feed includes data organized into several marking types. The API bundles these all within the `markings` object. The marking types that appear in the response are based on the API parameters you used. Within each of these markings objects is a list of objects, one for each instance of the given marking. For example, within the `shots` object would be a list of objects, one for each shot taken in the game, with the data fields we have included to help describe what is going on in that instance. ```json { "markings": { "shots": [ { "blocker_player_id_nba": null, "chance_id_ctg": "chance_51bfc1fda2cc0deb125bee9988859667", "end_game_clock": 708, "end_he_frame": 761, ... }, { "blocker_player_id_nba": null, "chance_id_ctg": "chance_4c33ded97f95174cc013b446c3981347", "end_game_clock": 688, "end_he_frame": 1971, ... } ], "jump_shots": [...], "interior_shots": [...], "chances": [...], "possessions": [...], ... } } ``` There is a section in these docs for each marking type available with detailed explanations of what that marking represents as well as all of the fields included with it. ===== END PAGE: Data Sets Overview ===== ===== BEGIN PAGE: Data Set: anthro ===== # Anthro Measurements # Anthro Measurements The `anthro_measurements` section in the markings response contains estimated body measurements for players, sampled from game tracking data. There is an object for each player who appeared in each game. ## Overview Player measurements are estimated by randomly sampling frames during the game and averaging the distances between joints. ::: warning NOTE The data itself is reasonably inexact and is missing some key data points for matching up to normal measurements. That is, we estimate height here, but the highest point on a player’s head that we have joint data for is the eyes, so we have to estimate the distance between the eyes and the top of the head. Similarly, we estimate wingspan, but we don’t know where the tips of the middle fingers are, so we have to guess at the extra distance to add. We have noticed average errors of around 1-2 inches from listed heights and wingspans given these issues. ::: ## Sample Response ```json { "markings": { "anthro_measurements": [ { "frames_sampled_for_measurement": 369, "game_id_nba": "0022500404", "height_inches": 78.7, "left_arm_length_inches": 35.9, "left_leg_length_inches": 40.7, "mid_hip_to_neck_length_inches": 24.8, "nba_game_id": "0022500404", "nba_player_id": 202691, "player_id_nba": 202691, "right_arm_length_inches": 35.8, "right_leg_length_inches": 40.4, "wingspan_inches": 86.4 } ] } } ``` ## Fields ### Identifiers #### `game_id_nba` **Type:** `string` NBA game ID --- #### `nba_game_id` **Type:** `string` NBA game ID ::: warning Deprecated Use `game_id_nba` instead. This field will be removed in a future version. ::: --- #### `player_id_nba` **Type:** `integer` NBA player ID --- #### `nba_player_id` **Type:** `integer` NBA player ID ::: warning Deprecated Use `player_id_nba` instead. This field will be removed in a future version. ::: --- #### `frames_sampled_for_measurement` **Type:** `integer` Number of frames sampled to calculate these measurements --- ### Body Measurements #### `height_inches` **Type:** `float` | **Unit:** `inches` Estimated player height --- #### `wingspan_inches` **Type:** `float` | **Unit:** `inches` Estimated wingspan (estimated middle finger tip to opposite estimated middle finger tip) --- #### `right_arm_length_inches` **Type:** `float` | **Unit:** `inches` Right arm length (shoulder to estimated middle finger tip) --- #### `left_arm_length_inches` **Type:** `float` | **Unit:** `inches` Left arm length (shoulder to estimated middle finger tip) --- #### `right_leg_length_inches` **Type:** `float` | **Unit:** `inches` Right leg length (hip to heel) --- #### `left_leg_length_inches` **Type:** `float` | **Unit:** `inches` Left leg length (hip to heel) --- #### `mid_hip_to_neck_length_inches` **Type:** `float` | **Unit:** `inches` Torso length (mid hip joint to neck joint) ===== END PAGE: Data Set: anthro ===== ===== BEGIN PAGE: Data Set: chances ===== # Chances # Chances The `chances` section in the markings response contains an object for each "chance". A chance is a segment of the game where the offense has the opportunity to score. ## Overview Defining a chance is a little tricky. We can explain it by first explaining possessions. We define a possession as starting when a team gets the ball and ending when they lose the ball (or the period ends). So one team starts with the ball, and then if they score, turn it over, miss a shot and don’t get an offensive rebound, or make free throws, the other team gets the ball, and that possession ends. If a team misses a shot but gets the offensive rebound, it doesn’t create a new possession, it just continues the prior possession. We can split a possession into smaller segments that basically chop it up based on these continuous stretches of play with no stoppage, or a “chance” to score. So let’s say a team gets the ball, then draws a non-shooting foul. The game has stopped. The beginning of the possession until that whistle is one chance. The next chance would start when the ball is given to the inbounder to inbound. It’s a continuation of the prior possession but a new “chance”. Similarly, if a team misses a jump shot but gets an offensive rebound, that would start a new chance but not a new possession. So the prior chance would end with the offensive rebound and a new chance would start with an offensive rebound. ::: tip NOTE A chance, by definition, should not contain more than one chance ending event, i.e. it cannot have both a field goal attempt and a turnover in the same chance. In a situation where the shot clock expires as the ball is in the air and the ball never hits the rim, for example, the shot is in one chance, then a new chance is created for the shot clock violation right after. ::: An important feature of chances is that a substitution cannot occur during the chance, since it is a stretch of continuous gameplay, which means the set of players on the court must stay the same throughout the chance. For more in-depth details on exactly how we start and stop chances, see the section below on [Chance Start and End Timing](#chance-start-and-end-timing). ## Sample Response ```json { "markings": { "chances": [ { "chance_id_ctg": "chance_51bfc1fda2cc0deb125bee9988859667", "chance_outcome": "fg2m", "chance_start_type": "jump_ball", "defense_players": [ 1630180, 1630529, 1630530, 1642847, 1642852 ], "defensive_team_id_nba": 1610612740, "end_game_clock": 708.0, "end_he_frame": 806, "end_shot_clock": 13.0, "end_wall_clock": "2025-12-23T01:10:47.889+00:00", "fg_dreb": 0, "fg_oreb": 0, "fga": 1, "fga_pts": 2, "fgm": 1, "frontcourt_he_frame": 414, "frontcourt_wall_clock": "2025-12-23T01:10:41.356+00:00", "fta": 0, "ftm": 0, "game_id_nba": "0022500404", "in_garbage_time": false, "is_after_timeout": true, "is_shooter_fouled": false, "is_shot_blocked": false, "is_shot_made": true, "led_to_offensive_rebound": null, "offense_players": [ 1629023, 1642843, 1642948, 203076, 1630230 ], "offensive_team_id_nba": 1610612742, "period": 1, "possession_id_ctg": "possession_640fb5737252cbe98b4f4a70dcee9d8f", "shot_location": "rim", "start_game_clock": 720.0, "start_he_frame": 118, "start_score_away": 0, "start_score_home": 0, "start_shot_clock": 24.0, "start_wall_clock": "2025-12-23T01:10:36.423+00:00", "tov": 0 } ] } } ``` ## Fields ### Identifiers #### `game_id_nba` **Type:** `string` NBA game ID --- #### `chance_id_ctg` **Type:** `string` CTG-generated unique chance ID --- #### `possession_id_ctg` **Type:** `string` CTG-generated possession ID that this chance belongs to --- #### `offensive_team_id_nba` **Type:** `integer` NBA team ID of the team on offense --- #### `defensive_team_id_nba` **Type:** `integer` NBA team ID of the team on defense --- ### Lineups #### `offense_players` **Type:** `array[integer]` Array of NBA player IDs for the five players on the court on offense during this chance. --- #### `defense_players` **Type:** `array[integer]` Array of NBA player IDs for the five players on the court on defense during this chance. --- ### Context #### `chance_start_type` **Type:** `string` How the chance began, taken from one of the following options. - **`jump_ball`**: Tip-off or jump ball situation - **`fgm`**: Chance begins immediately after a made field goal (inbound after made basket) - **`ftm`**: Chance begins immediately after a made free throw sequence (inbound after made free throw) - **`steal`**: Gained possession via a live-ball turnover - **`fg_dreb`**: Defensive rebound after a missed field goal - **`fg_dreb_block`**: Defensive rebound after a blocked shot - **`fg_oreb`**: Offensive rebound after a missed field goal - **`ft_dreb`**: Defensive rebound after a missed free throw - **`ft_oreb`**: Offensive rebound after a missed free throw - **`baseline_inbounds`**: Chance begins on a dead-ball inbound from the frontcourt baseline - **`sideline_inbounds`**: Chance begins on a dead-ball inbound from the frontcourt sideline - **`backcourt_inbounds`**: Chance begins on a dead-ball inbound in the backcourt (sideline or baseline) --- #### `chance_outcome` **Type:** `string` The outcome of the chance, taken from one of the following options. Shot results: - **`fg2m`**: Made 2-point field goal - **`fg2x`**: Missed 2-point field goal - **`fg3m`**: Made 3-point field goal - **`fg3x`**: Missed 3-point field goal - **`heave`**: A shot designated as an official heave by the scorer - **`fg2m_fouled`**: Made 2-point field goal where the shooter was fouled (and-one) - **`fg3m_fouled`**: Made 3-point field goal where the shooter was fouled (and-one) Turnovers: - **`steal`**: Live-ball turnover - **`deadball_turnover`**: Turnover that stops the clock and requires an inbounds (e.g. traveling, offensive foul, etc.) Fouls: - **`shooting_foul`**: Shooting foul on an attempt (not an and-one make) - **`non-shooting_foul`**: Personal foul not associated with a shot, and not resulting in free throws - **`non-shooting_foul_bonus`**: Non-shooting foul that results in free throws due to the bonus - **`transition_take_foul`**: Transition take foul - **`away_from_the_play_foul`**: Away-from-the-play foul - **`clear_path_foul`**: Clear path foul - **`flagrant_foul`**: Flagrant foul (type 1 or type 2) - **`offensive_foul`**: Offensive foul - **`technical_foul`**: Technical foul - **`technical_defensive_three_second_foul`**: Defensive 3-second technical foul Other endings / stoppages: - **`violation`**: Clock stops due to a violation - **`timeout`**: Chance ends due to a timeout - **`out_of_bounds_retain`**: Ball goes out of bounds and the offense retains possession - **`jump_ball`**: Chance ends in a jump ball situation - **`end_period`**: Period ended - **`other_stoppage`**: Any other stoppage types not covered above --- #### `is_after_timeout` **Type:** `boolean` `true` if this chance immediately follows a timeout --- ### Score #### `start_score_home` **Type:** `integer` Score of the home team at the start of the chance --- #### `start_score_away` **Type:** `integer` Score of the away team at the start of the chance --- ### Timing #### `period` **Type:** `integer` Period in which the chance occurred. Overtime would be period 5, double overtime period 6, etc. --- #### `start_he_frame` **Type:** `integer` Hawk-Eye frame when chance began --- #### `start_wall_clock` **Type:** `string` UTC timestamp when chance began --- #### `start_game_clock` **Type:** `float` Game clock (seconds remaining) when chance began --- #### `start_shot_clock` **Type:** `float` Shot clock when chance began. `null` if shot clock is off at the end of the quarter. --- #### `end_he_frame` **Type:** `integer` Hawk-Eye frame when chance ended --- #### `end_wall_clock` **Type:** `string` UTC timestamp when chance ended --- #### `end_game_clock` **Type:** `float` Game clock when chance ended --- #### `end_shot_clock` **Type:** `float` Shot clock when chance ended. `null` if shot clock is off at the end of the quarter. --- #### `frontcourt_he_frame` **Type:** `integer` Hawk-Eye frame when ball first crossed halfcourt into the frontcourt. `null` if the ball never crosses halfcourt during the chance. ::: tip NOTE This does not require a player to be in possession of the ball, it just the first time the x-coordinate of the ball crosses sides of the court in this chance, even if it's in mid-air. ::: --- #### `frontcourt_wall_clock` **Type:** `string` UTC timestamp corresponding to `frontcourt_he_frame`. `null` if the ball never crosses halfcourt. --- #### `in_garbage_time` **Type:** `boolean` `true` if this chance occurred during "garbage time". We use a definition of garbage time that is as objective as possible and generally matches up with most people's perception of when garbage time starts: when the game is out of hand, both teams have subbed out most of their starters, and the game never gets close again. :::info The Specific Definition The exact definition CTG uses is: the game has to be in the 4th quarter, the score differential has to be >= 25 for minutes 12-9, >= 20 for minutes 9-6, and >= 10 for the remainder of the quarter. Additionally, there have to be two or fewer starters on the floor combined between the two teams. Importantly, the game can never go back to being non-garbage time, or this clock resets. For example, if it's a 30 point game to start the 4th quarter, but one team comes back and pulls the game within 8, that comeback is not counted as garbage time. If the leading team regains control and expands the lead back out, garbage time would start when the score went back above 10. This might not capture all of what we'd call garbage time, but it seems important to err on the side of caution and not mistakenly filter out any game time that we would not consider garbage time. ::: --- ### Chance Outcomes These fields describe the outcome of the chance. --- #### `is_shot_made` **Type:** `boolean` `true` if the shot was made, `false` if it was missed. `null` if no shot was taken. --- #### `is_shot_blocked` **Type:** `boolean` `true` if the shot was blocked. `null` if no shot was taken. --- #### `is_shooter_fouled` **Type:** `boolean` `true` if the shooter was fouled during the shot attempt. `null` if no shot was taken. --- #### `led_to_offensive_rebound` **Type:** `boolean` `true` if a missed shot was rebounded by the offensive team. `null` if no shot was taken or if the shot was made. --- #### `fga_pts` **Type:** `integer` Points scored on the field goal attempt (2 or 3 for made shots, 0 for misses). `null` if no shot was taken or if the chance has not yet been processed into the application layer. --- #### `fgm` **Type:** `integer` Field goals made. `1` if the shot was made, `0` otherwise. `null` if no shot was taken or if the chance has not yet been processed into the application layer. --- #### `fga` **Type:** `integer` Field goal attempts. `1` if a shot was attempted (not including shooting fouls without a shot), `0` otherwise. `null` if no shot was taken or if the chance has not yet been processed into the application layer. --- #### `ftm` **Type:** `integer` Free throws made during this chance. `null` if the chance has not yet been processed into the application layer. --- #### `fta` **Type:** `integer` Free throw attempts during this chance. `null` if the chance has not yet been processed into the application layer. --- #### `tov` **Type:** `integer` Turnovers. `1` if the chance ended in a turnover, `0` otherwise. `null` if the chance has not yet been processed into the application layer. --- #### `fg_dreb` **Type:** `integer` Defensive rebounds on field goal attempts. `1` if the defense rebounded a missed field goal, `0` otherwise. `null` if the chance has not yet been processed into the application layer. --- #### `fg_oreb` **Type:** `integer` Offensive rebounds on field goal attempts. `1` if the offense rebounded a missed field goal, `0` otherwise. `null` if the chance has not yet been processed into the application layer. --- ### Shot Location #### `shot_location` **Type:** `string` The court zone where the shot was taken, one of the following values: - **`rim`**: At-rim shots (typically within ~4 feet of the basket) - **`short mid`**: Short mid-range shots (~4-14 feet from the basket) - **`long mid`**: Long mid-range shots (~14+ feet, inside the three-point line) - **`corner three`**: Three-point shots from the corner - **`non corner three`**: Three-point shots from above the break - **`heave`**: Full-court or half-court heave attempts `null` if no shot was taken. --- ## Chance Start and End Timing There are many decisions to make around when specifically to start and end a chance. The CTG Pro Data Feed utilizes the 3D data where possible to attempt precise placements of these start and end frames. Here is how chance boundaries are determined: - **Jump balls**: The chance starts the first time a player touches the ball with the game clock running after the jump ball. - **Inbounds plays**: The chance starts when the ball is in the hands of the inbounder and they have at least one foot out of bounds. - **Fouls**: The chance ends when the clock stops. If there are no free throws, the next chance starts following the inbounds timing described above. - For an and-one, the chance ends when the clock stops, not when the shot goes in. - **Made shots**: The chance ends when the top of the ball first drops below rim height, representing the moment the ball goes through the rim. The next chance starts when the inbounder has the ball out of bounds and is ready to inbound. - **Missed shots**: - If a player rebounds the ball, the chance ends when the ball is first touched by a potential rebounder. The next chance starts at the same frame. - If the ball goes out of bounds (even if touched first), the chance ends when the ball goes out of bounds and the clock stops. The next chance starts following the inbounds timing above. - If a loose ball foul occurs before the rebound is secured, the chance ends when the clock stops. The next chance starts at the same frame and ends one frame later, effectively creating a chance that only includes the foul. (We do this because in theory, a loose ball foul on a rebound like this is a scoring opportunity if the fouled team happened to be in the bonus.) The chance after that starts following the inbound rules above, or free throw rules noted below. - Blocked shots are treated like shots hitting the rim, with the same timing logic applying afterward. - **Fouls resulting in free throws**: The chance ends at the clock stopping as a result of the foul. The subsequent chance starts following the same rules as for field goal attempts: if the final free throw is made, the next chance starts when the inbounder has the ball with one foot out, and if the final free throw is missed the next chance starts following the rebound rules. - **Live ball turnovers**: The chance ends when the ball is first touched by the team that gains possession, and the next chance starts at the same frame. - That means in situations where there is a loose ball where both teams may deflect the ball but the defense ultimately gains possession, the prior chance ends and the next chance begins at the first frame where the defense touches the ball around the time of the turnover. ===== END PAGE: Data Set: chances ===== ===== BEGIN PAGE: Data Set: closeouts ===== # Closeouts # Closeouts The `closeouts` section in the markings response contains a row for each closeout we identify in the tracking data. ## Overview A closeout occurs when a defender closes the distance toward an offensive player who is receiving a pass. We identify a closeout when: - A **pass is completed** to an offensive player - A defender **moves meaningfully toward the pass receiver** as a result of that pass - The receiver catches the ball in a position where they could reasonably **score or attack** (roughly within 35–40 feet of the rim) We also include: - **Off-ball screen situations** where there is separation between the defender and receiver before the pass, requiring the defender to close distance - **Bobbled catches** where the receiver retains possession despite briefly losing control - **Hard stunts** where a defender covers meaningful ground toward the receiver, even if they don't end up right on the ball We do not count as closeouts: - **Handoffs and dribble handoffs** — when the separation is created by a screen/handoff action rather than defensive positioning before the pass - **Catches with back to the basket** — when the receiver is facing away from the rim on the catch and doesn't turn to face within about a second (since we view this as not in a position to score) - **Catches far from the rim** — when a player is simply getting open far from scoring range with no immediate threat - **Incomplete passes and loose balls** — when the intended receiver doesn't gain possession (though bobbles that result in retained possession are included) - **Trivial movements** — when a defender barely moves (less than roughly a step) because they're already in position ## Sample Response ```json { "markings": { "closeouts": [ { "ball_handler_id_nba": 1642852, "ball_handler_speed_before_touch_inches_per_sec": 58.12, "chance_id_ctg": "chance_4c33ded97f95174cc013b446c3981347", "closeout_attack_style": "other", "closeout_id_ctg": "closeout_a768e79d1936d3f3aef88b58e23472ba", "closeout_result": "hold", "closeout_stop_frame_distance_in": 117.98, "closeout_stop_he_frame": 1475, "closeout_stop_hips_angle": 14.38, "closeout_stop_hips_facing": "square", "closeout_stop_player_angle": -2.65, "closeout_stop_wall_clock": "2025-12-23T01:10:59.038+00:00", "defender_id_nba": 203076, "drive_direction": null, "end_game_clock": 694.0, "end_he_frame": 1588, "end_shot_clock": 13.0, "end_wall_clock": "2025-12-23T01:11:00.922+00:00", "game_id_nba": "0022500404", "hand_up_timing": null, "jump_timing": null, "passer_id_nba": 1630529, "period": 1, "receiver_touch_start_he_frame": 1417, "region": "middle three", "start_distance": 12.08, "start_game_clock": 698.0, "start_he_frame": 1394, "start_shot_clock": 16.0, "start_wall_clock": "2025-12-23T01:10:57.688+00:00", "touch_distance": 13.72 } ] } } ``` ## Fields ### Identifiers #### `game_id_nba` **Type:** `string` NBA game ID --- #### `closeout_id_ctg` **Type:** `string` CTG-generated unique closeout ID --- #### `chance_id_ctg` **Type:** `string` CTG chance ID --- ### Participants #### `defender_id_nba` **Type:** `integer` NBA player ID of the defender closing out --- #### `ball_handler_id_nba` **Type:** `integer` NBA player ID of the offensive player being closed out to --- #### `passer_id_nba` **Type:** `integer` NBA player ID of the player who passed to the ball handler --- ### Timing ### Period #### `period` **Type:** `integer` Period in which the closeout occurred ### Start (Closeout Begins) The closeout start frame is placed when the defender begins moving toward the pass receiver. #### `start_game_clock` **Type:** `float` Game clock when closeout begins --- #### `start_shot_clock` **Type:** `float` Shot clock when closeout begins --- #### `start_he_frame` **Type:** `integer` Hawk-Eye frame when closeout begins --- #### `start_wall_clock` **Type:** `string` UTC timestamp when closeout begins ### End (Closeout Ends) The closeout end frame is placed when the defender's closeout movement ends — either when the defender stops moving toward the receiver, when the receiver's touch ends, or when the ball/receiver has clearly passed the defender (e.g. on a drive), whichever comes first. #### `end_game_clock` **Type:** `float` Game clock when closeout ends --- #### `end_shot_clock` **Type:** `float` Shot clock when closeout ends --- #### `end_he_frame` **Type:** `integer` Hawk-Eye frame when closeout ends --- #### `end_wall_clock` **Type:** `string` UTC timestamp when closeout ends --- ### Closeout Details #### `closeout_stop_he_frame` **Type:** `integer` Hawk-Eye frame when the closeout player either (a) leaves the ground to jump at the end of the closeout or (b) decelerates significantly to stay in front of the offensive player --- #### `closeout_stop_wall_clock` **Type:** `string` UTC timestamp corresponding to `closeout_stop_he_frame` --- #### `receiver_touch_start_he_frame` **Type:** `integer` Hawk-Eye frame when the pass receiver's possession touch begins --- #### `closeout_result` **Type:** `string` What does the offensive player do after receiving the pass that triggered the closeout? - **`shot`** - immediately shoots the ball or pump fakes and shoots - **`pass`** - passes the ball very soon after receiving it without dribbling - **`drive`** - dribbles toward the basket - **`hold`** - does not do any of the options above. `hold` can include dribbling but not doing so in a way designed to attack the basket. --- #### `closeout_stop_frame_distance_in` **Type:** `float` | **Unit:** `inches` How many inches the mid hip of the defensive player was from the offensive player at the `closeout_stop_he_frame` --- #### `closeout_stop_player_angle` **Type:** `float` | **Unit:** `degrees` The angle formed by the defender, the offensive player and the rim at the `closeout_stop_he_frame`. If these players are in a straight line, the angle would be 0. The angle will be negative when the defender is to the right of the offensive player, as looked at as if you were standing under the basket. --- #### `closeout_stop_hips_angle` **Type:** `float` | **Unit:** `degrees` The angle formed by the way the defensive player's hips are facing relative to the rim and the offensive player at the `closeout_stop_he_frame`. 0 degrees means if you draw a line from the rim to the offensive player, the defensive player's hips are parallel with that line — i.e. completely square to the offensive player. A positive angle means the defender has his hips turned to his right, a negative angle means to his left. --- #### `closeout_stop_hips_facing` **Type:** `string` A category for how the defender's hips are facing at the `closeout_stop_he_frame`, attempting to measure whether the defender is forcing no middle, middle, or is square to the offensive player. - **`no_middle`** - when the defender's hips are facing away from the middle of the court, or the defender is significantly to the side of the offensive player in a way that would encourage a drive away from the middle of the court - **`middle`** - when the defender's hips are facing toward the middle of the court, or the defender is significantly to the side of the offensive player in a way that would encourage a drive toward the middle of the court - **`square`** - when the defender's hips and position are not facing either middle or no middle --- #### `drive_direction` **Type:** `string` When the `closeout_result` is `drive`, does the offensive player drive toward the middle of the floor or away from the middle of the floor (`no_middle`)? If the `closeout_result` is not `drive`, this field will be `null`. --- #### `hand_up_timing` **Type:** `string` When does the defender put his hand up? Options: - **`before_catch`** - if the hand is up before the offensive player catches the pass - **`before_action`** - if the hand is up before the player jumps to shoot/passes/drives - **`after_action`** - if the hand is up after the player jumps to shoot/passes/drives - **`null`** - if the defender never gets their hand up --- #### `jump_timing` **Type:** `string` When does the defender leave his feet? Options: - **`early`** - if the defender leaves his feet before the offensive player’s action (e.g. bites on a pump fake) - **`normal`** - if the defender leaves his feet in reaction to the offensive player’s action - **`null`** - if the defender never jumps --- #### `closeout_attack_style` **Type:** `string` Uses the pose data to determine how the offensive player attacked the closeout: - **`catch_to_shoot`** - caught the pass and immediately got into a shooting position before shooting/making a move - **`catch_to_drive`** - caught the pass in a position oriented for an immediate drive - **`other`** - something else --- #### `ball_handler_speed_before_touch_inches_per_sec` **Type:** `float` | **Unit:** `inches/second` The speed of the offensive player's mid hips in the half second before the touch. The combination of this field and `closeout_attack_style` could help you identify things like "stampede" catches, for example. --- #### `region` **Type:** `string` Court region label for where the ball handler is located at the end of the closeout --- #### `start_distance` **Type:** `float` Distance (in feet) between defender and ball handler at `start_he_frame` --- #### `touch_distance` **Type:** `float` Distance (in feet) between defender and ball handler at the receiver’s touch start frame ===== END PAGE: Data Set: closeouts ===== ===== BEGIN PAGE: Data Set: contested-rebounds ===== # Contested Rebound Touches # Contested Rebound Touches The `contested_rebound_touches` section in the markings response gives more detail around “contested rebounds”, i.e. rebounds where at least one player from each team is near the ball when the ball was touched. ::: warning NOTE Due to imprecision in finger tracking data, this data can have a higher error rate than other markings. ::: ## Overview For each contested rebound, we look at each time the ball was touched. For each of these touches, we give details about what the nearby players were doing: how close they were to the ball, whether they jumped, how high they jumped, etc. ::: tip NOTE Instead of identifying every individual touch, we group close touches together into a single “touch group”. This helps deal with situations such as when a player bobbles the ball, and so they touch the ball many times in a very short window, but in reality we want to treat it like a single touch. Or when multiple players touch the ball at the same time — we track that as a single event and show multiple players touching the ball. ::: Each object in this data represents one player who is nearby a given touch during the rebound. This gives much more resolution around the “jump ball” aspect of rebounding, where multiple players jump for the ball and it matters who gets a hand on it. It should also be helpful in modeling the probabilities around securing a rebound in these kinds of contested situations. ::: info NOTE Currently only includes rebounds from field goal attempts where the shot was not blocked. ::: ## Sample Response ```json { "markings": { "contested_rebound_touches": [ { "ball_height_at_touch_in": 23.83, "ball_rim_distance_at_touch_in": 221.45, "chance_id_ctg": "chance_63aea33af0863ea15ce93e7bb2511140", "contested_rebound_touch_id_ctg": "contested_rebound_touch_4eba3843c64c495c7a25719b2425993e", "did_jump_close_to_touch": false, "did_touch_ball": false, "game_id_nba": "0022500404", "is_rebounder": false, "jump_max_neck_height_in": null, "jump_max_wrist_height_in": null, "left_hand_dist_to_ball_at_touch_in": 68.92, "nba_game_id": "0022500404", "nba_player_id": 1630180, "nearest_jump_start_he_frame_after_touch": null, "nearest_jump_start_he_frame_before_touch": null, "nearest_jump_start_wall_clock_after_touch": null, "nearest_jump_start_wall_clock_before_touch": null, "player_id_nba": 1630180, "rebound_he_frame": 10245, "rebound_id_ctg": "rebound_8eb2b107cd90818e262d339fd3003e60", "rebound_wall_clock": "2025-12-23T01:13:25.211+00:00", "right_hand_dist_to_ball_at_touch_in": 59.85, "touch_group_end_he_frame": 10244, "touch_group_end_wall_clock": "2025-12-23T01:13:25.194+00:00", "touch_group_start_he_frame": 10244, "touch_group_start_wall_clock": "2025-12-23T01:13:25.194+00:00" } ] } } ``` ## Fields ### Identifiers #### `contested_rebound_touch_id_ctg` **Type:** `string` CTG-generated unique identifier for this contested rebound touch event --- #### `game_id_nba` **Type:** `string` NBA game ID --- #### `nba_game_id` **Type:** `string` NBA game ID ::: warning Deprecated Use `game_id_nba` instead. This field will be removed in a future version. ::: --- #### `player_id_nba` **Type:** `integer` NBA player ID of the nearby player --- #### `nba_player_id` **Type:** `integer` NBA player ID of the nearby player ::: warning Deprecated Use `player_id_nba` instead. This field will be removed in a future version. ::: --- #### `rebound_id_ctg` **Type:** `string` CTG-generated rebound ID --- #### `chance_id_ctg` **Type:** `string` CTG chance ID of the chance that the rebound started --- ### Timing #### `rebound_he_frame` **Type:** `integer` Hawk-Eye frame of the rebound --- #### `rebound_wall_clock` **Type:** `string` UTC timestamp corresponding to `rebound_he_frame`. --- #### `touch_group_start_he_frame` **Type:** `integer` First frame when a player touched the ball in this touch group --- #### `touch_group_start_wall_clock` **Type:** `string` UTC timestamp corresponding to `touch_group_start_he_frame`. --- #### `touch_group_end_he_frame` **Type:** `integer` Last frame when a player touched the ball in this touch group --- #### `touch_group_end_wall_clock` **Type:** `string` UTC timestamp corresponding to `touch_group_end_he_frame`. --- ### Touch Data #### `is_rebounder` **Type:** `boolean` `true` if this player received credit for the rebound --- #### `did_touch_ball` **Type:** `boolean` `true` if this player touched the ball between shot end and rebound ### Hand Distance to Ball #### `left_hand_dist_to_ball_at_touch_in` **Type:** `float` | **Unit:** `inches` Distance from left hand (midpoint of thumb/pinky) to ball center at touch --- #### `right_hand_dist_to_ball_at_touch_in` **Type:** `float` | **Unit:** `inches` Distance from right hand to ball center at touch --- ### Ball Position #### `ball_height_at_touch_in` **Type:** `float` | **Unit:** `inches` Ball height above floor at touch group start --- #### `ball_rim_distance_at_touch_in` **Type:** `float` | **Unit:** `inches` Distance from ball center to rim center at touch group start --- ### Jump Data #### `did_jump_close_to_touch` **Type:** `boolean` `true` if the player jumped near this touch --- #### `nearest_jump_start_he_frame_before_touch` **Type:** `integer` Hawk-Eye frame of nearest jump start before touch (if near). `null` otherwise --- #### `nearest_jump_start_wall_clock_before_touch` **Type:** `string` UTC timestamp corresponding to `nearest_jump_start_he_frame_before_touch`. `null` if no jump. --- #### `nearest_jump_start_he_frame_after_touch` **Type:** `integer` Hawk-Eye frame of nearest jump start after touch (if near). `null` otherwise --- #### `nearest_jump_start_wall_clock_after_touch` **Type:** `string` UTC timestamp corresponding to `nearest_jump_start_he_frame_after_touch`. `null` if no jump. ### Jump Height (when `did_jump_close_to_touch` is true) #### `jump_max_neck_height_in` **Type:** `float` | **Unit:** `inches` Max neck height during the jump. `null` if no jump --- #### `jump_max_wrist_height_in` **Type:** `float` | **Unit:** `inches` Max wrist height during the jump. `null` if no jump ===== END PAGE: Data Set: contested-rebounds ===== ===== BEGIN PAGE: Data Set: deflections ===== # Deflections # Deflections The `deflections` section in the markings response contains an object for each time a defender touched the ball with a hand while the game clock is running (or which causes the clock to start running), where the ball is loose or the defensive touch knocks the ball loose. ## Overview The deflection markings include some situations which we might not typically think of as a deflection, for example: - "deflecting" the ball with two hands, like catching a pass as a steal - collecting loose balls, which might be the result of a prior deflection by the player or a teammate It does **not** include touches with feet, legs, shoulders, or other body parts. ::: warning NOTE Due to imprecision in finger tracking data, this data can have a higher error rate than other markings. ::: ## Sample Response ```json { "markings": { "deflections": [ { "chance_id_ctg": "chance_4c33ded97f95174cc013b446c3981347", "context": "other", "def_player_id": 203076, "def_player_id_nba": 203076, "deflection_id_ctg": "deflection_b8126b816b292f3ad52049fe11477726", "deflection_touch_start_game_clock": 689, "deflection_touch_start_he_frame": 1911, "deflection_touch_start_shot_clock": 7, "deflection_touch_start_wall_clock": "2025-12-23T01:11:06.305+00:00", "game_id_nba": "0022500404", "is_high_hand_deflection": true, "location": "on_ball", "nba_game_id": "0022500404", "off_player_id": 1630180, "off_player_id_nba": 1630180, "offense_retains_possession": true, "outcome": "tipped_live_ball", "pass_id_ctg": null, "period": 1 } ] } } ``` ## Fields ### Identifiers #### `game_id_nba` **Type:** `string` NBA game ID --- #### `nba_game_id` **Type:** `string` NBA game ID ::: warning Deprecated Use `game_id_nba` instead. This field will be removed in a future version. ::: --- #### `deflection_id_ctg` **Type:** `string` CTG-generated unique deflection ID --- #### `chance_id_ctg` **Type:** `string` CTG chance ID --- #### `pass_id_ctg` **Type:** `string` If `context` is `pass`, the CTG pass ID. `null` otherwise --- ### Participants #### `def_player_id_nba` **Type:** `integer` NBA player ID of the defender who made the deflection --- #### `def_player_id` **Type:** `integer` NBA player ID of the defender who made the deflection ::: warning Deprecated Use `def_player_id_nba` instead. This field will be removed in a future version. ::: --- #### `off_player_id_nba` **Type:** `integer` NBA player ID of the offensive player who last touched ball. `null` for loose balls --- #### `off_player_id` **Type:** `integer` NBA player ID of the offensive player who last touched ball. `null` for loose balls ::: warning Deprecated Use `off_player_id_nba` instead. This field will be removed in a future version. ::: --- ### Timing #### `period` **Type:** `integer` Period when the deflection occurred --- #### `deflection_touch_start_game_clock` **Type:** `float` Game clock when defender first touched ball --- #### `deflection_touch_start_shot_clock` **Type:** `float` Shot clock when defender first touched ball --- #### `deflection_touch_start_he_frame` **Type:** `integer` Hawk-Eye frame when defender first touched ball --- #### `deflection_touch_start_wall_clock` **Type:** `string` UTC timestamp when defender first touched ball --- ### Context #### `context` **Type:** `string` Game situation when deflection occurred: - **`pass`**: While offense was attempting to pass or just after pass was received - **`drive`**: While an offensive player was driving to the basket - **`during_offensive_touch`**: While offensive player was touching ball (not passing or driving) - **`other`**: Anything else, usually a loose ball situation --- #### `location` **Type:** `string` Deflector's location/role when making the deflection (see values below) - **`on_ball`**: Guarding the passer/ball handler or right on the ball - **`loose_ball`**: Touching the ball while it is loose - **`passing_lane`**: Touching ball during a pass, not close to passer, receiver hasn't caught it - **`receiver`**: Deflecting the ball after the pass has been caught - **`help`**: When `context` is `drive` and deflector is not the ball handler's matchup --- ### Outcome #### `outcome` **Type:** `string` What happens as a result of the deflection: - **`tipped_live_ball`**: Deflector tips the ball and it remains live - **`caught_live_ball`**: Deflector catches the ball and it remains live - **`out_of_bounds`**: Ball goes out of bounds before anyone else touches it - **`foul`**: Deflector commits a foul during the deflection --- #### `offense_retains_possession` **Type:** `boolean` `true` if offense keeps the ball (no turnover within 2 seconds), `false` otherwise --- ### Deflection Style #### `is_high_hand_deflection` **Type:** `boolean` `true` if deflection was made with hand up high in the air ===== END PAGE: Data Set: deflections ===== ===== BEGIN PAGE: Data Set: dribbles ===== # Dribbles # Dribbles The `dribbles` section in the markings response contains individual dribble events with handedness, timing, and ball height information. ## Overview Each record represents a single dribble—from when the ball leaves the player's hand to when they touch it again. Occassionally, there are plays that are unclear whether they are dribbles or uncontrolled bouncing of the ball (e.g. a deflection of a pass onto the ground and then picking the ball up). :::warning NOTE For the purpose of this data set, a dribble is defined as a player having two consecutive touches of the ball with the ball hitting the ground in between. If a dribble is stolen or deflected and the offensive player doesn't recover the ball, that attempted dribble will not be included in this data set. ::: ## Sample Response ```json { "markings": { "dribbles": [ { "chance_id_ctg": "chance_51bfc1fda2cc0deb125bee9988859667", "did_switch_hands": false, "dribble_end_hand": "left", "dribble_end_height_in": 22.19, "dribble_hand": "left", "dribble_id_ctg": "dribble_f00be85fa245d2860c8f25018a840e62", "dribble_start_height_in": 23.26, "end_game_clock": 717, "end_he_frame": 252, "end_shot_clock": 22, "end_wall_clock": "2025-12-23T01:10:38.473+00:00", "game_id_nba": "0022500404", "nba_game_id": "0022500404", "nba_player_id": 1642843, "period": 1, "player_id_nba": 1642843, "start_game_clock": 718, "start_he_frame": 241, "start_shot_clock": 23, "start_wall_clock": "2025-12-23T01:10:37.473+00:00" } ] } } ``` ## Fields ### Identifiers #### `dribble_id_ctg` **Type:** `string` CTG-generated unique identifier for this dribble event --- #### `game_id_nba` **Type:** `string` NBA game ID --- #### `nba_game_id` **Type:** `string` NBA game ID ::: warning Deprecated Use `game_id_nba` instead. This field will be removed in a future version. ::: --- #### `player_id_nba` **Type:** `integer` NBA player ID of the dribbler --- #### `nba_player_id` **Type:** `integer` NBA player ID of the dribbler ::: warning Deprecated Use `player_id_nba` instead. This field will be removed in a future version. ::: --- #### `chance_id_ctg` **Type:** `string` CTG chance ID. `null` if the dribble doesn't fall within any chance window (which could occur due to a data error, e.g. the `chances` data not having a correct start and end frame) --- ### Timing ### Period #### `period` **Type:** `integer` Period in which the dribble occurred ### Start (Ball Leaves Hand) #### `start_game_clock` **Type:** `float` Game clock (seconds remaining) when ball left dribbler's hands --- #### `start_shot_clock` **Type:** `float` Shot clock when ball left hands --- #### `start_he_frame` **Type:** `integer` Hawk-Eye frame when ball left hands --- #### `start_wall_clock` **Type:** `string` UTC timestamp when ball left hands ### End (Ball Touched Again) #### `end_game_clock` **Type:** `float` Game clock when ball is touched again by dribbler --- #### `end_shot_clock` **Type:** `float` Shot clock when ball touched again --- #### `end_he_frame` **Type:** `integer` Hawk-Eye frame when ball touched again --- #### `end_wall_clock` **Type:** `string` UTC timestamp when ball touched again --- ### Handedness #### `dribble_hand` **Type:** `string` `right` or `left` — which hand touched the ball last before the dribble --- #### `dribble_end_hand` **Type:** `string` `right` or `left` — which hand touched the ball first after it hit ground --- #### `did_switch_hands` **Type:** `boolean` `true` if `dribble_end_hand` differs from `dribble_hand` (e.g. a crossover dribble) --- ### Ball Height #### `dribble_start_height_in` **Type:** `float` | **Unit:** `inches` Ball height when leaving the player's hand --- #### `dribble_end_height_in` **Type:** `float` | **Unit:** `inches` Ball height when player touches it again ===== END PAGE: Data Set: dribbles ===== ===== BEGIN PAGE: Data Set: drives ===== # Drives # Drives The `drives` section in the markings response contains data for offensive drives toward the basket. ## Overview A drive is defined as when a player takes at least one dribble in an effort to get closer to the rim. We follow the following guidelines to help identify these drives: - The player must start outside the paint and beyond 10 feet from the rim - The player must get closer to the rim - The player must get inside around three-point line distance during their drive - A player who catches a pass on the move in transition headed toward the rim at high speed would not be counted as driving ## Sample Response ```json { "markings": { "drives": [ { "ball_handler_defender_id_nba": 1630230, "drive_id_ctg": "drive_4c0859e1242cf39607d5896f6dae865c", "end_distance_to_hoop_in": 75.24, "end_game_clock": 689.0, "end_he_frame": 1908, "end_shot_clock": 7.0, "end_wall_clock": "2025-12-23T01:11:06.255+00:00", "game_id_nba": "0022500404", "max_ballhandler_speed_in_per_sec": 237.67, "period": 1, "player_id_nba": 1630180, "start_distance_to_hoop_in": 356.77, "start_game_clock": 691.0, "start_he_frame": 1776, "start_shot_clock": 10.0, "start_wall_clock": "2025-12-23T01:11:04.055+00:00", "team_id_nba": 1610612740 } ] } } ``` ## Fields ### Identifiers #### `game_id_nba` **Type:** `string` NBA game ID --- #### `drive_id_ctg` **Type:** `string` CTG-generated unique drive ID --- #### `player_id_nba` **Type:** `integer` NBA player ID of the driver --- #### `team_id_nba` **Type:** `integer` NBA team ID of the driving team --- #### `ball_handler_defender_id_nba` **Type:** `integer` NBA player ID of the primary defender on the ball handler. `null` when there is an upstream error that causes bad chance data which prevents us from identifying the defender. --- ### Timing ### Period #### `period` **Type:** `integer` Period in which the drive occurred ### Start The start of the drive is estimated to be when the player first starts to attack the basket. #### `start_game_clock` **Type:** `float` Game clock when drive began --- #### `start_shot_clock` **Type:** `float` Shot clock when drive began --- #### `start_he_frame` **Type:** `integer` Hawk-Eye frame when drive began --- #### `start_wall_clock` **Type:** `string` UTC timestamp when drive began ### End The end of the drive is estimated to be when: - The player stops their dribbling toward the rim for a significant period of time (e.g. retreats back out, dribbles under the rim and pulls the ball out, picks up the ball and stops). Note that if the player retreats for a little but then attacks again, we keep this as part of the same drive unless the retreat is significant. - The ball leaves the player's hands (via pass or shot or turnover). - The whistle is blown and play stops due to a foul/violation. #### `end_game_clock` **Type:** `float` Game clock when drive ended --- #### `end_shot_clock` **Type:** `float` Shot clock when drive ended --- #### `end_he_frame` **Type:** `integer` Hawk-Eye frame when drive ended --- #### `end_wall_clock` **Type:** `string` UTC timestamp when drive ended --- ### Drive Metrics #### `start_distance_to_hoop_in` **Type:** `float` | **Unit:** `inches` Distance from driver to hoop at drive start --- #### `end_distance_to_hoop_in` **Type:** `float` | **Unit:** `inches` Distance from driver to hoop at drive end --- #### `max_ballhandler_speed_in_per_sec` **Type:** `float` | **Unit:** `inches/second` Maximum ball handler speed reached during the drive ===== END PAGE: Data Set: drives ===== ===== BEGIN PAGE: Data Set: falls ===== # Falls # Falls The `falls` section in the markings response contains one object per time a player is estimated to have fallen to the floor sometime close to live play. ## Overview A fall is detected when a player's hips get near the ground during or close to live play. We exclude falls during stoppages due to higher data error rates in those periods. ## Sample Response ```json { "markings": { "falls": [ { "chance_id_ctg": "chance_389850564394d3b1753f7f56ad8ba9b7", "duration_sec": 1.72, "end_he_frame": 16159, "end_wall_clock": "2025-12-23T01:15:03.782+00:00", "fall_id_ctg": "fall_bce802d16729844e22595c66fd9aa3de", "game_id_nba": "0022500404", "nba_game_id": "0022500404", "nba_player_id": 1642843, "period": 1, "player_id_nba": 1642843, "start_he_frame": 16056, "start_wall_clock": "2025-12-23T01:15:02.066+00:00" } ] } } ``` ## Fields ### Identifiers #### `fall_id_ctg` **Type:** `string` CTG-generated unique identifier for this fall event --- #### `game_id_nba` **Type:** `string` NBA game ID --- #### `nba_game_id` **Type:** `string` NBA game ID ::: warning Deprecated Use `game_id_nba` instead. This field will be removed in a future version. ::: --- #### `player_id_nba` **Type:** `integer` NBA player ID of the player who fell --- #### `nba_player_id` **Type:** `integer` NBA player ID of the player who fell ::: warning Deprecated Use `player_id_nba` instead. This field will be removed in a future version. ::: --- #### `chance_id_ctg` **Type:** `string` CTG chance ID (if fall occurred during a chance). `null` otherwise --- ### Timing #### `period` **Type:** `integer` Period when the fall occurred --- #### `start_he_frame` **Type:** `integer` Hawk-Eye frame when player's hips first got near the ground --- #### `start_wall_clock` **Type:** `string` UTC timestamp at fall start --- #### `end_he_frame` **Type:** `integer` Hawk-Eye frame when player's hips were no longer near the ground --- #### `end_wall_clock` **Type:** `string` UTC timestamp at fall end --- #### `duration_sec` **Type:** `float` | **Unit:** `seconds` How long the player's hips continuously remained near the ground during this fall ===== END PAGE: Data Set: falls ===== ===== BEGIN PAGE: Data Set: fouls ===== # Fouls # Fouls The `fouls` section in the markings response contains foul event data from the game. ## Sample Response ```json { "markings": { "fouls": [ { "attacking_positive_x": null, "event_pbp_descriptor": "shooting", "event_pbp_foul_personal_total": 1, "event_pbp_foul_technical_total": 0, "event_pbp_id": 9, "event_pbp_qualifiers": "[\"2freethrow\"]", "event_pbp_subtype": "personal", "foul_he_frame": 1970, "foul_id_ctg": "foul_667403419384a15148c093ad99575474", "foul_wall_clock": "2025-12-23T01:11:07.288+00:00", "fouled_player_id_nba": 1630180, "game_clock": 688, "game_clock_running": true, "game_id_nba": "0022500404", "pbp_event_id": 9, "period": 1, "player_id_nba": 1629023, "possession_team_id_nba": 1610612740, "shot_clock": 6, "shot_clock_running": true } ] } } ``` ## Fields ### Identifiers #### `game_id_nba` **Type:** `string` NBA game ID --- #### `foul_id_ctg` **Type:** `string` CTG-generated foul ID --- #### `player_id_nba` **Type:** `integer` NBA player ID of the player who committed the foul --- #### `fouled_player_id_nba` **Type:** `integer` NBA player ID of the fouled player --- #### `possession_team_id_nba` **Type:** `integer` NBA team ID of the team with possession --- ### Timing #### `period` **Type:** `integer` Period when the foul occurred --- #### `game_clock` **Type:** `float` Game clock (seconds remaining) at the foul --- #### `shot_clock` **Type:** `float` Shot clock at the foul. `null` if the shot clock is off --- #### `foul_he_frame` **Type:** `integer` Hawk-Eye frame of the foul. `null` if there is no corresponding Hawk-Eye frame in the Hawk-Eye event data --- #### `foul_wall_clock` **Type:** `string` UTC timestamp corresponding to `foul_he_frame`. `null` if there is no corresponding Hawk-Eye frame. --- #### `game_clock_running` **Type:** `boolean` `true` if game clock was running ::: warning Deprecated This field is unreliable and not particularly useful for analyzing foul events. This field will be removed in a future version. ::: --- #### `shot_clock_running` **Type:** `boolean` `true` if shot clock was running ::: warning Deprecated This field is unreliable and not particularly useful for analyzing foul events. This field will be removed in a future version. ::: --- ### Play-by-Play Data #### `pbp_event_id` **Type:** `integer` Play-by-play event ID (i.e. NGSS event ID) for the foul --- #### `event_pbp_id` **Type:** `integer` Play-by-play event ID (i.e. NGSS event ID) for the foul ::: warning Deprecated Use `pbp_event_id` instead. This field will be removed in a future version. ::: --- #### `event_pbp_subtype` **Type:** `string` The `sub_type` field from the official play-by-play feed. `null` if not provided --- #### `event_pbp_descriptor` **Type:** `string` The `descriptor` field from the official play-by-play feed. `null` if not provided --- #### `event_pbp_qualifiers` **Type:** `string` The `qualifiers` field from the official play-by-play feed. `null` if not provided --- #### `event_pbp_foul_personal_total` **Type:** `integer` Player's personal foul total for the game. `null` if not provided ::: warning Deprecated This data is already available in the official NBA play-by-play feed. This field will be removed in a future version. ::: --- #### `event_pbp_foul_technical_total` **Type:** `integer` Player's technical foul total. `null` if not provided ::: warning Deprecated This data is already available in the official NBA play-by-play feed. This field will be removed in a future version. ::: --- ### Court Context #### `attacking_positive_x` **Type:** `boolean` `true` if offensive team is attacking the positive X basket. `null` if unknown ::: warning Deprecated This information is not relevant to analyzing foul events. This field will be removed in a future version. ::: ===== END PAGE: Data Set: fouls ===== ===== BEGIN PAGE: Data Set: free-throws ===== # Free Throws # Free Throws The `free_throws` section in the markings response contains shooting mechanics data for every free throw attempt, similar to jump shot data but without jump-related fields. ## Overview Free throw mechanics data mirrors [jump shot mechanics data](jump-shots.md) in structure, with checkpoints, ball position, timing, and joint angle data. Since players typically don't jump during free throws, the jump-related checkpoints and metrics are excluded. ## Sample Response ```json { "markings": { "free_throws": [ { "ball_height_relative_to_neck_at_min_hips_in": 4.14, "ball_in_hands_sec": 1.1, "ball_in_hands_to_min_hips_sec": 0.67, "ball_release_height_in": 99.09, "ball_velocity_after_release_inches_per_sec": 244.28, "ball_velocity_min_ball_to_set_inches_per_sec": 51.11, "ball_velocity_set_to_release_inches_per_sec": 94.52, "distance_to_center_of_rim_2d": 7.03, "elbow_relative_to_ball_at_release_forward_back_inches": 2.65, "elbow_relative_to_ball_at_release_side_to_side_inches": 2.94, "elbow_relative_to_ball_at_set_forward_back_inches": 11.16, "elbow_relative_to_ball_at_set_side_to_side_inches": 5.77, "entry_angle": 42.1, "entry_speed_inches_per_sec": 209.49, "first_ball_in_hands_he_frame": 56383, "first_ball_in_hands_wall_clock": "2025-12-23T01:26:14.201+00:00", "first_frame_non_shooting_wrist_below_eye": 56616, "first_frame_shooting_wrist_below_eye": 56622, "first_non_shooting_wrist_below_eye_after_release_he_frame": 56616, "first_non_shooting_wrist_below_eye_after_release_wall_clock": "2025-12-23T01:26:18.084+00:00", "first_shooting_wrist_below_eye_after_release_he_frame": 56622, "first_shooting_wrist_below_eye_after_release_wall_clock": "2025-12-23T01:26:18.184+00:00", "free_throw_id_ctg": "free_throw_b476f695d74a148454e2e4a0a84ae6b6", "game_id_nba": "0022500404", "hand_closest_to_ball_on_release": "right", "hip_facing_angle_relative_to_rim_at_first_ball_in_hands": 15.5, "hip_facing_angle_relative_to_rim_at_min_hips": 21.89, "hip_facing_angle_relative_to_rim_at_release": 26.78, "hip_turn_from_min_hips_to_release": 4.89, "is_made": false, "last_ball_in_hands_he_frame": 56449, "last_ball_in_hands_wall_clock": "2025-12-23T01:26:15.301+00:00", "left_hip_bend_angle_at_min_ball": 132.11, "left_hip_bend_angle_at_min_hips": 142.79, "left_knee_bend_angle_at_min_ball": 143.45, "left_knee_bend_angle_at_min_hips": 126.6, "location_relative_to_hoop_center_x": 1.09, "location_relative_to_hoop_center_y": 6.94, "min_ball_height_ball_position_forward_to_back_in": 25.18, "min_ball_height_ball_position_side_to_side_in": 0.06, "min_ball_height_he_frame": 56383, "min_ball_height_relative_to_hips_in": 0.85, "min_ball_height_wall_clock": "2025-12-23T01:26:14.201+00:00", "min_hips_height_he_frame": 56423, "min_hips_height_wall_clock": "2025-12-23T01:26:14.868+00:00", "nba_game_id": "0022500404", "nba_player_id": 202691, "neck_relative_to_feet_midpoint_at_release_xy_distance_in": 2.61, "neck_relative_to_knee_midpoint_at_release_xy_distance_in": 3.02, "neck_relative_to_mid_hip_at_release_xy_distance_in": 2.42, "non_shooting_wrist_above_eye_after_release_sec": 2.88, "non_shooting_wrist_below_eye_wall_clock": "2025-12-23T01:26:18.084+00:00", "pbp_event_id": 113, "player_id_nba": 202691, "release_angle": 47.22, "release_frame": 56449, "release_height_above_min_ball_height_in": 59.91, "release_height_above_nose_in": 24.17, "release_point_ball_position_forward_to_back_in": 4.56, "release_point_ball_position_side_to_side_in": -3.27, "release_wall_clock": "2025-12-23T01:26:15.301+00:00", "right_hip_bend_angle_at_min_ball": 130.16, "right_hip_bend_angle_at_min_hips": 145.52, "right_knee_bend_angle_at_min_ball": 135.13, "right_knee_bend_angle_at_min_hips": 122.14, "rim_depth": 0.76, "rim_left_right": 6.99, "set_height_above_min_ball_height_in": 43.96, "set_point_ball_position_forward_to_back_in": -2.57, "set_point_ball_position_side_to_side_in": -1.79, "set_point_frame": 56438, "set_point_he_frame": 56438, "set_point_height_above_nose_in": 12.46, "set_point_height_in": 83.13, "set_point_wall_clock": "2025-12-23T01:26:15.118+00:00", "set_to_release_sec": 0.18, "shooting_elbow_flare_angle_at_set_point": 19.6, "shooting_elbow_shoulder_hip_angle_at_set_point": 121.8, "shooting_elbow_shoulder_hoop_angle_at_set_point": -2.09, "shooting_wrist_above_eye_after_release_sec": 2.78, "shooting_wrist_below_eye_wall_clock": "2025-12-23T01:26:18.184+00:00", "shooting_wrist_elbow_shoulder_angle_at_set_point": 88.6, "shoulder_facing_angle_relative_to_rim_at_first_ball_in_hands": 10.1, "shoulder_facing_angle_relative_to_rim_at_min_hips": 13.03, "shoulder_facing_angle_relative_to_rim_at_release": 24.02, "shoulder_turn_from_min_hips_to_release": 10.99, "vertical_shoulder_tilt_at_min_hips": -2.13, "wrist_relative_to_ball_at_release_forward_back_inches": 2.32, "wrist_relative_to_ball_at_release_side_to_side_inches": -0.24, "wrist_relative_to_ball_at_set_forward_back_inches": 5.26, "wrist_relative_to_ball_at_set_side_to_side_inches": 0.72 } ] } } ``` ## Fields ### Identifiers #### `free_throw_id_ctg` **Type:** `string` CTG-generated unique identifier for this free throw event --- #### `game_id_nba` **Type:** `string` NBA game ID --- #### `nba_game_id` **Type:** `string` NBA game ID ::: warning Deprecated Use `game_id_nba` instead. This field will be removed in a future version. ::: --- #### `player_id_nba` **Type:** `integer` NBA player ID of the shooter --- #### `nba_player_id` **Type:** `integer` NBA player ID of the shooter ::: warning Deprecated Use `player_id_nba` instead. This field will be removed in a future version. ::: --- #### `pbp_event_id` **Type:** `integer` Play-by-play event ID (i.e. NGSS ID) for this free throw ### Outcome #### `is_made` **Type:** `boolean` `true` if the free throw was made --- ### Checkpoints Fields ending in `_he_frame` are Hawk-Eye frame numbers (60 FPS), and corresponding `_wall_clock` fields are UTC timestamps. #### `first_ball_in_hands_he_frame` **Type:** `integer` First frame where shooter has both hands on the ball continuously until release ::: tip NOTE This frame may be well before the actual shooting motion if the player has the ball in both hands the entire time. For example, if the shooter catches and holds the ball for a while and then goes into their shooting motion, this frame would be multiple seconds before the shooting motion begins. ::: --- #### `first_ball_in_hands_wall_clock` **Type:** `string` UTC timestamp of the above frame --- #### `min_ball_height_he_frame` **Type:** `integer` Frame where ball is at lowest height before upward motion into shot --- #### `min_ball_height_wall_clock` **Type:** `string` UTC timestamp of the above frame --- #### `min_hips_height_he_frame` **Type:** `integer` Frame where mid hips are at lowest height before upward motion --- #### `min_hips_height_wall_clock` **Type:** `string` UTC timestamp of the above frame --- #### `set_point_he_frame` **Type:** `integer` Our estimate for the "set point" of the shot. We define this as the point in which the ball is furthest back away from the rim before it starts going forward towards the rim. --- #### `set_point_frame` **Type:** `integer` Our estimate for the "set point" of the shot ::: warning Deprecated Use `set_point_he_frame` instead. This field will be removed in a future version. ::: --- #### `set_point_wall_clock` **Type:** `string` UTC timestamp of the above frame --- #### `last_ball_in_hands_he_frame` **Type:** `integer` Our estimate for the "release point" of the shot. This is the first frame where we are confident the ball is not touching either hand. --- #### `release_frame` **Type:** `integer` Our estimate for the "release point" of the shot ::: warning Deprecated Use `last_ball_in_hands_he_frame` instead. This field will be removed in a future version. ::: --- #### `last_ball_in_hands_wall_clock` **Type:** `string` UTC timestamp of the above frame --- #### `release_wall_clock` **Type:** `string` UTC timestamp of the above frame ::: warning Deprecated Use `last_ball_in_hands_wall_clock` instead. This field will be removed in a future version. ::: --- #### `first_shooting_wrist_below_eye_after_release_he_frame` **Type:** `integer` First frame where shooting wrist drops below eye level after release --- #### `first_frame_shooting_wrist_below_eye` **Type:** `integer` First frame where shooting wrist drops below eye level after release ::: warning Deprecated Use `first_shooting_wrist_below_eye_after_release_he_frame` instead. This field will be removed in a future version. ::: --- #### `first_shooting_wrist_below_eye_after_release_wall_clock` **Type:** `string` UTC timestamp of the above frame --- #### `shooting_wrist_below_eye_wall_clock` **Type:** `string` UTC timestamp of the above frame ::: warning Deprecated Use `first_shooting_wrist_below_eye_after_release_wall_clock` instead. This field will be removed in a future version. ::: --- #### `first_non_shooting_wrist_below_eye_after_release_he_frame` **Type:** `integer` First frame where non-shooting wrist drops below eye level after release --- #### `first_frame_non_shooting_wrist_below_eye` **Type:** `integer` First frame where non-shooting wrist drops below eye level after release ::: warning Deprecated Use `first_non_shooting_wrist_below_eye_after_release_he_frame` instead. This field will be removed in a future version. ::: --- #### `first_non_shooting_wrist_below_eye_after_release_wall_clock` **Type:** `string` UTC timestamp of the above frame --- #### `non_shooting_wrist_below_eye_wall_clock` **Type:** `string` UTC timestamp of the above frame ::: warning Deprecated Use `first_non_shooting_wrist_below_eye_after_release_wall_clock` instead. This field will be removed in a future version. ::: --- ### Shot Mechanics ### General Metrics #### `hand_closest_to_ball_on_release` **Type:** `string` Whether the `left` or `right` hand is closer to the center of the ball at release. This is almost always the shooting hand of the shooter, so it is a good way to filter these metrics based on the shooter's handedness. --- #### `release_angle` **Type:** `float` | **Unit:** `degrees` The angle the ball is released at from the shooter's hands, in degrees. 90 degrees would be straight up in the air, 0 degrees would be in a straight line parallel to the ground. This is calculated between the release frame and 1/6th of a second later. ### Ball Position #### `min_ball_height_relative_to_hips_in` **Type:** `float` | **Unit:** `inches` How many inches above the shooter's mid hip joint the ball is at the `min_ball_height_he_frame`, i.e. when the ball is at its lowest point before the upward motion into the shot. --- #### `ball_release_height_in` **Type:** `float` | **Unit:** `inches` Ball height above ground at release --- #### `release_height_above_nose_in` **Type:** `float` | **Unit:** `inches` Ball height above shooter's nose at release --- #### `set_point_height_in` **Type:** `float` | **Unit:** `inches` Ball height above ground at set point --- #### `set_point_height_above_nose_in` **Type:** `float` | **Unit:** `inches` Ball height above shooter's nose at set point --- #### `ball_height_relative_to_neck_at_min_hips_in` **Type:** `float` | **Unit:** `inches` How many inches the ball is above the neck at the `min_hips_height_he_frame`, when the hips are at their lowest point before the upward motion into the shot. --- #### `release_height_above_min_ball_height_in` **Type:** `float` | **Unit:** `inches` How many inches the ball is released above the height of the ball at the `min_ball_height_he_frame`, i.e. when the ball is at its lowest point before the upward motion into the shot. --- #### `set_height_above_min_ball_height_in` **Type:** `float` | **Unit:** `inches` How much higher the ball is at the set point vs. the `min_ball_height_he_frame`. ### Ball Position (Side to Side) Positive = left of nose, negative = right. #### `set_point_ball_position_side_to_side_in` **Type:** `float` | **Unit:** `inches` How many inches the ball is to the left or right of the nose at the set point. Positive values are to the left, negative values to the right. --- #### `min_ball_height_ball_position_side_to_side_in` **Type:** `float` | **Unit:** `inches` How many inches the ball is to the left or right of the nose at the `min_ball_height_he_frame`. Positive values are to the left, negative values to the right. --- #### `release_point_ball_position_side_to_side_in` **Type:** `float` | **Unit:** `inches` How many inches the ball is to the left or right of the nose at release. Positive values are to the left, negative values to the right. ### Ball Position (Forward to Back) #### `set_point_ball_position_forward_to_back_in` **Type:** `float` | **Unit:** `inches` Ball distance in front of nose at set point --- #### `min_ball_height_ball_position_forward_to_back_in` **Type:** `float` | **Unit:** `inches` Ball distance in front of nose at min ball height --- #### `release_point_ball_position_forward_to_back_in` **Type:** `float` | **Unit:** `inches` Ball distance in front of nose at release --- ### Shot Timing #### `ball_in_hands_sec` **Type:** `float` | **Unit:** `seconds` Duration from first ball in hands to release --- #### `set_to_release_sec` **Type:** `float` | **Unit:** `seconds` Duration from set point to release --- #### `ball_in_hands_to_min_hips_sec` **Type:** `float` | **Unit:** `seconds` Duration from first ball in hands to min hips --- #### `shooting_wrist_above_eye_after_release_sec` **Type:** `float` | **Unit:** `seconds` How many seconds the shooting hand remained above the shooter's eye level after release. This can help with measuring a player holding their follow through. --- #### `non_shooting_wrist_above_eye_after_release_sec` **Type:** `float` | **Unit:** `seconds` How many seconds the non-shooting hand (aka guide hand) remained above the shooter's eye level after release. --- ### Ball Velocity #### `ball_velocity_min_ball_to_set_inches_per_sec` **Type:** `float` | **Unit:** `in/sec` How many inches the ball traveled from the `min_ball_height_he_frame` to the set point divided by how many seconds elapsed in that time. --- #### `ball_velocity_set_to_release_inches_per_sec` **Type:** `float` | **Unit:** `in/sec` How many inches the ball traveled from the set point to release divided by how many seconds elapsed in that time. --- #### `ball_velocity_after_release_inches_per_sec` **Type:** `float` | **Unit:** `in/sec` How many inches the ball traveled from release to 1/6th of a second later divided by how many seconds elapsed in that time. --- ### Joint Angles ### Shoulder Tilt #### `vertical_shoulder_tilt_at_min_hips` **Type:** `float` | **Unit:** `degrees` A measurement of how tilted to the right or left the shoulders are at the `min_hips_height_he_frame`. 0 degrees means parallel to the ground, 90 degrees would mean the shoulders are stacked vertically, one on top of the other (i.e. the player is sideways in the air). Negative values mean the right shoulder is higher than the left, positive values mean the left shoulder is higher than the right. ### Hip Facing (relative to rim) 0° = facing rim, 90° = facing left of rim, -90° = facing right. #### `hip_facing_angle_relative_to_rim_at_first_ball_in_hands` **Type:** `float` | **Unit:** `degrees` Hip angle at first ball in hands --- #### `hip_facing_angle_relative_to_rim_at_min_hips` **Type:** `float` | **Unit:** `degrees` Hip angle at min hips --- #### `hip_facing_angle_relative_to_rim_at_release` **Type:** `float` | **Unit:** `degrees` Hip angle at release --- #### `hip_turn_from_min_hips_to_release` **Type:** `float` | **Unit:** `degrees` The difference in the hip facing angle from the `min_hips_height_he_frame` to release. A positive number means the player rotated to the left, a negative number means they rotated to the right. ### Shoulder Facing (relative to rim) #### `shoulder_facing_angle_relative_to_rim_at_first_ball_in_hands` **Type:** `float` | **Unit:** `degrees` Shoulder angle at first ball in hands --- #### `shoulder_facing_angle_relative_to_rim_at_min_hips` **Type:** `float` | **Unit:** `degrees` Shoulder angle at min hips --- #### `shoulder_facing_angle_relative_to_rim_at_release` **Type:** `float` | **Unit:** `degrees` Shoulder angle at release --- #### `shoulder_turn_from_min_hips_to_release` **Type:** `float` | **Unit:** `degrees` The difference in the shoulder facing angle from the `min_hips_height_he_frame` to release. A positive number means the player rotated to the left, a negative number means they rotated to the right. ### Knee Bend Angle formed by hip, knee, and ankle. #### `left_knee_bend_angle_at_min_hips` **Type:** `float` | **Unit:** `degrees` Left knee angle at min hips --- #### `left_knee_bend_angle_at_min_ball` **Type:** `float` | **Unit:** `degrees` Left knee angle at min ball height --- #### `right_knee_bend_angle_at_min_hips` **Type:** `float` | **Unit:** `degrees` Right knee angle at min hips --- #### `right_knee_bend_angle_at_min_ball` **Type:** `float` | **Unit:** `degrees` Right knee angle at min ball height ### Hip Bend Angle formed by shoulder, hip, and knee. #### `left_hip_bend_angle_at_min_hips` **Type:** `float` | **Unit:** `degrees` Left hip angle at min hips --- #### `left_hip_bend_angle_at_min_ball` **Type:** `float` | **Unit:** `degrees` Left hip angle at min ball height --- #### `right_hip_bend_angle_at_min_hips` **Type:** `float` | **Unit:** `degrees` Right hip angle at min hips --- #### `right_hip_bend_angle_at_min_ball` **Type:** `float` | **Unit:** `degrees` Right hip angle at min ball height --- ### Shooting Arm Position ### At Set Point #### `shooting_wrist_elbow_shoulder_angle_at_set_point` **Type:** `float` | **Unit:** `degrees` Angle formed by wrist, elbow, shoulder (from the side). --- #### `shooting_elbow_shoulder_hip_angle_at_set_point` **Type:** `float` | **Unit:** `degrees` Angle formed by elbow, shoulder, hip. --- #### `shooting_elbow_shoulder_hoop_angle_at_set_point` **Type:** `float` | **Unit:** `degrees` Measures where the elbow is pointing relative to the hoop. This tells you the angle formed by the shooting elbow, shooting shoulder, and hoop at the set point, where 0 degrees would be aiming straight at the rim, negative is to the left of the rim and positive to the right. --- #### `shooting_elbow_flare_angle_at_set_point` **Type:** `float` | **Unit:** `degrees` How flared out or in is the shooting elbow relative to the shoulders at the set point. 0 degrees would mean the elbow is directly in line with the way the shoulders are pointing, a positive number means it's flared out away from the center of the body (regardless of whether it's the left or right arm), a negative number would mean it's pointed in toward the center of the body. ### Elbow/Wrist Relative to Ball #### `elbow_relative_to_ball_at_set_forward_back_inches` **Type:** `float` | **Unit:** `inches` Viewed from above, how far in front of or behind the center of the ball is the elbow at the set point. The forward-back axis here is the line from the center of the ball to the center of the rim. --- #### `elbow_relative_to_ball_at_set_side_to_side_inches` **Type:** `float` | **Unit:** `inches` Viewed from above, how far to the left or right of the center of the ball is the elbow at the set point. The side-to-side axis here is the line perpendicular to the line from the center of the ball to the center of the rim. Negative is to the left of the ball, positive is to the right. --- #### `elbow_relative_to_ball_at_release_forward_back_inches` **Type:** `float` | **Unit:** `inches` Viewed from above, how far in front of or behind the center of the ball is the elbow at the release point. The forward-back axis here is the line from the center of the ball to the center of the rim. --- #### `elbow_relative_to_ball_at_release_side_to_side_inches` **Type:** `float` | **Unit:** `inches` Viewed from above, how far to the left or right of the center of the ball is the elbow at the release point. The side-to-side axis here is the line perpendicular to the line from the center of the ball to the center of the rim. Negative is to the left of the ball, positive is to the right. --- #### `wrist_relative_to_ball_at_set_forward_back_inches` **Type:** `float` | **Unit:** `inches` Viewed from above, how far in front of or behind the center of the ball is the wrist at the set point. The forward-back axis here is the line from the center of the ball to the center of the rim. --- #### `wrist_relative_to_ball_at_set_side_to_side_inches` **Type:** `float` | **Unit:** `inches` Viewed from above, how far to the left or right of the center of the ball is the wrist at the set point. The side-to-side axis here is the line perpendicular to the line from the center of the ball to the center of the rim. Negative is to the left of the ball, positive is to the right. --- #### `wrist_relative_to_ball_at_release_forward_back_inches` **Type:** `float` | **Unit:** `inches` Viewed from above, how far in front of or behind the center of the ball is the wrist at the release point. The forward-back axis here is the line from the center of the ball to the center of the rim. --- #### `wrist_relative_to_ball_at_release_side_to_side_inches` **Type:** `float` | **Unit:** `inches` Viewed from above, how far to the left or right of the center of the ball is the wrist at the release point. The side-to-side axis here is the line perpendicular to the line from the center of the ball to the center of the rim. Negative is to the left of the ball, positive is to the right. --- ### Balance Metrics #### `neck_relative_to_feet_midpoint_at_release_xy_distance_in` **Type:** `float` | **Unit:** `inches` Imagine looking at a player from straight overhead as they release their shot. This field measures the two-dimensional distance (ignoring the height distance) between the player's neck and the point in between their left and right ankles. A player standing straight up and down would have their neck right over their ankles (and a distance close to 0), while a player leaning back would have their neck much further from their ankles. --- #### `neck_relative_to_knee_midpoint_at_release_xy_distance_in` **Type:** `float` | **Unit:** `inches` 2D distance from neck to midpoint between knees --- #### `neck_relative_to_mid_hip_at_release_xy_distance_in` **Type:** `float` | **Unit:** `inches` Imagine looking at a player from straight overhead as they release their shot. This field measures the two-dimensional distance (ignoring the height distance) between the player's neck and the point in between their left and right hips. A player standing straight up and down would have their neck right over their hips (and a distance close to 0), while a player leaning back would have their neck much further from their hips. --- ### Rim Contact Metrics Where and how the ball entered (or missed) the basket. #### `location_relative_to_hoop_center_x` **Type:** `float` | **Unit:** `inches` X coordinate of ball with hoop center as origin --- #### `location_relative_to_hoop_center_y` **Type:** `float` | **Unit:** `inches` Y coordinate of ball with hoop center as origin --- #### `distance_to_center_of_rim_2d` **Type:** `float` | **Unit:** `inches` 2D distance from rim center at entry --- #### `entry_angle` **Type:** `float` | **Unit:** `degrees` Ball entry angle. 90° = straight down --- #### `entry_speed_inches_per_sec` **Type:** `float` | **Unit:** `in/sec` Ball speed at basket entry --- #### `rim_depth` **Type:** `float` | **Unit:** `inches` How far forward/back from rim center. Positive = long, negative = short --- #### `rim_left_right` **Type:** `float` | **Unit:** `inches` How far left/right from rim center. Positive = right ## Related Data - [Jump Shots](jump-shots) — Similar mechanics data for jump shots during gameplay ===== END PAGE: Data Set: free-throws ===== ===== BEGIN PAGE: Data Set: interior-shot-contests ===== # Interior Shot Contests # Interior Shot Contests The `interior_shot_contests` section in the markings response contains defensive contest information for [interior shots](interior-shots.md). ## Overview A "contester" for interior shots is any defender within 5 feet of the shooter at release AND within 7.5 feet at the shooter's jump start. If a shot has multiple contesters, there will be multiple records—one for each contester. ## Sample Response ```json { "markings": { "interior_shot_contests": [ { "angle_relative_to_shooter_at_ball_in_hands": -18.06, "angle_relative_to_shooter_at_release": -66.99, "angle_relative_to_shooter_at_shooter_jump_start": -38.72, "closest_hand_above_head_at_ball_in_hands": false, "closest_hand_above_head_at_release": false, "closest_hand_above_head_at_shooter_jump_start": false, "closest_hand_ball_dist_at_ball_in_hands_in": 140.73, "closest_hand_ball_dist_at_release_in": 55.39, "closest_hand_ball_dist_at_shooter_jump_start_in": 53.03, "closest_hand_ball_height_diff_at_ball_in_hands_in": -14.23, "closest_hand_ball_height_diff_at_release_in": -54.21, "closest_hand_ball_height_diff_at_shooter_jump_start_in": -45.38, "closest_hand_ball_hoop_angle_at_ball_in_hands": -18.22, "closest_hand_ball_hoop_angle_at_release": -121.84, "closest_hand_ball_hoop_angle_at_shooter_jump_start": -51.92, "closest_hand_ball_vertical_angle_at_ball_in_hands": -5.8, "closest_hand_ball_vertical_angle_at_release": -78.16, "closest_hand_ball_vertical_angle_at_shooter_jump_start": -58.83, "contester_id_nba": 1630530, "contester_jump_distance_in": null, "defender_distance_at_ball_in_hands_in": 166.83, "defender_distance_at_release_in": 42.79, "defender_distance_at_shooter_jump_start_in": 58.88, "did_contester_jump": false, "event_pbp_id": 7, "game_id_nba": "0022500404", "interior_shot_contest_id_ctg": "interior_shot_contest_d1d5c77f3c8fe13a8ba7ebc290e81b03", "is_verticality": false, "left_hand_above_head_at_ball_in_hands": false, "left_hand_above_head_at_release": false, "left_hand_above_head_at_shooter_jump_start": false, "left_hand_ball_dist_at_ball_in_hands_in": 156.01, "left_hand_ball_dist_at_release_in": 55.39, "left_hand_ball_dist_at_shooter_jump_start_in": 53.03, "left_hand_ball_height_diff_at_ball_in_hands_in": -16.83, "left_hand_ball_height_diff_at_release_in": -54.21, "left_hand_ball_height_diff_at_shooter_jump_start_in": -45.38, "left_hand_ball_hoop_angle_at_ball_in_hands": -26.06, "left_hand_ball_hoop_angle_at_release": -121.84, "left_hand_ball_hoop_angle_at_shooter_jump_start": -51.92, "left_hand_ball_vertical_angle_at_ball_in_hands": -6.19, "left_hand_ball_vertical_angle_at_release": -78.16, "left_hand_ball_vertical_angle_at_shooter_jump_start": -58.83, "left_hand_eye_height_diff_at_max_jump_in": null, "pbp_event_id": 7, "position_relative_to_shooter_at_ball_in_hands": "front", "position_relative_to_shooter_at_release": "right", "position_relative_to_shooter_at_shooter_jump_start": "front", "right_hand_above_head_at_ball_in_hands": false, "right_hand_above_head_at_release": false, "right_hand_above_head_at_shooter_jump_start": false, "right_hand_ball_dist_at_ball_in_hands_in": 140.73, "right_hand_ball_dist_at_release_in": 87.18, "right_hand_ball_dist_at_shooter_jump_start_in": 55.28, "right_hand_ball_height_diff_at_ball_in_hands_in": -14.23, "right_hand_ball_height_diff_at_release_in": -82.75, "right_hand_ball_height_diff_at_shooter_jump_start_in": -41.86, "right_hand_ball_hoop_angle_at_ball_in_hands": -18.22, "right_hand_ball_hoop_angle_at_release": -85.36, "right_hand_ball_hoop_angle_at_shooter_jump_start": -26.55, "right_hand_ball_vertical_angle_at_ball_in_hands": -5.8, "right_hand_ball_vertical_angle_at_release": -71.66, "right_hand_ball_vertical_angle_at_shooter_jump_start": -49.23, "right_hand_eye_height_diff_at_max_jump_in": null, "shooter_id_nba": 203076, "shot_id_ctg": "shot_105f89542695fcebf740bb7c426ac4c3" } ] } } ``` ## Fields ### Identifiers #### `interior_shot_contest_id_ctg` **Type:** `string` CTG-generated unique identifier for this interior shot contest event --- #### `game_id_nba` **Type:** `string` NBA game ID --- #### `shot_id_ctg` **Type:** `string` CTG-generated shot ID (can join with `shots` and `interior_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` **Type:** `integer` Play-by-play event ID (i.e. NGSS ID) for this shot ::: warning Deprecated Use `pbp_event_id` instead. This field will be removed in a future version. ::: --- ### Checkpoints Contest data is captured at three checkpoints: | 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 touches the ball in the gather | ::: warning Ball in Hands Checkpoint Availability All `*_at_ball_in_hands` fields can be `null` when the ball in hands checkpoint is unavailable. This occurs when the tracking data doesn't detect a clear two-handed ball touch during the gather phase—most commonly on **tip attempts** where the shooter tips the ball directly without a traditional gather. ::: --- ### Contest Classification #### `did_contester_jump` **Type:** `boolean` `true` if the defender jumped to contest --- #### `is_verticality` **Type:** `boolean` `true` if defender was in front with both hands above head. `null` for tip attempts --- #### `contester_jump_distance_in` **Type:** `float` 2D distance traveled by defender during their contest jump, i.e. measuring the distance along the floor from the jump takeoff point to jump landing point. `null` if no jump --- ### 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 jump start --- #### `angle_relative_to_shooter_at_ball_in_hands` **Type:** `float` | **Unit:** `degrees` Defender angle at ball in hands. `null` if ball in hands checkpoint unavailable ### 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). For interior shots, hand placement is also considered—see note below. ::: tip NOTE Defining angles and positioning around the rim can get tricky. There are many contests where a defender’s body is to the side of the shooter, but their hand gets between the shooter and the rim. This field uses the hand placement to help determine this angle, so on a play like the one below, when Naz Reid’s hand gets between Kuminga and the basket on release, we would mark Reid as being in front of Kuminga for the contest, even though his body is to the side. ![Naz Red contest](assets/CleanShot_2023-12-14_at_21.06.522x.png) ::: #### `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. `null` if ball in hands checkpoint unavailable ### Defender Distance #### `defender_distance_at_release_in` **Type:** `float` | **Unit:** `inches` 2D distance from defender's mid hip to shooter's mid hip at release --- #### `defender_distance_at_shooter_jump_start_in` **Type:** `float` | **Unit:** `inches` Distance at jump start --- #### `defender_distance_at_ball_in_hands_in` **Type:** `float` | **Unit:** `inches` Distance at ball in hands. `null` if ball in hands checkpoint unavailable --- ### Jump Metrics #### `left_hand_eye_height_diff_at_max_jump_in` **Type:** `float` | **Unit:** `inches` Left hand height above left eye at peak of jump. `null` if no jump --- #### `right_hand_eye_height_diff_at_max_jump_in` **Type:** `float` | **Unit:** `inches` Right hand height above right eye at peak of jump. `null` if no 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. ### 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. `null` if ball in hands checkpoint unavailable --- #### `right_hand_ball_dist_at_ball_in_hands_in` **Type:** `float` | **Unit:** `inches` Right hand distance at ball in hands. `null` if ball in hands checkpoint unavailable --- #### `closest_hand_ball_dist_at_ball_in_hands_in` **Type:** `float` | **Unit:** `inches` Closest hand distance at ball in hands. `null` if ball in hands checkpoint unavailable ### 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. `null` if ball in hands checkpoint unavailable --- #### `right_hand_above_head_at_ball_in_hands` **Type:** `boolean` Right hand above head at ball in hands. `null` if ball in hands checkpoint unavailable --- #### `closest_hand_above_head_at_ball_in_hands` **Type:** `boolean` Closest hand above head at ball in hands. `null` if ball in hands checkpoint unavailable ### 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. `null` if ball in hands checkpoint unavailable --- #### `right_hand_ball_vertical_angle_at_ball_in_hands` **Type:** `float` | **Unit:** `degrees` Right hand vertical angle at ball in hands. `null` if ball in hands checkpoint unavailable --- #### `closest_hand_ball_vertical_angle_at_ball_in_hands` **Type:** `float` | **Unit:** `degrees` Closest hand vertical angle at ball in hands. `null` if ball in hands checkpoint unavailable ### 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. `null` if ball in hands checkpoint unavailable --- #### `right_hand_ball_height_diff_at_ball_in_hands_in` **Type:** `float` | **Unit:** `inches` Right hand height diff at ball in hands. `null` if ball in hands checkpoint unavailable --- #### `closest_hand_ball_height_diff_at_ball_in_hands_in` **Type:** `float` | **Unit:** `inches` Closest hand height diff at ball in hands. `null` if ball in hands checkpoint unavailable ### 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. `null` if ball in hands checkpoint unavailable --- #### `right_hand_ball_hoop_angle_at_ball_in_hands` **Type:** `float` | **Unit:** `degrees` Right hand horizontal angle at ball in hands. `null` if ball in hands checkpoint unavailable --- #### `closest_hand_ball_hoop_angle_at_ball_in_hands` **Type:** `float` | **Unit:** `degrees` Closest hand horizontal angle at ball in hands. `null` if ball in hands checkpoint unavailable ===== END PAGE: Data Set: interior-shot-contests ===== ===== BEGIN PAGE: Data Set: interior-shots ===== # Interior Shots # Interior Shots The `interior_shots` section in the markings response contains mechanics data for shots that are not jump shots or heaves. ## Overview Interior shots are any shots **not** classified as jump shots or heaves. This includes: - **Layups** — Shots near the basket that aren't dunks, lobs, or tips - **Dunks** — Any dunk or dunk attempt that isn't a lob - **Floaters** — One-handed overhand shots near the rim while facing the basket - **Hooks** — One-handed shots with back/side turned toward basket - **Tips** — One-handed redirections after a missed shot - **Putbacks** — Shots immediately after an offensive rebound without landing - **Lobs** — Shots where shooter receives a pass and shoots without landing ## Sample Response ```json { "markings": { "interior_shots": [ { "ball_release_height_in": 126.23, "ball_rim_distance_at_release_in": 16.22, "closest_toe_takeoff_distance_in": 86.84, "event_pbp_id": 7, "first_ball_in_hands_he_frame": 692, "first_ball_in_hands_wall_clock": "2025-12-23T01:10:45.989+00:00", "game_id_nba": "0022500404", "hand_to_hoop_center_distance": 18.7, "landing_feet": "left", "last_ball_in_hands_he_frame": 756, "last_ball_in_hands_wall_clock": "2025-12-23T01:10:47.056+00:00", "last_hand_to_touch_ball": "left", "last_left_foot_on_floor_he_frame": 730, "last_left_foot_on_floor_wall_clock": "2025-12-23T01:10:46.623+00:00", "last_right_foot_on_floor_he_frame": 725, "last_right_foot_on_floor_wall_clock": "2025-12-23T01:10:46.539+00:00", "neck_relative_to_feet_midpoint_xy_distance_in": 12.46, "neck_relative_to_knee_midpoint_xy_distance_in": 8.67, "neck_relative_to_mid_hip_xy_distance_in": 2.49, "pbp_event_id": 7, "shooter_id_nba": 203076, "shot_id_ctg": "shot_105f89542695fcebf740bb7c426ac4c3", "takeoff_feet": "both" } ] } } ``` ## Fields ### Identifiers #### `game_id_nba` **Type:** `string` NBA game ID --- #### `shot_id_ctg` **Type:** `string` CTG-generated unique shot ID (can join with `shots`) --- #### `shooter_id_nba` **Type:** `integer` NBA player ID of the shooter --- #### `pbp_event_id` **Type:** `integer` Play-by-play event ID (i.e. NGSS ID) for this shot --- #### `event_pbp_id` **Type:** `integer` Play-by-play event ID (i.e. NGSS ID) for this shot ::: warning Deprecated Use `pbp_event_id` instead. This field will be removed in a future version. ::: --- ### Checkpoints Checkpoints are key frames in the shooting motion. Fields ending in `_he_frame` are Hawk-Eye frame numbers (60 FPS). #### `first_ball_in_hands_he_frame` **Type:** `integer` The first frame where the shooter is touching the ball with both hands and doesn't take both hands off the ball until the release of the shot. ::: tip NOTE If the ball is never in both hands and only in one hand (for example, the shooter only gathers the ball with one hand and shoots it without putting the second hand on it, or they tip the ball with one hand) this will be the frame where the shooter's last continuous touch of the ball started before the release. If the data does not show any touch of the ball (because the data is bad or the player never touched the ball, like when a *defender* tips the ball in but someone else gets credit for the shot), this field will be `null`. ::: --- #### `first_ball_in_hands_wall_clock` **Type:** `string` UTC timestamp corresponding to `first_ball_in_hands_he_frame`. This field can be `null` for the same reasons as `first_ball_in_hands_he_frame`. --- #### `last_ball_in_hands_he_frame` **Type:** `integer` Our estimate for the "release point" of the shot. This is the first frame where we are confident the ball is not touching either hand. ::: tip NOTE This field can be `null` when our ball touch detection algorithm cannot identify the shooter's touch of the ball prior to release (e.g. due to missing or inconsistent tracking data). ::: --- #### `last_ball_in_hands_wall_clock` **Type:** `string` UTC timestamp corresponding to `last_ball_in_hands_he_frame`. This field can be `null` when upstream data issues prevent detection of the shooter's touch of the ball. --- #### `last_left_foot_on_floor_he_frame` **Type:** `integer` Frame when left foot leaves floor. This field can be `null` when we do not detect the shooter's feet leaving the ground for the shot (either because the player does not jump or our methods are not sensitive to detect them). --- #### `last_left_foot_on_floor_wall_clock` **Type:** `string` UTC timestamp corresponding to `last_left_foot_on_floor_he_frame`. This field can be `null` when we do not detect the shooter's feet leaving the ground for the shot (either because the player does not jump or our methods are not sensitive to detect them). --- #### `last_right_foot_on_floor_he_frame` **Type:** `integer` Frame when right foot leaves floor. This field can be `null` when we do not detect the shooter's feet leaving the ground for the shot (either because the player does not jump or our methods are not sensitive to detect them). --- #### `last_right_foot_on_floor_wall_clock` **Type:** `string` UTC timestamp corresponding to `last_right_foot_on_floor_he_frame`. This field can be `null` when we do not detect the shooter's feet leaving the ground for the shot (either because the player does not jump or our methods are not sensitive to detect them). --- ### Shot Mechanics #### `last_hand_to_touch_ball` **Type:** `string` Which hand the player shot with: `right`, `left`, or `both` (for two-handed dunks). ::: tip NOTE This field can be `null` due to upstream data errors or if the player never touches the ball. ::: --- #### `ball_release_height_in` **Type:** `float` | **Unit:** `inches` Height of ball center above ground at release. ::: tip NOTE This field can be `null` when the release frame is unknown. ::: --- #### `ball_rim_distance_at_release_in` **Type:** `float` | **Unit:** `inches` Distance from ball center to rim center at release. ::: tip NOTE This field can be `null` when the release frame is unknown. ::: --- #### `closest_toe_takeoff_distance_in` **Type:** `float` | **Unit:** `inches` Distance from shooter's closest toe to the center of the basket at takeoff. This field can be `null` when we do not detect the shooter's feet leaving the ground for the shot (either because the player does not jump or our methods are not sensitive to detect them). --- #### `hand_to_hoop_center_distance` **Type:** `float` | **Unit:** `inches` | **Nullable:** Yes 3D distance from shooting hand (thumb) to rim center at release. This field can be `null` when upstream data issues prevent proper identification of the release frame. --- ### Footwork #### `takeoff_feet` **Type:** `string` Which foot the shooter jumped from: `right`, `left`, or `both`. This field can be `null` when we do not detect the shooter's feet leaving the ground for the shot (either because the player does not jump or our methods are not sensitive to detect them). --- #### `landing_feet` **Type:** `string` Which foot landed first: `right`, `left`, or `both`. This field can be `null` when we do not detect the shooter's feet leaving the ground for the shot (either because the player does not jump or our methods are not sensitive to detect them). --- ### Balance Metrics These fields measure how balanced the shooter was at release. A player standing straight up would have values close to 0. A player leaning significantly (e.g., extending for a layup) would have higher values. #### `neck_relative_to_feet_midpoint_xy_distance_in` **Type:** `float` | **Unit:** `inches` Imagine looking at a player from straight overhead as they release their shot. This field measures the left-to-right distance (i.e. ignoring the height distance) between the player's neck and the point in between their left and right ankles. This field can be `null` when upstream data issues prevent proper identification of the release frame. --- #### `neck_relative_to_knee_midpoint_xy_distance_in` **Type:** `float` | **Unit:** `inches` Imagine looking at a player from straight overhead as they release their shot. This field measures the left-to-right distance (i.e. ignoring the height distance) between the player's neck and the point in between their left and right knees. This field can be `null` when upstream data issues prevent proper identification of the release frame. --- #### `neck_relative_to_mid_hip_xy_distance_in` **Type:** `float` | **Unit:** `inches` Imagine looking at a player from straight overhead as they release their shot. This field measures the left-to-right distance (i.e. ignoring the height distance) between the player's neck and their mid hip. This field can be `null` when upstream data issues prevent proper identification of the release frame. ===== END PAGE: Data Set: interior-shots ===== ===== BEGIN PAGE: Data Set: jump-shot-contests ===== # Jump Shot Contests # 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` **Type:** `integer` Play-by-play event ID (i.e. NGSS ID) for this shot ::: warning 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 | ::: tip 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 ===== END PAGE: Data Set: jump-shot-contests ===== ===== BEGIN PAGE: Data Set: jump-shots ===== # Jump Shots # Jump Shots The `jump_shots` section in the markings response contains shooting mechanics data for every jump shot, including checkpoints (key frames), body positions, timing, and balance metrics. ## Sample Response ```json { "markings": { "jump_shots": [ { "ankle_distance_2d_at_jump_start_inches": 19.35, "ball_height_relative_to_neck_at_min_hips_in": 15.57, "ball_in_hands_sec": 0.92, "ball_in_hands_to_min_hips_sec": 0.63, "ball_release_height_in": 111.37, "ball_rim_distance_at_release_in": 288.57, "ball_velocity_after_release_inches_per_sec": 329.0, "ball_velocity_min_ball_to_set_inches_per_sec": 103.5, "ball_velocity_set_to_release_inches_per_sec": 181.48, "basket_entry_angle": 46.21, "basket_entry_depth": 5.38, "basket_entry_distance_to_center_of_rim_2d": 6.26, "basket_entry_he_frame": 272361, "basket_entry_left_right": 3.21, "basket_entry_location_relative_to_hoop_center_x": 4.19, "basket_entry_location_relative_to_hoop_center_y": 4.66, "basket_entry_speed_inches_per_sec": 302.5, "basket_entry_wall_clock": "2025-12-23T02:41:51.781+00:00", "elbow_relative_to_ball_at_release_forward_back_inches": 0.81, "elbow_relative_to_ball_at_release_side_to_side_inches": 3.74, "elbow_relative_to_ball_at_set_forward_back_inches": 14.73, "elbow_relative_to_ball_at_set_side_to_side_inches": 4.0, "event_pbp_id": 506, "first_ball_in_hands_he_frame": 272227, "first_ball_in_hands_wall_clock": "2025-12-23T02:41:49.548+00:00", "first_left_wrist_below_eye_after_release_he_frame": 272308, "first_left_wrist_below_eye_after_release_wall_clock": "2025-12-23T02:41:50.898+00:00", "first_right_wrist_below_eye_after_release_he_frame": 272306, "first_right_wrist_below_eye_after_release_wall_clock": "2025-12-23T02:41:50.864+00:00", "game_id_nba": "0022500404", "hand_closest_to_ball_on_release": "right", "heel_distance_at_jump_start_inches": 19.43, "hip_facing_angle_relative_to_rim_at_first_ball_in_hands": 42.13, "hip_facing_angle_relative_to_rim_at_jump_landing": 42.11, "hip_facing_angle_relative_to_rim_at_jump_start": 39.26, "hip_facing_angle_relative_to_rim_at_min_hips": 33.66, "hip_facing_angle_relative_to_rim_at_release": 42.13, "hip_turn_from_first_ball_in_hands_to_jump_landing": -0.02, "hip_turn_from_jump_start_to_jump_landing": 2.85, "hip_turn_from_min_hips_to_jump_landing": 8.45, "hip_turn_from_min_hips_to_release": 8.47, "is_off_balance": false, "jump_distance_not_toward_rim_in": 1.13, "jump_end_he_frame": 272302, "jump_end_wall_clock": "2025-12-23T02:41:50.798+00:00", "jump_shot_footwork_type": "left_right", "landing_ankle_height_difference_in": 0.81, "last_ball_in_hands_he_frame": 272282, "last_ball_in_hands_wall_clock": "2025-12-23T02:41:50.464+00:00", "last_either_foot_on_floor_he_frame": 272277, "last_either_foot_on_floor_wall_clock": "2025-12-23T02:41:50.381+00:00", "last_left_foot_on_floor_he_frame": 272277, "last_left_foot_on_floor_wall_clock": "2025-12-23T02:41:50.381+00:00", "last_right_foot_on_floor_he_frame": 272276, "last_right_foot_on_floor_wall_clock": "2025-12-23T02:41:50.364+00:00", "left_ankle_distance_forward_back_at_jump_start_inches": -4.49, "left_ankle_distance_side_to_side_at_jump_start_inches": 6.03, "left_ankle_vs_hip_side_to_side_at_jump_start_inches": 1.89, "left_foot_angle_to_hoop_at_jump_start": -44.43, "left_hip_bend_angle_at_min_ball": 141.53, "left_hip_bend_angle_at_min_hips": 140.04, "left_knee_bend_angle_at_min_ball": 144.18, "left_knee_bend_angle_at_min_hips": 110.08, "mid_toe_distance_at_jump_start_inches": 21.63, "mid_toe_heel_dist_difference_at_jump_start_inches": 2.2, "min_ball_height_ball_position_forward_to_back_in": 13.75, "min_ball_height_ball_position_side_to_side_in": 8.23, "min_ball_height_he_frame": 272247, "min_ball_height_relative_to_hips_in": -0.13, "min_ball_height_wall_clock": "2025-12-23T02:41:49.881+00:00", "min_hips_height_he_frame": 272265, "min_hips_height_wall_clock": "2025-12-23T02:41:50.181+00:00", "neck_relative_to_feet_midpoint_at_release_xy_distance_in": 4.26, "neck_relative_to_knee_midpoint_at_release_xy_distance_in": 2.7, "neck_relative_to_mid_hip_at_release_xy_distance_in": 0.44, "non_shooting_wrist_above_eye_after_release_sec": 0.43, "pbp_event_id": 506, "release_angle": 44.51, "release_height_above_min_ball_height_in": 69.31, "release_height_above_nose_in": 24.86, "release_point_ball_position_forward_to_back_in": 10.29, "release_point_ball_position_side_to_side_in": -1.07, "release_relative_to_jump_peak_timing": 0.1, "release_relative_to_jump_sec": 0.08, "right_ankle_distance_forward_back_at_jump_start_inches": -8.14, "right_ankle_distance_side_to_side_at_jump_start_inches": 12.98, "right_ankle_vs_hip_side_to_side_at_jump_start_inches": 8.85, "right_foot_angle_to_hoop_at_jump_start": -27.88, "right_hip_bend_angle_at_min_ball": 138.22, "right_hip_bend_angle_at_min_hips": 150.1, "right_knee_bend_angle_at_min_ball": 132.3, "right_knee_bend_angle_at_min_hips": 121.62, "set_height_above_min_ball_height_in": 40.36, "set_point_ball_position_forward_to_back_in": -4.77, "set_point_ball_position_side_to_side_in": -1.22, "set_point_he_frame": 272271, "set_point_height_above_nose_in": 9.97, "set_point_height_in": 82.43, "set_point_wall_clock": "2025-12-23T02:41:50.281+00:00", "set_relative_to_jump_sec": -0.1, "set_to_release_sec": 0.18, "shooter_id_nba": 1631255, "shooting_elbow_flare_angle_at_set_point": 20.23, "shooting_elbow_shoulder_hip_angle_at_set_point": 132.65, "shooting_elbow_shoulder_hoop_angle_at_set_point": 11.05, "shooting_wrist_above_eye_after_release_sec": 0.4, "shooting_wrist_elbow_shoulder_angle_at_set_point": 78.87, "shot_id_ctg": "shot_009f4b290df7ad4f18532b2d660ca60e", "shot_jump_direction_ankles": -36.93, "shot_jump_direction_mid_hips": -39.3, "shot_jump_distance_ankles_in": 13.64, "shot_jump_distance_mid_hips_in": 4.9, "shot_jump_max_hip_height_vs_standing_hip_height_diff_in": 12.47, "shoulder_facing_angle_relative_to_rim_at_first_ball_in_hands": 58.8, "shoulder_facing_angle_relative_to_rim_at_jump_landing": 31.97, "shoulder_facing_angle_relative_to_rim_at_jump_start": 35.29, "shoulder_facing_angle_relative_to_rim_at_min_hips": 31.49, "shoulder_facing_angle_relative_to_rim_at_release": 34.68, "shoulder_turn_from_first_ball_in_hands_to_jump_landing": -26.83, "shoulder_turn_from_jump_start_to_jump_landing": -3.32, "shoulder_turn_from_min_hips_to_jump_landing": 0.48, "shoulder_turn_from_min_hips_to_release": 3.19, "vertical_shoulder_tilt_at_min_hips": -5.35, "wrist_relative_to_ball_at_release_forward_back_inches": -0.08, "wrist_relative_to_ball_at_release_side_to_side_inches": -0.96, "wrist_relative_to_ball_at_set_forward_back_inches": 6.26, "wrist_relative_to_ball_at_set_side_to_side_inches": -1.6 } ] } } ``` ## Fields ### Identifiers #### `game_id_nba` **Type:** `string` NBA game ID --- #### `shot_id_ctg` **Type:** `string` CTG-generated unique shot ID (can join with `shots`) --- #### `shooter_id_nba` **Type:** `integer` NBA player ID of the shooter --- #### `pbp_event_id` **Type:** `integer` Play-by-play event ID (i.e. NGSS ID) for this shot --- #### `event_pbp_id` **Type:** `integer` Play-by-play event ID (i.e. NGSS ID) for this shot ::: warning Deprecated Use `pbp_event_id` instead. This field will be removed in a future version. ::: --- ### Checkpoints Checkpoints are key frames in the shooting motion. Fields ending in `_he_frame` are Hawk-Eye frame numbers (60 FPS), and corresponding `_wall_clock` fields are UTC timestamps. ### Gather & Setup #### `first_ball_in_hands_he_frame` **Type:** `integer` First frame where shooter has both hands on the ball continuously until release ::: tip NOTE This frame may be well before the actual shooting motion if the player has the ball in both hands the entire time. For example, if the shooter catches and holds the ball for a while, jabs a few times, and then goes into their shooting motion, this frame would be multiple seconds before the shooting motion begins. ::: --- #### `first_ball_in_hands_wall_clock` **Type:** `string` UTC timestamp of the above frame --- #### `min_ball_height_he_frame` **Type:** `integer` Frame where ball is at lowest height before upward motion into shot --- #### `min_ball_height_wall_clock` **Type:** `string` UTC timestamp of the above frame --- #### `min_hips_height_he_frame` **Type:** `integer` Frame where mid hips are at lowest height before upward motion. `null` if no minimum hip height before both feet are off the ground (e.g. catch and shoot in midair) --- #### `min_hips_height_wall_clock` **Type:** `string` UTC timestamp of the above frame ### Jump Timing #### `last_left_foot_on_floor_he_frame` **Type:** `integer` Frame when left foot leaves the floor. `null` if player didn't jump --- #### `last_left_foot_on_floor_wall_clock` **Type:** `string` UTC timestamp of the above frame --- #### `last_right_foot_on_floor_he_frame` **Type:** `integer` Frame when right foot leaves the floor. `null` if player didn't jump --- #### `last_right_foot_on_floor_wall_clock` **Type:** `string` UTC timestamp of the above frame --- #### `last_either_foot_on_floor_he_frame` **Type:** `integer` Last frame where either foot is on floor (i.e. the frame right before they are completely in the air). `null` if player didn't jump --- #### `last_either_foot_on_floor_wall_clock` **Type:** `string` UTC timestamp of the above frame --- #### `jump_end_he_frame` **Type:** `integer` First frame where at least one foot is back on ground after jump. `null` if player didn't jump --- #### `jump_end_wall_clock` **Type:** `string` UTC timestamp of the above frame ### Release #### `set_point_he_frame` **Type:** `integer` Our estimate for the "set point" of the shot. We define this as the point in which the ball is furthest back away from the rim before it starts going forward towards the rim. --- #### `set_point_wall_clock` **Type:** `string` UTC timestamp of the above frame --- #### `last_ball_in_hands_he_frame` **Type:** `integer` Our estimate for the "release point" of the shot. This is the first frame where we are confident the ball is not touching either hand. --- #### `last_ball_in_hands_wall_clock` **Type:** `string` UTC timestamp of the above frame --- #### `first_right_wrist_below_eye_after_release_he_frame` **Type:** `integer` First frame where right wrist drops below eye level after release --- #### `first_right_wrist_below_eye_after_release_wall_clock` **Type:** `string` UTC timestamp of the above frame --- #### `first_left_wrist_below_eye_after_release_he_frame` **Type:** `integer` First frame where left wrist drops below eye level after release --- #### `first_left_wrist_below_eye_after_release_wall_clock` **Type:** `string` UTC timestamp of the above frame --- ### Basket Entry The goal of the basket entry checkpoint is to identify where the ball "lands" for a shot relative to the height of the rim, so that you can see whether players are shooting short/long or left/right. #### `basket_entry_he_frame` **Type:** `integer` The frame where we estimate the ball enters the basket, i.e. when, after the peak of the shot arc, it gets to a height that if it were in a spot to go into the basket that the bottom of the ball would be below the height of the rim. - If the ball is over the rim, this will be the frame in which the ball contacts the rim. - If the ball goes through the basket but hits the back of the rim, this will still be the first frame in which the bottom of the ball is below rim height. - If the ball airballs/is blocked, it will still be the first frame after the peak of the shot where the ball is below the height where it would have gone in the basket had it been in the right spot. - If the ball hits the backboard first, it will still be the frame where the ball reaches the appropriate height. --- #### `basket_entry_wall_clock` **Type:** `string` UTC timestamp of the `basket_entry_he_frame`. --- #### `basket_entry_depth` **Type:** `float` | **Unit:** `inches` How many inches forward/back the center of the ball was from the center of the rim at the `basket_entry_he_frame`, from the perspective of the shooter. Positive numbers mean the ball was long, negative means short. We determine the "perspective of the shooter" by essentially drawing a line from the ball at release to the center of the rim. --- #### `basket_entry_left_right` **Type:** `float` | **Unit:** `inches` How many inches left/right the center of the ball was from the center of the rim at the `basket_entry_he_frame`, from the perspective of the shooter. Positive numbers mean the ball was right, negative means left. We determine the "perspective of the shooter" by essentially drawing a line from the ball at release to the center of the rim. --- #### `basket_entry_location_relative_to_hoop_center_x` **Type:** `float` | **Unit:** `inches` The x coordinate of the center of the ball at the `basket_entry_he_frame` if you imagine the center of the hoop as the origin, i.e. coordinate (0,0). --- #### `basket_entry_location_relative_to_hoop_center_y` **Type:** `float` | **Unit:** `inches` The y coordinate of the center of the ball at the `basket_entry_he_frame` if you imagine the center of the hoop as the origin, i.e. coordinate (0,0). --- #### `basket_entry_distance_to_center_of_rim_2d` **Type:** `float` | **Unit:** `inches` The distance, ignoring the height of the ball, from the center of the rim at the `basket_entry_he_frame`. In other words, imagine looking at the hoop from straight above and putting a dot where the center of the ball is at the `basket_entry_he_frame`. The distance from that dot to the center of the rim is the `basket_entry_distance_to_center_of_rim_2d`. --- #### `basket_entry_angle` **Type:** `float` | **Unit:** `degrees` The angle formed between the ball at the `basket_entry_he_frame`, the ball 1/10th of a second prior, and the horizontal plane of the ball at the `basket_entry_he_frame`. The ball dropping straight down into the hoop from above would be a 90 degree angle, coming in completely flat in a straight line parallel to the floor would be a 0 degree angle. --- #### `basket_entry_speed_inches_per_sec` **Type:** `float` | **Unit:** `in/sec` The speed of the ball over the 1/10th of a second prior to the `basket_entry_he_frame`, measured in inches per second. This is calculated by measuring the distance traveled by the ball in that time and multiplying by 10 to scale it to distance per second. --- ### Shot Mechanics ### General Metrics #### `hand_closest_to_ball_on_release` **Type:** `string` Whether the `left` or `right` hand is closer to the center of the ball at the `last_ball_in_hands_he_frame`. This is almost always the shooting hand of the shooter, so it is a good way to filter these metrics based on the shooter’s handedness. --- #### `release_angle` **Type:** `float` | **Unit:** `degrees` The angle the ball is released at from the shooter's hands, in degrees. 90 degrees would be straight up in the air, 0 degrees would be in a straight line parallel to the ground. This is calculated between the `last_ball_in_hands_he_frame` and 1/6th of a second later. `null` for blocked shots. ### Ball Position #### `min_ball_height_relative_to_hips_in` **Type:** `float` | **Unit:** `inches` How many inches above the shooter's mid hip joint the ball is at the `min_ball_height_he_frame`, i.e. when the ball is at its lowest point before the upward motion into the shot. --- #### `ball_release_height_in` **Type:** `float` | **Unit:** `inches` Ball height above ground at release --- #### `release_height_above_nose_in` **Type:** `float` | **Unit:** `inches` Ball height above shooter's nose at release --- #### `set_point_height_in` **Type:** `float` | **Unit:** `inches` Ball height above ground at set point --- #### `set_point_height_above_nose_in` **Type:** `float` | **Unit:** `inches` Ball height above shooter's nose at set point --- #### `ball_height_relative_to_neck_at_min_hips_in` **Type:** `float` | **Unit:** `inches` How many inches the ball is above the neck at the `min_hips_height_he_frame`, when the hips are at their lowest point before the upward motion into the shot. --- #### `release_height_above_min_ball_height_in` **Type:** `float` | **Unit:** `inches` How many inches the ball is released above the height of the ball at the `min_ball_height_he_frame`, i.e. when the ball is at its lowest point before the upward motion into the shot. --- #### `set_height_above_min_ball_height_in` **Type:** `float` | **Unit:** `inches` How much higher the ball is at the `set_point_he_frame` vs. the `min_ball_height_he_frame`. ### Ball Position (Side to Side) #### `set_point_ball_position_side_to_side_in` **Type:** `float` | **Unit:** `inches` How many inches the ball is to the left or right of the nose at the `set_point_he_frame`. Positive values are to the left, negative values to the right. --- #### `min_ball_height_ball_position_side_to_side_in` **Type:** `float` | **Unit:** `inches` How many inches the ball is to the left or right of the nose at the `min_ball_height_he_frame`. Positive values are to the left, negative values to the right. --- #### `release_point_ball_position_side_to_side_in` **Type:** `float` | **Unit:** `inches` How many inches the ball is to the left or right of the nose at the `last_ball_in_hands_he_frame`. Positive values are to the left, negative values to the right. ### Ball Position (Forward to Back) #### `set_point_ball_position_forward_to_back_in` **Type:** `float` | **Unit:** `inches` Ball position in front of nose at set point --- #### `min_ball_height_ball_position_forward_to_back_in` **Type:** `float` | **Unit:** `inches` Ball position in front of nose at min ball height --- #### `release_point_ball_position_forward_to_back_in` **Type:** `float` | **Unit:** `inches` Ball position in front of nose at release ### Shot Distance #### `ball_rim_distance_at_release_in` **Type:** `float` | **Unit:** `inches` How many inches the center of the ball was from the center of the rim at the `last_ball_in_hands_he_frame`. ### Ball Velocity #### `ball_velocity_min_ball_to_set_inches_per_sec` **Type:** `float` | **Unit:** `in/sec` How many inches the ball traveled from the `min_ball_height_he_frame` to the `set_point_he_frame` divided by how many seconds elapsed in that time. --- #### `ball_velocity_set_to_release_inches_per_sec` **Type:** `float` | **Unit:** `in/sec` How many inches the ball traveled from the `set_point_he_frame` to the `last_ball_in_hands_he_frame` divided by how many seconds elapsed in that time. --- #### `ball_velocity_after_release_inches_per_sec` **Type:** `float` | **Unit:** `in/sec` How many inches the ball traveled from the `last_ball_in_hands_he_frame` to 1/6th of a second later divided by how many seconds elapsed in that time. `null` if the shot is blocked. --- ### Shot Timing #### `release_relative_to_jump_sec` **Type:** `float` | **Unit:** `seconds` Time from feet leaving floor to ball release --- #### `set_relative_to_jump_sec` **Type:** `float` | **Unit:** `seconds` Time from feet leaving floor to set point --- #### `set_to_release_sec` **Type:** `float` | **Unit:** `seconds` Duration from set point to release --- #### `ball_in_hands_sec` **Type:** `float` | **Unit:** `seconds` Duration from first ball in hands to release --- #### `ball_in_hands_to_min_hips_sec` **Type:** `float` | **Unit:** `seconds` Duration from first ball in hands to min hips --- #### `release_relative_to_jump_peak_timing` **Type:** `float` | **Unit:** `seconds` Time from release to peak of jump. Negative = released on the way down --- #### `shooting_wrist_above_eye_after_release_sec` **Type:** `float` | **Unit:** `seconds` How many seconds the shooting hand remained above the shooter's eye level after the `last_ball_in_hands_he_frame`. This can help with measuring a player holding their follow through. --- #### `non_shooting_wrist_above_eye_after_release_sec` **Type:** `float` | **Unit:** `seconds` How many seconds the non-shooting hand (aka guide hand) remained above the shooter's eye level after the `last_ball_in_hands_he_frame`. --- ### Joint Angles ### Shoulder Tilt #### `vertical_shoulder_tilt_at_min_hips` **Type:** `float` | **Unit:** `degrees` A measurement of how tilted to the right or left the shoulders are at the `min_hips_height_he_frame`. 0 degrees means parallel to the ground, 90 degrees would mean the shoulders are stacked vertically, one on top of the other (i.e. the player is sideways in the air). Negative values mean the right shoulder is higher than the left, positive values mean the left shoulder is higher than the right. ### Hip Facing (relative to rim) 0° = facing rim, 90° = facing left of rim, -90° = facing right of rim. #### `hip_facing_angle_relative_to_rim_at_first_ball_in_hands` **Type:** `float` | **Unit:** `degrees` Hip angle at first ball in hands --- #### `hip_facing_angle_relative_to_rim_at_min_hips` **Type:** `float` | **Unit:** `degrees` Hip angle at min hips --- #### `hip_facing_angle_relative_to_rim_at_jump_start` **Type:** `float` | **Unit:** `degrees` Hip angle at jump start --- #### `hip_facing_angle_relative_to_rim_at_release` **Type:** `float` | **Unit:** `degrees` Hip angle at release --- #### `hip_facing_angle_relative_to_rim_at_jump_landing` **Type:** `float` | **Unit:** `degrees` Hip angle at jump landing ### Hip Turn #### `hip_turn_from_first_ball_in_hands_to_jump_landing` **Type:** `float` | **Unit:** `degrees` The difference in the hip facing angle from the `first_ball_in_hands_he_frame` to the `jump_end_he_frame`. A positive number means the player rotated to the left, a negative number means they rotated to the right. ::: tip NOTE This will usually be meaningful only for shots where the player went into a shooting motion right after putting both hands on the ball. For those shots, this will show you the full extent of the hip turn from the beginning of the shooting motion through the landing. Otherwise, there may be a significant amount of time between having both hands on the ball and going into the shooting motion and this measurement is unlikely to tell you much in that case. ::: --- #### `hip_turn_from_min_hips_to_jump_landing` **Type:** `float` | **Unit:** `degrees` The difference in the hip facing angle from the `min_hips_height_he_frame` to the `jump_end_he_frame`. A positive number means the player rotated to the left, a negative number means they rotated to the right. --- #### `hip_turn_from_jump_start_to_jump_landing` **Type:** `float` | **Unit:** `degrees` The difference in the hip facing angle from the `last_either_foot_on_floor_he_frame` to the `jump_end_he_frame`. A positive number means the player rotated to the left, a negative number means they rotated to the right. --- #### `hip_turn_from_min_hips_to_release` **Type:** `float` | **Unit:** `degrees` The difference in the hip facing angle from the `min_hips_height_he_frame` to the `last_ball_in_hands_he_frame`. A positive number means the player rotated to the left, a negative number means they rotated to the right. ### Shoulder Facing (relative to rim) Same convention as hip facing. #### `shoulder_facing_angle_relative_to_rim_at_first_ball_in_hands` **Type:** `float` | **Unit:** `degrees` Shoulder angle at first ball in hands --- #### `shoulder_facing_angle_relative_to_rim_at_min_hips` **Type:** `float` | **Unit:** `degrees` Shoulder angle at min hips --- #### `shoulder_facing_angle_relative_to_rim_at_jump_start` **Type:** `float` | **Unit:** `degrees` Shoulder angle at jump start --- #### `shoulder_facing_angle_relative_to_rim_at_release` **Type:** `float` | **Unit:** `degrees` Shoulder angle at release --- #### `shoulder_facing_angle_relative_to_rim_at_jump_landing` **Type:** `float` | **Unit:** `degrees` Shoulder angle at jump landing ### Shoulder Turn #### `shoulder_turn_from_first_ball_in_hands_to_jump_landing` **Type:** `float` | **Unit:** `degrees` The difference in the shoulder facing angle from the `first_ball_in_hands_he_frame` to the `jump_end_he_frame`. A positive number means the player rotated to the left, a negative number means they rotated to the right. ::: tip NOTE This will usually be meaningful only for shots where the player went into a shooting motion right after putting both hands on the ball. For those shots, this will show you the full extent of the shoulder turn from the beginning of the shooting motion through the landing. Otherwise, there may be a significant amount of time between having both hands on the ball and going into the shooting motion and this measurement is unlikely to tell you much in that case. ::: --- #### `shoulder_turn_from_min_hips_to_jump_landing` **Type:** `float` | **Unit:** `degrees` The difference in the shoulder facing angle from the `min_hips_height_he_frame` to the `jump_end_he_frame`. A positive number means the player rotated to the left, a negative number means they rotated to the right. --- #### `shoulder_turn_from_jump_start_to_jump_landing` **Type:** `float` | **Unit:** `degrees` The difference in the shoulder facing angle from the `last_either_foot_on_floor_he_frame` to the `jump_end_he_frame`. A positive number means the player rotated to the left, a negative number means they rotated to the right. --- #### `shoulder_turn_from_min_hips_to_release` **Type:** `float` | **Unit:** `degrees` The difference in the shoulder facing angle from the `min_hips_height_he_frame` to the `last_ball_in_hands_he_frame`. A positive number means the player rotated to the left, a negative number means they rotated to the right. ### Knee Bend Angle formed by hip, knee, and ankle. Knee bend angle illustration #### `left_knee_bend_angle_at_min_hips` **Type:** `float` | **Unit:** `degrees` Left knee angle at min hips --- #### `left_knee_bend_angle_at_min_ball` **Type:** `float` | **Unit:** `degrees` Left knee angle at min ball height --- #### `right_knee_bend_angle_at_min_hips` **Type:** `float` | **Unit:** `degrees` Right knee angle at min hips --- #### `right_knee_bend_angle_at_min_ball` **Type:** `float` | **Unit:** `degrees` Right knee angle at min ball height ### Hip Bend Angle formed by shoulder, hip, and knee. Hip bend angle illustration #### `left_hip_bend_angle_at_min_hips` **Type:** `float` | **Unit:** `degrees` Left hip angle at min hips --- #### `left_hip_bend_angle_at_min_ball` **Type:** `float` | **Unit:** `degrees` Left hip angle at min ball height --- #### `right_hip_bend_angle_at_min_hips` **Type:** `float` | **Unit:** `degrees` Right hip angle at min hips --- #### `right_hip_bend_angle_at_min_ball` **Type:** `float` | **Unit:** `degrees` Right hip angle at min ball height --- ### Foot Position at Jump Start ### Ankle Distance ::: warning NOTE All fields in this section are `null` when no jump was detected for the shot (e.g., set shots, or tracking gaps during the shot attempt). ::: #### `ankle_distance_2d_at_jump_start_inches` **Type:** `float` | **Unit:** `inches` The two dimensional distance between the left ankle joint at the `last_left_foot_on_floor_he_frame` and the right ankle joint at the `last_right_foot_on_floor_he_frame`. Imagine looking at the player from overhead and seeing how far apart the feet are as each leaves the ground. `null` if no jump detected. Ankle distance 2D illustration --- #### `left_ankle_distance_side_to_side_at_jump_start_inches` **Type:** `float` | **Unit:** `inches` How many inches to the left side of the middle of the hips is the shooter's left ankle as the left foot leaves the ground. To measure this, imagine a graph based on the way the hips are facing, with the center (at 0, 0) being the middle of the hips, the vertical axis being forward-back and the horizontal axis being side-to-side. This field shows the distance on the side-to-side dimension between the ankle point and the middle of the hips. `null` if no shot jump detected. Ankle distance side to side illustration --- #### `right_ankle_distance_side_to_side_at_jump_start_inches` **Type:** `float` | **Unit:** `inches` How many inches to the right side of the middle of the hips is the shooter's right ankle as the right foot leaves the ground. To measure this, imagine a graph based on the way the hips are facing, with the center (at 0, 0) being the middle of the hips, the vertical axis being forward-back and the horizontal axis being side-to-side. This field shows the distance on the side-to-side dimension between the ankle point and the middle of the hips. `null` if no shot jump detected. --- #### `left_ankle_vs_hip_side_to_side_at_jump_start_inches` **Type:** `float` | **Unit:** `inches` How many inches to the outside of the left hip is the left ankle. 0 would mean directly in line with the hip on that side of the body, negative numbers show the foot is inside the hip. `null` if no shot jump detected. Ankle vs hip side to side illustration --- #### `right_ankle_vs_hip_side_to_side_at_jump_start_inches` **Type:** `float` | **Unit:** `inches` How many inches to the outside of the right hip is the right ankle. 0 would mean directly in line with the hip on that side of the body, negative numbers show the foot is inside the hip. `null` if no shot jump detected. --- #### `right_ankle_distance_forward_back_at_jump_start_inches` **Type:** `float` | **Unit:** `inches` How many inches forward or back of the hips is the shooter's right ankle as the right foot leaves the ground. To measure this, imagine a graph based on the way the hips are facing, with the center (at 0, 0) being the middle of the hips, the vertical axis being forward-back and the horizontal axis being side-to-side. This field shows the distance on the vertical axis between the ankle point and the middle of the hips. `null` if no shot jump detected. --- #### `left_ankle_distance_forward_back_at_jump_start_inches` **Type:** `float` | **Unit:** `inches` How many inches forward or back of the hips is the shooter's left ankle as the left foot leaves the ground. To measure this, imagine a graph based on the way the hips are facing, with the center (at 0, 0) being the middle of the hips, the vertical axis being forward-back and the horizontal axis being side-to-side. This field shows the distance on the vertical axis between the ankle point and the middle of the hips. `null` if no shot jump detected. ### Foot Angle #### `right_foot_angle_to_hoop_at_jump_start` **Type:** `float` | **Unit:** `degrees` The angle formed by the center of the rim, the heel of the right foot, and the midpoint of the big and little toes. If the foot is pointing straight at the rim, this would be 0 degrees; to the left side of the hoop, this angle will be negative; to the right will be positive. `null` if no shot jump detected. Foot angle to hoop illustration --- #### `left_foot_angle_to_hoop_at_jump_start` **Type:** `float` | **Unit:** `degrees` The angle formed by the center of the rim, the heel of the left foot, and the midpoint of the big and little toes. If the foot is pointing straight at the rim, this would be 0 degrees; to the left side of the hoop, this angle will be negative; to the right will be positive. `null` if no shot jump detected. ### Heel and Toe Distance #### `heel_distance_at_jump_start_inches` **Type:** `float` | **Unit:** `inches` How far apart are the shooter's heels, measured as each foot leaves the floor. This is measured in two dimensions, i.e. it ignores a difference in height. `null` if no shot jump detected. Heel distance illustration --- #### `mid_toe_distance_at_jump_start_inches` **Type:** `float` | **Unit:** `inches` How far apart is the midpoint of the shooter's toes on each foot, measured as each foot leaves the floor. This is measured in two dimensions, i.e. it ignores a difference in height. `null` if no shot jump detected. --- #### `mid_toe_heel_dist_difference_at_jump_start_inches` **Type:** `float` | **Unit:** `inches` Toe distance minus heel distance. Positive = feet turned out, negative = turned in. `null` if no shot jump detected. Toe heel distance difference illustration *Paul George's toes are turned in on this shot. The value of this field for this shot is -6.6.* --- ### Shooting Arm Position ### At Set Point #### `shooting_wrist_elbow_shoulder_angle_at_set_point` **Type:** `float` | **Unit:** `degrees` Angle formed by wrist, elbow, shoulder (from the side). Wrist elbow shoulder angle illustration --- #### `shooting_elbow_shoulder_hip_angle_at_set_point` **Type:** `float` | **Unit:** `degrees` Angle formed by elbow, shoulder, hip. Elbow shoulder hip angle illustration --- #### `shooting_elbow_shoulder_hoop_angle_at_set_point` **Type:** `float` | **Unit:** `degrees` Measures where the elbow is pointing relative to the hoop. This tells you the angle formed by the shooting elbow, shooting shoulder, and hoop at the set point, where 0 degrees would be aiming straight at the rim, negative is to the left of the rim and positive to the right. Elbow shoulder hoop angle illustration --- #### `shooting_elbow_flare_angle_at_set_point` **Type:** `float` | **Unit:** `degrees` How flared out or in is the shooting elbow relative to the shoulders at the set point. 0 degrees would mean the elbow is directly in line with the way the shoulders are pointing, a positive number means it's flared out away from the center of the body (regardless of whether it's the left or right arm), a negative number would mean it's pointed in toward the center of the body. ### Elbow/Wrist Relative to Ball #### `elbow_relative_to_ball_at_set_forward_back_inches` **Type:** `float` | **Unit:** `inches` Viewed from above, how far in front of or behind the center of the ball is the elbow at the set point. The forward-back axis here is the line from the center of the ball to the center of the rim. --- #### `elbow_relative_to_ball_at_set_side_to_side_inches` **Type:** `float` | **Unit:** `inches` Viewed from above, how far to the left or right of the center of the ball is the elbow at the set point. The side-to-side axis here is the line perpendicular to the line from the center of the ball to the center of the rim. Negative is to the left of the ball, positive is to the right. --- #### `elbow_relative_to_ball_at_release_forward_back_inches` **Type:** `float` | **Unit:** `inches` Viewed from above, how far in front of or behind the center of the ball is the elbow at the release point. The forward-back axis here is the line from the center of the ball to the center of the rim. --- #### `elbow_relative_to_ball_at_release_side_to_side_inches` **Type:** `float` | **Unit:** `inches` Viewed from above, how far to the left or right of the center of the ball is the elbow at the release point. The side-to-side axis here is the line perpendicular to the line from the center of the ball to the center of the rim. Negative is to the left of the ball, positive is to the right. --- #### `wrist_relative_to_ball_at_set_forward_back_inches` **Type:** `float` | **Unit:** `inches` Viewed from above, how far in front of or behind the center of the ball is the wrist at the set point. The forward-back axis here is the line from the center of the ball to the center of the rim. --- #### `wrist_relative_to_ball_at_set_side_to_side_inches` **Type:** `float` | **Unit:** `inches` Viewed from above, how far to the left or right of the center of the ball is the wrist at the set point. The side-to-side axis here is the line perpendicular to the line from the center of the ball to the center of the rim. Negative is to the left of the ball, positive is to the right. --- #### `wrist_relative_to_ball_at_release_forward_back_inches` **Type:** `float` | **Unit:** `inches` Viewed from above, how far in front of or behind the center of the ball is the wrist at the release point. The forward-back axis here is the line from the center of the ball to the center of the rim. --- #### `wrist_relative_to_ball_at_release_side_to_side_inches` **Type:** `float` | **Unit:** `inches` Viewed from above, how far to the left or right of the center of the ball is the wrist at the release point. The side-to-side axis here is the line perpendicular to the line from the center of the ball to the center of the rim. Negative is to the left of the ball, positive is to the right. --- ### Balance #### `is_off_balance` **Type:** `boolean` `true` if we estimate that the shooter would be judged as off balance when they release the ball, `false` otherwise. We measure this by looking at whether the player is fading any direction in the air at release, whether they jump a far distance in a direction away from the rim, and what their balance and feet are like when they land. ::: tip NOTE This is a more subjective marking than many of the others we've produced data on, but we think it's valuable. We also include all of the inputs we've used for this as separate fields below if you would like to develop your own estimate of balance or simply use each individual field as its own input in a larger model. ::: --- #### `neck_relative_to_feet_midpoint_at_release_xy_distance_in` **Type:** `float` | **Unit:** `inches` Imagine looking at a player from straight overhead as they release their shot. This field measures the two-dimensional distance (ignoring the height distance) between the player's neck and the point in between their left and right ankles. A player standing straight up and down would have their neck right over their ankles (and a distance close to 0), while a player leaning back would have their neck much further from their ankles. --- #### `neck_relative_to_knee_midpoint_at_release_xy_distance_in` **Type:** `float` | **Unit:** `inches` Imagine looking at a player from straight overhead as they release their shot. This field measures the left-to-right distance (i.e. ignoring the height distance) between the player's neck and the point in between their knees. A player standing straight up and down would have their neck right over their knees (and a distance close to 0), while a player leaning back would have their neck much further from their knees. --- #### `neck_relative_to_mid_hip_at_release_xy_distance_in` **Type:** `float` | **Unit:** `inches` Imagine looking at a player from straight overhead as they release their shot. This field measures the two-dimensional distance (ignoring the height distance) between the player's neck and the point in between their left and right hips. A player standing straight up and down would have their neck right over their hips (and a distance close to 0), while a player leaning back would have their neck much further from their hips. --- #### `jump_distance_not_toward_rim_in` **Type:** `float` | **Unit:** `inches` How many inches the player's jump for the shot took them in a direction that was not toward the rim. --- #### `landing_ankle_height_difference_in` **Type:** `float` | **Unit:** `inches` When the player landed from their jump for their shot, how many inches different was the height of their ankles from each other. A player who is off balance when shooting is much more likely to land on one foot and kick the other foot out for balance. --- ### Shot Jump These fields relate to the player's jump into the shot attempt. #### `shot_jump_max_hip_height_vs_standing_hip_height_diff_in` **Type:** `float` | **Unit:** `inches` The maximum number of inches the player got their hips off the ground during the jump above where we estimate they would have been if they were standing on the ground straight up. A value of 12, for example, means the player's mid hip is 12 inches higher in the air than our estimate of their standing mid hip height during this jump. --- #### `shot_jump_distance_mid_hips_in` **Type:** `float` | **Unit:** `inches` The two-dimensional distance covered by the player's jump, based on where their mid hip is at the start and end of the jump. Imagine putting a dot on the floor where the mid hip is when they start their jump and where it is when they land, and then measuring the distance with a tape measure. --- #### `shot_jump_direction_mid_hips` **Type:** `float` | **Unit:** `degrees` The angle formed by the rim, the mid hip location at the start of the jump, and the mid hip location at the end of the jump. 0 degrees would be directly toward the rim, 180 would be directly away. Any negative numbers mean the player went to the left on their jump relative to the rim, positive means to the right. --- #### `shot_jump_distance_ankles_in` **Type:** `float` | **Unit:** `inches` The two-dimensional distance covered by the player's jump, based on where the midpoint of their ankles is at the start and end of the jump. Imagine drawing a line between the two ankles and putting a dot on the floor at the middle of that line when they start their jump and where it is when they land, and then measuring the distance with a tape measure. --- #### `shot_jump_direction_ankles` **Type:** `float` | **Unit:** `degrees` The angle formed by the rim, the midpoint of the ankles at the start of the jump, and the midpoint of the ankles at the end of the jump. 0 degrees would be directly toward the rim, 180 would be directly away. Any negative numbers mean the player went to the left on their jump relative to the rim, positive means to the right. --- #### `jump_shot_footwork_type` **Type:** `string` Classifies the type of footwork the player used to get into their shot jump. **Options:** - `hop` - the player lifts both feet off the ground and lands with them both very close to the same time before jumping for their shot - `left_right` - the player steps into the shot, first with their left foot, then with their right - `right_left` - the player steps into the shot, first with their right foot, then with their left - `plant_foot_left` - the player has their left foot planted on the ground for a reasonable period of time and moves their right foot before jumping to shoot - `plant_foot_right` - the player has their right foot planted on the ground for a reasonable period of time and moves their left foot before jumping to shoot - `both_planted` - both feet are planted on the ground for a reasonable period of time before jumping ===== END PAGE: Data Set: jump-shots ===== ===== BEGIN PAGE: Data Set: jumps ===== # Jumps # Jumps The `jumps` section in the markings response contains one object for every instance of a player jumping. The clock must be running during at least part of the jump for the jump to be included in this data. :::tip NOTE We remove jumps when the game clock is not running because we have found that the player tracking data is frequently unreliable during stoppages. ::: ## Overview At the margins, it is difficult to separate out jumps from other instances where a player may not have either foot on the floor. In particular, very slight hops are hard to distinguish from running with both feet off the ground, skips, or other movements that we might not call jumps but involve very similar movements. We currently err on the side of excluding some of the borderline jumps rather than including too much, but that means some instances that look like jumps where the player barely gets off the floor may be missing from this data. ## Sample Response ```json { "markings": { "jumps": [ { "did_swing_on_rim": false, "game_id_nba": "0022500404", "highest_max_wrist_height_in": 99.51, "jump_distance_in": 10.94, "jump_duration_sec": 0.48, "jump_end_game_clock": 468, "jump_end_he_frame": 25102, "jump_end_shot_clock": 20, "jump_end_wall_clock": "2025-12-23T01:17:32.836+00:00", "jump_id_ctg": "jump_95fb43c1130765f6dd156a6998bf891f", "jump_start_game_clock": 469, "jump_start_he_frame": 25073, "jump_start_shot_clock": 20, "jump_start_wall_clock": "2025-12-23T01:17:32.353+00:00", "jump_type": "jump", "lowest_max_ankle_height_in": 18.71, "lowest_max_big_toe_height_in": 12.08, "max_hip_height_vs_standing_hip_height_diff_in": 14.55, "max_left_ankle_height_in": 18.71, "max_left_big_toe_height_in": 12.08, "max_left_wrist_height_in": 99.51, "max_mid_hip_height_he_frame": 25088, "max_mid_hip_height_wall_clock": "2025-12-23T01:17:32.603+00:00", "max_neck_height_in": 80.82, "max_right_ankle_height_in": 19.17, "max_right_big_toe_height_in": 12.82, "max_right_wrist_height_in": 99.04, "period": 1, "player_id_nba": 202691 } ] } } ``` ## Fields ### Identifiers #### `jump_id_ctg` **Type:** `string` CTG-generated unique identifier for this jump event --- #### `game_id_nba` **Type:** `string` NBA game ID --- #### `player_id_nba` **Type:** `integer` NBA player ID of the jumping player --- ### Jump Timing #### Start The jump start frame is placed when both feet first leave the floor. #### `period` **Type:** `integer` Period when the jump occurred --- #### `jump_start_he_frame` **Type:** `integer` Hawk-Eye frame when both feet first leave the floor --- #### `jump_start_game_clock` **Type:** `float` Game clock at jump start --- #### `jump_start_shot_clock` **Type:** `float` Shot clock at jump start --- #### `jump_start_wall_clock` **Type:** `string` UTC timestamp at jump start #### End The jump end frame is the last frame when both feet are still off the floor (i.e., the frame immediately before landing). #### `jump_end_he_frame` **Type:** `integer` Last Hawk-Eye frame after the jump start when both feet are still off the floor (i.e., the frame immediately before landing) --- #### `jump_end_game_clock` **Type:** `float` Game clock at jump end --- #### `jump_end_shot_clock` **Type:** `float` Shot clock at jump end --- #### `jump_end_wall_clock` **Type:** `string` UTC timestamp at jump end #### Peak #### `max_mid_hip_height_he_frame` **Type:** `integer` Hawk-Eye frame when mid hip height was highest (jump peak) --- #### `max_mid_hip_height_wall_clock` **Type:** `string` UTC timestamp corresponding to `max_mid_hip_height_he_frame`. --- ### Jump Classification #### `jump_type` **Type:** `string` `hop` (small jump, not much height) or `jump` (traditional jump) --- ### Jump Metrics #### `jump_duration_sec` **Type:** `float` | **Unit:** `seconds` Time in the air --- #### `jump_distance_in` **Type:** `float` | **Unit:** `inches` The two-dimensional distance covered by the player's mid hip from start of the jump to the end of the jump. Imagine placing a dot on the floor where the player's mid hip is when he takes off and another when he lands, and then taking a tape measure and measuring the distance between them. --- #### `max_hip_height_vs_standing_hip_height_diff_in` **Type:** `float` | **Unit:** `inches` How many inches the player got their hips off the ground during the jump above where we estimate they would have been if they were standing on the ground straight up. A value of 25, for example, means the player’s mid hip is 25 inches higher in the air than our estimate of their standing mid hip height. If the player's jump peaks and then goes back up (e.g. when hanging on the rim), this is measured at the point where the player's hips first begin to come down from the jump. --- #### `did_swing_on_rim` **Type:** `boolean` `true` if we estimate that the player who jumped swung on the rim to a degree that it will change these jump metrics relative to if he had never touched the rim. For example, on this jump, Jayson Tatum's swing affects the time in air and max hip height: --- ### Height Measurements All heights are measured in inches above the floor. ### Maximum Heights #### `max_neck_height_in` **Type:** `float` | **Unit:** `inches` Highest neck position during jump --- #### `max_right_wrist_height_in` **Type:** `float` | **Unit:** `inches` Highest right wrist position --- #### `max_left_wrist_height_in` **Type:** `float` | **Unit:** `inches` Highest left wrist position --- #### `highest_max_wrist_height_in` **Type:** `float` | **Unit:** `inches` Whichever wrist got higher --- #### `max_right_ankle_height_in` **Type:** `float` | **Unit:** `inches` Highest right ankle position --- #### `max_left_ankle_height_in` **Type:** `float` | **Unit:** `inches` Highest left ankle position --- #### `lowest_max_ankle_height_in` **Type:** `float` | **Unit:** `inches` The lower of the two max ankle heights --- #### `max_right_big_toe_height_in` **Type:** `float` | **Unit:** `inches` Highest right big toe position --- #### `max_left_big_toe_height_in` **Type:** `float` | **Unit:** `inches` Highest left big toe position --- #### `lowest_max_big_toe_height_in` **Type:** `float` | **Unit:** `inches` The lower of the two max toe heights ===== END PAGE: Data Set: jumps ===== ===== BEGIN PAGE: Data Set: passes ===== # Passes # 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_hit_ground_during_completed_pass": false, "catch_distance_forward_in": 23.68, "catch_distance_from_mid_chest_in": 35.37, "catch_distance_left_right_in": 17.8, "catch_height_above_mid_hip_in": 31.74, "catch_height_above_standing_hip_in": 32.98, "catch_height_in": 75.18, "chance_id_ctg": "chance_e9d3153f5458a3aa36815fc17753fd89", "game_id_nba": "0022500404", "intended_receiver_id_ctg": 1629023, "intended_receiver_id_nba": 1629023, "is_jump_pass": false, "is_one_handed_pass": true, "nba_game_id": "0022500404", "pass_handedness": "right", "pass_id_ctg": "pass_0079826aceb4eba4ac64d619ed795067", "pass_release_he_frame": 298364, "pass_release_wall_clock": "2025-12-23T02:49:05.174+00:00", "passer_id_ctg": 1630314, "passer_id_nba": 1630314, "receiver_jumped_for_touch": false, "receiver_touch_start_he_frame": 298392, "receiver_touch_start_wall_clock": "2025-12-23T02:49:05.641+00:00", "receiver_touched_ball": true } ] } } ``` ## Fields ### Identifiers #### `game_id_nba` **Type:** `string` NBA game ID --- #### `nba_game_id` **Type:** `string` NBA game ID ::: warning 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` **Type:** `integer` NBA player ID of the passer ::: warning 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` **Type:** `integer` NBA player ID of the intended receiver ::: warning 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 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: - `right` - `left` - `both` - `null` if player pose data is unavailable for the passer at the time of the pass :::: tip 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 --- ### 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) :::tip 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) ===== END PAGE: Data Set: passes ===== ===== BEGIN PAGE: Data Set: possession-touches ===== # Possession Touches # 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_51bfc1fda2cc0deb125bee9988859667", "duration_sec": 0.78, "end_game_clock": 718.0, "end_he_frame": 167, "end_loc_x": -309.77, "end_loc_y": 84.92, "end_wall_clock": "2025-12-23T01:10:37.24+00:00", "game_id_nba": "0022500404", "is_inbounds": false, "num_dribbles": 0, "outcome_ctg_id": "pass_ddcb210634b503b4b98c8f95610863b1", "outcome_game_clock_seconds": 718, "outcome_pbp_event_id": null, "outcome_type": "pass", "period": 1, "player_id_nba": 1642948, "possession_touch_id_ctg": "possession_touch_0ffa15a0b96c63c29b1d6041f60fb589", "start_game_clock": 719.0, "start_he_frame": 120, "start_loc_x": -297.69, "start_loc_y": 61.2, "start_wall_clock": "2025-12-23T01:10:36.457+00:00", "team_id_nba": 1610612742 } ] } } ``` ## 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. --- ### 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. --- #### `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. --- ### 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 (e.g., shot ID, pass ID). `null` if not applicable or unknown. ===== END PAGE: Data Set: possession-touches ===== ===== BEGIN PAGE: Data Set: possessions ===== # Possessions # Possessions The `possessions` section in the markings response contains an object for each team possession in the game. A team possession is a segment of the game that starts when one team gets the ball and ends when they lose the ball or the period ends. ## Overview While a [`chance`](chances.md) ends when the clock stops or a shot is taken, a possession does not end if the offense retains possession after those events. So a situation where a team takes a shot, misses, gets the offensive rebound, gets fouled without free throws, inbounds the ball, and then turns the ball over are all part of one possession, even though that possession contains three chances. ## Sample Response ```json { "markings": { "possessions": [ { "defensive_team_id_nba": 1610612740, "end_game_clock": 708.0, "end_he_frame": 806, "end_wall_clock": "2025-12-23T01:10:47.889+00:00", "fg_dreb": 0, "fg_oreb": 0, "fga": 1, "fga_pts": 2, "fgm": 1, "fta": 0, "ftm": 0, "game_id_nba": "0022500404", "in_garbage_time": false, "is_after_timeout": true, "offensive_team_id_nba": 1610612742, "period": 1, "possession_id_ctg": "possession_640fb5737252cbe98b4f4a70dcee9d8f", "possession_start_type": "jump_ball", "start_game_clock": 720.0, "start_he_frame": 118, "start_score_away": 0, "start_score_home": 0, "start_wall_clock": "2025-12-23T01:10:36.423+00:00", "tov": 0 } ] } } ``` ## Fields ### Identifiers #### `game_id_nba` **Type:** `string` NBA game ID --- #### `possession_id_ctg` **Type:** `string` CTG-generated unique possession ID --- #### `offensive_team_id_nba` **Type:** `integer` NBA team ID of the offensive team --- #### `defensive_team_id_nba` **Type:** `integer` NBA team ID of the defensive team --- ### Timing ### Period #### `period` **Type:** `integer` Period in which the possession occurred. Overtime would be period 5, double overtime period 6, etc. ### Start #### `start_he_frame` **Type:** `integer` Hawk-Eye frame when possession began --- #### `start_wall_clock` **Type:** `string` UTC timestamp when possession began --- #### `start_game_clock` **Type:** `float` Game clock when possession began --- #### `end_he_frame` **Type:** `integer` Hawk-Eye frame when possession ended --- #### `end_wall_clock` **Type:** `string` UTC timestamp when possession ended --- #### `end_game_clock` **Type:** `float` Game clock when possession ended --- ### Context #### `possession_start_type` **Type:** `string` How the possession began, taken from the `chance_start_type` of the first chance in the possession. See the [`chances`](chances.md#chance-start-type) documentation for possible values. --- #### `is_after_timeout` **Type:** `boolean` `true` if the first chance of the possession immediately follows a timeout. This value comes from the first chance in the possession. --- ### Score #### `start_score_home` **Type:** `integer` Score of the home team at the start of the possession (from the first chance in the possession). --- #### `start_score_away` **Type:** `integer` Score of the away team at the start of the possession (from the first chance in the possession). --- ### Garbage Time #### `in_garbage_time` **Type:** `boolean` `true` if the first chance of the possession occurred during "garbage time". See the [`chances`](chances.md#in-garbage-time) documentation for the definition of garbage time. --- ### Possession Outcomes These fields describe the aggregated outcomes across all chances in the possession. --- #### `fgm` **Type:** `integer` Total field goals made across all chances in the possession. --- #### `fga` **Type:** `integer` Total field goal attempts across all chances in the possession. --- #### `fga_pts` **Type:** `integer` Total points scored on field goal attempts across all chances in the possession (2 or 3 for made shots, 0 for misses). --- #### `ftm` **Type:** `integer` Total free throws made across all chances in the possession. --- #### `fta` **Type:** `integer` Total free throw attempts across all chances in the possession. --- #### `tov` **Type:** `integer` Total turnovers across all chances in the possession. --- #### `fg_dreb` **Type:** `integer` Total defensive rebounds on field goal attempts across all chances in the possession. --- #### `fg_oreb` **Type:** `integer` Total offensive rebounds on field goal attempts across all chances in the possession. ===== END PAGE: Data Set: possessions ===== ===== BEGIN PAGE: Data Set: rebounds ===== # Rebounds # Rebounds The `rebounds` section in the markings response contains information on each official rebound. ## Sample Response ```json { "markings": { "rebounds": [ { "attacking_positive_x": true, "event_pbp_descriptor": null, "event_pbp_id": 14, "event_pbp_qualifiers": null, "event_pbp_rebound_x": 11.51, "event_pbp_rebound_y": 55.39, "event_pbp_subtype": "defensive", "free_throw_id_ctg": null, "game_clock": 673, "game_clock_running": true, "game_id_nba": "0022500404", "is_defensive": true, "is_live_ball_rebound": true, "is_rebounded": true, "pbp_event_id": 14, "period": 1, "player_id_nba": 1630180, "possession_team_id_nba": 1610612742, "rebound_chance_id_ctg": "chance_21ecb103f480c9650f2ee50f13f02cf2", "rebound_he_frame": 5677, "rebound_id_ctg": "rebound_c2533fca1df2c116cf7de28e4acbcc6f", "shot_chance_id_ctg": "chance_c4ed1838eb3166c707182e13c83ebb83", "shot_clock": 24, "shot_clock_running": true, "shot_id_ctg": "shot_c02d176b015b05088e75b098632da86c", "wall_clock": "2025-12-23T01:12:09.084+00:00" } ] } } ``` ## Fields ### Identifiers #### `game_id_nba` **Type:** `string` NBA game ID --- #### `rebound_id_ctg` **Type:** `string` CTG-generated unique rebound ID --- #### `rebound_chance_id_ctg` **Type:** `string` CTG chance ID for the chance that the rebound starts. `null` if the rebound does not start a new chance (e.g. some free throw rebounds, end of period rebounds, etc.) or possibly due to upstream data error --- #### `shot_chance_id_ctg` **Type:** `string` CTG chance ID of the shot that was missed that led to this rebound. `null` for free throw rebounds (or possibly due to upstream data error) --- #### `shot_id_ctg` **Type:** `string` CTG shot ID of the missed shot. `null` for free throws --- #### `free_throw_id_ctg` **Type:** `string` CTG free throw ID if the rebound was a result of a missed free throw. `null` for field goal rebounds --- #### `player_id_nba` **Type:** `integer` NBA player ID of the rebounder. `null` for team rebounds --- #### `pbp_event_id` **Type:** `integer` Play-by-play event ID (i.e. NGSS event ID) for the rebound --- #### `event_pbp_id` **Type:** `integer` Play-by-play event ID (i.e. NGSS event ID) for the rebound ::: warning Deprecated Use `pbp_event_id` instead. This field will be removed in a future version. ::: --- #### `possession_team_id_nba` **Type:** `integer` NBA team ID of the team that secured the rebound --- ### Rebound Type #### `is_live_ball_rebound` **Type:** `boolean` `true` if the rebound was secured as a live ball (not a team rebound or out of bounds) --- #### `is_rebounded` **Type:** `boolean` `true` if the rebound was secured as a live ball (not a team rebound or out of bounds) ::: warning Deprecated Use `is_live_ball_rebound` instead. This field will be removed in a future version. ::: --- #### `is_defensive` **Type:** `boolean` `true` for defensive rebounds, `false` for offensive rebounds --- ### Timing #### `period` **Type:** `integer` Period when the rebound occurred --- #### `game_clock` **Type:** `float` Game clock (seconds remaining) at the rebound --- #### `shot_clock` **Type:** `float` Shot clock at the rebound. `null` if the shot clock is off --- #### `rebound_he_frame` **Type:** `integer` Hawk-Eye frame of the rebound --- #### `wall_clock` **Type:** `string` UTC timestamp of the rebound --- #### `game_clock_running` **Type:** `boolean` `true` if game clock was running --- #### `shot_clock_running` **Type:** `boolean` `true` if shot clock was running --- ### Court Context #### `attacking_positive_x` **Type:** `boolean` `true` if rebounding team is attacking the positive X basket. `null` if not determined ::: warning Deprecated This field is not particularly accurate and not useful in this data set. It will be removed in a future version. ::: --- ### Play-by-Play Data These columns are taken directly from the official play-by-play feed. #### `event_pbp_subtype` **Type:** `string` Rebound type (e.g., `"offensive"`, `"defensive"`) --- #### `event_pbp_descriptor` **Type:** `string` Additional description. `null` if not provided ::: warning Deprecated This field is always `null` and provides no value. It will be removed in a future version. ::: --- #### `event_pbp_qualifiers` **Type:** `string` Qualifier information. `null` if not provided ::: warning Deprecated This information is redundant with other fields in the response. It will be removed in a future version. ::: --- #### `event_pbp_rebound_x` **Type:** `float` X coordinate of the rebound location from play-by-play --- #### `event_pbp_rebound_y` **Type:** `float` Y coordinate of the rebound location from play-by-play ===== END PAGE: Data Set: rebounds ===== ===== BEGIN PAGE: Data Set: shots ===== # Shots # Shots The `shots` section in the markings response contains an object for each official field goal attempt in a game. ## Overview This data set provides complete shot information including timing, location, outcome, and classification. Every shot from the play by play data will appear here, and can be joined with more detailed mechanics data in `jump_shots` or `interior_shots` depending on the shot type. ## Sample Response ```json { "markings": { "shots": [ { "blocker_player_id_nba": null, "chance_id_ctg": "chance_51bfc1fda2cc0deb125bee9988859667", "end_game_clock": 708, "end_he_frame": 761, "end_shot_clock": 13, "end_wall_clock": "2025-12-23T01:10:47.139+00:00", "event_pbp_id": 7, "game_id_nba": "0022500404", "is_and_one": false, "is_bank": false, "is_blocked": false, "is_fouled": false, "is_made": true, "is_three": false, "is_tip": false, "loc_x": 460.5, "loc_y": 13.91, "pbp_event_id": 7, "period": 1, "possession_id_ctg": "possession_640fb5737252cbe98b4f4a70dcee9d8f", "shooter_id_nba": 203076, "shot_distance_in": 42.82, "shot_id_ctg": "shot_105f89542695fcebf740bb7c426ac4c3", "shot_type": "layup", "start_game_clock": 708, "start_he_frame": 749, "start_shot_clock": 14, "start_wall_clock": "2025-12-23T01:10:46.939+00:00", "team_id_nba": 1610612742 } ] } } ``` ## Fields ### Identifiers #### `shot_id_ctg` **Type:** `string` CTG-generated unique shot ID --- #### `game_id_nba` **Type:** `string` NBA game ID --- #### `chance_id_ctg` **Type:** `string` CTG chance ID in which the shot occurred --- #### `possession_id_ctg` **Type:** `string` CTG possession ID in which the shot occurred --- #### `shooter_id_nba` **Type:** `integer` NBA player ID of the shooter --- #### `team_id_nba` **Type:** `integer` NBA team ID of the shooting team --- #### `pbp_event_id` **Type:** `integer` Play-by-play event ID (i.e. NGSS ID) for this shot --- #### `event_pbp_id` **Type:** `integer` Play-by-play event ID (i.e. NGSS ID) for this shot ::: warning Deprecated Use `pbp_event_id` instead. This field will be removed in a future version. ::: --- ### Timing #### `period` **Type:** `integer` Period in which the shot occurred (1-4 for regulation, 5+ for OT) ### Shot Start The shot start is defined as the first frame after the player releases the ball. #### `start_game_clock` **Type:** `float` Game clock (seconds remaining in period) at shot start --- #### `start_shot_clock` **Type:** `float` Shot clock at shot start --- #### `start_he_frame` **Type:** `integer` Hawk-Eye frame at shot start --- #### `start_wall_clock` **Type:** `string` UTC timestamp at shot start ### Shot End The shot end is defined as the first frame where the ball reaches basket height after the shot's peak. Specifically, it's the earliest of: 1. **Close to hoop**: The first frame where the center of the ball is within 16 inches of the center of the hoop and at basket height (between 118-125 inches / ~10 feet) 2. **Below 10 feet**: The first frame where the ball drops below 10 feet after reaching its peak The shot's "peak" is the frame where the ball reaches its highest point and begins descending. If neither condition is met within 5 seconds of the shot release, the peak frame itself is used as the shot end. (This can happen when a shot is blocked out of bounds, for example, so there is no ball tracking data with the ball below 10 feet.) ::: warning Nullable Fields The shot end fields (`end_game_clock`, `end_he_frame`, `end_shot_clock`, `end_wall_clock`) can be `null` in rare cases where upstream HawkEye data has timing issues. When shot end cannot be determined, `is_tip` and `shot_type` will also be `null`. ::: #### `end_game_clock` **Type:** `float` Game clock at shot end. Can be `null` if shot end detection fails due to upstream data issues (see note above). --- #### `end_shot_clock` **Type:** `float` Shot clock at shot end. Can be `null` if shot end detection fails due to upstream data issues (see note above). --- #### `end_he_frame` **Type:** `integer` Hawk-Eye frame at shot end. Can be `null` if shot end detection fails due to upstream data issues (see note above). --- #### `end_wall_clock` **Type:** `string` UTC timestamp at shot end. Can be `null` if shot end detection fails due to upstream data issues (see note above). --- ### Shot Location The shot location is defined as the shooter's centroid at the shot release frame. #### `shot_distance_in` **Type:** `float` | **Unit:** `inches` Distance from the shot location (as defined above) to the center of the basket at the shot release frame. This distance is measured in 2D, i.e. as if you marked a spot on the floor where shooter's centroid was and then measured along the floor to the spot directly under the center of the basket. --- #### `loc_x` **Type:** `float` | **Unit:** `inches` X coordinate of the shot location on the court --- #### `loc_y` **Type:** `float` | **Unit:** `inches` Y coordinate of the shot location on the court --- ### Shot Details #### `shot_type` **Type:** `string` The `shot_type` field classifies the shot using 3D tracking data to analyze movement and release style. Can be `null` if shot end detection fails due to upstream data issues. - **`dunk`**: A dunk or dunk attempt that is not a lob. - **`floater`**: A floater would be a shot taken near the rim and uses one hand to shoot overhand with the player largely facing the basket. A baby hook shot or push shot with the player's shoulder mostly turned to the basket would be different (see below). This also includes runners and shots from further away that are taken without a normal jump shot shooting motion, almost always with a one-handed push shooting motion. - **`heave`**: A shot from very far away taken up against the end of the shot/game clock. - **`hook`**: A shot taken primarily with one hand and with the back or side turned toward the basket, usually not moving toward the basket. - **`jumper`**: A jump shot with two hands on the ball until pushing to release. This includes a large variety of jump shots like a standard jumper, a fadeaway out of the post, a pull up, etc. - **`layup`**: Any shot near the basket that is not a dunk, lob, or tip. Layups and floaters can sometimes be difficult to distinguish. More weight is given to a shot being classified as a layup over a floater if it uses the backboard. - **`lob`**: A shot near the basket where shooter receives a pass and shoots without landing first. Includes lob dunks. - **`lost_ball_on_way_up`**: A shot where the ball is blocked or the player is fouled and loses the ball such that you can’t actually tell which type of shot it was going to be. - **`putback`**: Player dunks or shoots immediately after an offensive rebound without landing. - **`tip`**: Player hits the ball with one hand after a missed shot to tip it in without landing from their jump first. This does not include tips from passes, which would be considered lobs. ::: info Jump Shots vs Interior Shots In other sections of our markings, we separate jump shots from interior shots. `jumper` shots have detailed mechanics in the [`jump_shots`](jump-shots) section, while other shot types have their mechanics in [`interior_shots`](interior-shots). ::: --- #### `is_three` **Type:** `boolean` `true` if the shot was a three-point attempt --- #### `is_tip` **Type:** `boolean` `true` if the shot was a tip-in attempt. Can be `null` if shot end detection fails due to upstream data issues. --- #### `is_made` **Type:** `boolean` `true` if the shot was made --- #### `is_bank` **Type:** `boolean` The `is_bank` field indicates whether the ball hit the front side of the backboard and changed trajectory before hitting the rim. - Returns `true` only if the ball hits the **front** of the backboard first - Returns `false` if the ball hits the side, back, or top of the backboard first - Returns `false` if the ball hits the rim first - Returns `false` if the ball never gets near the backboard before the shot end frame (e.g. an airball) - Returns `null` if the shot is blocked (since we can't determine if it would have been a bank) --- #### `is_blocked` **Type:** `boolean` `true` if the shot was blocked --- #### `blocker_player_id_nba` **Type:** `integer` NBA player ID of the blocker. `null` if not blocked --- #### `is_fouled` **Type:** `boolean` `true` if the shooter was fouled during the shot --- #### `is_and_one` **Type:** `boolean` `true` if the shot was made and the shooter was fouled ===== END PAGE: Data Set: shots ===== ===== BEGIN PAGE: Data Set: turnovers ===== # Turnovers # Turnovers The `turnovers` section in the markings response contains details on each official turnover. ## Sample Response ```json { "markings": { "turnovers": [ { "attacking_positive_x": null, "defensive_team_id_nba": 1610612740, "event_pbp_descriptor": null, "event_pbp_id": 20, "event_pbp_qualifiers": null, "event_pbp_subtype": "badpass", "event_pbp_turnover_total": 1, "game_clock": 636, "game_clock_running": true, "game_id_nba": "0022500404", "pbp_event_id": 20, "period": 1, "player_id_nba": 1642948, "possession_team_id_nba": 1610612742, "shot_clock": 12, "shot_clock_running": true, "stealer_id_nba": 1642852, "turnover_he_frame": 8690, "turnover_id_ctg": "turnover_a2ec347932d326efe9d81bcebcf08390", "turnover_wall_clock": "2025-12-23T01:12:59.297+00:00" } ] } } ``` ## Fields ### Identifiers #### `game_id_nba` **Type:** `string` NBA game ID --- #### `turnover_id_ctg` **Type:** `string` CTG-generated unique turnover ID --- #### `player_id_nba` **Type:** `integer` NBA player ID who committed the turnover --- #### `possession_team_id_nba` **Type:** `integer` NBA team ID of the team that lost possession --- #### `defensive_team_id_nba` **Type:** `integer` NBA team ID of the team that gained possession --- #### `stealer_id_nba` **Type:** `integer` NBA player ID who recorded the steal. `null` if not a steal --- ### Timing #### `period` **Type:** `integer` Period when the turnover occurred --- #### `game_clock` **Type:** `float` Game clock (seconds remaining) at the turnover --- #### `shot_clock` **Type:** `float` Shot clock at the turnover. `null` if the shot clock is off --- #### `turnover_he_frame` **Type:** `integer` Hawk-Eye frame of the turnover. `null` if there is no corresponding Hawk-Eye frame in the Hawk-Eye event data --- #### `turnover_wall_clock` **Type:** `string` UTC timestamp corresponding to `turnover_he_frame`. `null` if there is no corresponding Hawk-Eye frame. --- #### `game_clock_running` **Type:** `boolean` `true` if game clock was running ::: warning Deprecated This field is unreliable and not particularly useful for analyzing turnover events. This field will be removed in a future version. ::: --- #### `shot_clock_running` **Type:** `boolean` `true` if shot clock was running ::: warning Deprecated This field is unreliable and not particularly useful for analyzing turnover events. This field will be removed in a future version. ::: --- ### Court Context #### `attacking_positive_x` **Type:** `boolean` `true` if offensive team was attacking positive X basket. `null` if unknown ::: warning Deprecated This information is not particularly accurate and not useful for analyzing turnover events. This field will be removed in a future version. ::: --- ### Play-by-Play Data #### `pbp_event_id` **Type:** `integer` Play-by-play event ID --- #### `event_pbp_id` **Type:** `integer` Play-by-play event ID ::: warning Deprecated Use `pbp_event_id` instead. This field will be removed in a future version. ::: --- #### `event_pbp_subtype` **Type:** `string` Turnover type (see values below) --- #### `event_pbp_descriptor` **Type:** `string` Additional description (e.g., `"lostball"` for out of bounds). `null` if not provided ::: warning Deprecated This information is not particularly useful for analyzing turnover events. This field will be removed in a future version. ::: --- #### `event_pbp_qualifiers` **Type:** `string` Qualifier information. `null` if not provided ::: warning Deprecated This information is not useful for analyzing turnover events. This field will be removed in a future version. ::: --- #### `event_pbp_turnover_total` **Type:** `integer` Player's turnover total for the game at this point in the game ::: warning Deprecated This data is already available in the official NBA play-by-play feed. This field will be removed in a future version. ::: ===== END PAGE: Data Set: turnovers ===== ===== BEGIN PAGE: Changelog ===== # Changelog # Changelog ## [0.2.0-alpha] - 2026-01-09 ### Added - New [Possession Touches](/data-sets/possession-touches) data set ## [0.1.0-alpha] - 2026-01-08 ### Added - Initial creation of the CTG Pro Data Feed API documentation - New `is_live_ball_rebound` field on [Rebounds](/data-sets/rebounds) data set - Indicates whether the rebound was secured as a live ball (not a team rebound or out of bounds). This is a clearer name for what was previously `is_rebounded` - New `offense_players` and `defense_players` fields on [Chances](/data-sets/chances) data set - Arrays of NBA player IDs for the five players on offense and defense during each chance - New context and outcome fields on [Chances](/data-sets/chances) data set - `in_garbage_time` (indicates if chance occurred during garbage time), `shot_location` (court zone where shot was taken), `is_shot_made`, `is_shot_blocked`, `is_shooter_fouled`, and `led_to_offensive_rebound` (shot outcome indicators) - New statistical fields on [Chances](/data-sets/chances) data set - `fga_pts` (points scored on field goal attempt), `fgm`, `fga`, `ftm`, `fta`, `tov`, `fg_dreb`, and `fg_oreb` (four factors and basic statistics) - Standardized field names across markings data sets for consistency: - New `game_id_nba` field on [Passes](/data-sets/passes), [Deflections](/data-sets/deflections), [Dribbles](/data-sets/dribbles), [Contested Rebound Touches](/data-sets/contested-rebounds), [Anthro Measurements](/data-sets/anthro), [Free Throws](/data-sets/free-throws), [Falls](/data-sets/falls) - Consistent NBA game ID naming - New `player_id_nba` field on [Dribbles](/data-sets/dribbles), [Contested Rebound Touches](/data-sets/contested-rebounds), [Anthro Measurements](/data-sets/anthro), [Free Throws](/data-sets/free-throws), [Falls](/data-sets/falls) - Consistent NBA player ID naming - New `passer_id_nba` and `intended_receiver_id_nba` fields on [Passes](/data-sets/passes) - Correct suffix for NBA player IDs - New `def_player_id_nba` and `off_player_id_nba` fields on [Deflections](/data-sets/deflections) - Added missing `_nba` suffix - New `pbp_event_id` field on [Shots](/data-sets/shots), [Jump Shots](/data-sets/jump-shots), [Jump Shot Contests](/data-sets/jump-shot-contests), [Interior Shots](/data-sets/interior-shots), [Interior Shot Contests](/data-sets/interior-shot-contests), [Rebounds](/data-sets/rebounds), [Fouls](/data-sets/fouls), [Turnovers](/data-sets/turnovers) - Consistent PBP event ID naming - New `set_point_he_frame`, `last_ball_in_hands_he_frame`, `last_ball_in_hands_wall_clock`, `first_shooting_wrist_below_eye_after_release_he_frame`, `first_shooting_wrist_below_eye_after_release_wall_clock`, `first_non_shooting_wrist_below_eye_after_release_he_frame`, `first_non_shooting_wrist_below_eye_after_release_wall_clock` fields on [Free Throws](/data-sets/free-throws) - Aligned naming with Jump Shots - New `possession_id_ctg` field on [Chances](/data-sets/chances) data set - CTG-generated possession ID that links chances to their parent possession, enabling grouping of chances that belong to the same possession (e.g., after offensive rebounds) ### Changed - New `heave` option added to `chance_outcome` on [Chances](/data-sets/chances) data set - Indicates an official heave ### Deprecated - `is_rebounded` on [Rebounds](/data-sets/rebounds) - Use `is_live_ball_rebound` instead. The old field name was confusing; the new name better describes the field's purpose - `attacking_positive_x` on [Rebounds](/data-sets/rebounds) - This information is not particularly accurate and not useful in this data set - `event_pbp_descriptor` on [Rebounds](/data-sets/rebounds) - This field is always `null` and provides no value - `event_pbp_qualifiers` on [Rebounds](/data-sets/rebounds) - This information is redundant with other fields in the response - `attacking_positive_x` on [Fouls](/data-sets/fouls) - This information is not particularly accurate and not so useful in this data set - `event_pbp_foul_personal_total` on [Fouls](/data-sets/fouls) - This data is already available in the official NBA play-by-play feed - `event_pbp_foul_technical_total` on [Fouls](/data-sets/fouls) - This data is already available in the official NBA play-by-play feed - `attacking_positive_x` on [Turnovers](/data-sets/turnovers) - This information is not particularly accurate and not useful for analyzing turnover events - `event_pbp_descriptor` on [Turnovers](/data-sets/turnovers) - This information is not particularly useful for analyzing turnover events - `event_pbp_qualifiers` on [Turnovers](/data-sets/turnovers) - This information is not useful for analyzing turnover events - `event_pbp_turnover_total` on [Turnovers](/data-sets/turnovers) - This data is already available in the official NBA play-by-play feed - Deprecated field names replaced by standardized versions (all retain backward compatibility): - `nba_game_id` on [Passes](/data-sets/passes), [Deflections](/data-sets/deflections), [Dribbles](/data-sets/dribbles), [Contested Rebound Touches](/data-sets/contested-rebounds), [Anthro Measurements](/data-sets/anthro), [Free Throws](/data-sets/free-throws), [Falls](/data-sets/falls) - Use `game_id_nba` instead - `nba_player_id` on [Dribbles](/data-sets/dribbles), [Contested Rebound Touches](/data-sets/contested-rebounds), [Anthro Measurements](/data-sets/anthro), [Free Throws](/data-sets/free-throws), [Falls](/data-sets/falls) - Use `player_id_nba` instead - `passer_id_ctg` and `intended_receiver_id_ctg` on [Passes](/data-sets/passes) - Use `passer_id_nba` and `intended_receiver_id_nba` instead - `def_player_id` and `off_player_id` on [Deflections](/data-sets/deflections) - Use `def_player_id_nba` and `off_player_id_nba` instead - `event_pbp_id` on [Shots](/data-sets/shots), [Jump Shots](/data-sets/jump-shots), [Jump Shot Contests](/data-sets/jump-shot-contests), [Interior Shots](/data-sets/interior-shots), [Interior Shot Contests](/data-sets/interior-shot-contests), [Rebounds](/data-sets/rebounds), [Fouls](/data-sets/fouls), [Turnovers](/data-sets/turnovers) - Use `pbp_event_id` instead - `set_point_frame`, `release_frame`, `release_wall_clock`, `first_frame_shooting_wrist_below_eye`, `shooting_wrist_below_eye_wall_clock`, `first_frame_non_shooting_wrist_below_eye`, `non_shooting_wrist_below_eye_wall_clock` on [Free Throws](/data-sets/free-throws) - Use standardized names matching Jump Shots - `game_clock_running` on [Turnovers](/data-sets/turnovers) - This field is unreliable and not particularly useful for analyzing turnover events - `shot_clock_running` on [Turnovers](/data-sets/turnovers) - This field is unreliable and not particularly useful for analyzing turnover events - `game_clock_running` on [Fouls](/data-sets/fouls) - This field is unreliable and not particularly useful for analyzing foul events - `shot_clock_running` on [Fouls](/data-sets/fouls) - This field is unreliable and not particularly useful for analyzing foul events ## Format and Versioning The changelog format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). It includes the following types of changes: - **Added** - New data sets, fields, or API features - **Changed** - Changes to existing data or behavior (may be breaking) - **Deprecated** - Features that will be removed in future versions - **Removed** - Features that have been removed - **Fixed** - Bug fixes in data accuracy or API behavior The API follows [Semantic Versioning](https://semver.org/) (SemVer). Version numbers are formatted as **MAJOR.MINOR.PATCH** with optional pre-release labels: | Component | When It Changes | Example | |-----------|-----------------|---------| | **MAJOR** | Breaking changes that require client updates | `1.0.0` → `2.0.0` | | **MINOR** | New features added in a backward-compatible way | `1.0.0` → `1.1.0` | | **PATCH** | Bug fixes that don't change the API contract | `1.0.0` → `1.0.1` | ### Pre-release Labels - **alpha** - Early development; API may change significantly between releases - **beta** - Feature complete; API is stabilizing but may still have minor changes - **rc** (release candidate) - Final testing before stable release ### Versioning Policy - **0.x.x versions**: The API is in active development. Breaking changes may occur between minor versions. We will notify you before this occurs. - **1.0.0 and beyond**: The API is stable. Breaking changes will only occur in major version bumps, with advance notice in the changelog. ===== END PAGE: Changelog ===== ===== BEGIN MACHINE-READABLE FIELD CATALOG (fields.json) ===== ```json { "anthro": { "title": "Anthro Measurements", "description": "The `anthro_measurements` section in the markings response contains estimated body measurements for players, sampled from game tracking data. There is an object for each player who appeared in each game.", "fields": { "game_id_nba": { "type": "string", "unit": null, "description": "NBA game ID" }, "nba_game_id": { "type": "string", "unit": null, "description": "NBA game ID ::: warning Deprecated Use `game_id_nba` instead. This field will be removed in a future version. :::" }, "player_id_nba": { "type": "integer", "unit": null, "description": "NBA player ID" }, "nba_player_id": { "type": "integer", "unit": null, "description": "NBA player ID ::: warning Deprecated Use `player_id_nba` instead. This field will be removed in a future version. :::" }, "frames_sampled_for_measurement": { "type": "integer", "unit": null, "description": "Number of frames sampled to calculate these measurements" }, "height_inches": { "type": "float", "unit": "inches", "description": "Estimated player height" }, "wingspan_inches": { "type": "float", "unit": "inches", "description": "Estimated wingspan (estimated middle finger tip to opposite estimated middle finger tip)" }, "right_arm_length_inches": { "type": "float", "unit": "inches", "description": "Right arm length (shoulder to estimated middle finger tip)" }, "left_arm_length_inches": { "type": "float", "unit": "inches", "description": "Left arm length (shoulder to estimated middle finger tip)" }, "right_leg_length_inches": { "type": "float", "unit": "inches", "description": "Right leg length (hip to heel)" }, "left_leg_length_inches": { "type": "float", "unit": "inches", "description": "Left leg length (hip to heel)" }, "mid_hip_to_neck_length_inches": { "type": "float", "unit": "inches", "description": "Torso length (mid hip joint to neck joint)" } } }, "chances": { "title": "Chances", "description": "The `chances` section in the markings response contains an object for each \"chance\". A chance is a segment of the game where the offense has the opportunity to score.", "fields": { "game_id_nba": { "type": "string", "unit": null, "description": "NBA game ID" }, "chance_id_ctg": { "type": "string", "unit": null, "description": "CTG-generated unique chance ID" }, "possession_id_ctg": { "type": "string", "unit": null, "description": "CTG-generated possession ID that this chance belongs to" }, "offensive_team_id_nba": { "type": "integer", "unit": null, "description": "NBA team ID of the team on offense" }, "defensive_team_id_nba": { "type": "integer", "unit": null, "description": "NBA team ID of the team on defense" }, "offense_players": { "type": "array[integer]", "unit": null, "description": "Array of NBA player IDs for the five players on the court on offense during this chance." }, "defense_players": { "type": "array[integer]", "unit": null, "description": "Array of NBA player IDs for the five players on the court on defense during this chance." }, "chance_start_type": { "type": "string", "unit": null, "description": "How the chance began, taken from one of the following options. - **`jump_ball`**: Tip-off or jump ball situation - **`fgm`**: Chance begins immediately after a made field goal (inbound after made basket) - **`ftm`**: Chance begins immediately after a made free throw sequence (inbound after made free throw) - **`steal`**: Gained possession via a live-ball turnover - **`fg_dreb`**: Defensive rebound after a missed field goal - **`fg_dreb_block`**: Defensive rebound after a blocked shot - **`fg_oreb`**: Offensive rebound after a missed field goal - **`ft_dreb`**: Defensive rebound after a missed free throw - **`ft_oreb`**: Offensive rebound after a missed free throw - **`baseline_inbounds`**: Chance begins on a dead-ball inbound from the frontcourt baseline - **`sideline_inbounds`**: Chance begins on a dead-ball inbound from the frontcourt sideline - **`backcourt_inbounds`**: Chance begins on a dead-ball inbound in the backcourt (sideline or baseline)" }, "chance_outcome": { "type": "string", "unit": null, "description": "The outcome of the chance, taken from one of the following options. Shot results: - **`fg2m`**: Made 2-point field goal - **`fg2x`**: Missed 2-point field goal - **`fg3m`**: Made 3-point field goal - **`fg3x`**: Missed 3-point field goal - **`heave`**: A shot designated as an official heave by the scorer - **`fg2m_fouled`**: Made 2-point field goal where the shooter was fouled (and-one) - **`fg3m_fouled`**: Made 3-point field goal where the shooter was fouled (and-one) Turnovers: - **`steal`**: Live-ball turnover - **`deadball_turnover`**: Turnover that stops the clock and requires an inbounds (e.g. traveling, offensive foul, etc.) Fouls: - **`shooting_foul`**: Shooting foul on an attempt (not an and-one make) - **`non-shooting_foul`**: Personal foul not associated with a shot, and not resulting in free throws - **`non-shooting_foul_bonus`**: Non-shooting foul that results in free throws due to the bonus - **`transition_take_foul`**: Transition take foul - **`away_from_the_play_foul`**: Away-from-the-play foul - **`clear_path_foul`**: Clear path foul - **`flagrant_foul`**: Flagrant foul (type 1 or type 2) - **`offensive_foul`**: Offensive foul - **`technical_foul`**: Technical foul - **`technical_defensive_three_second_foul`**: Defensive 3-second technical foul Other endings / stoppages: - **`violation`**: Clock stops due to a violation - **`timeout`**: Chance ends due to a timeout - **`out_of_bounds_retain`**: Ball goes out of bounds and the offense retains possession - **`jump_ball`**: Chance ends in a jump ball situation - **`end_period`**: Period ended - **`other_stoppage`**: Any other stoppage types not covered above" }, "is_after_timeout": { "type": "boolean", "unit": null, "description": "`true` if this chance immediately follows a timeout" }, "start_score_home": { "type": "integer", "unit": null, "description": "Score of the home team at the start of the chance" }, "start_score_away": { "type": "integer", "unit": null, "description": "Score of the away team at the start of the chance" }, "period": { "type": "integer", "unit": null, "description": "Period in which the chance occurred. Overtime would be period 5, double overtime period 6, etc." }, "start_he_frame": { "type": "integer", "unit": null, "description": "Hawk-Eye frame when chance began" }, "start_wall_clock": { "type": "string", "unit": null, "description": "UTC timestamp when chance began" }, "start_game_clock": { "type": "float", "unit": null, "description": "Game clock (seconds remaining) when chance began" }, "start_shot_clock": { "type": "float", "unit": null, "description": "Shot clock when chance began. `null` if shot clock is off at the end of the quarter." }, "end_he_frame": { "type": "integer", "unit": null, "description": "Hawk-Eye frame when chance ended" }, "end_wall_clock": { "type": "string", "unit": null, "description": "UTC timestamp when chance ended" }, "end_game_clock": { "type": "float", "unit": null, "description": "Game clock when chance ended" }, "end_shot_clock": { "type": "float", "unit": null, "description": "Shot clock when chance ended. `null` if shot clock is off at the end of the quarter." }, "frontcourt_he_frame": { "type": "integer", "unit": null, "description": "Hawk-Eye frame when ball first crossed halfcourt into the frontcourt. `null` if the ball never crosses halfcourt during the chance. ::: tip NOTE This does not require a player to be in possession of the ball, it just the first time the x-coordinate of the ball crosses sides of the court in this chance, even if it's in mid-air. :::" }, "frontcourt_wall_clock": { "type": "string", "unit": null, "description": "UTC timestamp corresponding to `frontcourt_he_frame`. `null` if the ball never crosses halfcourt." }, "in_garbage_time": { "type": "boolean", "unit": null, "description": "`true` if this chance occurred during \"garbage time\". We use a definition of garbage time that is as objective as possible and generally matches up with most people's perception of when garbage time starts: when the game is out of hand, both teams have subbed out most of their starters, and the game never gets close again. :::info The Specific Definition The exact definition CTG uses is: the game has to be in the 4th quarter, the score differential has to be >= 25 for minutes 12-9, >= 20 for minutes 9-6, and >= 10 for the remainder of the quarter. Additionally, there have to be two or fewer starters on the floor combined between the two teams. Importantly, the game can never go back to being non-garbage time, or this clock resets. For example, if it's a 30 point game to start the 4th quarter, but one team comes back and pulls the game within 8, that comeback is not counted as garbage time. If the leading team regains control and expands the lead back out, garbage time would start when the score went back above 10. This might not capture all of what we'd call garbage time, but it seems important to err on the side of caution and not mistakenly filter out any game time that we would not consider garbage time. :::" }, "is_shot_made": { "type": "boolean", "unit": null, "description": "`true` if the shot was made, `false` if it was missed. `null` if no shot was taken." }, "is_shot_blocked": { "type": "boolean", "unit": null, "description": "`true` if the shot was blocked. `null` if no shot was taken." }, "is_shooter_fouled": { "type": "boolean", "unit": null, "description": "`true` if the shooter was fouled during the shot attempt. `null` if no shot was taken." }, "led_to_offensive_rebound": { "type": "boolean", "unit": null, "description": "`true` if a missed shot was rebounded by the offensive team. `null` if no shot was taken or if the shot was made." }, "fga_pts": { "type": "integer", "unit": null, "description": "Points scored on the field goal attempt (2 or 3 for made shots, 0 for misses). `null` if no shot was taken or if the chance has not yet been processed into the application layer." }, "fgm": { "type": "integer", "unit": null, "description": "Field goals made. `1` if the shot was made, `0` otherwise. `null` if no shot was taken or if the chance has not yet been processed into the application layer." }, "fga": { "type": "integer", "unit": null, "description": "Field goal attempts. `1` if a shot was attempted (not including shooting fouls without a shot), `0` otherwise. `null` if no shot was taken or if the chance has not yet been processed into the application layer." }, "ftm": { "type": "integer", "unit": null, "description": "Free throws made during this chance. `null` if the chance has not yet been processed into the application layer." }, "fta": { "type": "integer", "unit": null, "description": "Free throw attempts during this chance. `null` if the chance has not yet been processed into the application layer." }, "tov": { "type": "integer", "unit": null, "description": "Turnovers. `1` if the chance ended in a turnover, `0` otherwise. `null` if the chance has not yet been processed into the application layer." }, "fg_dreb": { "type": "integer", "unit": null, "description": "Defensive rebounds on field goal attempts. `1` if the defense rebounded a missed field goal, `0` otherwise. `null` if the chance has not yet been processed into the application layer." }, "fg_oreb": { "type": "integer", "unit": null, "description": "Offensive rebounds on field goal attempts. `1` if the offense rebounded a missed field goal, `0` otherwise. `null` if the chance has not yet been processed into the application layer." }, "shot_location": { "type": "string", "unit": null, "description": "The court zone where the shot was taken, one of the following values: - **`rim`**: At-rim shots (typically within ~4 feet of the basket) - **`short mid`**: Short mid-range shots (~4-14 feet from the basket) - **`long mid`**: Long mid-range shots (~14+ feet, inside the three-point line) - **`corner three`**: Three-point shots from the corner - **`non corner three`**: Three-point shots from above the break - **`heave`**: Full-court or half-court heave attempts `null` if no shot was taken." } } }, "closeouts": { "title": "Closeouts", "description": "The `closeouts` section in the markings response contains a row for each closeout we identify in the tracking data.", "fields": { "game_id_nba": { "type": "string", "unit": null, "description": "NBA game ID" }, "closeout_id_ctg": { "type": "string", "unit": null, "description": "CTG-generated unique closeout ID" }, "chance_id_ctg": { "type": "string", "unit": null, "description": "CTG chance ID" }, "defender_id_nba": { "type": "integer", "unit": null, "description": "NBA player ID of the defender closing out" }, "ball_handler_id_nba": { "type": "integer", "unit": null, "description": "NBA player ID of the offensive player being closed out to" }, "passer_id_nba": { "type": "integer", "unit": null, "description": "NBA player ID of the player who passed to the ball handler" }, "period": { "type": "integer", "unit": null, "description": "Period in which the closeout occurred" }, "start_game_clock": { "type": "float", "unit": null, "description": "Game clock when closeout begins" }, "start_shot_clock": { "type": "float", "unit": null, "description": "Shot clock when closeout begins" }, "start_he_frame": { "type": "integer", "unit": null, "description": "Hawk-Eye frame when closeout begins" }, "start_wall_clock": { "type": "string", "unit": null, "description": "UTC timestamp when closeout begins" }, "end_game_clock": { "type": "float", "unit": null, "description": "Game clock when closeout ends" }, "end_shot_clock": { "type": "float", "unit": null, "description": "Shot clock when closeout ends" }, "end_he_frame": { "type": "integer", "unit": null, "description": "Hawk-Eye frame when closeout ends" }, "end_wall_clock": { "type": "string", "unit": null, "description": "UTC timestamp when closeout ends" }, "closeout_stop_he_frame": { "type": "integer", "unit": null, "description": "Hawk-Eye frame when the closeout player either (a) leaves the ground to jump at the end of the closeout or (b) decelerates significantly to stay in front of the offensive player" }, "closeout_stop_wall_clock": { "type": "string", "unit": null, "description": "UTC timestamp corresponding to `closeout_stop_he_frame`" }, "receiver_touch_start_he_frame": { "type": "integer", "unit": null, "description": "Hawk-Eye frame when the pass receiver's possession touch begins" }, "closeout_result": { "type": "string", "unit": null, "description": "What does the offensive player do after receiving the pass that triggered the closeout? - **`shot`** - immediately shoots the ball or pump fakes and shoots - **`pass`** - passes the ball very soon after receiving it without dribbling - **`drive`** - dribbles toward the basket - **`hold`** - does not do any of the options above. `hold` can include dribbling but not doing so in a way designed to attack the basket." }, "closeout_stop_frame_distance_in": { "type": "float", "unit": "inches", "description": "How many inches the mid hip of the defensive player was from the offensive player at the `closeout_stop_he_frame`" }, "closeout_stop_player_angle": { "type": "float", "unit": "degrees", "description": "The angle formed by the defender, the offensive player and the rim at the `closeout_stop_he_frame`. If these players are in a straight line, the angle would be 0. The angle will be negative when the defender is to the right of the offensive player, as looked at as if you were standing under the basket." }, "closeout_stop_hips_angle": { "type": "float", "unit": "degrees", "description": "The angle formed by the way the defensive player's hips are facing relative to the rim and the offensive player at the `closeout_stop_he_frame`. 0 degrees means if you draw a line from the rim to the offensive player, the defensive player's hips are parallel with that line — i.e. completely square to the offensive player. A positive angle means the defender has his hips turned to his right, a negative angle means to his left." }, "closeout_stop_hips_facing": { "type": "string", "unit": null, "description": "A category for how the defender's hips are facing at the `closeout_stop_he_frame`, attempting to measure whether the defender is forcing no middle, middle, or is square to the offensive player. - **`no_middle`** - when the defender's hips are facing away from the middle of the court, or the defender is significantly to the side of the offensive player in a way that would encourage a drive away from the middle of the court - **`middle`** - when the defender's hips are facing toward the middle of the court, or the defender is significantly to the side of the offensive player in a way that would encourage a drive toward the middle of the court - **`square`** - when the defender's hips and position are not facing either middle or no middle" }, "drive_direction": { "type": "string", "unit": null, "description": "When the `closeout_result` is `drive`, does the offensive player drive toward the middle of the floor or away from the middle of the floor (`no_middle`)? If the `closeout_result` is not `drive`, this field will be `null`." }, "hand_up_timing": { "type": "string", "unit": null, "description": "When does the defender put his hand up? Options: - **`before_catch`** - if the hand is up before the offensive player catches the pass - **`before_action`** - if the hand is up before the player jumps to shoot/passes/drives - **`after_action`** - if the hand is up after the player jumps to shoot/passes/drives - **`null`** - if the defender never gets their hand up" }, "jump_timing": { "type": "string", "unit": null, "description": "When does the defender leave his feet? Options: - **`early`** - if the defender leaves his feet before the offensive player’s action (e.g. bites on a pump fake) - **`normal`** - if the defender leaves his feet in reaction to the offensive player’s action - **`null`** - if the defender never jumps" }, "closeout_attack_style": { "type": "string", "unit": null, "description": "Uses the pose data to determine how the offensive player attacked the closeout: - **`catch_to_shoot`** - caught the pass and immediately got into a shooting position before shooting/making a move - **`catch_to_drive`** - caught the pass in a position oriented for an immediate drive - **`other`** - something else" }, "ball_handler_speed_before_touch_inches_per_sec": { "type": "float", "unit": "inches/second", "description": "The speed of the offensive player's mid hips in the half second before the touch. The combination of this field and `closeout_attack_style` could help you identify things like \"stampede\" catches, for example." }, "region": { "type": "string", "unit": null, "description": "Court region label for where the ball handler is located at the end of the closeout" }, "start_distance": { "type": "float", "unit": null, "description": "Distance (in feet) between defender and ball handler at `start_he_frame`" }, "touch_distance": { "type": "float", "unit": null, "description": "Distance (in feet) between defender and ball handler at the receiver’s touch start frame" } } }, "contested-rebounds": { "title": "Contested Rebound Touches", "description": "The `contested_rebound_touches` section in the markings response gives more detail around “contested rebounds”, i.e. rebounds where at least one player from each team is near the ball when the ball was touched.", "fields": { "contested_rebound_touch_id_ctg": { "type": "string", "unit": null, "description": "CTG-generated unique identifier for this contested rebound touch event" }, "game_id_nba": { "type": "string", "unit": null, "description": "NBA game ID" }, "nba_game_id": { "type": "string", "unit": null, "description": "NBA game ID ::: warning Deprecated Use `game_id_nba` instead. This field will be removed in a future version. :::" }, "player_id_nba": { "type": "integer", "unit": null, "description": "NBA player ID of the nearby player" }, "nba_player_id": { "type": "integer", "unit": null, "description": "NBA player ID of the nearby player ::: warning Deprecated Use `player_id_nba` instead. This field will be removed in a future version. :::" }, "rebound_id_ctg": { "type": "string", "unit": null, "description": "CTG-generated rebound ID" }, "chance_id_ctg": { "type": "string", "unit": null, "description": "CTG chance ID of the chance that the rebound started" }, "rebound_he_frame": { "type": "integer", "unit": null, "description": "Hawk-Eye frame of the rebound" }, "rebound_wall_clock": { "type": "string", "unit": null, "description": "UTC timestamp corresponding to `rebound_he_frame`." }, "touch_group_start_he_frame": { "type": "integer", "unit": null, "description": "First frame when a player touched the ball in this touch group" }, "touch_group_start_wall_clock": { "type": "string", "unit": null, "description": "UTC timestamp corresponding to `touch_group_start_he_frame`." }, "touch_group_end_he_frame": { "type": "integer", "unit": null, "description": "Last frame when a player touched the ball in this touch group" }, "touch_group_end_wall_clock": { "type": "string", "unit": null, "description": "UTC timestamp corresponding to `touch_group_end_he_frame`." }, "is_rebounder": { "type": "boolean", "unit": null, "description": "`true` if this player received credit for the rebound" }, "did_touch_ball": { "type": "boolean", "unit": null, "description": "`true` if this player touched the ball between shot end and rebound" }, "left_hand_dist_to_ball_at_touch_in": { "type": "float", "unit": "inches", "description": "Distance from left hand (midpoint of thumb/pinky) to ball center at touch" }, "right_hand_dist_to_ball_at_touch_in": { "type": "float", "unit": "inches", "description": "Distance from right hand to ball center at touch" }, "ball_height_at_touch_in": { "type": "float", "unit": "inches", "description": "Ball height above floor at touch group start" }, "ball_rim_distance_at_touch_in": { "type": "float", "unit": "inches", "description": "Distance from ball center to rim center at touch group start" }, "did_jump_close_to_touch": { "type": "boolean", "unit": null, "description": "`true` if the player jumped near this touch" }, "nearest_jump_start_he_frame_before_touch": { "type": "integer", "unit": null, "description": "Hawk-Eye frame of nearest jump start before touch (if near). `null` otherwise" }, "nearest_jump_start_wall_clock_before_touch": { "type": "string", "unit": null, "description": "UTC timestamp corresponding to `nearest_jump_start_he_frame_before_touch`. `null` if no jump." }, "nearest_jump_start_he_frame_after_touch": { "type": "integer", "unit": null, "description": "Hawk-Eye frame of nearest jump start after touch (if near). `null` otherwise" }, "nearest_jump_start_wall_clock_after_touch": { "type": "string", "unit": null, "description": "UTC timestamp corresponding to `nearest_jump_start_he_frame_after_touch`. `null` if no jump." }, "jump_max_neck_height_in": { "type": "float", "unit": "inches", "description": "Max neck height during the jump. `null` if no jump" }, "jump_max_wrist_height_in": { "type": "float", "unit": "inches", "description": "Max wrist height during the jump. `null` if no jump" } } }, "deflections": { "title": "Deflections", "description": "The `deflections` section in the markings response contains an object for each time a defender touched the ball with a hand while the game clock is running (or which causes the clock to start running), where the ball is loose or the defensive touch knocks the ball loose.", "fields": { "game_id_nba": { "type": "string", "unit": null, "description": "NBA game ID" }, "nba_game_id": { "type": "string", "unit": null, "description": "NBA game ID ::: warning Deprecated Use `game_id_nba` instead. This field will be removed in a future version. :::" }, "deflection_id_ctg": { "type": "string", "unit": null, "description": "CTG-generated unique deflection ID" }, "chance_id_ctg": { "type": "string", "unit": null, "description": "CTG chance ID" }, "pass_id_ctg": { "type": "string", "unit": null, "description": "If `context` is `pass`, the CTG pass ID. `null` otherwise" }, "def_player_id_nba": { "type": "integer", "unit": null, "description": "NBA player ID of the defender who made the deflection" }, "def_player_id": { "type": "integer", "unit": null, "description": "NBA player ID of the defender who made the deflection ::: warning Deprecated Use `def_player_id_nba` instead. This field will be removed in a future version. :::" }, "off_player_id_nba": { "type": "integer", "unit": null, "description": "NBA player ID of the offensive player who last touched ball. `null` for loose balls" }, "off_player_id": { "type": "integer", "unit": null, "description": "NBA player ID of the offensive player who last touched ball. `null` for loose balls ::: warning Deprecated Use `off_player_id_nba` instead. This field will be removed in a future version. :::" }, "period": { "type": "integer", "unit": null, "description": "Period when the deflection occurred" }, "deflection_touch_start_game_clock": { "type": "float", "unit": null, "description": "Game clock when defender first touched ball" }, "deflection_touch_start_shot_clock": { "type": "float", "unit": null, "description": "Shot clock when defender first touched ball" }, "deflection_touch_start_he_frame": { "type": "integer", "unit": null, "description": "Hawk-Eye frame when defender first touched ball" }, "deflection_touch_start_wall_clock": { "type": "string", "unit": null, "description": "UTC timestamp when defender first touched ball" }, "context": { "type": "string", "unit": null, "description": "Game situation when deflection occurred: - **`pass`**: While offense was attempting to pass or just after pass was received - **`drive`**: While an offensive player was driving to the basket - **`during_offensive_touch`**: While offensive player was touching ball (not passing or driving) - **`other`**: Anything else, usually a loose ball situation" }, "location": { "type": "string", "unit": null, "description": "Deflector's location/role when making the deflection (see values below) - **`on_ball`**: Guarding the passer/ball handler or right on the ball - **`loose_ball`**: Touching the ball while it is loose - **`passing_lane`**: Touching ball during a pass, not close to passer, receiver hasn't caught it - **`receiver`**: Deflecting the ball after the pass has been caught - **`help`**: When `context` is `drive` and deflector is not the ball handler's matchup" }, "outcome": { "type": "string", "unit": null, "description": "What happens as a result of the deflection: - **`tipped_live_ball`**: Deflector tips the ball and it remains live - **`caught_live_ball`**: Deflector catches the ball and it remains live - **`out_of_bounds`**: Ball goes out of bounds before anyone else touches it - **`foul`**: Deflector commits a foul during the deflection" }, "offense_retains_possession": { "type": "boolean", "unit": null, "description": "`true` if offense keeps the ball (no turnover within 2 seconds), `false` otherwise" }, "is_high_hand_deflection": { "type": "boolean", "unit": null, "description": "`true` if deflection was made with hand up high in the air" } } }, "dribbles": { "title": "Dribbles", "description": "The `dribbles` section in the markings response contains individual dribble events with handedness, timing, and ball height information.", "fields": { "dribble_id_ctg": { "type": "string", "unit": null, "description": "CTG-generated unique identifier for this dribble event" }, "game_id_nba": { "type": "string", "unit": null, "description": "NBA game ID" }, "nba_game_id": { "type": "string", "unit": null, "description": "NBA game ID ::: warning Deprecated Use `game_id_nba` instead. This field will be removed in a future version. :::" }, "player_id_nba": { "type": "integer", "unit": null, "description": "NBA player ID of the dribbler" }, "nba_player_id": { "type": "integer", "unit": null, "description": "NBA player ID of the dribbler ::: warning Deprecated Use `player_id_nba` instead. This field will be removed in a future version. :::" }, "chance_id_ctg": { "type": "string", "unit": null, "description": "CTG chance ID. `null` if the dribble doesn't fall within any chance window (which could occur due to a data error, e.g. the `chances` data not having a correct start and end frame)" }, "period": { "type": "integer", "unit": null, "description": "Period in which the dribble occurred" }, "start_game_clock": { "type": "float", "unit": null, "description": "Game clock (seconds remaining) when ball left dribbler's hands" }, "start_shot_clock": { "type": "float", "unit": null, "description": "Shot clock when ball left hands" }, "start_he_frame": { "type": "integer", "unit": null, "description": "Hawk-Eye frame when ball left hands" }, "start_wall_clock": { "type": "string", "unit": null, "description": "UTC timestamp when ball left hands" }, "end_game_clock": { "type": "float", "unit": null, "description": "Game clock when ball is touched again by dribbler" }, "end_shot_clock": { "type": "float", "unit": null, "description": "Shot clock when ball touched again" }, "end_he_frame": { "type": "integer", "unit": null, "description": "Hawk-Eye frame when ball touched again" }, "end_wall_clock": { "type": "string", "unit": null, "description": "UTC timestamp when ball touched again" }, "dribble_hand": { "type": "string", "unit": null, "description": "`right` or `left` — which hand touched the ball last before the dribble" }, "dribble_end_hand": { "type": "string", "unit": null, "description": "`right` or `left` — which hand touched the ball first after it hit ground" }, "did_switch_hands": { "type": "boolean", "unit": null, "description": "`true` if `dribble_end_hand` differs from `dribble_hand` (e.g. a crossover dribble)" }, "dribble_start_height_in": { "type": "float", "unit": "inches", "description": "Ball height when leaving the player's hand" }, "dribble_end_height_in": { "type": "float", "unit": "inches", "description": "Ball height when player touches it again" } } }, "drives": { "title": "Drives", "description": "The `drives` section in the markings response contains data for offensive drives toward the basket.", "fields": { "game_id_nba": { "type": "string", "unit": null, "description": "NBA game ID" }, "drive_id_ctg": { "type": "string", "unit": null, "description": "CTG-generated unique drive ID" }, "player_id_nba": { "type": "integer", "unit": null, "description": "NBA player ID of the driver" }, "team_id_nba": { "type": "integer", "unit": null, "description": "NBA team ID of the driving team" }, "ball_handler_defender_id_nba": { "type": "integer", "unit": null, "description": "NBA player ID of the primary defender on the ball handler. `null` when there is an upstream error that causes bad chance data which prevents us from identifying the defender." }, "period": { "type": "integer", "unit": null, "description": "Period in which the drive occurred" }, "start_game_clock": { "type": "float", "unit": null, "description": "Game clock when drive began" }, "start_shot_clock": { "type": "float", "unit": null, "description": "Shot clock when drive began" }, "start_he_frame": { "type": "integer", "unit": null, "description": "Hawk-Eye frame when drive began" }, "start_wall_clock": { "type": "string", "unit": null, "description": "UTC timestamp when drive began" }, "end_game_clock": { "type": "float", "unit": null, "description": "Game clock when drive ended" }, "end_shot_clock": { "type": "float", "unit": null, "description": "Shot clock when drive ended" }, "end_he_frame": { "type": "integer", "unit": null, "description": "Hawk-Eye frame when drive ended" }, "end_wall_clock": { "type": "string", "unit": null, "description": "UTC timestamp when drive ended" }, "start_distance_to_hoop_in": { "type": "float", "unit": "inches", "description": "Distance from driver to hoop at drive start" }, "end_distance_to_hoop_in": { "type": "float", "unit": "inches", "description": "Distance from driver to hoop at drive end" }, "max_ballhandler_speed_in_per_sec": { "type": "float", "unit": "inches/second", "description": "Maximum ball handler speed reached during the drive" } } }, "falls": { "title": "Falls", "description": "The `falls` section in the markings response contains one object per time a player is estimated to have fallen to the floor sometime close to live play.", "fields": { "fall_id_ctg": { "type": "string", "unit": null, "description": "CTG-generated unique identifier for this fall event" }, "game_id_nba": { "type": "string", "unit": null, "description": "NBA game ID" }, "nba_game_id": { "type": "string", "unit": null, "description": "NBA game ID ::: warning Deprecated Use `game_id_nba` instead. This field will be removed in a future version. :::" }, "player_id_nba": { "type": "integer", "unit": null, "description": "NBA player ID of the player who fell" }, "nba_player_id": { "type": "integer", "unit": null, "description": "NBA player ID of the player who fell ::: warning Deprecated Use `player_id_nba` instead. This field will be removed in a future version. :::" }, "chance_id_ctg": { "type": "string", "unit": null, "description": "CTG chance ID (if fall occurred during a chance). `null` otherwise" }, "period": { "type": "integer", "unit": null, "description": "Period when the fall occurred" }, "start_he_frame": { "type": "integer", "unit": null, "description": "Hawk-Eye frame when player's hips first got near the ground" }, "start_wall_clock": { "type": "string", "unit": null, "description": "UTC timestamp at fall start" }, "end_he_frame": { "type": "integer", "unit": null, "description": "Hawk-Eye frame when player's hips were no longer near the ground" }, "end_wall_clock": { "type": "string", "unit": null, "description": "UTC timestamp at fall end" }, "duration_sec": { "type": "float", "unit": "seconds", "description": "How long the player's hips continuously remained near the ground during this fall" } } }, "fouls": { "title": "Fouls", "description": "The `fouls` section in the markings response contains foul event data from the game.", "fields": { "game_id_nba": { "type": "string", "unit": null, "description": "NBA game ID" }, "foul_id_ctg": { "type": "string", "unit": null, "description": "CTG-generated foul ID" }, "player_id_nba": { "type": "integer", "unit": null, "description": "NBA player ID of the player who committed the foul" }, "fouled_player_id_nba": { "type": "integer", "unit": null, "description": "NBA player ID of the fouled player" }, "possession_team_id_nba": { "type": "integer", "unit": null, "description": "NBA team ID of the team with possession" }, "period": { "type": "integer", "unit": null, "description": "Period when the foul occurred" }, "game_clock": { "type": "float", "unit": null, "description": "Game clock (seconds remaining) at the foul" }, "shot_clock": { "type": "float", "unit": null, "description": "Shot clock at the foul. `null` if the shot clock is off" }, "foul_he_frame": { "type": "integer", "unit": null, "description": "Hawk-Eye frame of the foul. `null` if there is no corresponding Hawk-Eye frame in the Hawk-Eye event data" }, "foul_wall_clock": { "type": "string", "unit": null, "description": "UTC timestamp corresponding to `foul_he_frame`. `null` if there is no corresponding Hawk-Eye frame." }, "game_clock_running": { "type": "boolean", "unit": null, "description": "`true` if game clock was running ::: warning Deprecated This field is unreliable and not particularly useful for analyzing foul events. This field will be removed in a future version. :::" }, "shot_clock_running": { "type": "boolean", "unit": null, "description": "`true` if shot clock was running ::: warning Deprecated This field is unreliable and not particularly useful for analyzing foul events. This field will be removed in a future version. :::" }, "pbp_event_id": { "type": "integer", "unit": null, "description": "Play-by-play event ID (i.e. NGSS event ID) for the foul" }, "event_pbp_id": { "type": "integer", "unit": null, "description": "Play-by-play event ID (i.e. NGSS event ID) for the foul ::: warning Deprecated Use `pbp_event_id` instead. This field will be removed in a future version. :::" }, "event_pbp_subtype": { "type": "string", "unit": null, "description": "The `sub_type` field from the official play-by-play feed. `null` if not provided" }, "event_pbp_descriptor": { "type": "string", "unit": null, "description": "The `descriptor` field from the official play-by-play feed. `null` if not provided" }, "event_pbp_qualifiers": { "type": "string", "unit": null, "description": "The `qualifiers` field from the official play-by-play feed. `null` if not provided" }, "event_pbp_foul_personal_total": { "type": "integer", "unit": null, "description": "Player's personal foul total for the game. `null` if not provided ::: warning Deprecated This data is already available in the official NBA play-by-play feed. This field will be removed in a future version. :::" }, "event_pbp_foul_technical_total": { "type": "integer", "unit": null, "description": "Player's technical foul total. `null` if not provided ::: warning Deprecated This data is already available in the official NBA play-by-play feed. This field will be removed in a future version. :::" }, "attacking_positive_x": { "type": "boolean", "unit": null, "description": "`true` if offensive team is attacking the positive X basket. `null` if unknown ::: warning Deprecated This information is not relevant to analyzing foul events. This field will be removed in a future version. :::" } } }, "free-throws": { "title": "Free Throws", "description": "The `free_throws` section in the markings response contains shooting mechanics data for every free throw attempt, similar to jump shot data but without jump-related fields.", "fields": { "free_throw_id_ctg": { "type": "string", "unit": null, "description": "CTG-generated unique identifier for this free throw event" }, "game_id_nba": { "type": "string", "unit": null, "description": "NBA game ID" }, "nba_game_id": { "type": "string", "unit": null, "description": "NBA game ID ::: warning Deprecated Use `game_id_nba` instead. This field will be removed in a future version. :::" }, "player_id_nba": { "type": "integer", "unit": null, "description": "NBA player ID of the shooter" }, "nba_player_id": { "type": "integer", "unit": null, "description": "NBA player ID of the shooter ::: warning Deprecated Use `player_id_nba` instead. This field will be removed in a future version. :::" }, "pbp_event_id": { "type": "integer", "unit": null, "description": "Play-by-play event ID (i.e. NGSS ID) for this free throw" }, "is_made": { "type": "boolean", "unit": null, "description": "`true` if the free throw was made" }, "first_ball_in_hands_he_frame": { "type": "integer", "unit": null, "description": "First frame where shooter has both hands on the ball continuously until release ::: tip NOTE This frame may be well before the actual shooting motion if the player has the ball in both hands the entire time. For example, if the shooter catches and holds the ball for a while and then goes into their shooting motion, this frame would be multiple seconds before the shooting motion begins. :::" }, "first_ball_in_hands_wall_clock": { "type": "string", "unit": null, "description": "UTC timestamp of the above frame" }, "min_ball_height_he_frame": { "type": "integer", "unit": null, "description": "Frame where ball is at lowest height before upward motion into shot" }, "min_ball_height_wall_clock": { "type": "string", "unit": null, "description": "UTC timestamp of the above frame" }, "min_hips_height_he_frame": { "type": "integer", "unit": null, "description": "Frame where mid hips are at lowest height before upward motion" }, "min_hips_height_wall_clock": { "type": "string", "unit": null, "description": "UTC timestamp of the above frame" }, "set_point_he_frame": { "type": "integer", "unit": null, "description": "Our estimate for the \"set point\" of the shot. We define this as the point in which the ball is furthest back away from the rim before it starts going forward towards the rim." }, "set_point_frame": { "type": "integer", "unit": null, "description": "Our estimate for the \"set point\" of the shot ::: warning Deprecated Use `set_point_he_frame` instead. This field will be removed in a future version. :::" }, "set_point_wall_clock": { "type": "string", "unit": null, "description": "UTC timestamp of the above frame" }, "last_ball_in_hands_he_frame": { "type": "integer", "unit": null, "description": "Our estimate for the \"release point\" of the shot. This is the first frame where we are confident the ball is not touching either hand." }, "release_frame": { "type": "integer", "unit": null, "description": "Our estimate for the \"release point\" of the shot ::: warning Deprecated Use `last_ball_in_hands_he_frame` instead. This field will be removed in a future version. :::" }, "last_ball_in_hands_wall_clock": { "type": "string", "unit": null, "description": "UTC timestamp of the above frame" }, "release_wall_clock": { "type": "string", "unit": null, "description": "UTC timestamp of the above frame ::: warning Deprecated Use `last_ball_in_hands_wall_clock` instead. This field will be removed in a future version. :::" }, "first_shooting_wrist_below_eye_after_release_he_frame": { "type": "integer", "unit": null, "description": "First frame where shooting wrist drops below eye level after release" }, "first_frame_shooting_wrist_below_eye": { "type": "integer", "unit": null, "description": "First frame where shooting wrist drops below eye level after release ::: warning Deprecated Use `first_shooting_wrist_below_eye_after_release_he_frame` instead. This field will be removed in a future version. :::" }, "first_shooting_wrist_below_eye_after_release_wall_clock": { "type": "string", "unit": null, "description": "UTC timestamp of the above frame" }, "shooting_wrist_below_eye_wall_clock": { "type": "string", "unit": null, "description": "UTC timestamp of the above frame ::: warning Deprecated Use `first_shooting_wrist_below_eye_after_release_wall_clock` instead. This field will be removed in a future version. :::" }, "first_non_shooting_wrist_below_eye_after_release_he_frame": { "type": "integer", "unit": null, "description": "First frame where non-shooting wrist drops below eye level after release" }, "first_frame_non_shooting_wrist_below_eye": { "type": "integer", "unit": null, "description": "First frame where non-shooting wrist drops below eye level after release ::: warning Deprecated Use `first_non_shooting_wrist_below_eye_after_release_he_frame` instead. This field will be removed in a future version. :::" }, "first_non_shooting_wrist_below_eye_after_release_wall_clock": { "type": "string", "unit": null, "description": "UTC timestamp of the above frame" }, "non_shooting_wrist_below_eye_wall_clock": { "type": "string", "unit": null, "description": "UTC timestamp of the above frame ::: warning Deprecated Use `first_non_shooting_wrist_below_eye_after_release_wall_clock` instead. This field will be removed in a future version. :::" }, "hand_closest_to_ball_on_release": { "type": "string", "unit": null, "description": "Whether the `left` or `right` hand is closer to the center of the ball at release. This is almost always the shooting hand of the shooter, so it is a good way to filter these metrics based on the shooter's handedness." }, "release_angle": { "type": "float", "unit": "degrees", "description": "The angle the ball is released at from the shooter's hands, in degrees. 90 degrees would be straight up in the air, 0 degrees would be in a straight line parallel to the ground. This is calculated between the release frame and 1/6th of a second later." }, "min_ball_height_relative_to_hips_in": { "type": "float", "unit": "inches", "description": "How many inches above the shooter's mid hip joint the ball is at the `min_ball_height_he_frame`, i.e. when the ball is at its lowest point before the upward motion into the shot." }, "ball_release_height_in": { "type": "float", "unit": "inches", "description": "Ball height above ground at release" }, "release_height_above_nose_in": { "type": "float", "unit": "inches", "description": "Ball height above shooter's nose at release" }, "set_point_height_in": { "type": "float", "unit": "inches", "description": "Ball height above ground at set point" }, "set_point_height_above_nose_in": { "type": "float", "unit": "inches", "description": "Ball height above shooter's nose at set point" }, "ball_height_relative_to_neck_at_min_hips_in": { "type": "float", "unit": "inches", "description": "How many inches the ball is above the neck at the `min_hips_height_he_frame`, when the hips are at their lowest point before the upward motion into the shot." }, "release_height_above_min_ball_height_in": { "type": "float", "unit": "inches", "description": "How many inches the ball is released above the height of the ball at the `min_ball_height_he_frame`, i.e. when the ball is at its lowest point before the upward motion into the shot." }, "set_height_above_min_ball_height_in": { "type": "float", "unit": "inches", "description": "How much higher the ball is at the set point vs. the `min_ball_height_he_frame`." }, "set_point_ball_position_side_to_side_in": { "type": "float", "unit": "inches", "description": "How many inches the ball is to the left or right of the nose at the set point. Positive values are to the left, negative values to the right." }, "min_ball_height_ball_position_side_to_side_in": { "type": "float", "unit": "inches", "description": "How many inches the ball is to the left or right of the nose at the `min_ball_height_he_frame`. Positive values are to the left, negative values to the right." }, "release_point_ball_position_side_to_side_in": { "type": "float", "unit": "inches", "description": "How many inches the ball is to the left or right of the nose at release. Positive values are to the left, negative values to the right." }, "set_point_ball_position_forward_to_back_in": { "type": "float", "unit": "inches", "description": "Ball distance in front of nose at set point" }, "min_ball_height_ball_position_forward_to_back_in": { "type": "float", "unit": "inches", "description": "Ball distance in front of nose at min ball height" }, "release_point_ball_position_forward_to_back_in": { "type": "float", "unit": "inches", "description": "Ball distance in front of nose at release" }, "ball_in_hands_sec": { "type": "float", "unit": "seconds", "description": "Duration from first ball in hands to release" }, "set_to_release_sec": { "type": "float", "unit": "seconds", "description": "Duration from set point to release" }, "ball_in_hands_to_min_hips_sec": { "type": "float", "unit": "seconds", "description": "Duration from first ball in hands to min hips" }, "shooting_wrist_above_eye_after_release_sec": { "type": "float", "unit": "seconds", "description": "How many seconds the shooting hand remained above the shooter's eye level after release. This can help with measuring a player holding their follow through." }, "non_shooting_wrist_above_eye_after_release_sec": { "type": "float", "unit": "seconds", "description": "How many seconds the non-shooting hand (aka guide hand) remained above the shooter's eye level after release." }, "ball_velocity_min_ball_to_set_inches_per_sec": { "type": "float", "unit": "in/sec", "description": "How many inches the ball traveled from the `min_ball_height_he_frame` to the set point divided by how many seconds elapsed in that time." }, "ball_velocity_set_to_release_inches_per_sec": { "type": "float", "unit": "in/sec", "description": "How many inches the ball traveled from the set point to release divided by how many seconds elapsed in that time." }, "ball_velocity_after_release_inches_per_sec": { "type": "float", "unit": "in/sec", "description": "How many inches the ball traveled from release to 1/6th of a second later divided by how many seconds elapsed in that time." }, "vertical_shoulder_tilt_at_min_hips": { "type": "float", "unit": "degrees", "description": "A measurement of how tilted to the right or left the shoulders are at the `min_hips_height_he_frame`. 0 degrees means parallel to the ground, 90 degrees would mean the shoulders are stacked vertically, one on top of the other (i.e. the player is sideways in the air). Negative values mean the right shoulder is higher than the left, positive values mean the left shoulder is higher than the right." }, "hip_facing_angle_relative_to_rim_at_first_ball_in_hands": { "type": "float", "unit": "degrees", "description": "Hip angle at first ball in hands" }, "hip_facing_angle_relative_to_rim_at_min_hips": { "type": "float", "unit": "degrees", "description": "Hip angle at min hips" }, "hip_facing_angle_relative_to_rim_at_release": { "type": "float", "unit": "degrees", "description": "Hip angle at release" }, "hip_turn_from_min_hips_to_release": { "type": "float", "unit": "degrees", "description": "The difference in the hip facing angle from the `min_hips_height_he_frame` to release. A positive number means the player rotated to the left, a negative number means they rotated to the right." }, "shoulder_facing_angle_relative_to_rim_at_first_ball_in_hands": { "type": "float", "unit": "degrees", "description": "Shoulder angle at first ball in hands" }, "shoulder_facing_angle_relative_to_rim_at_min_hips": { "type": "float", "unit": "degrees", "description": "Shoulder angle at min hips" }, "shoulder_facing_angle_relative_to_rim_at_release": { "type": "float", "unit": "degrees", "description": "Shoulder angle at release" }, "shoulder_turn_from_min_hips_to_release": { "type": "float", "unit": "degrees", "description": "The difference in the shoulder facing angle from the `min_hips_height_he_frame` to release. A positive number means the player rotated to the left, a negative number means they rotated to the right." }, "left_knee_bend_angle_at_min_hips": { "type": "float", "unit": "degrees", "description": "Left knee angle at min hips" }, "left_knee_bend_angle_at_min_ball": { "type": "float", "unit": "degrees", "description": "Left knee angle at min ball height" }, "right_knee_bend_angle_at_min_hips": { "type": "float", "unit": "degrees", "description": "Right knee angle at min hips" }, "right_knee_bend_angle_at_min_ball": { "type": "float", "unit": "degrees", "description": "Right knee angle at min ball height" }, "left_hip_bend_angle_at_min_hips": { "type": "float", "unit": "degrees", "description": "Left hip angle at min hips" }, "left_hip_bend_angle_at_min_ball": { "type": "float", "unit": "degrees", "description": "Left hip angle at min ball height" }, "right_hip_bend_angle_at_min_hips": { "type": "float", "unit": "degrees", "description": "Right hip angle at min hips" }, "right_hip_bend_angle_at_min_ball": { "type": "float", "unit": "degrees", "description": "Right hip angle at min ball height" }, "shooting_wrist_elbow_shoulder_angle_at_set_point": { "type": "float", "unit": "degrees", "description": "Angle formed by wrist, elbow, shoulder (from the side)." }, "shooting_elbow_shoulder_hip_angle_at_set_point": { "type": "float", "unit": "degrees", "description": "Angle formed by elbow, shoulder, hip." }, "shooting_elbow_shoulder_hoop_angle_at_set_point": { "type": "float", "unit": "degrees", "description": "Measures where the elbow is pointing relative to the hoop. This tells you the angle formed by the shooting elbow, shooting shoulder, and hoop at the set point, where 0 degrees would be aiming straight at the rim, negative is to the left of the rim and positive to the right." }, "shooting_elbow_flare_angle_at_set_point": { "type": "float", "unit": "degrees", "description": "How flared out or in is the shooting elbow relative to the shoulders at the set point. 0 degrees would mean the elbow is directly in line with the way the shoulders are pointing, a positive number means it's flared out away from the center of the body (regardless of whether it's the left or right arm), a negative number would mean it's pointed in toward the center of the body." }, "elbow_relative_to_ball_at_set_forward_back_inches": { "type": "float", "unit": "inches", "description": "Viewed from above, how far in front of or behind the center of the ball is the elbow at the set point. The forward-back axis here is the line from the center of the ball to the center of the rim." }, "elbow_relative_to_ball_at_set_side_to_side_inches": { "type": "float", "unit": "inches", "description": "Viewed from above, how far to the left or right of the center of the ball is the elbow at the set point. The side-to-side axis here is the line perpendicular to the line from the center of the ball to the center of the rim. Negative is to the left of the ball, positive is to the right." }, "elbow_relative_to_ball_at_release_forward_back_inches": { "type": "float", "unit": "inches", "description": "Viewed from above, how far in front of or behind the center of the ball is the elbow at the release point. The forward-back axis here is the line from the center of the ball to the center of the rim." }, "elbow_relative_to_ball_at_release_side_to_side_inches": { "type": "float", "unit": "inches", "description": "Viewed from above, how far to the left or right of the center of the ball is the elbow at the release point. The side-to-side axis here is the line perpendicular to the line from the center of the ball to the center of the rim. Negative is to the left of the ball, positive is to the right." }, "wrist_relative_to_ball_at_set_forward_back_inches": { "type": "float", "unit": "inches", "description": "Viewed from above, how far in front of or behind the center of the ball is the wrist at the set point. The forward-back axis here is the line from the center of the ball to the center of the rim." }, "wrist_relative_to_ball_at_set_side_to_side_inches": { "type": "float", "unit": "inches", "description": "Viewed from above, how far to the left or right of the center of the ball is the wrist at the set point. The side-to-side axis here is the line perpendicular to the line from the center of the ball to the center of the rim. Negative is to the left of the ball, positive is to the right." }, "wrist_relative_to_ball_at_release_forward_back_inches": { "type": "float", "unit": "inches", "description": "Viewed from above, how far in front of or behind the center of the ball is the wrist at the release point. The forward-back axis here is the line from the center of the ball to the center of the rim." }, "wrist_relative_to_ball_at_release_side_to_side_inches": { "type": "float", "unit": "inches", "description": "Viewed from above, how far to the left or right of the center of the ball is the wrist at the release point. The side-to-side axis here is the line perpendicular to the line from the center of the ball to the center of the rim. Negative is to the left of the ball, positive is to the right." }, "neck_relative_to_feet_midpoint_at_release_xy_distance_in": { "type": "float", "unit": "inches", "description": "Imagine looking at a player from straight overhead as they release their shot. This field measures the two-dimensional distance (ignoring the height distance) between the player's neck and the point in between their left and right ankles. A player standing straight up and down would have their neck right over their ankles (and a distance close to 0), while a player leaning back would have their neck much further from their ankles." }, "neck_relative_to_knee_midpoint_at_release_xy_distance_in": { "type": "float", "unit": "inches", "description": "2D distance from neck to midpoint between knees" }, "neck_relative_to_mid_hip_at_release_xy_distance_in": { "type": "float", "unit": "inches", "description": "Imagine looking at a player from straight overhead as they release their shot. This field measures the two-dimensional distance (ignoring the height distance) between the player's neck and the point in between their left and right hips. A player standing straight up and down would have their neck right over their hips (and a distance close to 0), while a player leaning back would have their neck much further from their hips." }, "location_relative_to_hoop_center_x": { "type": "float", "unit": "inches", "description": "X coordinate of ball with hoop center as origin" }, "location_relative_to_hoop_center_y": { "type": "float", "unit": "inches", "description": "Y coordinate of ball with hoop center as origin" }, "distance_to_center_of_rim_2d": { "type": "float", "unit": "inches", "description": "2D distance from rim center at entry" }, "entry_angle": { "type": "float", "unit": "degrees", "description": "Ball entry angle. 90° = straight down" }, "entry_speed_inches_per_sec": { "type": "float", "unit": "in/sec", "description": "Ball speed at basket entry" }, "rim_depth": { "type": "float", "unit": "inches", "description": "How far forward/back from rim center. Positive = long, negative = short" }, "rim_left_right": { "type": "float", "unit": "inches", "description": "How far left/right from rim center. Positive = right" } } }, "interior-shot-contests": { "title": "Interior Shot Contests", "description": "The `interior_shot_contests` section in the markings response contains defensive contest information for [interior shots](interior-shots.md).", "fields": { "interior_shot_contest_id_ctg": { "type": "string", "unit": null, "description": "CTG-generated unique identifier for this interior shot contest event" }, "game_id_nba": { "type": "string", "unit": null, "description": "NBA game ID" }, "shot_id_ctg": { "type": "string", "unit": null, "description": "CTG-generated shot ID (can join with `shots` and `interior_shots`)" }, "shooter_id_nba": { "type": "integer", "unit": null, "description": "NBA player ID of the shooter" }, "contester_id_nba": { "type": "integer", "unit": null, "description": "NBA player ID of the defender" }, "pbp_event_id": { "type": "integer", "unit": null, "description": "Play-by-play event ID (i.e. NGSS ID) for this shot" }, "event_pbp_id": { "type": "integer", "unit": null, "description": "Play-by-play event ID (i.e. NGSS ID) for this shot ::: warning Deprecated Use `pbp_event_id` instead. This field will be removed in a future version. :::" }, "did_contester_jump": { "type": "boolean", "unit": null, "description": "`true` if the defender jumped to contest" }, "is_verticality": { "type": "boolean", "unit": null, "description": "`true` if defender was in front with both hands above head. `null` for tip attempts" }, "contester_jump_distance_in": { "type": "float", "unit": null, "description": "2D distance traveled by defender during their contest jump, i.e. measuring the distance along the floor from the jump takeoff point to jump landing point. `null` if no jump" }, "angle_relative_to_shooter_at_release": { "type": "float", "unit": "degrees", "description": "Defender angle at release" }, "angle_relative_to_shooter_at_shooter_jump_start": { "type": "float", "unit": "degrees", "description": "Defender angle at jump start" }, "angle_relative_to_shooter_at_ball_in_hands": { "type": "float", "unit": "degrees", "description": "Defender angle at ball in hands. `null` if ball in hands checkpoint unavailable" }, "position_relative_to_shooter_at_release": { "type": "string", "unit": null, "description": "`front`, `back`, `left`, or `right`" }, "position_relative_to_shooter_at_shooter_jump_start": { "type": "string", "unit": null, "description": "Position at jump start" }, "position_relative_to_shooter_at_ball_in_hands": { "type": "string", "unit": null, "description": "Position at ball in hands. `null` if ball in hands checkpoint unavailable" }, "defender_distance_at_release_in": { "type": "float", "unit": "inches", "description": "2D distance from defender's mid hip to shooter's mid hip at release" }, "defender_distance_at_shooter_jump_start_in": { "type": "float", "unit": "inches", "description": "Distance at jump start" }, "defender_distance_at_ball_in_hands_in": { "type": "float", "unit": "inches", "description": "Distance at ball in hands. `null` if ball in hands checkpoint unavailable" }, "left_hand_eye_height_diff_at_max_jump_in": { "type": "float", "unit": "inches", "description": "Left hand height above left eye at peak of jump. `null` if no jump" }, "right_hand_eye_height_diff_at_max_jump_in": { "type": "float", "unit": "inches", "description": "Right hand height above right eye at peak of jump. `null` if no jump" }, "left_hand_ball_dist_at_release_in": { "type": "float", "unit": "inches", "description": "Left hand distance to ball at release" }, "right_hand_ball_dist_at_release_in": { "type": "float", "unit": "inches", "description": "Right hand distance to ball at release" }, "closest_hand_ball_dist_at_release_in": { "type": "float", "unit": "inches", "description": "Closest hand distance to ball at release" }, "left_hand_ball_dist_at_shooter_jump_start_in": { "type": "float", "unit": "inches", "description": "Left hand distance at jump start" }, "right_hand_ball_dist_at_shooter_jump_start_in": { "type": "float", "unit": "inches", "description": "Right hand distance at jump start" }, "closest_hand_ball_dist_at_shooter_jump_start_in": { "type": "float", "unit": "inches", "description": "Closest hand distance at jump start" }, "left_hand_ball_dist_at_ball_in_hands_in": { "type": "float", "unit": "inches", "description": "Left hand distance at ball in hands. `null` if ball in hands checkpoint unavailable" }, "right_hand_ball_dist_at_ball_in_hands_in": { "type": "float", "unit": "inches", "description": "Right hand distance at ball in hands. `null` if ball in hands checkpoint unavailable" }, "closest_hand_ball_dist_at_ball_in_hands_in": { "type": "float", "unit": "inches", "description": "Closest hand distance at ball in hands. `null` if ball in hands checkpoint unavailable" }, "left_hand_above_head_at_release": { "type": "boolean", "unit": null, "description": "Left hand above head at release" }, "right_hand_above_head_at_release": { "type": "boolean", "unit": null, "description": "Right hand above head at release" }, "closest_hand_above_head_at_release": { "type": "boolean", "unit": null, "description": "Closest hand above head at release" }, "left_hand_above_head_at_shooter_jump_start": { "type": "boolean", "unit": null, "description": "Left hand above head at jump start" }, "right_hand_above_head_at_shooter_jump_start": { "type": "boolean", "unit": null, "description": "Right hand above head at jump start" }, "closest_hand_above_head_at_shooter_jump_start": { "type": "boolean", "unit": null, "description": "Closest hand above head at jump start" }, "left_hand_above_head_at_ball_in_hands": { "type": "boolean", "unit": null, "description": "Left hand above head at ball in hands. `null` if ball in hands checkpoint unavailable" }, "right_hand_above_head_at_ball_in_hands": { "type": "boolean", "unit": null, "description": "Right hand above head at ball in hands. `null` if ball in hands checkpoint unavailable" }, "closest_hand_above_head_at_ball_in_hands": { "type": "boolean", "unit": null, "description": "Closest hand above head at ball in hands. `null` if ball in hands checkpoint unavailable" }, "left_hand_ball_vertical_angle_at_release": { "type": "float", "unit": "degrees", "description": "Left hand vertical angle at release" }, "right_hand_ball_vertical_angle_at_release": { "type": "float", "unit": "degrees", "description": "Right hand vertical angle at release" }, "closest_hand_ball_vertical_angle_at_release": { "type": "float", "unit": "degrees", "description": "Closest hand vertical angle at release" }, "left_hand_ball_vertical_angle_at_shooter_jump_start": { "type": "float", "unit": "degrees", "description": "Left hand vertical angle at jump start" }, "right_hand_ball_vertical_angle_at_shooter_jump_start": { "type": "float", "unit": "degrees", "description": "Right hand vertical angle at jump start" }, "closest_hand_ball_vertical_angle_at_shooter_jump_start": { "type": "float", "unit": "degrees", "description": "Closest hand vertical angle at jump start" }, "left_hand_ball_vertical_angle_at_ball_in_hands": { "type": "float", "unit": "degrees", "description": "Left hand vertical angle at ball in hands. `null` if ball in hands checkpoint unavailable" }, "right_hand_ball_vertical_angle_at_ball_in_hands": { "type": "float", "unit": "degrees", "description": "Right hand vertical angle at ball in hands. `null` if ball in hands checkpoint unavailable" }, "closest_hand_ball_vertical_angle_at_ball_in_hands": { "type": "float", "unit": "degrees", "description": "Closest hand vertical angle at ball in hands. `null` if ball in hands checkpoint unavailable" }, "left_hand_ball_height_diff_at_release_in": { "type": "float", "unit": "inches", "description": "Left hand height diff at release" }, "right_hand_ball_height_diff_at_release_in": { "type": "float", "unit": "inches", "description": "Right hand height diff at release" }, "closest_hand_ball_height_diff_at_release_in": { "type": "float", "unit": "inches", "description": "Closest hand height diff at release" }, "left_hand_ball_height_diff_at_shooter_jump_start_in": { "type": "float", "unit": "inches", "description": "Left hand height diff at jump start" }, "right_hand_ball_height_diff_at_shooter_jump_start_in": { "type": "float", "unit": "inches", "description": "Right hand height diff at jump start" }, "closest_hand_ball_height_diff_at_shooter_jump_start_in": { "type": "float", "unit": "inches", "description": "Closest hand height diff at jump start" }, "left_hand_ball_height_diff_at_ball_in_hands_in": { "type": "float", "unit": "inches", "description": "Left hand height diff at ball in hands. `null` if ball in hands checkpoint unavailable" }, "right_hand_ball_height_diff_at_ball_in_hands_in": { "type": "float", "unit": "inches", "description": "Right hand height diff at ball in hands. `null` if ball in hands checkpoint unavailable" }, "closest_hand_ball_height_diff_at_ball_in_hands_in": { "type": "float", "unit": "inches", "description": "Closest hand height diff at ball in hands. `null` if ball in hands checkpoint unavailable" }, "left_hand_ball_hoop_angle_at_release": { "type": "float", "unit": "degrees", "description": "Left hand horizontal angle at release" }, "right_hand_ball_hoop_angle_at_release": { "type": "float", "unit": "degrees", "description": "Right hand horizontal angle at release" }, "closest_hand_ball_hoop_angle_at_release": { "type": "float", "unit": "degrees", "description": "Closest hand horizontal angle at release" }, "left_hand_ball_hoop_angle_at_shooter_jump_start": { "type": "float", "unit": "degrees", "description": "Left hand horizontal angle at jump start" }, "right_hand_ball_hoop_angle_at_shooter_jump_start": { "type": "float", "unit": "degrees", "description": "Right hand horizontal angle at jump start" }, "closest_hand_ball_hoop_angle_at_shooter_jump_start": { "type": "float", "unit": "degrees", "description": "Closest hand horizontal angle at jump start" }, "left_hand_ball_hoop_angle_at_ball_in_hands": { "type": "float", "unit": "degrees", "description": "Left hand horizontal angle at ball in hands. `null` if ball in hands checkpoint unavailable" }, "right_hand_ball_hoop_angle_at_ball_in_hands": { "type": "float", "unit": "degrees", "description": "Right hand horizontal angle at ball in hands. `null` if ball in hands checkpoint unavailable" }, "closest_hand_ball_hoop_angle_at_ball_in_hands": { "type": "float", "unit": "degrees", "description": "Closest hand horizontal angle at ball in hands. `null` if ball in hands checkpoint unavailable" } } }, "interior-shots": { "title": "Interior Shots", "description": "The `interior_shots` section in the markings response contains mechanics data for shots that are not jump shots or heaves.", "fields": { "game_id_nba": { "type": "string", "unit": null, "description": "NBA game ID" }, "shot_id_ctg": { "type": "string", "unit": null, "description": "CTG-generated unique shot ID (can join with `shots`)" }, "shooter_id_nba": { "type": "integer", "unit": null, "description": "NBA player ID of the shooter" }, "pbp_event_id": { "type": "integer", "unit": null, "description": "Play-by-play event ID (i.e. NGSS ID) for this shot" }, "event_pbp_id": { "type": "integer", "unit": null, "description": "Play-by-play event ID (i.e. NGSS ID) for this shot ::: warning Deprecated Use `pbp_event_id` instead. This field will be removed in a future version. :::" }, "first_ball_in_hands_he_frame": { "type": "integer", "unit": null, "description": "The first frame where the shooter is touching the ball with both hands and doesn't take both hands off the ball until the release of the shot. ::: tip NOTE If the ball is never in both hands and only in one hand (for example, the shooter only gathers the ball with one hand and shoots it without putting the second hand on it, or they tip the ball with one hand) this will be the frame where the shooter's last continuous touch of the ball started before the release. If the data does not show any touch of the ball (because the data is bad or the player never touched the ball, like when a *defender* tips the ball in but someone else gets credit for the shot), this field will be `null`. :::" }, "first_ball_in_hands_wall_clock": { "type": "string", "unit": null, "description": "UTC timestamp corresponding to `first_ball_in_hands_he_frame`. This field can be `null` for the same reasons as `first_ball_in_hands_he_frame`." }, "last_ball_in_hands_he_frame": { "type": "integer", "unit": null, "description": "Our estimate for the \"release point\" of the shot. This is the first frame where we are confident the ball is not touching either hand. ::: tip NOTE This field can be `null` when our ball touch detection algorithm cannot identify the shooter's touch of the ball prior to release (e.g. due to missing or inconsistent tracking data). :::" }, "last_ball_in_hands_wall_clock": { "type": "string", "unit": null, "description": "UTC timestamp corresponding to `last_ball_in_hands_he_frame`. This field can be `null` when upstream data issues prevent detection of the shooter's touch of the ball." }, "last_left_foot_on_floor_he_frame": { "type": "integer", "unit": null, "description": "Frame when left foot leaves floor. This field can be `null` when we do not detect the shooter's feet leaving the ground for the shot (either because the player does not jump or our methods are not sensitive to detect them)." }, "last_left_foot_on_floor_wall_clock": { "type": "string", "unit": null, "description": "UTC timestamp corresponding to `last_left_foot_on_floor_he_frame`. This field can be `null` when we do not detect the shooter's feet leaving the ground for the shot (either because the player does not jump or our methods are not sensitive to detect them)." }, "last_right_foot_on_floor_he_frame": { "type": "integer", "unit": null, "description": "Frame when right foot leaves floor. This field can be `null` when we do not detect the shooter's feet leaving the ground for the shot (either because the player does not jump or our methods are not sensitive to detect them)." }, "last_right_foot_on_floor_wall_clock": { "type": "string", "unit": null, "description": "UTC timestamp corresponding to `last_right_foot_on_floor_he_frame`. This field can be `null` when we do not detect the shooter's feet leaving the ground for the shot (either because the player does not jump or our methods are not sensitive to detect them)." }, "last_hand_to_touch_ball": { "type": "string", "unit": null, "description": "Which hand the player shot with: `right`, `left`, or `both` (for two-handed dunks). ::: tip NOTE This field can be `null` due to upstream data errors or if the player never touches the ball. :::" }, "ball_release_height_in": { "type": "float", "unit": "inches", "description": "Height of ball center above ground at release. ::: tip NOTE This field can be `null` when the release frame is unknown. :::" }, "ball_rim_distance_at_release_in": { "type": "float", "unit": "inches", "description": "Distance from ball center to rim center at release. ::: tip NOTE This field can be `null` when the release frame is unknown. :::" }, "closest_toe_takeoff_distance_in": { "type": "float", "unit": "inches", "description": "Distance from shooter's closest toe to the center of the basket at takeoff. This field can be `null` when we do not detect the shooter's feet leaving the ground for the shot (either because the player does not jump or our methods are not sensitive to detect them)." }, "hand_to_hoop_center_distance": { "type": "float", "unit": "inches", "description": "3D distance from shooting hand (thumb) to rim center at release. This field can be `null` when upstream data issues prevent proper identification of the release frame." }, "takeoff_feet": { "type": "string", "unit": null, "description": "Which foot the shooter jumped from: `right`, `left`, or `both`. This field can be `null` when we do not detect the shooter's feet leaving the ground for the shot (either because the player does not jump or our methods are not sensitive to detect them)." }, "landing_feet": { "type": "string", "unit": null, "description": "Which foot landed first: `right`, `left`, or `both`. This field can be `null` when we do not detect the shooter's feet leaving the ground for the shot (either because the player does not jump or our methods are not sensitive to detect them)." }, "neck_relative_to_feet_midpoint_xy_distance_in": { "type": "float", "unit": "inches", "description": "Imagine looking at a player from straight overhead as they release their shot. This field measures the left-to-right distance (i.e. ignoring the height distance) between the player's neck and the point in between their left and right ankles. This field can be `null` when upstream data issues prevent proper identification of the release frame." }, "neck_relative_to_knee_midpoint_xy_distance_in": { "type": "float", "unit": "inches", "description": "Imagine looking at a player from straight overhead as they release their shot. This field measures the left-to-right distance (i.e. ignoring the height distance) between the player's neck and the point in between their left and right knees. This field can be `null` when upstream data issues prevent proper identification of the release frame." }, "neck_relative_to_mid_hip_xy_distance_in": { "type": "float", "unit": "inches", "description": "Imagine looking at a player from straight overhead as they release their shot. This field measures the left-to-right distance (i.e. ignoring the height distance) between the player's neck and their mid hip. This field can be `null` when upstream data issues prevent proper identification of the release frame." } } }, "jump-shot-contests": { "title": "Jump Shot Contests", "description": "The `jump_shot_contests` section in the markings response contains defensive contest information for every jump shot.", "fields": { "jump_shot_contest_id_ctg": { "type": "string", "unit": null, "description": "CTG-generated unique identifier for this jump shot contest event" }, "game_id_nba": { "type": "string", "unit": null, "description": "NBA game ID" }, "shot_id_ctg": { "type": "string", "unit": null, "description": "CTG-generated shot ID (join with `shots` and `jump_shots`)" }, "shooter_id_nba": { "type": "integer", "unit": null, "description": "NBA player ID of the shooter" }, "contester_id_nba": { "type": "integer", "unit": null, "description": "NBA player ID of the defender" }, "pbp_event_id": { "type": "integer", "unit": null, "description": "Play-by-play event ID (i.e. NGSS ID) for this shot" }, "event_pbp_id": { "type": "integer", "unit": null, "description": "Play-by-play event ID (i.e. NGSS ID) for this shot ::: warning Deprecated Use `pbp_event_id` instead. This field will be removed in a future version. :::" }, "angle_relative_to_shooter_at_release": { "type": "float", "unit": "degrees", "description": "Defender angle at release" }, "angle_relative_to_shooter_at_shooter_jump_start": { "type": "float", "unit": "degrees", "description": "Defender angle at shooter's jump start" }, "angle_relative_to_shooter_at_ball_in_hands": { "type": "float", "unit": "degrees", "description": "Defender angle when ball first in hands" }, "angle_relative_to_shooter_at_min_hips": { "type": "float", "unit": "degrees", "description": "Defender angle at min hips" }, "position_relative_to_shooter_at_release": { "type": "string", "unit": null, "description": "`front`, `back`, `left`, or `right`" }, "position_relative_to_shooter_at_shooter_jump_start": { "type": "string", "unit": null, "description": "Position at jump start" }, "position_relative_to_shooter_at_ball_in_hands": { "type": "string", "unit": null, "description": "Position at ball in hands" }, "position_relative_to_shooter_at_min_hips": { "type": "string", "unit": null, "description": "Position at min hips" }, "contester_ball_dist_at_first_both_hands_on_ball_in": { "type": "float", "unit": "inches", "description": "2D distance from defender's mid hip to ball when shooter first touches it" }, "jump_timing": { "type": "string", "unit": null, "description": "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" }, "closest_hand_at_release": { "type": "string", "unit": null, "description": "`left` or `right` — which hand was closest to ball at release" }, "left_hand_ball_dist_at_release_in": { "type": "float", "unit": "inches", "description": "Left hand distance to ball at release" }, "right_hand_ball_dist_at_release_in": { "type": "float", "unit": "inches", "description": "Right hand distance to ball at release" }, "closest_hand_ball_dist_at_release_in": { "type": "float", "unit": "inches", "description": "Closest hand distance to ball at release" }, "left_hand_ball_dist_at_shooter_jump_start_in": { "type": "float", "unit": "inches", "description": "Left hand distance at jump start" }, "right_hand_ball_dist_at_shooter_jump_start_in": { "type": "float", "unit": "inches", "description": "Right hand distance at jump start" }, "closest_hand_ball_dist_at_shooter_jump_start_in": { "type": "float", "unit": "inches", "description": "Closest hand distance at jump start" }, "left_hand_ball_dist_at_ball_in_hands_in": { "type": "float", "unit": "inches", "description": "Left hand distance at ball in hands" }, "right_hand_ball_dist_at_ball_in_hands_in": { "type": "float", "unit": "inches", "description": "Right hand distance at ball in hands" }, "closest_hand_ball_dist_at_ball_in_hands_in": { "type": "float", "unit": "inches", "description": "Closest hand distance at ball in hands" }, "left_hand_ball_dist_at_min_hips_in": { "type": "float", "unit": "inches", "description": "Left hand distance at min hips" }, "right_hand_ball_dist_at_min_hips_in": { "type": "float", "unit": "inches", "description": "Right hand distance at min hips" }, "closest_hand_ball_dist_at_min_hips_in": { "type": "float", "unit": "inches", "description": "Closest hand distance at min hips" }, "left_hand_above_head_at_release": { "type": "boolean", "unit": null, "description": "Left hand above head at release" }, "right_hand_above_head_at_release": { "type": "boolean", "unit": null, "description": "Right hand above head at release" }, "closest_hand_above_head_at_release": { "type": "boolean", "unit": null, "description": "Closest hand above head at release" }, "left_hand_above_head_at_shooter_jump_start": { "type": "boolean", "unit": null, "description": "Left hand above head at jump start" }, "right_hand_above_head_at_shooter_jump_start": { "type": "boolean", "unit": null, "description": "Right hand above head at jump start" }, "closest_hand_above_head_at_shooter_jump_start": { "type": "boolean", "unit": null, "description": "Closest hand above head at jump start" }, "left_hand_above_head_at_ball_in_hands": { "type": "boolean", "unit": null, "description": "Left hand above head at ball in hands" }, "right_hand_above_head_at_ball_in_hands": { "type": "boolean", "unit": null, "description": "Right hand above head at ball in hands" }, "closest_hand_above_head_at_ball_in_hands": { "type": "boolean", "unit": null, "description": "Closest hand above head at ball in hands" }, "left_hand_above_head_at_min_hips": { "type": "boolean", "unit": null, "description": "Left hand above head at min hips" }, "right_hand_above_head_at_min_hips": { "type": "boolean", "unit": null, "description": "Right hand above head at min hips" }, "closest_hand_above_head_at_min_hips": { "type": "boolean", "unit": null, "description": "Closest hand above head at min hips" }, "left_hand_ball_vertical_angle_at_release": { "type": "float", "unit": "degrees", "description": "Left hand vertical angle at release" }, "right_hand_ball_vertical_angle_at_release": { "type": "float", "unit": "degrees", "description": "Right hand vertical angle at release" }, "closest_hand_ball_vertical_angle_at_release": { "type": "float", "unit": "degrees", "description": "Closest hand vertical angle at release" }, "left_hand_ball_vertical_angle_at_shooter_jump_start": { "type": "float", "unit": "degrees", "description": "Left hand vertical angle at jump start" }, "right_hand_ball_vertical_angle_at_shooter_jump_start": { "type": "float", "unit": "degrees", "description": "Right hand vertical angle at jump start" }, "closest_hand_ball_vertical_angle_at_shooter_jump_start": { "type": "float", "unit": "degrees", "description": "Closest hand vertical angle at jump start" }, "left_hand_ball_vertical_angle_at_ball_in_hands": { "type": "float", "unit": "degrees", "description": "Left hand vertical angle at ball in hands" }, "right_hand_ball_vertical_angle_at_ball_in_hands": { "type": "float", "unit": "degrees", "description": "Right hand vertical angle at ball in hands" }, "closest_hand_ball_vertical_angle_at_ball_in_hands": { "type": "float", "unit": "degrees", "description": "Closest hand vertical angle at ball in hands" }, "left_hand_ball_vertical_angle_at_min_hips": { "type": "float", "unit": "degrees", "description": "Left hand vertical angle at min hips" }, "right_hand_ball_vertical_angle_at_min_hips": { "type": "float", "unit": "degrees", "description": "Right hand vertical angle at min hips" }, "closest_hand_ball_vertical_angle_at_min_hips": { "type": "float", "unit": "degrees", "description": "Closest hand vertical angle at min hips" }, "left_hand_ball_height_diff_at_release_in": { "type": "float", "unit": "inches", "description": "Left hand height diff at release" }, "right_hand_ball_height_diff_at_release_in": { "type": "float", "unit": "inches", "description": "Right hand height diff at release" }, "closest_hand_ball_height_diff_at_release_in": { "type": "float", "unit": "inches", "description": "Closest hand height diff at release" }, "left_hand_ball_height_diff_at_shooter_jump_start_in": { "type": "float", "unit": "inches", "description": "Left hand height diff at jump start" }, "right_hand_ball_height_diff_at_shooter_jump_start_in": { "type": "float", "unit": "inches", "description": "Right hand height diff at jump start" }, "closest_hand_ball_height_diff_at_shooter_jump_start_in": { "type": "float", "unit": "inches", "description": "Closest hand height diff at jump start" }, "left_hand_ball_height_diff_at_ball_in_hands_in": { "type": "float", "unit": "inches", "description": "Left hand height diff at ball in hands" }, "right_hand_ball_height_diff_at_ball_in_hands_in": { "type": "float", "unit": "inches", "description": "Right hand height diff at ball in hands" }, "closest_hand_ball_height_diff_at_ball_in_hands_in": { "type": "float", "unit": "inches", "description": "Closest hand height diff at ball in hands" }, "left_hand_ball_height_diff_at_min_hips_in": { "type": "float", "unit": "inches", "description": "Left hand height diff at min hips" }, "right_hand_ball_height_diff_at_min_hips_in": { "type": "float", "unit": "inches", "description": "Right hand height diff at min hips" }, "closest_hand_ball_height_diff_at_min_hips_in": { "type": "float", "unit": "inches", "description": "Closest hand height diff at min hips" }, "left_hand_ball_hoop_angle_at_release": { "type": "float", "unit": "degrees", "description": "Left hand horizontal angle at release" }, "right_hand_ball_hoop_angle_at_release": { "type": "float", "unit": "degrees", "description": "Right hand horizontal angle at release" }, "closest_hand_ball_hoop_angle_at_release": { "type": "float", "unit": "degrees", "description": "Closest hand horizontal angle at release" }, "left_hand_ball_hoop_angle_at_shooter_jump_start": { "type": "float", "unit": "degrees", "description": "Left hand horizontal angle at jump start" }, "right_hand_ball_hoop_angle_at_shooter_jump_start": { "type": "float", "unit": "degrees", "description": "Right hand horizontal angle at jump start" }, "closest_hand_ball_hoop_angle_at_shooter_jump_start": { "type": "float", "unit": "degrees", "description": "Closest hand horizontal angle at jump start" }, "left_hand_ball_hoop_angle_at_ball_in_hands": { "type": "float", "unit": "degrees", "description": "Left hand horizontal angle at ball in hands" }, "right_hand_ball_hoop_angle_at_ball_in_hands": { "type": "float", "unit": "degrees", "description": "Right hand horizontal angle at ball in hands" }, "closest_hand_ball_hoop_angle_at_ball_in_hands": { "type": "float", "unit": "degrees", "description": "Closest hand horizontal angle at ball in hands" }, "left_hand_ball_hoop_angle_at_min_hips": { "type": "float", "unit": "degrees", "description": "Left hand horizontal angle at min hips" }, "right_hand_ball_hoop_angle_at_min_hips": { "type": "float", "unit": "degrees", "description": "Right hand horizontal angle at min hips" }, "closest_hand_ball_hoop_angle_at_min_hips": { "type": "float", "unit": "degrees", "description": "Closest hand horizontal angle at min hips" }, "min_right_hand_to_ball_dist_after_release_he_frame": { "type": "integer", "unit": null, "description": "Frame when right hand was closest to ball after release" }, "min_right_hand_to_ball_dist_after_release_wall_clock": { "type": "string", "unit": null, "description": "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", "unit": null, "description": "Frame when left hand was closest to ball after release" }, "min_left_hand_to_ball_dist_after_release_wall_clock": { "type": "string", "unit": null, "description": "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", "unit": null, "description": "Minimum distance (inches) from right hand to ball after release" }, "min_left_hand_to_ball_dist_after_release_in": { "type": "float", "unit": null, "description": "Minimum distance (inches) from left hand to ball after release" } } }, "jump-shots": { "title": "Jump Shots", "description": "The `jump_shots` section in the markings response contains shooting mechanics data for every jump shot, including checkpoints (key frames), body positions, timing, and balance metrics.", "fields": { "game_id_nba": { "type": "string", "unit": null, "description": "NBA game ID" }, "shot_id_ctg": { "type": "string", "unit": null, "description": "CTG-generated unique shot ID (can join with `shots`)" }, "shooter_id_nba": { "type": "integer", "unit": null, "description": "NBA player ID of the shooter" }, "pbp_event_id": { "type": "integer", "unit": null, "description": "Play-by-play event ID (i.e. NGSS ID) for this shot" }, "event_pbp_id": { "type": "integer", "unit": null, "description": "Play-by-play event ID (i.e. NGSS ID) for this shot ::: warning Deprecated Use `pbp_event_id` instead. This field will be removed in a future version. :::" }, "first_ball_in_hands_he_frame": { "type": "integer", "unit": null, "description": "First frame where shooter has both hands on the ball continuously until release ::: tip NOTE This frame may be well before the actual shooting motion if the player has the ball in both hands the entire time. For example, if the shooter catches and holds the ball for a while, jabs a few times, and then goes into their shooting motion, this frame would be multiple seconds before the shooting motion begins. :::" }, "first_ball_in_hands_wall_clock": { "type": "string", "unit": null, "description": "UTC timestamp of the above frame" }, "min_ball_height_he_frame": { "type": "integer", "unit": null, "description": "Frame where ball is at lowest height before upward motion into shot" }, "min_ball_height_wall_clock": { "type": "string", "unit": null, "description": "UTC timestamp of the above frame" }, "min_hips_height_he_frame": { "type": "integer", "unit": null, "description": "Frame where mid hips are at lowest height before upward motion. `null` if no minimum hip height before both feet are off the ground (e.g. catch and shoot in midair)" }, "min_hips_height_wall_clock": { "type": "string", "unit": null, "description": "UTC timestamp of the above frame" }, "last_left_foot_on_floor_he_frame": { "type": "integer", "unit": null, "description": "Frame when left foot leaves the floor. `null` if player didn't jump" }, "last_left_foot_on_floor_wall_clock": { "type": "string", "unit": null, "description": "UTC timestamp of the above frame" }, "last_right_foot_on_floor_he_frame": { "type": "integer", "unit": null, "description": "Frame when right foot leaves the floor. `null` if player didn't jump" }, "last_right_foot_on_floor_wall_clock": { "type": "string", "unit": null, "description": "UTC timestamp of the above frame" }, "last_either_foot_on_floor_he_frame": { "type": "integer", "unit": null, "description": "Last frame where either foot is on floor (i.e. the frame right before they are completely in the air). `null` if player didn't jump" }, "last_either_foot_on_floor_wall_clock": { "type": "string", "unit": null, "description": "UTC timestamp of the above frame" }, "jump_end_he_frame": { "type": "integer", "unit": null, "description": "First frame where at least one foot is back on ground after jump. `null` if player didn't jump" }, "jump_end_wall_clock": { "type": "string", "unit": null, "description": "UTC timestamp of the above frame" }, "set_point_he_frame": { "type": "integer", "unit": null, "description": "Our estimate for the \"set point\" of the shot. We define this as the point in which the ball is furthest back away from the rim before it starts going forward towards the rim." }, "set_point_wall_clock": { "type": "string", "unit": null, "description": "UTC timestamp of the above frame" }, "last_ball_in_hands_he_frame": { "type": "integer", "unit": null, "description": "Our estimate for the \"release point\" of the shot. This is the first frame where we are confident the ball is not touching either hand." }, "last_ball_in_hands_wall_clock": { "type": "string", "unit": null, "description": "UTC timestamp of the above frame" }, "first_right_wrist_below_eye_after_release_he_frame": { "type": "integer", "unit": null, "description": "First frame where right wrist drops below eye level after release" }, "first_right_wrist_below_eye_after_release_wall_clock": { "type": "string", "unit": null, "description": "UTC timestamp of the above frame" }, "first_left_wrist_below_eye_after_release_he_frame": { "type": "integer", "unit": null, "description": "First frame where left wrist drops below eye level after release" }, "first_left_wrist_below_eye_after_release_wall_clock": { "type": "string", "unit": null, "description": "UTC timestamp of the above frame" }, "basket_entry_he_frame": { "type": "integer", "unit": null, "description": "The frame where we estimate the ball enters the basket, i.e. when, after the peak of the shot arc, it gets to a height that if it were in a spot to go into the basket that the bottom of the ball would be below the height of the rim. - If the ball is over the rim, this will be the frame in which the ball contacts the rim. - If the ball goes through the basket but hits the back of the rim, this will still be the first frame in which the bottom of the ball is below rim height. - If the ball airballs/is blocked, it will still be the first frame after the peak of the shot where the ball is below the height where it would have gone in the basket had it been in the right spot. - If the ball hits the backboard first, it will still be the frame where the ball reaches the appropriate height." }, "basket_entry_wall_clock": { "type": "string", "unit": null, "description": "UTC timestamp of the `basket_entry_he_frame`." }, "basket_entry_depth": { "type": "float", "unit": "inches", "description": "How many inches forward/back the center of the ball was from the center of the rim at the `basket_entry_he_frame`, from the perspective of the shooter. Positive numbers mean the ball was long, negative means short. We determine the \"perspective of the shooter\" by essentially drawing a line from the ball at release to the center of the rim." }, "basket_entry_left_right": { "type": "float", "unit": "inches", "description": "How many inches left/right the center of the ball was from the center of the rim at the `basket_entry_he_frame`, from the perspective of the shooter. Positive numbers mean the ball was right, negative means left. We determine the \"perspective of the shooter\" by essentially drawing a line from the ball at release to the center of the rim." }, "basket_entry_location_relative_to_hoop_center_x": { "type": "float", "unit": "inches", "description": "The x coordinate of the center of the ball at the `basket_entry_he_frame` if you imagine the center of the hoop as the origin, i.e. coordinate (0,0)." }, "basket_entry_location_relative_to_hoop_center_y": { "type": "float", "unit": "inches", "description": "The y coordinate of the center of the ball at the `basket_entry_he_frame` if you imagine the center of the hoop as the origin, i.e. coordinate (0,0)." }, "basket_entry_distance_to_center_of_rim_2d": { "type": "float", "unit": "inches", "description": "The distance, ignoring the height of the ball, from the center of the rim at the `basket_entry_he_frame`. In other words, imagine looking at the hoop from straight above and putting a dot where the center of the ball is at the `basket_entry_he_frame`. The distance from that dot to the center of the rim is the `basket_entry_distance_to_center_of_rim_2d`." }, "basket_entry_angle": { "type": "float", "unit": "degrees", "description": "The angle formed between the ball at the `basket_entry_he_frame`, the ball 1/10th of a second prior, and the horizontal plane of the ball at the `basket_entry_he_frame`. The ball dropping straight down into the hoop from above would be a 90 degree angle, coming in completely flat in a straight line parallel to the floor would be a 0 degree angle." }, "basket_entry_speed_inches_per_sec": { "type": "float", "unit": "in/sec", "description": "The speed of the ball over the 1/10th of a second prior to the `basket_entry_he_frame`, measured in inches per second. This is calculated by measuring the distance traveled by the ball in that time and multiplying by 10 to scale it to distance per second." }, "hand_closest_to_ball_on_release": { "type": "string", "unit": null, "description": "Whether the `left` or `right` hand is closer to the center of the ball at the `last_ball_in_hands_he_frame`. This is almost always the shooting hand of the shooter, so it is a good way to filter these metrics based on the shooter’s handedness." }, "release_angle": { "type": "float", "unit": "degrees", "description": "The angle the ball is released at from the shooter's hands, in degrees. 90 degrees would be straight up in the air, 0 degrees would be in a straight line parallel to the ground. This is calculated between the `last_ball_in_hands_he_frame` and 1/6th of a second later. `null` for blocked shots." }, "min_ball_height_relative_to_hips_in": { "type": "float", "unit": "inches", "description": "How many inches above the shooter's mid hip joint the ball is at the `min_ball_height_he_frame`, i.e. when the ball is at its lowest point before the upward motion into the shot." }, "ball_release_height_in": { "type": "float", "unit": "inches", "description": "Ball height above ground at release" }, "release_height_above_nose_in": { "type": "float", "unit": "inches", "description": "Ball height above shooter's nose at release" }, "set_point_height_in": { "type": "float", "unit": "inches", "description": "Ball height above ground at set point" }, "set_point_height_above_nose_in": { "type": "float", "unit": "inches", "description": "Ball height above shooter's nose at set point" }, "ball_height_relative_to_neck_at_min_hips_in": { "type": "float", "unit": "inches", "description": "How many inches the ball is above the neck at the `min_hips_height_he_frame`, when the hips are at their lowest point before the upward motion into the shot." }, "release_height_above_min_ball_height_in": { "type": "float", "unit": "inches", "description": "How many inches the ball is released above the height of the ball at the `min_ball_height_he_frame`, i.e. when the ball is at its lowest point before the upward motion into the shot." }, "set_height_above_min_ball_height_in": { "type": "float", "unit": "inches", "description": "How much higher the ball is at the `set_point_he_frame` vs. the `min_ball_height_he_frame`." }, "set_point_ball_position_side_to_side_in": { "type": "float", "unit": "inches", "description": "How many inches the ball is to the left or right of the nose at the `set_point_he_frame`. Positive values are to the left, negative values to the right." }, "min_ball_height_ball_position_side_to_side_in": { "type": "float", "unit": "inches", "description": "How many inches the ball is to the left or right of the nose at the `min_ball_height_he_frame`. Positive values are to the left, negative values to the right." }, "release_point_ball_position_side_to_side_in": { "type": "float", "unit": "inches", "description": "How many inches the ball is to the left or right of the nose at the `last_ball_in_hands_he_frame`. Positive values are to the left, negative values to the right." }, "set_point_ball_position_forward_to_back_in": { "type": "float", "unit": "inches", "description": "Ball position in front of nose at set point" }, "min_ball_height_ball_position_forward_to_back_in": { "type": "float", "unit": "inches", "description": "Ball position in front of nose at min ball height" }, "release_point_ball_position_forward_to_back_in": { "type": "float", "unit": "inches", "description": "Ball position in front of nose at release" }, "ball_rim_distance_at_release_in": { "type": "float", "unit": "inches", "description": "How many inches the center of the ball was from the center of the rim at the `last_ball_in_hands_he_frame`." }, "ball_velocity_min_ball_to_set_inches_per_sec": { "type": "float", "unit": "in/sec", "description": "How many inches the ball traveled from the `min_ball_height_he_frame` to the `set_point_he_frame` divided by how many seconds elapsed in that time." }, "ball_velocity_set_to_release_inches_per_sec": { "type": "float", "unit": "in/sec", "description": "How many inches the ball traveled from the `set_point_he_frame` to the `last_ball_in_hands_he_frame` divided by how many seconds elapsed in that time." }, "ball_velocity_after_release_inches_per_sec": { "type": "float", "unit": "in/sec", "description": "How many inches the ball traveled from the `last_ball_in_hands_he_frame` to 1/6th of a second later divided by how many seconds elapsed in that time. `null` if the shot is blocked." }, "release_relative_to_jump_sec": { "type": "float", "unit": "seconds", "description": "Time from feet leaving floor to ball release" }, "set_relative_to_jump_sec": { "type": "float", "unit": "seconds", "description": "Time from feet leaving floor to set point" }, "set_to_release_sec": { "type": "float", "unit": "seconds", "description": "Duration from set point to release" }, "ball_in_hands_sec": { "type": "float", "unit": "seconds", "description": "Duration from first ball in hands to release" }, "ball_in_hands_to_min_hips_sec": { "type": "float", "unit": "seconds", "description": "Duration from first ball in hands to min hips" }, "release_relative_to_jump_peak_timing": { "type": "float", "unit": "seconds", "description": "Time from release to peak of jump. Negative = released on the way down" }, "shooting_wrist_above_eye_after_release_sec": { "type": "float", "unit": "seconds", "description": "How many seconds the shooting hand remained above the shooter's eye level after the `last_ball_in_hands_he_frame`. This can help with measuring a player holding their follow through." }, "non_shooting_wrist_above_eye_after_release_sec": { "type": "float", "unit": "seconds", "description": "How many seconds the non-shooting hand (aka guide hand) remained above the shooter's eye level after the `last_ball_in_hands_he_frame`." }, "vertical_shoulder_tilt_at_min_hips": { "type": "float", "unit": "degrees", "description": "A measurement of how tilted to the right or left the shoulders are at the `min_hips_height_he_frame`. 0 degrees means parallel to the ground, 90 degrees would mean the shoulders are stacked vertically, one on top of the other (i.e. the player is sideways in the air). Negative values mean the right shoulder is higher than the left, positive values mean the left shoulder is higher than the right." }, "hip_facing_angle_relative_to_rim_at_first_ball_in_hands": { "type": "float", "unit": "degrees", "description": "Hip angle at first ball in hands" }, "hip_facing_angle_relative_to_rim_at_min_hips": { "type": "float", "unit": "degrees", "description": "Hip angle at min hips" }, "hip_facing_angle_relative_to_rim_at_jump_start": { "type": "float", "unit": "degrees", "description": "Hip angle at jump start" }, "hip_facing_angle_relative_to_rim_at_release": { "type": "float", "unit": "degrees", "description": "Hip angle at release" }, "hip_facing_angle_relative_to_rim_at_jump_landing": { "type": "float", "unit": "degrees", "description": "Hip angle at jump landing" }, "hip_turn_from_first_ball_in_hands_to_jump_landing": { "type": "float", "unit": "degrees", "description": "The difference in the hip facing angle from the `first_ball_in_hands_he_frame` to the `jump_end_he_frame`. A positive number means the player rotated to the left, a negative number means they rotated to the right. ::: tip NOTE This will usually be meaningful only for shots where the player went into a shooting motion right after putting both hands on the ball. For those shots, this will show you the full extent of the hip turn from the beginning of the shooting motion through the landing. Otherwise, there may be a significant amount of time between having both hands on the ball and going into the shooting motion and this measurement is unlikely to tell you much in that case. :::" }, "hip_turn_from_min_hips_to_jump_landing": { "type": "float", "unit": "degrees", "description": "The difference in the hip facing angle from the `min_hips_height_he_frame` to the `jump_end_he_frame`. A positive number means the player rotated to the left, a negative number means they rotated to the right." }, "hip_turn_from_jump_start_to_jump_landing": { "type": "float", "unit": "degrees", "description": "The difference in the hip facing angle from the `last_either_foot_on_floor_he_frame` to the `jump_end_he_frame`. A positive number means the player rotated to the left, a negative number means they rotated to the right." }, "hip_turn_from_min_hips_to_release": { "type": "float", "unit": "degrees", "description": "The difference in the hip facing angle from the `min_hips_height_he_frame` to the `last_ball_in_hands_he_frame`. A positive number means the player rotated to the left, a negative number means they rotated to the right." }, "shoulder_facing_angle_relative_to_rim_at_first_ball_in_hands": { "type": "float", "unit": "degrees", "description": "Shoulder angle at first ball in hands" }, "shoulder_facing_angle_relative_to_rim_at_min_hips": { "type": "float", "unit": "degrees", "description": "Shoulder angle at min hips" }, "shoulder_facing_angle_relative_to_rim_at_jump_start": { "type": "float", "unit": "degrees", "description": "Shoulder angle at jump start" }, "shoulder_facing_angle_relative_to_rim_at_release": { "type": "float", "unit": "degrees", "description": "Shoulder angle at release" }, "shoulder_facing_angle_relative_to_rim_at_jump_landing": { "type": "float", "unit": "degrees", "description": "Shoulder angle at jump landing" }, "shoulder_turn_from_first_ball_in_hands_to_jump_landing": { "type": "float", "unit": "degrees", "description": "The difference in the shoulder facing angle from the `first_ball_in_hands_he_frame` to the `jump_end_he_frame`. A positive number means the player rotated to the left, a negative number means they rotated to the right. ::: tip NOTE This will usually be meaningful only for shots where the player went into a shooting motion right after putting both hands on the ball. For those shots, this will show you the full extent of the shoulder turn from the beginning of the shooting motion through the landing. Otherwise, there may be a significant amount of time between having both hands on the ball and going into the shooting motion and this measurement is unlikely to tell you much in that case. :::" }, "shoulder_turn_from_min_hips_to_jump_landing": { "type": "float", "unit": "degrees", "description": "The difference in the shoulder facing angle from the `min_hips_height_he_frame` to the `jump_end_he_frame`. A positive number means the player rotated to the left, a negative number means they rotated to the right." }, "shoulder_turn_from_jump_start_to_jump_landing": { "type": "float", "unit": "degrees", "description": "The difference in the shoulder facing angle from the `last_either_foot_on_floor_he_frame` to the `jump_end_he_frame`. A positive number means the player rotated to the left, a negative number means they rotated to the right." }, "shoulder_turn_from_min_hips_to_release": { "type": "float", "unit": "degrees", "description": "The difference in the shoulder facing angle from the `min_hips_height_he_frame` to the `last_ball_in_hands_he_frame`. A positive number means the player rotated to the left, a negative number means they rotated to the right." }, "left_knee_bend_angle_at_min_hips": { "type": "float", "unit": "degrees", "description": "Left knee angle at min hips" }, "left_knee_bend_angle_at_min_ball": { "type": "float", "unit": "degrees", "description": "Left knee angle at min ball height" }, "right_knee_bend_angle_at_min_hips": { "type": "float", "unit": "degrees", "description": "Right knee angle at min hips" }, "right_knee_bend_angle_at_min_ball": { "type": "float", "unit": "degrees", "description": "Right knee angle at min ball height" }, "left_hip_bend_angle_at_min_hips": { "type": "float", "unit": "degrees", "description": "Left hip angle at min hips" }, "left_hip_bend_angle_at_min_ball": { "type": "float", "unit": "degrees", "description": "Left hip angle at min ball height" }, "right_hip_bend_angle_at_min_hips": { "type": "float", "unit": "degrees", "description": "Right hip angle at min hips" }, "right_hip_bend_angle_at_min_ball": { "type": "float", "unit": "degrees", "description": "Right hip angle at min ball height" }, "ankle_distance_2d_at_jump_start_inches": { "type": "float", "unit": "inches", "description": "The two dimensional distance between the left ankle joint at the `last_left_foot_on_floor_he_frame` and the right ankle joint at the `last_right_foot_on_floor_he_frame`. Imagine looking at the player from overhead and seeing how far apart the feet are as each leaves the ground. `null` if no jump detected. \"Ankle" }, "left_ankle_distance_side_to_side_at_jump_start_inches": { "type": "float", "unit": "inches", "description": "How many inches to the left side of the middle of the hips is the shooter's left ankle as the left foot leaves the ground. To measure this, imagine a graph based on the way the hips are facing, with the center (at 0, 0) being the middle of the hips, the vertical axis being forward-back and the horizontal axis being side-to-side. This field shows the distance on the side-to-side dimension between the ankle point and the middle of the hips. `null` if no shot jump detected. \"Ankle" }, "right_ankle_distance_side_to_side_at_jump_start_inches": { "type": "float", "unit": "inches", "description": "How many inches to the right side of the middle of the hips is the shooter's right ankle as the right foot leaves the ground. To measure this, imagine a graph based on the way the hips are facing, with the center (at 0, 0) being the middle of the hips, the vertical axis being forward-back and the horizontal axis being side-to-side. This field shows the distance on the side-to-side dimension between the ankle point and the middle of the hips. `null` if no shot jump detected." }, "left_ankle_vs_hip_side_to_side_at_jump_start_inches": { "type": "float", "unit": "inches", "description": "How many inches to the outside of the left hip is the left ankle. 0 would mean directly in line with the hip on that side of the body, negative numbers show the foot is inside the hip. `null` if no shot jump detected. \"Ankle" }, "right_ankle_vs_hip_side_to_side_at_jump_start_inches": { "type": "float", "unit": "inches", "description": "How many inches to the outside of the right hip is the right ankle. 0 would mean directly in line with the hip on that side of the body, negative numbers show the foot is inside the hip. `null` if no shot jump detected." }, "right_ankle_distance_forward_back_at_jump_start_inches": { "type": "float", "unit": "inches", "description": "How many inches forward or back of the hips is the shooter's right ankle as the right foot leaves the ground. To measure this, imagine a graph based on the way the hips are facing, with the center (at 0, 0) being the middle of the hips, the vertical axis being forward-back and the horizontal axis being side-to-side. This field shows the distance on the vertical axis between the ankle point and the middle of the hips. `null` if no shot jump detected." }, "left_ankle_distance_forward_back_at_jump_start_inches": { "type": "float", "unit": "inches", "description": "How many inches forward or back of the hips is the shooter's left ankle as the left foot leaves the ground. To measure this, imagine a graph based on the way the hips are facing, with the center (at 0, 0) being the middle of the hips, the vertical axis being forward-back and the horizontal axis being side-to-side. This field shows the distance on the vertical axis between the ankle point and the middle of the hips. `null` if no shot jump detected." }, "right_foot_angle_to_hoop_at_jump_start": { "type": "float", "unit": "degrees", "description": "The angle formed by the center of the rim, the heel of the right foot, and the midpoint of the big and little toes. If the foot is pointing straight at the rim, this would be 0 degrees; to the left side of the hoop, this angle will be negative; to the right will be positive. `null` if no shot jump detected. \"Foot" }, "left_foot_angle_to_hoop_at_jump_start": { "type": "float", "unit": "degrees", "description": "The angle formed by the center of the rim, the heel of the left foot, and the midpoint of the big and little toes. If the foot is pointing straight at the rim, this would be 0 degrees; to the left side of the hoop, this angle will be negative; to the right will be positive. `null` if no shot jump detected." }, "heel_distance_at_jump_start_inches": { "type": "float", "unit": "inches", "description": "How far apart are the shooter's heels, measured as each foot leaves the floor. This is measured in two dimensions, i.e. it ignores a difference in height. `null` if no shot jump detected. \"Heel" }, "mid_toe_distance_at_jump_start_inches": { "type": "float", "unit": "inches", "description": "How far apart is the midpoint of the shooter's toes on each foot, measured as each foot leaves the floor. This is measured in two dimensions, i.e. it ignores a difference in height. `null` if no shot jump detected." }, "mid_toe_heel_dist_difference_at_jump_start_inches": { "type": "float", "unit": "inches", "description": "Toe distance minus heel distance. Positive = feet turned out, negative = turned in. `null` if no shot jump detected. \"Toe *Paul George's toes are turned in on this shot. The value of this field for this shot is -6.6.*" }, "shooting_wrist_elbow_shoulder_angle_at_set_point": { "type": "float", "unit": "degrees", "description": "Angle formed by wrist, elbow, shoulder (from the side). \"Wrist" }, "shooting_elbow_shoulder_hip_angle_at_set_point": { "type": "float", "unit": "degrees", "description": "Angle formed by elbow, shoulder, hip. \"Elbow" }, "shooting_elbow_shoulder_hoop_angle_at_set_point": { "type": "float", "unit": "degrees", "description": "Measures where the elbow is pointing relative to the hoop. This tells you the angle formed by the shooting elbow, shooting shoulder, and hoop at the set point, where 0 degrees would be aiming straight at the rim, negative is to the left of the rim and positive to the right. \"Elbow" }, "shooting_elbow_flare_angle_at_set_point": { "type": "float", "unit": "degrees", "description": "How flared out or in is the shooting elbow relative to the shoulders at the set point. 0 degrees would mean the elbow is directly in line with the way the shoulders are pointing, a positive number means it's flared out away from the center of the body (regardless of whether it's the left or right arm), a negative number would mean it's pointed in toward the center of the body." }, "elbow_relative_to_ball_at_set_forward_back_inches": { "type": "float", "unit": "inches", "description": "Viewed from above, how far in front of or behind the center of the ball is the elbow at the set point. The forward-back axis here is the line from the center of the ball to the center of the rim." }, "elbow_relative_to_ball_at_set_side_to_side_inches": { "type": "float", "unit": "inches", "description": "Viewed from above, how far to the left or right of the center of the ball is the elbow at the set point. The side-to-side axis here is the line perpendicular to the line from the center of the ball to the center of the rim. Negative is to the left of the ball, positive is to the right." }, "elbow_relative_to_ball_at_release_forward_back_inches": { "type": "float", "unit": "inches", "description": "Viewed from above, how far in front of or behind the center of the ball is the elbow at the release point. The forward-back axis here is the line from the center of the ball to the center of the rim." }, "elbow_relative_to_ball_at_release_side_to_side_inches": { "type": "float", "unit": "inches", "description": "Viewed from above, how far to the left or right of the center of the ball is the elbow at the release point. The side-to-side axis here is the line perpendicular to the line from the center of the ball to the center of the rim. Negative is to the left of the ball, positive is to the right." }, "wrist_relative_to_ball_at_set_forward_back_inches": { "type": "float", "unit": "inches", "description": "Viewed from above, how far in front of or behind the center of the ball is the wrist at the set point. The forward-back axis here is the line from the center of the ball to the center of the rim." }, "wrist_relative_to_ball_at_set_side_to_side_inches": { "type": "float", "unit": "inches", "description": "Viewed from above, how far to the left or right of the center of the ball is the wrist at the set point. The side-to-side axis here is the line perpendicular to the line from the center of the ball to the center of the rim. Negative is to the left of the ball, positive is to the right." }, "wrist_relative_to_ball_at_release_forward_back_inches": { "type": "float", "unit": "inches", "description": "Viewed from above, how far in front of or behind the center of the ball is the wrist at the release point. The forward-back axis here is the line from the center of the ball to the center of the rim." }, "wrist_relative_to_ball_at_release_side_to_side_inches": { "type": "float", "unit": "inches", "description": "Viewed from above, how far to the left or right of the center of the ball is the wrist at the release point. The side-to-side axis here is the line perpendicular to the line from the center of the ball to the center of the rim. Negative is to the left of the ball, positive is to the right." }, "is_off_balance": { "type": "boolean", "unit": null, "description": "`true` if we estimate that the shooter would be judged as off balance when they release the ball, `false` otherwise. We measure this by looking at whether the player is fading any direction in the air at release, whether they jump a far distance in a direction away from the rim, and what their balance and feet are like when they land. ::: tip NOTE This is a more subjective marking than many of the others we've produced data on, but we think it's valuable. We also include all of the inputs we've used for this as separate fields below if you would like to develop your own estimate of balance or simply use each individual field as its own input in a larger model. :::" }, "neck_relative_to_feet_midpoint_at_release_xy_distance_in": { "type": "float", "unit": "inches", "description": "Imagine looking at a player from straight overhead as they release their shot. This field measures the two-dimensional distance (ignoring the height distance) between the player's neck and the point in between their left and right ankles. A player standing straight up and down would have their neck right over their ankles (and a distance close to 0), while a player leaning back would have their neck much further from their ankles." }, "neck_relative_to_knee_midpoint_at_release_xy_distance_in": { "type": "float", "unit": "inches", "description": "Imagine looking at a player from straight overhead as they release their shot. This field measures the left-to-right distance (i.e. ignoring the height distance) between the player's neck and the point in between their knees. A player standing straight up and down would have their neck right over their knees (and a distance close to 0), while a player leaning back would have their neck much further from their knees." }, "neck_relative_to_mid_hip_at_release_xy_distance_in": { "type": "float", "unit": "inches", "description": "Imagine looking at a player from straight overhead as they release their shot. This field measures the two-dimensional distance (ignoring the height distance) between the player's neck and the point in between their left and right hips. A player standing straight up and down would have their neck right over their hips (and a distance close to 0), while a player leaning back would have their neck much further from their hips." }, "jump_distance_not_toward_rim_in": { "type": "float", "unit": "inches", "description": "How many inches the player's jump for the shot took them in a direction that was not toward the rim." }, "landing_ankle_height_difference_in": { "type": "float", "unit": "inches", "description": "When the player landed from their jump for their shot, how many inches different was the height of their ankles from each other. A player who is off balance when shooting is much more likely to land on one foot and kick the other foot out for balance." }, "shot_jump_max_hip_height_vs_standing_hip_height_diff_in": { "type": "float", "unit": "inches", "description": "The maximum number of inches the player got their hips off the ground during the jump above where we estimate they would have been if they were standing on the ground straight up. A value of 12, for example, means the player's mid hip is 12 inches higher in the air than our estimate of their standing mid hip height during this jump." }, "shot_jump_distance_mid_hips_in": { "type": "float", "unit": "inches", "description": "The two-dimensional distance covered by the player's jump, based on where their mid hip is at the start and end of the jump. Imagine putting a dot on the floor where the mid hip is when they start their jump and where it is when they land, and then measuring the distance with a tape measure." }, "shot_jump_direction_mid_hips": { "type": "float", "unit": "degrees", "description": "The angle formed by the rim, the mid hip location at the start of the jump, and the mid hip location at the end of the jump. 0 degrees would be directly toward the rim, 180 would be directly away. Any negative numbers mean the player went to the left on their jump relative to the rim, positive means to the right." }, "shot_jump_distance_ankles_in": { "type": "float", "unit": "inches", "description": "The two-dimensional distance covered by the player's jump, based on where the midpoint of their ankles is at the start and end of the jump. Imagine drawing a line between the two ankles and putting a dot on the floor at the middle of that line when they start their jump and where it is when they land, and then measuring the distance with a tape measure." }, "shot_jump_direction_ankles": { "type": "float", "unit": "degrees", "description": "The angle formed by the rim, the midpoint of the ankles at the start of the jump, and the midpoint of the ankles at the end of the jump. 0 degrees would be directly toward the rim, 180 would be directly away. Any negative numbers mean the player went to the left on their jump relative to the rim, positive means to the right." }, "jump_shot_footwork_type": { "type": "string", "unit": null, "description": "Classifies the type of footwork the player used to get into their shot jump. **Options:** - `hop` - the player lifts both feet off the ground and lands with them both very close to the same time before jumping for their shot - `left_right` - the player steps into the shot, first with their left foot, then with their right - `right_left` - the player steps into the shot, first with their right foot, then with their left - `plant_foot_left` - the player has their left foot planted on the ground for a reasonable period of time and moves their right foot before jumping to shoot - `plant_foot_right` - the player has their right foot planted on the ground for a reasonable period of time and moves their left foot before jumping to shoot - `both_planted` - both feet are planted on the ground for a reasonable period of time before jumping" } } }, "jumps": { "title": "Jumps", "description": "The `jumps` section in the markings response contains one object for every instance of a player jumping. The clock must be running during at least part of the jump for the jump to be included in this data.", "fields": { "jump_id_ctg": { "type": "string", "unit": null, "description": "CTG-generated unique identifier for this jump event" }, "game_id_nba": { "type": "string", "unit": null, "description": "NBA game ID" }, "player_id_nba": { "type": "integer", "unit": null, "description": "NBA player ID of the jumping player" }, "period": { "type": "integer", "unit": null, "description": "Period when the jump occurred" }, "jump_start_he_frame": { "type": "integer", "unit": null, "description": "Hawk-Eye frame when both feet first leave the floor" }, "jump_start_game_clock": { "type": "float", "unit": null, "description": "Game clock at jump start" }, "jump_start_shot_clock": { "type": "float", "unit": null, "description": "Shot clock at jump start" }, "jump_start_wall_clock": { "type": "string", "unit": null, "description": "UTC timestamp at jump start" }, "jump_end_he_frame": { "type": "integer", "unit": null, "description": "Last Hawk-Eye frame after the jump start when both feet are still off the floor (i.e., the frame immediately before landing)" }, "jump_end_game_clock": { "type": "float", "unit": null, "description": "Game clock at jump end" }, "jump_end_shot_clock": { "type": "float", "unit": null, "description": "Shot clock at jump end" }, "jump_end_wall_clock": { "type": "string", "unit": null, "description": "UTC timestamp at jump end" }, "max_mid_hip_height_he_frame": { "type": "integer", "unit": null, "description": "Hawk-Eye frame when mid hip height was highest (jump peak)" }, "max_mid_hip_height_wall_clock": { "type": "string", "unit": null, "description": "UTC timestamp corresponding to `max_mid_hip_height_he_frame`." }, "jump_type": { "type": "string", "unit": null, "description": "`hop` (small jump, not much height) or `jump` (traditional jump)" }, "jump_duration_sec": { "type": "float", "unit": "seconds", "description": "Time in the air" }, "jump_distance_in": { "type": "float", "unit": "inches", "description": "The two-dimensional distance covered by the player's mid hip from start of the jump to the end of the jump. Imagine placing a dot on the floor where the player's mid hip is when he takes off and another when he lands, and then taking a tape measure and measuring the distance between them." }, "max_hip_height_vs_standing_hip_height_diff_in": { "type": "float", "unit": "inches", "description": "How many inches the player got their hips off the ground during the jump above where we estimate they would have been if they were standing on the ground straight up. A value of 25, for example, means the player’s mid hip is 25 inches higher in the air than our estimate of their standing mid hip height. If the player's jump peaks and then goes back up (e.g. when hanging on the rim), this is measured at the point where the player's hips first begin to come down from the jump." }, "did_swing_on_rim": { "type": "boolean", "unit": null, "description": "`true` if we estimate that the player who jumped swung on the rim to a degree that it will change these jump metrics relative to if he had never touched the rim. For example, on this jump, Jayson Tatum's swing affects the time in air and max hip height: " }, "max_neck_height_in": { "type": "float", "unit": "inches", "description": "Highest neck position during jump" }, "max_right_wrist_height_in": { "type": "float", "unit": "inches", "description": "Highest right wrist position" }, "max_left_wrist_height_in": { "type": "float", "unit": "inches", "description": "Highest left wrist position" }, "highest_max_wrist_height_in": { "type": "float", "unit": "inches", "description": "Whichever wrist got higher" }, "max_right_ankle_height_in": { "type": "float", "unit": "inches", "description": "Highest right ankle position" }, "max_left_ankle_height_in": { "type": "float", "unit": "inches", "description": "Highest left ankle position" }, "lowest_max_ankle_height_in": { "type": "float", "unit": "inches", "description": "The lower of the two max ankle heights" }, "max_right_big_toe_height_in": { "type": "float", "unit": "inches", "description": "Highest right big toe position" }, "max_left_big_toe_height_in": { "type": "float", "unit": "inches", "description": "Highest left big toe position" }, "lowest_max_big_toe_height_in": { "type": "float", "unit": "inches", "description": "The lower of the two max toe heights" } } }, "passes": { "title": "Passes", "description": "The `passes` section in the markings response contains an object for every pass that we detect in the game.", "fields": { "game_id_nba": { "type": "string", "unit": null, "description": "NBA game ID" }, "nba_game_id": { "type": "string", "unit": null, "description": "NBA game ID ::: warning Deprecated Use `game_id_nba` instead. This field will be removed in a future version. :::" }, "pass_id_ctg": { "type": "string", "unit": null, "description": "CTG-generated unique pass ID." }, "chance_id_ctg": { "type": "string", "unit": null, "description": "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", "unit": null, "description": "NBA player ID of the passer." }, "passer_id_ctg": { "type": "integer", "unit": null, "description": "NBA player ID of the passer ::: warning Deprecated Use `passer_id_nba` instead. This field will be removed in a future version. :::" }, "intended_receiver_id_nba": { "type": "integer", "unit": null, "description": "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": { "type": "integer", "unit": null, "description": "NBA player ID of the intended receiver ::: warning Deprecated Use `intended_receiver_id_nba` instead. This field will be removed in a future version. :::" }, "pass_release_he_frame": { "type": "integer", "unit": null, "description": "Hawk-Eye frame when the pass left the passer's hands." }, "pass_release_wall_clock": { "type": "string", "unit": null, "description": "UTC timestamp corresponding to `pass_release_he_frame`." }, "receiver_touch_start_he_frame": { "type": "integer", "unit": null, "description": "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", "unit": null, "description": "UTC timestamp corresponding to `receiver_touch_start_he_frame`. `null` if the receiver never touched the ball." }, "is_one_handed_pass": { "type": "boolean", "unit": null, "description": "`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", "unit": null, "description": "Which hand primarily threw the pass: - `right` - `left` - `both` - `null` if player pose data is unavailable for the passer at the time of the pass :::: tip 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", "unit": null, "description": "`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" }, "receiver_touched_ball": { "type": "boolean", "unit": null, "description": "`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", "unit": null, "description": "`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", "unit": null, "description": "`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) :::tip 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_height_in": { "type": "float", "unit": "inches", "description": "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", "description": "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", "description": "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", "description": "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", "description": "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", "description": "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)" } } }, "possession-touches": { "title": "Possession Touches", "description": "The `possession_touches` section in the markings response contains an object for each individual player \"possession touch\" during the game.", "fields": { "possession_touch_id_ctg": { "type": "string", "unit": null, "description": "CTG-generated unique ID for this possession touch" }, "game_id_nba": { "type": "string", "unit": null, "description": "NBA game ID" }, "team_id_nba": { "type": "integer", "unit": null, "description": "NBA team ID of the player's team" }, "player_id_nba": { "type": "integer", "unit": null, "description": "NBA player ID of the player with the ball" }, "chance_id_ctg": { "type": "string", "unit": null, "description": "CTG-generated chance ID that this possession touch belongs to. `null` if the touch could not be associated with a chance." }, "period": { "type": "integer", "unit": null, "description": "Period in which the possession touch occurred. Overtime would be period 5, double overtime period 6, etc." }, "start_he_frame": { "type": "integer", "unit": null, "description": "Hawk-Eye frame when the possession touch began." }, "end_he_frame": { "type": "integer", "unit": null, "description": "Hawk-Eye frame when the possession touch ended." }, "start_wall_clock": { "type": "string", "unit": null, "description": "UTC timestamp when the possession touch began." }, "end_wall_clock": { "type": "string", "unit": null, "description": "UTC timestamp when the possession touch ended." }, "start_game_clock": { "type": "float", "unit": null, "description": "Game clock (in seconds remaining in the period) when the possession touch began." }, "end_game_clock": { "type": "float", "unit": null, "description": "Game clock (in seconds remaining in the period) when the possession touch ended." }, "duration_sec": { "type": "float", "unit": null, "description": "Duration of the possession touch in seconds." }, "is_inbounds": { "type": "boolean", "unit": null, "description": "`true` if this possession touch involves the player making an inbounds pass." }, "num_dribbles": { "type": "integer", "unit": null, "description": "Number of dribbles the player took during this possession touch. `null` if dribble count could not be determined." }, "start_loc_x": { "type": "float", "unit": "inches", "description": "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", "description": "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", "description": "X coordinate of the player's centroid at the end of the touch." }, "end_loc_y": { "type": "float", "unit": "inches", "description": "Y coordinate of the player's centroid at the end of the touch." }, "outcome_type": { "type": "string", "unit": null, "description": "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", "unit": null, "description": "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", "unit": null, "description": "NBA Play-by-Play event ID associated with the outcome event. `null` if no PBP event is associated." }, "outcome_ctg_id": { "type": "string", "unit": null, "description": "CTG ID of the related event (e.g., shot ID, pass ID). `null` if not applicable or unknown." } } }, "possessions": { "title": "Possessions", "description": "The `possessions` section in the markings response contains an object for each team possession in the game. A team possession is a segment of the game that starts when one team gets the ball and ends when they lose the ball or the period ends.", "fields": { "game_id_nba": { "type": "string", "unit": null, "description": "NBA game ID" }, "possession_id_ctg": { "type": "string", "unit": null, "description": "CTG-generated unique possession ID" }, "offensive_team_id_nba": { "type": "integer", "unit": null, "description": "NBA team ID of the offensive team" }, "defensive_team_id_nba": { "type": "integer", "unit": null, "description": "NBA team ID of the defensive team" }, "period": { "type": "integer", "unit": null, "description": "Period in which the possession occurred. Overtime would be period 5, double overtime period 6, etc." }, "start_he_frame": { "type": "integer", "unit": null, "description": "Hawk-Eye frame when possession began" }, "start_wall_clock": { "type": "string", "unit": null, "description": "UTC timestamp when possession began" }, "start_game_clock": { "type": "float", "unit": null, "description": "Game clock when possession began" }, "end_he_frame": { "type": "integer", "unit": null, "description": "Hawk-Eye frame when possession ended" }, "end_wall_clock": { "type": "string", "unit": null, "description": "UTC timestamp when possession ended" }, "end_game_clock": { "type": "float", "unit": null, "description": "Game clock when possession ended" }, "possession_start_type": { "type": "string", "unit": null, "description": "How the possession began, taken from the `chance_start_type` of the first chance in the possession. See the [`chances`](chances.md#chance-start-type) documentation for possible values." }, "is_after_timeout": { "type": "boolean", "unit": null, "description": "`true` if the first chance of the possession immediately follows a timeout. This value comes from the first chance in the possession." }, "start_score_home": { "type": "integer", "unit": null, "description": "Score of the home team at the start of the possession (from the first chance in the possession)." }, "start_score_away": { "type": "integer", "unit": null, "description": "Score of the away team at the start of the possession (from the first chance in the possession)." }, "in_garbage_time": { "type": "boolean", "unit": null, "description": "`true` if the first chance of the possession occurred during \"garbage time\". See the [`chances`](chances.md#in-garbage-time) documentation for the definition of garbage time." }, "fgm": { "type": "integer", "unit": null, "description": "Total field goals made across all chances in the possession." }, "fga": { "type": "integer", "unit": null, "description": "Total field goal attempts across all chances in the possession." }, "fga_pts": { "type": "integer", "unit": null, "description": "Total points scored on field goal attempts across all chances in the possession (2 or 3 for made shots, 0 for misses)." }, "ftm": { "type": "integer", "unit": null, "description": "Total free throws made across all chances in the possession." }, "fta": { "type": "integer", "unit": null, "description": "Total free throw attempts across all chances in the possession." }, "tov": { "type": "integer", "unit": null, "description": "Total turnovers across all chances in the possession." }, "fg_dreb": { "type": "integer", "unit": null, "description": "Total defensive rebounds on field goal attempts across all chances in the possession." }, "fg_oreb": { "type": "integer", "unit": null, "description": "Total offensive rebounds on field goal attempts across all chances in the possession." } } }, "rebounds": { "title": "Rebounds", "description": "The `rebounds` section in the markings response contains information on each official rebound.", "fields": { "game_id_nba": { "type": "string", "unit": null, "description": "NBA game ID" }, "rebound_id_ctg": { "type": "string", "unit": null, "description": "CTG-generated unique rebound ID" }, "rebound_chance_id_ctg": { "type": "string", "unit": null, "description": "CTG chance ID for the chance that the rebound starts. `null` if the rebound does not start a new chance (e.g. some free throw rebounds, end of period rebounds, etc.) or possibly due to upstream data error" }, "shot_chance_id_ctg": { "type": "string", "unit": null, "description": "CTG chance ID of the shot that was missed that led to this rebound. `null` for free throw rebounds (or possibly due to upstream data error)" }, "shot_id_ctg": { "type": "string", "unit": null, "description": "CTG shot ID of the missed shot. `null` for free throws" }, "free_throw_id_ctg": { "type": "string", "unit": null, "description": "CTG free throw ID if the rebound was a result of a missed free throw. `null` for field goal rebounds" }, "player_id_nba": { "type": "integer", "unit": null, "description": "NBA player ID of the rebounder. `null` for team rebounds" }, "pbp_event_id": { "type": "integer", "unit": null, "description": "Play-by-play event ID (i.e. NGSS event ID) for the rebound" }, "event_pbp_id": { "type": "integer", "unit": null, "description": "Play-by-play event ID (i.e. NGSS event ID) for the rebound ::: warning Deprecated Use `pbp_event_id` instead. This field will be removed in a future version. :::" }, "possession_team_id_nba": { "type": "integer", "unit": null, "description": "NBA team ID of the team that secured the rebound" }, "is_live_ball_rebound": { "type": "boolean", "unit": null, "description": "`true` if the rebound was secured as a live ball (not a team rebound or out of bounds)" }, "is_rebounded": { "type": "boolean", "unit": null, "description": "`true` if the rebound was secured as a live ball (not a team rebound or out of bounds) ::: warning Deprecated Use `is_live_ball_rebound` instead. This field will be removed in a future version. :::" }, "is_defensive": { "type": "boolean", "unit": null, "description": "`true` for defensive rebounds, `false` for offensive rebounds" }, "period": { "type": "integer", "unit": null, "description": "Period when the rebound occurred" }, "game_clock": { "type": "float", "unit": null, "description": "Game clock (seconds remaining) at the rebound" }, "shot_clock": { "type": "float", "unit": null, "description": "Shot clock at the rebound. `null` if the shot clock is off" }, "rebound_he_frame": { "type": "integer", "unit": null, "description": "Hawk-Eye frame of the rebound" }, "wall_clock": { "type": "string", "unit": null, "description": "UTC timestamp of the rebound" }, "game_clock_running": { "type": "boolean", "unit": null, "description": "`true` if game clock was running" }, "shot_clock_running": { "type": "boolean", "unit": null, "description": "`true` if shot clock was running" }, "attacking_positive_x": { "type": "boolean", "unit": null, "description": "`true` if rebounding team is attacking the positive X basket. `null` if not determined ::: warning Deprecated This field is not particularly accurate and not useful in this data set. It will be removed in a future version. :::" }, "event_pbp_subtype": { "type": "string", "unit": null, "description": "Rebound type (e.g., `\"offensive\"`, `\"defensive\"`)" }, "event_pbp_descriptor": { "type": "string", "unit": null, "description": "Additional description. `null` if not provided ::: warning Deprecated This field is always `null` and provides no value. It will be removed in a future version. :::" }, "event_pbp_qualifiers": { "type": "string", "unit": null, "description": "Qualifier information. `null` if not provided ::: warning Deprecated This information is redundant with other fields in the response. It will be removed in a future version. :::" }, "event_pbp_rebound_x": { "type": "float", "unit": null, "description": "X coordinate of the rebound location from play-by-play" }, "event_pbp_rebound_y": { "type": "float", "unit": null, "description": "Y coordinate of the rebound location from play-by-play" } } }, "shots": { "title": "Shots", "description": "The `shots` section in the markings response contains an object for each official field goal attempt in a game.", "fields": { "shot_id_ctg": { "type": "string", "unit": null, "description": "CTG-generated unique shot ID" }, "game_id_nba": { "type": "string", "unit": null, "description": "NBA game ID" }, "chance_id_ctg": { "type": "string", "unit": null, "description": "CTG chance ID in which the shot occurred" }, "possession_id_ctg": { "type": "string", "unit": null, "description": "CTG possession ID in which the shot occurred" }, "shooter_id_nba": { "type": "integer", "unit": null, "description": "NBA player ID of the shooter" }, "team_id_nba": { "type": "integer", "unit": null, "description": "NBA team ID of the shooting team" }, "pbp_event_id": { "type": "integer", "unit": null, "description": "Play-by-play event ID (i.e. NGSS ID) for this shot" }, "event_pbp_id": { "type": "integer", "unit": null, "description": "Play-by-play event ID (i.e. NGSS ID) for this shot ::: warning Deprecated Use `pbp_event_id` instead. This field will be removed in a future version. :::" }, "period": { "type": "integer", "unit": null, "description": "Period in which the shot occurred (1-4 for regulation, 5+ for OT)" }, "start_game_clock": { "type": "float", "unit": null, "description": "Game clock (seconds remaining in period) at shot start" }, "start_shot_clock": { "type": "float", "unit": null, "description": "Shot clock at shot start" }, "start_he_frame": { "type": "integer", "unit": null, "description": "Hawk-Eye frame at shot start" }, "start_wall_clock": { "type": "string", "unit": null, "description": "UTC timestamp at shot start" }, "end_game_clock": { "type": "float", "unit": null, "description": "Game clock at shot end. Can be `null` if shot end detection fails due to upstream data issues (see note above)." }, "end_shot_clock": { "type": "float", "unit": null, "description": "Shot clock at shot end. Can be `null` if shot end detection fails due to upstream data issues (see note above)." }, "end_he_frame": { "type": "integer", "unit": null, "description": "Hawk-Eye frame at shot end. Can be `null` if shot end detection fails due to upstream data issues (see note above)." }, "end_wall_clock": { "type": "string", "unit": null, "description": "UTC timestamp at shot end. Can be `null` if shot end detection fails due to upstream data issues (see note above)." }, "shot_distance_in": { "type": "float", "unit": "inches", "description": "Distance from the shot location (as defined above) to the center of the basket at the shot release frame. This distance is measured in 2D, i.e. as if you marked a spot on the floor where shooter's centroid was and then measured along the floor to the spot directly under the center of the basket." }, "loc_x": { "type": "float", "unit": "inches", "description": "X coordinate of the shot location on the court" }, "loc_y": { "type": "float", "unit": "inches", "description": "Y coordinate of the shot location on the court" }, "shot_type": { "type": "string", "unit": null, "description": "The `shot_type` field classifies the shot using 3D tracking data to analyze movement and release style. Can be `null` if shot end detection fails due to upstream data issues. - **`dunk`**: A dunk or dunk attempt that is not a lob. - **`floater`**: A floater would be a shot taken near the rim and uses one hand to shoot overhand with the player largely facing the basket. A baby hook shot or push shot with the player's shoulder mostly turned to the basket would be different (see below). This also includes runners and shots from further away that are taken without a normal jump shot shooting motion, almost always with a one-handed push shooting motion. - **`heave`**: A shot from very far away taken up against the end of the shot/game clock. - **`hook`**: A shot taken primarily with one hand and with the back or side turned toward the basket, usually not moving toward the basket. - **`jumper`**: A jump shot with two hands on the ball until pushing to release. This includes a large variety of jump shots like a standard jumper, a fadeaway out of the post, a pull up, etc. - **`layup`**: Any shot near the basket that is not a dunk, lob, or tip. Layups and floaters can sometimes be difficult to distinguish. More weight is given to a shot being classified as a layup over a floater if it uses the backboard. - **`lob`**: A shot near the basket where shooter receives a pass and shoots without landing first. Includes lob dunks. - **`lost_ball_on_way_up`**: A shot where the ball is blocked or the player is fouled and loses the ball such that you can’t actually tell which type of shot it was going to be. - **`putback`**: Player dunks or shoots immediately after an offensive rebound without landing. - **`tip`**: Player hits the ball with one hand after a missed shot to tip it in without landing from their jump first. This does not include tips from passes, which would be considered lobs. ::: info Jump Shots vs Interior Shots In other sections of our markings, we separate jump shots from interior shots. `jumper` shots have detailed mechanics in the [`jump_shots`](jump-shots) section, while other shot types have their mechanics in [`interior_shots`](interior-shots). :::" }, "is_three": { "type": "boolean", "unit": null, "description": "`true` if the shot was a three-point attempt" }, "is_tip": { "type": "boolean", "unit": null, "description": "`true` if the shot was a tip-in attempt. Can be `null` if shot end detection fails due to upstream data issues." }, "is_made": { "type": "boolean", "unit": null, "description": "`true` if the shot was made" }, "is_bank": { "type": "boolean", "unit": null, "description": "The `is_bank` field indicates whether the ball hit the front side of the backboard and changed trajectory before hitting the rim. - Returns `true` only if the ball hits the **front** of the backboard first - Returns `false` if the ball hits the side, back, or top of the backboard first - Returns `false` if the ball hits the rim first - Returns `false` if the ball never gets near the backboard before the shot end frame (e.g. an airball) - Returns `null` if the shot is blocked (since we can't determine if it would have been a bank)" }, "is_blocked": { "type": "boolean", "unit": null, "description": "`true` if the shot was blocked" }, "blocker_player_id_nba": { "type": "integer", "unit": null, "description": "NBA player ID of the blocker. `null` if not blocked" }, "is_fouled": { "type": "boolean", "unit": null, "description": "`true` if the shooter was fouled during the shot" }, "is_and_one": { "type": "boolean", "unit": null, "description": "`true` if the shot was made and the shooter was fouled" } } }, "turnovers": { "title": "Turnovers", "description": "The `turnovers` section in the markings response contains details on each official turnover.", "fields": { "game_id_nba": { "type": "string", "unit": null, "description": "NBA game ID" }, "turnover_id_ctg": { "type": "string", "unit": null, "description": "CTG-generated unique turnover ID" }, "player_id_nba": { "type": "integer", "unit": null, "description": "NBA player ID who committed the turnover" }, "possession_team_id_nba": { "type": "integer", "unit": null, "description": "NBA team ID of the team that lost possession" }, "defensive_team_id_nba": { "type": "integer", "unit": null, "description": "NBA team ID of the team that gained possession" }, "stealer_id_nba": { "type": "integer", "unit": null, "description": "NBA player ID who recorded the steal. `null` if not a steal" }, "period": { "type": "integer", "unit": null, "description": "Period when the turnover occurred" }, "game_clock": { "type": "float", "unit": null, "description": "Game clock (seconds remaining) at the turnover" }, "shot_clock": { "type": "float", "unit": null, "description": "Shot clock at the turnover. `null` if the shot clock is off" }, "turnover_he_frame": { "type": "integer", "unit": null, "description": "Hawk-Eye frame of the turnover. `null` if there is no corresponding Hawk-Eye frame in the Hawk-Eye event data" }, "turnover_wall_clock": { "type": "string", "unit": null, "description": "UTC timestamp corresponding to `turnover_he_frame`. `null` if there is no corresponding Hawk-Eye frame." }, "game_clock_running": { "type": "boolean", "unit": null, "description": "`true` if game clock was running ::: warning Deprecated This field is unreliable and not particularly useful for analyzing turnover events. This field will be removed in a future version. :::" }, "shot_clock_running": { "type": "boolean", "unit": null, "description": "`true` if shot clock was running ::: warning Deprecated This field is unreliable and not particularly useful for analyzing turnover events. This field will be removed in a future version. :::" }, "attacking_positive_x": { "type": "boolean", "unit": null, "description": "`true` if offensive team was attacking positive X basket. `null` if unknown ::: warning Deprecated This information is not particularly accurate and not useful for analyzing turnover events. This field will be removed in a future version. :::" }, "pbp_event_id": { "type": "integer", "unit": null, "description": "Play-by-play event ID" }, "event_pbp_id": { "type": "integer", "unit": null, "description": "Play-by-play event ID ::: warning Deprecated Use `pbp_event_id` instead. This field will be removed in a future version. :::" }, "event_pbp_subtype": { "type": "string", "unit": null, "description": "Turnover type (see values below)" }, "event_pbp_descriptor": { "type": "string", "unit": null, "description": "Additional description (e.g., `\"lostball\"` for out of bounds). `null` if not provided ::: warning Deprecated This information is not particularly useful for analyzing turnover events. This field will be removed in a future version. :::" }, "event_pbp_qualifiers": { "type": "string", "unit": null, "description": "Qualifier information. `null` if not provided ::: warning Deprecated This information is not useful for analyzing turnover events. This field will be removed in a future version. :::" }, "event_pbp_turnover_total": { "type": "integer", "unit": null, "description": "Player's turnover total for the game at this point in the game ::: warning Deprecated This data is already available in the official NBA play-by-play feed. This field will be removed in a future version. :::" } } } } ``` ===== END MACHINE-READABLE FIELD CATALOG (fields.json) =====