Appearance
Fouls
The fouls section in the markings response contains foul event data from the game.
Sample Response
json
{
"markings": {
"fouls": [
{
"attacking_positive_x": false,
"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_type": "shooting",
"foul_wall_clock": "2025-12-23T01:11:07.288+00:00",
"fouled_player_id_nba": 1630180,
"fouled_player_loc_x": -649.3,
"fouled_player_loc_y": 84.01,
"fouled_player_region": null,
"game_clock": 688,
"game_clock_running": true,
"game_id_nba": "0022500404",
"is_charge": false,
"is_shooting_foul": true,
"is_take_foul": false,
"loc_x": -385.68,
"loc_y": 186.18,
"pbp_event_id": 9,
"period": 1,
"player_id_nba": 1629023,
"possession_touch_id_ctg": "possession_touch_71435614ec7ccbc094fe1f0bb3b8e98c",
"possession_team_id_nba": 1610612740,
"region": "right wing two",
"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
possession_touch_id_ctg
Type: string | Nullable
CTG-generated ID for the offensive possession touch that ended in this foul. For an offensive foul, this is the fouler's touch. For other live-ball fouls, this is the fouled player's touch. null if no possession touch can be linked.
player_id_nba
Type: integer | null
NBA player ID of the player who committed the foul. null for team-assigned fouls where the official play-by-play does not assign the foul to an individual player, and for technical fouls on a coach or anyone else who is not on either team's roster for the game.
fouled_player_id_nba
Type: integer | null
NBA player ID of the fouled player. null when the official play-by-play does not identify a fouled player.
possession_team_id_nba
Type: integer
NBA team ID of the team with possession: the fouler's team for an offensive foul, and the other team for a personal foul or defensive three seconds. Other technical fouls use the official play-by-play 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. When the Hawk-Eye event has no frame, this is the last frame before the game clock stops for the foul, and foul_wall_clock is null. null if neither is available, as for most technical fouls.
foul_wall_clock
Type: string
UTC timestamp of the Hawk-Eye event's frame. null if the Hawk-Eye event has no frame, including when foul_he_frame comes from the clock stop.
game_clock_running deprecated
Type: boolean
true if game clock was running
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 deprecated
Type: boolean
true if shot clock was running
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 deprecated
Type: integer
Play-by-play event ID (i.e. NGSS event ID) for the foul
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
Foul Classification
foul_type
Type: string
Normalized foul type based on official play-by-play data. Expected values are shooting, offensive, flagrant, technical, bonus, clear_path, away_from_play, loose_ball, and other.
is_shooting_foul
Type: boolean
true if the official play-by-play identifies the foul as a shooting foul.
is_take_foul
Type: boolean
true if the official play-by-play identifies the foul as a take foul or transition take foul.
is_charge
Type: boolean
true if the official play-by-play identifies the foul as a charge.
event_pbp_foul_personal_total deprecated
Type: integer
Player's personal foul total for the game. null if not provided
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 deprecated
Type: integer
Player's technical foul total. null if not provided
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
loc_x
Type: float
X coordinate of the fouling player's location in inches. null if location is unavailable.
loc_y
Type: float
Y coordinate of the fouling player's location in inches. null if location is unavailable.
region
Type: string
Court region of the fouling player's location. If the foul-frame location is out of bounds or does not map to a court region, this uses the most recent in-bounds location in the 45 frames before the foul. null if location is unavailable.
fouled_player_loc_x
Type: float
X coordinate of the fouled player's location in inches. null if the fouled player or location is unavailable.
fouled_player_loc_y
Type: float
Y coordinate of the fouled player's location in inches. null if the fouled player or location is unavailable.
fouled_player_region
Type: string
Court region of the fouled player's location. If the foul-frame location is out of bounds or does not map to a court region, this uses the most recent in-bounds location in the 45 frames before the foul. null if the fouled player or location is unavailable.
attacking_positive_x deprecated
Type: boolean
true if offensive team is attacking the positive X basket. null if unknown
Deprecated
This information is not relevant to analyzing foul events. This field will be removed in a future version.