CTG Pro Data Feed

Appearance

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.

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.

Sample Response ​

json
{
  "markings": {
    "chances": [
      {
        "chance_id_ctg": "chance_51bfc1fda2cc0deb125bee9988859667",
        "chance_context": "halfcourt",
        "defense_starts_in_zone": false,
        "chance_outcome": "fg2m",
        "outcome_pbp_id": 7,
        "chance_start_type": "jump_ball",
        "bring_up_ball_handler_defender_id_nba": 1630529,
        "bring_up_ball_handler_id_nba": 1642843,
        "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_shot_clock": 19.0,
        "frontcourt_wall_clock": "2025-12-23T01:10:41.356+00:00",
        "frontcourt_with_possession_he_frame": 414,
        "frontcourt_with_possession_shot_clock": 19.0,
        "frontcourt_with_possession_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_defense_lineup_inferred": false,
        "is_offense_lineup_inferred": false,
        "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",
        "chance_order_in_game": 1,
        "chance_order_in_possession": 1,
        "chance_was_used": true,
        "used_chance_order": 1,
        "used_by_player_id_nba": 1630162,
        "is_last_chance_in_possession": true,
        "previous_chance_id_ctg": null,
        "next_chance_id_ctg": "chance_4c33ded97f95174cc013b446c3981347",
        "previous_possession_id_ctg": null,
        "next_possession_id_ctg": "possession_90461f431f3586f0ba39f25f0cefdec7",
        "first_chance_id_of_next_possession_ctg": "chance_4c33ded97f95174cc013b446c3981347",
        "reversals": 0,
        "home_score_differential": 0,
        "shot_location": "rim",
        "start_game_clock": 719.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,
        "total_paint_touches": 1
      }
    ]
  }
}

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

previous_chance_id_ctg ​

Type: string

CTG-generated ID for the previous chance in the game. null for the first chance in a game.

next_chance_id_ctg ​

Type: string

CTG-generated ID for the next chance in the game. null for the last chance in a game.

previous_possession_id_ctg ​

Type: string

CTG-generated ID for the previous possession in the game. null for the first possession in a game.

next_possession_id_ctg ​

Type: string

CTG-generated ID for the next possession in the game. null for the last possession in a game.

first_chance_id_of_next_possession_ctg ​

Type: string

CTG-generated ID for the first chance of the next possession. null when there is no next possession or when the next possession has no linked chance.

outcome_pbp_id ​

Type: integer

Play by play event ID associated with chance_outcome. For shot outcomes, this is the shot event. For foul, turnover, violation, timeout, jump ball, end-period, and retained out-of-bounds outcomes, this is the event that ended the chance. null if no matching event is available.

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 ​

Lineups come from tracking. Occasionally tracking loses a player who is on the court. When that happens, we fill in the missing player from the play-by-play and set is_offense_lineup_inferred or is_defense_lineup_inferred to true. If the play-by-play doesn't line up with the players we did track, we leave the lineup alone, so in rare cases it can have fewer than five players. Filled-in players have no tracking for that chance, so they don't show up in matchups or other tracking-based data.

offense_players ​

Type: array[integer]

Array of NBA player IDs for the five players on the court on offense during this chance. In rare cases it has fewer than five (see Lineups).

defense_players ​

Type: array[integer]

Array of NBA player IDs for the five players on the court on defense during this chance. In rare cases it has fewer than five (see Lineups).

is_offense_lineup_inferred ​

Type: boolean

true if any player in offense_players was filled in from the play-by-play because tracking lost them.

is_defense_lineup_inferred ​

Type: boolean

true if any player in defense_players was filled in from the play-by-play because tracking lost them.

bring_up_ball_handler_id_nba ​

Type: integer

NBA player ID of the offensive player who brought the ball up the floor for this chance. null when no bring-up ballhandler is identified, such as some offensive-rebound chances or very short chances without a qualifying offensive touch.

This field is also null when the ball is not touched in the backcourt. For example, if the ball is passed or rolled from the backcourt all the way into the frontcourt before being touched, this field will be null.

bring_up_ball_handler_defender_id_nba ​

Type: integer

NBA player ID of the defender matched to the bring-up ballhandler. This is populated when bring_up_ball_handler_id_nba is populated, and null when no bring-up ballhandler is identified.

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.). Offensive fouls are reported here, not under Fouls.

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)
  • 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

chance_context ​

Type: string

The context of the chance ending event. The goal is to classify where the advantage that led to the chance ending event originated.

