stats.nba.com Data Loaders¶

stats.nba.com data loaders are used to load data for a specific resource either from file stored on disk or via an API request to stats.nba.com.

Base¶

class pbpstats.data_loader.stats_nba.base.StatsNbaLoaderBase[source]¶

Bases: object

Base Class for all stats.nba.com data loaders

This class should not be instantiated directly

static dedupe_events_row_set(events_row_set)[source]¶

Dedupes list of results while preserving order

Used to dedupe events rowSets pbp response because some games have duplicate events

Parameters: events_row_set (list) – List of results from API Response
Returns: deduped list of results

make_list_of_dicts(results_set_index=0)[source]¶

Creates list of dicts from source data

Parameters: results_set_index (int) – Index results are in. Default is 0
Returns: list of dicts with data for results

Boxscore¶

StatsNbaBoxscoreLoader loads boxscore data for a game and creates StatsNbaBoxscoreItem objects for each player and team

The following code will load boxscore data for game id “0021900001” from a file located in a subdirectory of the /data directory

from pbpstats.data_loader import StatsNbaBoxscoreLoader

boxscore_loader = StatsNbaBoxscoreLoader("0021900001", "file", "/data")
print(boxscore_loader.items[0].data) # prints dict with a player's boxscore data for game

class pbpstats.data_loader.stats_nba.boxscore_loader.StatsNbaBoxscoreLoader(game_id, source, file_directory=None)[source]¶

Bases: pbpstats.data_loader.stats_nba.file_loader.StatsNbaFileLoader, pbpstats.data_loader.stats_nba.web_loader.StatsNbaWebLoader

Loads stats.nba.com source boxscore data for game. Team/Player data is stored in items attribute as StatsNbaBoxscoreItem objects

Parameters

game_id (str) – NBA Stats Game Id
source (str) – Where should data be loaded from. Options are ‘web’ or ‘file’
file_directory (str) – (optional if source is ‘web’) Directory in which data should be either stored (if source is web) or loaded from (if source is file). The specific file location will be stats_boxscore_<game_id>.json in the /game_details subdirectory. If not provided response data will not be saved on disk.

data_provider = 'stats_nba'¶

parent_object = 'Game'¶

resource = 'Boxscore'¶

Enhanced PBP¶

StatsNbaEnhancedPbpLoader loads pbp data for a game and creates EnhancedPbpItem objects for each event

Enhanced data for each event includes current players on floor, score, fouls to give and number of fouls committed by each player, plus additional data depending on event type

The following code will load pbp data for game id “0021900001” from a file located in a subdirectory of the /data directory

from pbpstats.data_loader import StatsNbaEnhancedPbpLoader

pbp_loader = StatsNbaEnhancedPbpLoader("0021900001", "file", "/data")
print(pbp_loader.items[0].data)  # prints dict with the first event of the game

class pbpstats.data_loader.stats_nba.enhanced_pbp_loader.StatsNbaEnhancedPbpLoader(game_id, source, file_directory=None)[source]¶

Bases: pbpstats.data_loader.stats_nba.pbp_loader.StatsNbaPbpLoader, pbpstats.data_loader.nba_enhanced_pbp_loader.NbaEnhancedPbpLoader

Loads stats.nba.com source enhanced pbp data for game. Events are stored in items attribute as EnhancedPbpItem objects

Parameters

game_id (str) – NBA Stats Game Id
source (str) – Where should data be loaded from. Options are ‘web’ or ‘file’
file_directory (str) – (optional if source is ‘web’) Directory in which data should be either stored (if source is web) or loaded from (if source is file). The specific file location will be stats_<game_id>.json in the /pbp subdirectory. If not provided response data will not be saved on disk.

Raises

InvalidNumberOfStartersException: If all 5 players that start the period for a team can’t be determined. You can add the correct period starters to overrides/missing_period_starters.json in your data directory to fix this.

Raises

EventOrderError: If rebound event is not immediately following a missed shot event. You can manually edit the event order in the pbp file stored on disk to fix this.

data_provider = 'stats_nba'¶

parent_object = 'Game'¶

resource = 'EnhancedPbp'¶

File Loader¶

class pbpstats.data_loader.stats_nba.file_loader.StatsNbaFileLoader[source]¶

Bases: pbpstats.data_loader.abs_data_loader.AbsDataLoader, pbpstats.data_loader.stats_nba.base.StatsNbaLoaderBase

Base class for loading stats.nba.com files saved on disk.

All stats.nba.com data loader classes should inherit from this class.

This class should not be instantiated directly.

property data¶: returns data from response JSON as a list of dicts

Game Finder¶

StatsNbaGameFinderLoader loads all games for a season and creates StatsNbaGameItem objects for each game

The following code will load data for the 2019-20 NBA Regular Season

from pbpstats.data_loader import StatsNbaGameFinderLoader

