CTG Pro Data Feed

Appearance

Matchups ​

The matchups section in the markings response contains one row per continuous defender-to-offensive-player matchup segment.

Overview ​

This data set is defender-centered. Each row describes a stretch of a chance where one defender is matched to the same offensive player. When the defender's matchup changes, the prior segment ends and a new segment begins.

These matchups use 1-to-1 assignments: at each frame, we try to estimate who each player is assigned to. Double teams are not allowed, so each player must be assigned to exactly one other player.

Use this data set when you need the timing of matchup changes within a chance. For a chance-level summary of each player's start, end, and most common matchup, see Chance Matchups.

Sample Response ​

json
{
  "markings": {
    "matchups": [
      {
        "game_id_nba": "0022500404",
        "chance_id_ctg": "chance_005f7222cf4ea11d6bd5678d1b2bfdb0",
        "possession_id_ctg": "possession_81d6bb1c2a4d9f6cb65543bc1263ad34",
        "period": 1,
        "defender_id_nba": 1629627,
        "offensive_player_id_nba": 1630230,
        "prior_offensive_player_id_nba": null,
        "start_he_frame": 86657,
        "end_he_frame": 86687,
        "start_game_clock": 57.5,
        "end_game_clock": 57.0,
        "start_shot_clock": 9.0,
        "end_shot_clock": 9.0,
        "start_wall_clock": "2025-12-23T01:34:38.764+00:00",
        "end_wall_clock": "2025-12-23T01:34:39.264+00:00",
        "was_ball_in_backcourt_at_matchup_start": true,
        "was_offensive_player_in_backcourt_at_matchup_start": true
      }
    ]
  }
}

Fields ​

Identifiers ​

game_id_nba ​

Type: string

NBA game ID

chance_id_ctg ​

Type: string

CTG-generated chance ID that contains this matchup segment

possession_id_ctg ​

Type: string | Nullable

CTG-generated possession ID that contains this matchup segment

Players ​

defender_id_nba ​

Type: integer

NBA player ID for the defender

offensive_player_id_nba ​

Type: integer

NBA player ID for the offensive player the defender is matched to during this segment

prior_offensive_player_id_nba ​

Type: integer | Nullable

NBA player ID for the offensive player this defender was matched to immediately before this segment within the same chance. null when this is the defender's first matchup segment in the chance.

Timing ​

period ​

Type: integer

Game period

start_he_frame ​

Type: integer

Hawk-Eye frame where the matchup segment starts

end_he_frame ​

Type: integer

Hawk-Eye frame where the matchup segment ends

start_game_clock ​

Type: float | Nullable

Game clock, in seconds, when the matchup segment starts

end_game_clock ​

Type: float | Nullable

Game clock, in seconds, when the matchup segment ends

start_shot_clock ​

Type: float | Nullable

Shot clock, in seconds, when the matchup segment starts

end_shot_clock ​

Type: float | Nullable

Shot clock, in seconds, when the matchup segment ends

start_wall_clock ​

Type: string | Nullable

Timestamp when the matchup segment starts

end_wall_clock ​

Type: string | Nullable

Timestamp when the matchup segment ends

Backcourt Context ​

was_ball_in_backcourt_at_matchup_start ​

Type: boolean | Nullable

true when the ball had not yet reached the frontcourt at the start of the matchup segment

was_offensive_player_in_backcourt_at_matchup_start ​

Type: boolean | Nullable

true when the matched offensive player was in the backcourt at the start of the matchup segment