Values can include:

  • halfcourt: the chance end event occurs after the defense has gotten back and set, or from an advantage created after the defense has gotten back and set.
  • transition: the chance end event occurs during an advantage created by the defense not being fully back and set after a change of possession. If a chance begins with the offense attacking in transition but they do not have a chance ending event from that advantage and the defense gets set, and then they later create an advantage it would be categorized as halfcourt.
  • putback: the chance end event occurs during an advantage created by an offensive rebound. This includes situations in which the offensive rebounder passes to another player who keeps the advantage alive.
  • press: the chance end event occurs as a result of an advantage created by the defense applying backcourt pressure. Backcourt pressure is defined as when any member of the defense is attempting to defend the ball or a player in the backcourt rather than just getting back on defense.
  • backcourt: the ball never gets out of the backcourt and the chance ending event is not caused by defensive pressure. Examples would be an intentional foul or quick turnover in the backcourt or a heave or a loose ball foul on a rebound.
  • backcourt_turnover: this chance is an abnormal chance because it starts with a live ball turnover in the opponent’s backcourt. For example, if a player gets a rebound and then the ball is immediately stolen and shot, the chance with the shot would be a backcourt_turnover chance since it doesn’t neatly fit into any other category—it is not transition because the defense never really has an opportunity to transition one way or the other.
  • jump_ball_scramble: the chance end event occurs as a result of a scramble after a jump ball without the defense getting set.
  • running_out_clock: when a team is just holding the ball running out the clock and not looking to score

defense_starts_in_zone ​

Type: boolean

true when the chance_context is halfcourt and the defense is classified as beginning the chance in a zone defense. If the defense starts in zone and switches into a man defense later in the chance, this would still be true.

is_after_timeout ​

Type: boolean

true if this chance starts after a timeout or is the first chance of a period. Otherwise false.

chance_order_in_game ​

Type: integer

Chronological order of this chance within the game, starting at 1.

chance_order_in_possession ​

Type: integer

Chronological order of this chance within its possession, starting at 1. null when the chance is not linked to a possession.

chance_was_used ​

Type: boolean

true when the chance ends with a shot attempt, shooting foul, turnover, or bonus foul. Otherwise false.

used_chance_order ​

Type: integer

Chronological order among used chances in the possession, starting at 1. null when the chance was not used or is not linked to a possession.

used_by_player_id_nba ​

Type: integer

NBA player ID of the player who used the chance. This is the shooter, fouled player, or player who committed the turnover. null when the chance was not used or the player is unavailable.

is_last_chance_in_possession ​

Type: boolean

true when this is the last chance in its possession, otherwise false. null when the chance is not linked to a possession.

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

home_score_differential ​

Type: integer

Home team score minus away team score at the start of the chance. Positive values mean the home team is leading, and negative values mean the away team is leading.

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.

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.

frontcourt_shot_clock ​

Type: float

Shot clock corresponding to frontcourt_he_frame. null if the ball never crosses halfcourt or if the shot clock is off.

frontcourt_with_possession_he_frame ​

Type: integer

Hawk-Eye frame when the ball is first in the frontcourt during an offensive player's possession touch. In other words, this is when the ball is first possessed in the frontcourt. null if the ball is never possessed in the frontcourt.

frontcourt_with_possession_wall_clock ​

Type: string

UTC timestamp corresponding to frontcourt_with_possession_he_frame. null if the ball never enters the frontcourt while an offensive player has possession during the chance.

frontcourt_with_possession_shot_clock ​

Type: float

Shot clock corresponding to frontcourt_with_possession_he_frame. null if the ball never enters the frontcourt while an offensive player has possession during the chance or if the shot clock is off.

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.

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.

total_paint_touches ​

Type: integer

Number of possession touches in this chance that had a paint touch. A qualifying paint touch requires the ball and both feet to be in the paint at some point during the touch or shortly after the touch ends.

reversals ​

Type: integer

Number of passes in this chance that moved the ball from an established strong side of the court to a receiver on the weak side. This excludes passes where the passer stayed in the middle of the floor after multiple middle dribbles and passed to a receiver on the same side of the court.

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 one frame later.
    • 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 one frame later and lasts for one frame, 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.
    • If a shot-clock violation occurs while the shot is in the air, the chance ends when the clock stops. The next chance will start with an offensive rebound and end with the shot-clock violation turnover, and will start at the frame directly after the prior chance ended and have the same start and end frame.
    • 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 one frame later.
    • 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.