game_finder_loader = StatsNbaGameFinderLoader("nba", "2019-20", "Regular Season", "web")
print(game_finder_loader.items[0].data) # prints dict for first game

class pbpstats.data_loader.stats_nba.game_finder_loader.StatsNbaGameFinderLoader(league, season, season_type, source, file_directory=None)[source]¶

Bases: pbpstats.data_loader.stats_nba.file_loader.StatsNbaFileLoader, pbpstats.data_loader.stats_nba.web_loader.StatsNbaWebLoader

Loads stats.nba.com source data for season. Games are stored in items attribute as StatsNbaGameItem objects

Parameters

league (str) – Options are ‘nba’, ‘wnba’ or ‘gleague’
season (str) – Formatted as 2019-20 for NBA and G-League, 2019 of WNBA.
season_type (str) – Options are ‘Regular Season’ or ‘Playoffs’
source (str) – Where should data be loaded from. Options are ‘web’ or ‘file’
file_directory (str) – (optional if source is ‘web’) Directory in which data should be either stored (if source is web) or loaded from (if source is file). The specific file location will be stats_<league>_<season>_<season_type>.json in the /schedule subdirectory. If not provided response data will not be saved on disk.

data_provider = 'stats_nba'¶

property league_id¶

Returns League Id for league.

00 for nba, 10 for wnba, 20 for g-league

parent_object = 'Season'¶

resource = 'Games'¶

PBP¶

StatsNbaPbpLoader loads pbp data for a game and creates StatsNbaPbpItem objects for each event

The following code will load pbp data for game id “0021900001” from a file located in a subdirectory of the /data directory

from pbpstats.data_loader import StatsNbaPbpLoader

pbp_loader = StatsNbaPbpLoader("0021900001", "file", "/data")
print(pbp_loader.items[0].data)  # prints dict with the first event of the game

class pbpstats.data_loader.stats_nba.pbp_loader.StatsNbaPbpLoader(game_id, source, file_directory=None)[source]¶

Bases: pbpstats.data_loader.stats_nba.web_loader.StatsNbaWebLoader, pbpstats.data_loader.stats_nba.file_loader.StatsNbaFileLoader

Loads stats.nba.com source pbp data for game. Events are stored in items attribute as StatsNbaPbpItem objects

Parameters

game_id (str) – NBA Stats Game Id
source (str) – Where should data be loaded from. Options are ‘web’ or ‘file’
file_directory (str) – (optional if source is ‘web’) Directory in which data should be either stored (if source is web) or loaded from (if source is file). The specific file location will be stats_<game_id>.json in the /pbp subdirectory. If not provided response data will not be saved on disk.

data_provider = 'stats_nba'¶

parent_object = 'Game'¶

resource = 'Pbp'¶

Possessions¶

StatsNbaPossessionLoader loads possession data for a game and creates Possession objects for each possession

The following code will load possession data for game id “0021900001” from a pbp file located in the /pbp subdirectory of the /data directory

from pbpstats.data_loader import StatsNbaPossessionLoader

possession_loader = StatsNbaPossessionLoader("0021900001", "file", "/data")
print(possession_loader.items[0].data)  # prints dict with the first possession of the game

class pbpstats.data_loader.stats_nba.possessions_loader.StatsNbaPossessionLoader(game_id, source, file_directory=None)[source]¶

Bases: pbpstats.data_loader.nba_possession_loader.NbaPossessionLoader

Loads stats.nba.com source possession data for game. Possessions are stored in items attribute as Possession objects

Parameters

game_id (str) – NBA Stats Game Id
source (str) – Where should data be loaded from. Options are ‘web’ or ‘file’
file_directory (str) – (optional if source is ‘web’) Directory in which data should be either stored (if source is web) or loaded from (if source is file). The specific file location will be stats_<game_id>.json in the /pbp subdirectory. If not provided response data will not be saved on disk.

Raises

TeamHasBackToBackPossessionsException: If team has the ball on back-to-back possessions.

data_provider = 'stats_nba'¶

property league¶

Returns League for game id.

First 2 in game id represent league - 00 for nba, 10 for wnba, 20 for g-league

parent_object = 'Game'¶

resource = 'Possessions'¶

exception pbpstats.data_loader.stats_nba.possessions_loader.TeamHasBackToBackPossessionsException[source]¶

Bases: Exception

Class for exception when a team is credited with back-to-back possessions.

You can manually edit the event order in the pbp file stored on disk or add an event to the overrides file in your data directory to fix this.

Scoreboard¶

StatsNbaScoreboardLoader loads all games for a date and creates StatsNbaGameItem objects for each game

The following code will load data for 02/03/2020

from pbpstats.data_loader import StatsNbaScoreboardLoader

