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_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
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.
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
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 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.