game_finder_loader = StatsNbaScoreboardLoader("02/03/2020", "nba", "/data, "file")
print(game_finder_loader.items[0].data) # prints dict for first game

class pbpstats.data_loader.stats_nba.scoreboard_loader.StatsNbaScoreboardLoader(date, league_string, file_directory, source)[source]¶

Bases: pbpstats.data_loader.stats_nba.file_loader.StatsNbaFileLoader, pbpstats.data_loader.stats_nba.web_loader.StatsNbaWebLoader

Loads stats.nba.com source data for date. Games are stored in items attribute as StatsNbaGameItem objects

Parameters

date (str) – Formatted as MM/DD/YYYY
league_string (str) – Options are ‘nba’, ‘wnba’ or ‘gleague’
file_directory (str) – (optional if source is ‘web’) Directory in which data should be either stored (if source is web) or loaded from (if source is file). The specific file location will be stats_<league>_<date>.json in the /schedule subdirectory. If None response data will not be saved on disk.
source (str) – Where should data be loaded from. Options are ‘web’ or ‘file’

data_provider = 'stats_nba'¶

property league_id¶

Returns League Id for league.

00 for nba, 10 for wnba, 20 for g-league

parent_object = 'Day'¶

resource = 'Games'¶

Shots¶

StatsNbaShotsLoader loads shot data for a game and creates StatsNbaShot objects for all shots

The following code will load shot data for game id “0021900001” from a file located in a subdirectory of the /data directory

from pbpstats.data_loader import StatsNbaShotsLoader

shot_loader = StatsNbaShotsLoader("0021900001", "file", "/data")
print(shot_loader.items[0].data) # prints dict with data for one shot from game

class pbpstats.data_loader.stats_nba.shots_loader.StatsNbaShotsLoader(game_id, source, file_directory=None)[source]¶

Bases: pbpstats.data_loader.stats_nba.web_loader.StatsNbaWebLoader, pbpstats.data_loader.stats_nba.file_loader.StatsNbaFileLoader

Loads stats.nba.com source shot data for game. Shots are stored in items attribute as StatsNbaShot objects

Parameters

game_id (str) – NBA Stats Game Id
source (str) – Where should data be loaded from. Options are ‘web’ or ‘file’
file_directory (str) – (optional if source is ‘web’) Directory in which data should be either stored (if source is web) or loaded from (if source is file). The specific file location will be stats_home_shots_<game_id>.json and stats_away_shots_<game_id>.json in the /game_details subdirectory. If not provided response data will not be saved on disk.

data_provider = 'stats_nba'¶

make_list_of_dicts(results_set_index=0)[source]¶

Creates list of dicts from home and away source data

Parameters: results_set_index (int) – Index results are in. Default is 0
Returns: list of dicts with shot data for all shots

parent_object = 'Game'¶

resource = 'Shots'¶

Game Summary¶

StatsNbaSummaryLoader loads summary data for a game and creates StatsNbaGameItem objects for game

The following code will load summary data for game id “0021900001” from a file located in a subdirectory of the /data directory

from pbpstats.data_loader.stats_nba.summary_loader import StatsNbaSummaryLoader

summary_loader = StatsNbaSummaryLoader("0021900001", "file", "/data")
print(summary_loader.items[0].data) # prints game summary dict for game

class pbpstats.data_loader.stats_nba.summary_loader.StatsNbaSummaryLoader(game_id, source, file_directory=None)[source]¶

Bases: pbpstats.data_loader.stats_nba.file_loader.StatsNbaFileLoader, pbpstats.data_loader.stats_nba.web_loader.StatsNbaWebLoader

Loads stats.nba.com source summary data for game. Summary data is stored in items attribute as StatsNbaGameItem objects

Parameters

game_id (str) – NBA Stats Game Id
source (str) – Where should data be loaded from. Options are ‘web’ or ‘file’
file_directory (str) – (optional if source is ‘web’) Directory in which data should be either stored (if source is web) or loaded from (if source is file). The specific file location will be stats_summary_<game_id>.json in the /game_details subdirectory. If not provided response data will not be saved on disk.

data_provider = 'stats_nba'¶

parent_object = 'Game'¶

resource = 'Games'¶

Web Loader¶

class pbpstats.data_loader.stats_nba.web_loader.StatsNbaWebLoader[source]¶

Bases: pbpstats.data_loader.abs_data_loader.AbsDataLoader, pbpstats.data_loader.stats_nba.base.StatsNbaLoaderBase

Base class for loading data from data.nba.com API request.

All stats.nba.com data loader classes should inherit from this class.

This class should not be instantiated directly.

property data¶: returns data from response JSON as a list of dicts

property league¶

Returns League for game id.

First 2 in game id represent league - 00 for nba, 10 for wnba, 20 for g-league

property season¶

Returns season for game id

4th and 5th characters in game id represent season year ex. for 2016-17 season 4th and 5th characters would be 16 and season should return 2016-17 For WNBA just returns season year

property season_type¶

Returns season type for game id

3rd character in game id represent season type - 2 for reg season, 4 for playoffs