py_ball

Python API for stats.nba.com with a focus on NBA and WNBA applications. Documentation for the wrapper can be found here. The documentation includes endpoint, parameter, and feature definitions for the API.

Indices and tables

utils

Created on Sun Oct 21 16:06:31 2018

@author: patrickmcfarlane

utils.py

Utilities for the py_ball package

py_ball.utils.api_call(endpoint, params, headers)

This function completes the API call at the given end point with the provided parameters.

Args:
  • @param endpoint (str): string corresponding to a stats.nba.com API endpoint
Returns:
  • JSON object of the API response
py_ball.utils.parse_api_call(api_resp)

This function parses the API call returned from api_call and stores the response in a dictionary.

Args:
  • @param api_resp (dict): JSON object of an API response. This dictionary is keyed by ‘resource’, ‘parameters’, and ‘resultSets’/’resultSet’. ‘resource’ contains the endpoint of the API call. ‘parameters’ contains the parameters passed to the API call. ‘resultSets’/’resultSet’ contains the data returned from the API call.
Returns:
  • Dictionary keyed by all table names returned from the API call containing all data in ‘resultSets’/’resultSet’.

Classes

BoxScore class

(additional documentation here)

class py_ball.boxscore.BoxScore(headers, game_id, endpoint='boxscoreadvancedv2', range_type='1', start_period='0', end_period='10', start_range='0', end_range='0')

The BoxScore class contains all resources needed to use the boxscore- related API calls. stats.nba.com has the following boxscore-related API endpoints:

  • boxscoreadvancedv2: Game boxscore containing several advanced statistics
  • boxscorefourfactorsv2: Game boxscore containing statistics related to the Four Factors, for team and opponent
  • boxscoremiscv2: Game boxscore containing points scored by type of change (paint, fastbreak, etc.) for team and opponent
  • boxscoreplayertrackv2: Game boxscore containing aggregated player tracking statistics
  • boxscorescoringv2: Game boxscore containing percentage scoring statistics broken down by shot type.
  • boxscoresummaryv2: Game boxscore containing a summary of a particular matchup (including game metadata and results)
  • boxscoretraditionalv2: Game boxscore containing basic statistics
  • boxscoreusagev2: Game boxscore containing usage statistics and percentage

The BoxScore class has the following required parameters:

@param headers (dict): Dictionary of request header information
required by the API. Specifically, the API requires you to declare the ‘User-Agent’ key of the request header dictionary. More information can be found here and an example request header dictionary can be found in the __init__.py file in the tests folder of this module.

@param game_id (str): GameID in the API. 10-digit string that represents a unique game. The format is two leading zeroes, followed by a season indicator number (‘1’ for preseason, ‘2’ for regular season, ‘4’ for the post-season), then the trailing digits of the season in which the game took place (e.g. ‘17’ for the 2017-18 season). The following 5 digits increment from ‘00001’ in order as the season progresses. For example, ‘0021600001’ is the game_id of the first game of the 2016-17 NBA regular season.

@param range_type (str): RangeType in the API. range_type controls the type of boxscore that is returned. If using the start_period and end_period parameters (defined below), range_type should have a value of ‘0’ (DNP players included) or ‘1’ (DNP players excluded). With a range_type value of ‘2’, the start_range and end_range values can be used to return a boxscore from a customized subset of the given game.

@param start_period (str): StartPeriod in the API. String of an integer that corresponds to the period for which the boxscore begins.

@param end_period (str): EndPeriod in the API. String of an integer that corresponds to the period for which the boxscore ends (Overtime increments logically, e.g. ‘5’ is the first overtime period).

@param start_range (str): StartRange in the API. String of an integer that corresponds to the tenths of seconds that have elapsed in the game for which the boxscore begins. Valid when range_type =‘2’.

@param end_range (str) : EndRange in the API. String of an integer that corresponds to the tenths of seconds that have elapsed in the game for which the boxscore ends. Valid when range_type =‘2’.

Attributes:

  • api_resp (dict): JSON object of the API response. The API response has three keys. The ‘resource’ key describes the type of response returned (‘boxscore’ in this instance). The ‘parameters’ key describes the parameters provided in the API call. The ‘resultSets’ key contains the data returned in the API call.
  • data (dict): A dictionary of response names. Each response name is a key to a list of dictionaries containing the corresponding data.

Draft class

(additional documentation here)
class py_ball.draft.Draft(headers, endpoint='draftcombinestats', league_id='00', season_year='2017-18')

The Draft class contains all resources needed to use the draft- related API calls. stats.nba.com has the following draft-related API endpoints:

  • draftcombinestats: Draft combine drill results and measurement data for players.
  • drafthistory: Draft results detailing metadata of draftees by season.

The Draft class has the following required parameters:

@param headers (dict): Dictionary of request header information
required by the API. Specifically, the API requires you to declare the ‘User-Agent’ key of the request header dictionary. More information can be found here and an example request header dictionary can be found in the __init__.py file in the tests folder of this module.

@param league_id (str): LeagueID in the API. String of a two-digit number corresponding to the league. ‘00’ is the NBA, ‘10’ is the WNBA, and ‘01’ is the ABA. Draft data is only available for the NBA.

@param season_year (str): SeasonYear in the API. String of a two-year season year in a YYYY-ZZ format, where the ZZ are the last two digits of the following year. For example, ‘2017-18’ is a valid value of season_year and represents the 2017-18 NBA season. ‘All Time’ is a valid value for the ‘draftcombinestats’ endpoint.

Attributes:

api_resp (dict): JSON object of the API response. The API response has three keys. The ‘resource’ key describes the type of response returned (the endpoint in this instance). The ‘parameters’ key describes the parameters provided in the API call. The ‘resultSets’ key contains the data returned in the API call.

data (dict): A dictionary of response names. Each response name is a key to a list of dictionaries containing the corresponding data.

Headshot class

(additional documentation here)

class py_ball.image.Headshot(league='WNBA', player_id='203400', team_id='', season='')

The Headshot class contains all resources needed to pull headshot images for NBA and WNBA players.

The Headshot class has the following required parameters:

@param league (str): String, either ‘WNBA’ or ‘NBA’,
to the league in which the desired player or team plays.

@param player_id (str): String of an integer corresponding to a player ID for a given player.

@param team_id (str): String of a 10-digit integer that uniquely identifies a team for which data is to be returned.

@param season (str): String of a year in YYYY format corresponding to the year in which the NBA season begins.

Attributes:

image (PngImageFile): Image file of the desired headshot.
Note that this image file is not saved locally, but stored in the Headshot class object.

Logo class

(additional documentation here)

The Logo class contains all resources needed to pull logo images for NBA and WNBA players.

The Logo class has the following required parameters:

@param league (str): String, either ‘WNBA’ or ‘NBA’,
to the league in which the desired player plays.

@param team_id (str): String of a 10-digit integer that uniquely identifies a team for which data is to be returned.

@param season_year (str): String of a two-year season year in a YYYY-ZZ format, where the ZZ are the last two digits of the following year. For example, ‘2017-18’ is a valid value of season_year and represents the 2017-18 NBA season. season_year is only required for NBA logos.

Attributes:

image (PngImageFile): Image file of the desired headshot.
Note that this image file is not saved locally, but stored in the Headshot class object.

LeaderBoard class

(additional documentation here)

class py_ball.leaderboard.LeaderBoard(headers, endpoint='homepageleaders', league_id='00', stat_category='Points', stat_category_ll='PTS', stat_type='Tracking', stat='PTS', season='2017-18', season_type='Regular Season', player_or_team='Player', game_scope='Season', player_scope='All Players', per_mode='PerGame', scope='S')

The LeaderBoard class contains all resources needed to use the leader board API calls. stats.nba.com has the following leader board API endpoints:

  • homepageleaders: Top 5 leaders in a number of statistical categories.
  • homepagev2: Groups of top 5 leaders in statistical categories related to a given concept.
  • leaderstiles: Top 5 leaders in a number of statistical categories, some included in ‘homepageleaders’ and some not.
  • leagueleaders: Longer list of league leaders in a number of statistical categories.

The LeaderBoard class has the following required parameters:

@param headers (dict): Dictionary of request header information
required by the API. Specifically, the API requires you to declare the ‘User-Agent’ key of the request header dictionary. More information can be found here and an example request header dictionary can be found in the __init__.py file in the tests folder of this module.

@param league_id (str): LeagueID in the API. String of a two-digit number corresponding to the league. ‘00’ is the NBA, ‘10’ is the WNBA, and ‘01’ is the ABA.

@param stat_category (str): StatCategory in the API. String corresponding to the stat_category desired in the API response. Valid values include:

  • ‘Points’, ‘Rebounds’, ‘Assists’, ‘Defense’, ‘Playmaking’, ‘Efficiency’, ‘Fast Break’,’Scoring Breakdown’

The stat_category parameter is only required by the ‘homepageleaders’ endpoint.

@param stat_category_ll (str): StatCategory in the API. String corresponding to the stat_category desired in the API response. Valid values include:

  • ‘MIN’, ‘FGM’, ‘FGA’, ‘FG_PCT’, ‘FG3M’, ‘FG3A’, ‘FG3_PCT’ ‘FTM’, ‘FTA’, ‘FT_PCT’, ‘OREB’, ‘DREB’, ‘REB’, ‘AST’ ‘STL’, ‘BLK’, ‘TOV’, ‘PTS’, ‘EFF’

The stat_category_ll parameter is only required by the ‘leagueleaders’ endpoint.

@param stat_type (str): StatType in the API. String corresponding to the stat_type desired in the API response. Valid values include:

  • ‘Traditional’, ‘Advanced’, ‘Tracking’

The stat_type parameter is only required by the ‘homepagev2’ endpoint.

@param stat (str): Stat in the API. String corresponding to the stat desired in the API response. Valid values include:

  • ‘PTS’, ‘REB’, ‘AST’, ‘FG_PCT’, ‘FT_PCT’, ‘FG3_PCT’ ‘STL’, ‘BLK’

The stat parameter is only required by the ‘leaderstiles’ endpoint.

@param season (str): Season in the API. String of a two-year season in a YYYY-ZZ format, where the ZZ are the last two digits of the following year. For example, ‘2017-18’ is a valid value of season and represents the 2017-18 NBA season.

@param season_type (str): SeasonType in the API. String indicating the type of season for which data is desired. Valid values include:

  • ‘Regular Season’, ‘Pre Season’, ‘Playoffs’

@param player_or_team (str): PlayerOrTeam in the API. String indicating whether data returned is for ‘Player’ or ‘Team’ leaders.

@param game_scope (str): GameScope in the API. String indicating the period of time for which data is desired. Valid values include:

  • ‘Season’, ‘Last 10’, ‘Yesterday’, ‘Finals’

@param player_scope (str): PlayerScope in the API. String indicating the type of players for which data is desired. Valid values include:

  • ‘All Players’, ‘Rookies’

@param per_mode (str): PerMode in the API. String indicating the rate of the statistics to be returned. Valid values include:

  • ‘Totals’, ‘PerGame’, ‘Per48’

The per_mode parameter is only required by the ‘leagueleaders’ endpoint.

@param scope (str): Scope in the API. String indicating the type of players for which data is desired. This is nearly identical to player_scope above, but for the ‘leagueleaders’ endpoint. Valid values include:

  • ‘S’ (All players), ‘Rookies’

Attributes:

api_resp (dict): JSON object of the API response. The API response has three keys. The ‘resource’ key describes the type of response returned (the endpoint in this instance). The ‘parameters’ key describes the parameters provided in the API call. The ‘resultSets’ key contains the data returned in the API call.

data (dict): A dictionary of response names. Each response name is a key to a list of dictionaries containing the corresponding data.

League class

(additional documentation here)

class py_ball.league.League(headers, endpoint='commonallplayers', league_id='00', season='2017-18', season_id='22017', current_season='1')

The League class contains all resources needed to use the league- related API calls. stats.nba.com has the following league-related API endpoints:

  • commonallplayers: Current roster information if the current_season flag is ‘1’, historical player information if the current_season flag is ‘0’.
  • commonteamyears: Start and end dates for teams in league history.
  • commonplayoffseries: Playoff series matchup breakdown by game.
  • franchisehistory: Current and defunct franchise histories, including performance and franchise metadata.
  • playoffpicture: Current state of the playoff picture by conference.

The League class has the following required parameters:

@param headers (dict): Dictionary of request header information
required by the API. Specifically, the API requires you to declare the ‘User-Agent’ key of the request header dictionary. More information can be found here and an example request header dictionary can be found in the __init__.py file in the tests folder of this module.

@param league_id (str): LeagueID in the API. String of a two-digit number corresponding to the league. ‘00’ is the NBA, ‘10’ is the WNBA, and ‘01’ is the ABA.

@param season (str): Season in the API. String of a two-year
season in a YYYY-ZZ format, where the ZZ are the last two digits of the following year. For example, ‘2017-18’ is a valid value of season and represents the 2017-18 NBA season. season is required by the ‘commonallplayers’ and ‘commonplayoffseries’ endpoints.
@param season_id (str): SeasonID in the API. String of a year season in a XYYYY format. X indicates the season type (‘1’ for preseason, ‘2’ for regular season, ‘4’ for the playoffs). For example, ‘22017’ is a valid value of season_id and represents the 2017-18 NBA regular
season. season_id is required by the ‘playoffpicture’ endpoint.

@param current_season (str): IsOnlyCurrentSeason in the API. Boolean value (‘1’ or ‘0’) indicating whether only the current season should be returned (‘1’). A value of ‘0’ returns all players in league history. current_season is required by the ‘commonallplayers’ endpoint.

Attributes:

api_resp (dict): JSON object of the API response. The API response has three keys. The ‘resource’ key describes the type of response returned (the endpoint in this instance). The ‘parameters’ key describes the parameters provided in the API call. The ‘resultSets’ key contains the data returned in the API call.

data (dict): A dictionary of response names. Each response name is a key to a list of dictionaries containing the corresponding data.

LeagueDash class

(additional documentation here)

class py_ball.league_dash.LeagueDash(headers, endpoint='leaguedashlineups', league_id='00', group_quantity='5', per_mode='PerGame', plus_minus='N', rank='Y', pace_adjust='N', measure_type='Base', period='0', vs_conference='', last_n_games='0', team_id='0', location='', outcome='', date_from='', date_to='', opp_team_id='0', season='2017-18', vs_division='', game_segment='', month='0', season_type='Regular Season', season_segment='', clutch_time='Last 5 Minutes', ahead_behind='Ahead or Behind', point_diff='0', game_scope='', player_experience='', player_position='', starters_bench='', distance_range='By Zone', defense_category='Overall')

The LeagueDash class contains all resources needed to use the league performance stats related API calls. stats.nba.com has the following league performance stats related API endpoints:

- **leaguedashlineups*: Traditional and plus/minus statistics for sets of lineups between sizes 2 to 5 players, inclusive. - leaguedashplayerbiostats: Player metadata and performance statistics for a given season. - **leaguedashplayerclutch*: Traditional, plus/minus, and rank statistics for players in a defined clutch period. - **leaguedashplayershotlocations*: Player shooting-related statistics by shot distance/type. - leaguedashplayerptshot: Shooting-related statistics for a given season by player. - **leaguedashplayerstats*: Traditional, plus/minus, and rank statistics for players. - leaguedashptdefend: Defensive statistics for a given season by player. - leaguedashptteamdefend: Defensive statistics for a given season by team. - leaguedashteamptshot: Shooting-related statistics for a given season by team.

The LeagueDash class has the following required parameters:

@param headers (dict): Dictionary of request header information
required by the API. Specifically, the API requires you to declare the ‘User-Agent’ key of the request header dictionary. More information can be found here and an example request header dictionary can be found in the __init__.py file in the tests folder of this module.

@param league_id (str): LeagueID in the API). String of a two-digit number corresponding to the league. ‘00’ is the NBA, ‘10’ is the WNBA, and ‘01’ is the ABA.

@param group_quantity (str): GroupQuantity in the API. String of an integer indicating the number of players to include a lineup for the leaguedashlineups endpoint. The minimum value is ‘2’ and the maximum value is ‘5’.

@param per_mode (str): PerMode in the API. String indicating the type of rate stats to be returned. Valid values include:

  • ‘Totals’, ‘PerGame’, ‘MinutesPer’, ‘Per48’, ‘Per40’, ‘Per36’, ‘PerMinute’, ‘PerPossession’, ‘PerPlay’, ‘Per100Possessions’, ‘Per100Plays’

@param plus_minus (str): PlusMinus in the API. String representing a Boolean value that indicates whether the values being returned should be in plus-minus form. Valid values include:

  • ‘Y’, ‘N’

@param rank (str): Rank in the API. String representing a Boolean value that indicates whether the values being returned should be in rank form. Valid values include:

  • ‘Y’, ‘N’

@param pace_adjust (str): PaceAdjust in the API. String representing a Boolean value that indicates whether the values being returned should be pace-adjusted. Valid values include:

  • ‘Y’, ‘N’

@param measure_type (str): MeasureType in the API. String indicating the set of statistics to be returned. Valid values include:

  • ‘Base’, ‘Advanced’, ‘Misc’, ‘Four Factors’, ‘Scoring’, ‘Opponent’, ‘Usage’, ‘Defense’

@param period (str): Period in the API. String of an integer value that corresponds to a desired quarter for data to be returned. A value of ‘0’ returns data across all quarters.

@param vs_conference (str): VsConference in the API. String indicating the conference of the opposing team for data to be returned. An empty string returns data across all conferences. Valid values include:

  • ‘East’, ‘West’, ‘’

@param last_n_games (str): LastNGames in the API. String of an integer indicating the desired number of most recent games for data to be returned. A value of ‘0’ returns data across all previous games, subject to other constraints in the API call.

@param team_id (str): TeamID in the API. String of a 10-digit integer that uniquely identifies a team for which data is to be returned.

@param location (str): Location in the API. String indicating the game location for the data to be returned. An empty string returns data across both home and road games. Valid values include:

  • ‘Home’, ‘Road’, ‘’

@param outcome (str): Outcome in the API. String indicating the game outcome for the data to be returned. An empty string returns data across both wins and losses. Valid values include:

  • ‘W’, ‘L’, ‘’

@param date_from (str): DateFrom in the API. String of a date in a MM/DD/YYYY format indicating the start date for which data is to be returned.

@param date_to (str): DateTo in the API. String of a date in a MM/DD/YYYY format indicating the end date for which data is to be returned.

@param opp_team_id (str): OpponentTeamID in the API. String of a 10-digit integer that uniquely identifies an opposing team for which data is to be returned.

@param season (str): Season in the API. String of a two-year season in a YYYY-ZZ format, where the ZZ are the last two digits of the following year. For example, ‘2017-18’ is a valid value of season and represents the 2017-18 NBA season.

@param vs_division (str): VsDivision in the API. String indicating the division of the opposing team for data to be returned. An empty string returns data across all divisions. Valid values include:

  • ‘Atlantic’, ‘Central’, ‘Northwest’, ‘Pacific’, ‘Southeast’, ‘Southwest’, ‘East’, ‘West’, ‘’

The ‘East’ and ‘West’ values correspond to conferences.

@param game_segment (str): GameSegment in the API. String indicating the section of a game for data to be returned. An empty string returns data across all game segments. Valid values include:

  • ‘First Half’, ‘Overtime’, ‘Second Half’, ‘’

@param month (str): Month in the API. String of an integer corresponding to a month for data to be returned. A value of ‘0’ returns data across all months.

@param season_type (str): SeasonType in the API. String indicating the type of season for data to be returned. Valid values include:

  • ‘Regular Season’, ‘Pre Season’, ‘Playoffs’, ‘All Star’

@param season_segment (str): SeasonSegment in the API. String indicating the section of the season for data to be returned. An empty string returns data across all season segments. Valid values include:

  • ‘Pre All-Star’, ‘Post All-Star’, ‘’

@param clutch_time (str): ClutchTime in the API. String that defines the type of clutch time for the data to be returned. Valid values include:

  • ‘Last 5 Minutes’, ‘Last 4 Minutes’, ‘Last 3 Minutes’, ‘Last 2 Minutes’, ‘Last 1 Minute’, ‘Last 30 Seconds’, ‘Last 10 Seconds’

@param ahead_behind (str): AheadBehind in the API. String indicating the type of score differential for the data to be returned. Valid values include:

  • ‘Ahead or Behind’, ‘Behind or Tied’, ‘Ahead or Tied’

@param point_diff (str): PointDiff in the API. String of zero or a positive integer indicating the maximum point differential for data to be returned.

@param game_scope (str): GameScope in the API. String indicating the recency of the data to be returned. An empty string returns data across all past games, subject to other constraints in the API call. Valid values include:

  • ‘Yesterday’, ‘Last 10’, ‘’

@param player_experience (str): PlayerExperience in the API. String indicating the level of player experience for data to be returned. An empty string returns data across all levels of player experience. Valid values include:

  • ‘Rookie’, ‘Sophomore’, ‘Veteran’, ‘’

@param player_position (str): PlayerPosition in the API. String indicating the player position for data to be returned. An empty string returns data across all player positions. Valid values include:

  • ‘F’, ‘C’, ‘G’, ‘C-F’, ‘F-C’, ‘F-G’, ‘G-F’, ‘’

@param starters_bench (str): StarterBench in the API. String indicating whether data should be returned for either or both starters or bench players. An empty string returns data across both starters and bench players. Valid values include:

  • ‘Starters’, ‘Bench’, ‘’

@param distance_range (str): DistanceRange in the API. String indicating the size/type of the distance range bins for data to be returned. Valid values include:

  • ‘5ft Range’, ‘8ft Range’, ‘By Zone’

@param defense_category (str): DefenseCategory in the API. String indicating the shot type of defensive data to be returned. Valid values include:

  • ‘Overall’, ‘3 Pointers’, ‘2 Pointers’, ‘Less Than 6Ft’, ‘Less Than 10Ft’, ‘Greater Than 15Ft’

Attributes:

api_resp (dict): JSON object of the API response. The API response has three keys. The ‘resource’ key describes the type of response returned (the endpoint in this instance). The ‘parameters’ key describes the parameters provided in the API call. The ‘resultSets’ key contains the data returned in the API call.

data (dict): A dictionary of response names. Each response name is a key to a list of dictionaries containing the corresponding data.

PlayByPlay class

(additional documentation here)

class py_ball.playbyplay.PlayByPlay(headers, game_id, endpoint='playbyplay', start_period='1', end_period='10')

The PlayByPlay class contains all resources needed to use the pbp-related API calls. stats.nba.com has the following pbp-related API endpoints:

  • playbyplay: Game play-by-play with basic fields, such as play desscription, score, margin, period, and game time.
  • playbyplayv2: Game play-by-play with the basic fields above, as well as player information of those involved in the play.

The PlayByPlay class has the following required parameters:

@param headers (dict): Dictionary of request header information
required by the API. Specifically, the API requires you to declare the ‘User-Agent’ key of the request header dictionary. More information can be found here and an example request header dictionary can be found in the __init__.py file in the tests folder of this module.

@param game_id (str): GameID in the API. 10-digit string that represents a unique game. The format is two leading zeroes, followed by a season indicator number (‘1’ for preseason, ‘2’ for regular season, ‘4’ for the post-season), then the trailing digits of the season in which the game took place (e.g. ‘17’ for the 2017-18 season). The following 5 digits increment from ‘00001’ in order as the season progresses. For example, ‘0021600001’ is the game_id of the first game of the 2016-17 NBA regular season.

@param start_period (str): StartPeriod in the API. String of an integer that corresponds to the period for which the boxscore begins.

@param end_period (str): EndPeriod in the API. String of an integer that corresponds to the period for which the boxscore ends (Overtime increments logically, e.g. ‘5’ is the first overtime period).

Attributes:

api_resp (dict): JSON object of the API response. The API response has three keys. The ‘resource’ key describes the type of response returned (‘playbyplay’ in this instance). The ‘parameters’ key describes the parameters provided in the API call. The ‘resultSets’ key contains the data returned in the API call.

data (dict): A dictionary of response names. Each response name is a key to a list of dictionaries containing the corresponding data.

Player class

(additional documentation here)

class py_ball.player.Player(headers, endpoint='playercareerstats', player_id='2544', player_id_list='2544', vs_player_id_list='201939', league_id='00', per_mode='PerGame', plus_minus='N', rank='Y', pace_adjust='N', measure_type='Base', period='0', vs_conference='', last_n_games='0', team_id='0', location='', outcome='', date_from='', date_to='', opp_team_id='0', season='2017-18', vs_division='', game_segment='', month='0', season_type='Regular Season', season_segment='', vs_player_id='201939', player_team_id='1610612747', vs_player_team_id='1610612744', player_id_1='2544', player_id_2='0', player_id_3='0', player_id_4='0', player_id_5='0', vs_player_id_1='201939', vs_player_id_2='0', vs_player_id_3='0', vs_player_id_4='0', vs_player_id_5='0', rookie_year='', context_measure='FGA', player_position='', game_id='0011800079')

The Player class contains all resources needed to use the player-related API calls. stats.nba.com has the following player performance stats related API endpoints:

  • playercareerstats: Season and career stats for a given player, broken down by season type (including college).
  • playercompare: Individual and combined (overall) statistics for a given list of players and opposing players.
  • playerdashboardbyclutch: Traditional and rank statistics broken down by different definitions of clutch for a player.
  • playerdashboardbygamesplits: Traditional and rank statistics broken down by different splits (half, quarter, and score differential).
  • playerdashboardbygeneralsplits: Traditional and rank statistics broken down by different splits (win/loss, location, month, pre/post All-Star, days rest).
  • playerdashboardbylastngames: Traditional and rank statistics broken down by the number of n recent games and game number bins.
  • playerdashboardbyopponent: Traditional and rank statistics broken down by opponent splits (conference, division, and individual team).
  • playerdashboardbyshootingsplits: Traditional and rank statistics broken down by shooting splits (shot distance, shot area, assisted/unassisted, shot type, and indivdual assistant).
  • playerdashboardbyteamperformance: Traditional and rank statistics broken down by team performance splits (win/loss, score differential, points for, and points against).
  • playerdashboardbyyearoveryear: Traditional and rank statistics broken down by year.
  • playerdashptpass: Shooting statistics for passes to and from a player broken down by teammates.
  • playerdashptreb: Rebound statistics broken down by shot type, contesting players, and shot/rebound distance.
  • playerdashptshotdefend: Defensive statistics broken down by shot type/distance.
  • playerdashptshots: Shooting statistics broken down by shot type, shot clock time, number of tribbles, defender proximity, and length of touch.
  • playergamelog: Game log statistics for a given year.
  • playerprofilev2: Career and season summary statistics broken down by season type.
  • playervsplayer: Player statistics versus a given opponent player broken down by several shooting related splits (shot distance and area)
  • playersvsplayers: Currently not available
  • shotchartdetail: Player and league shot chart data giving results and location-related information for several player actions, such as shots and fouls.

The Player class has the following required parameters:

@param headers (dict): Dictionary of request header information
required by the API. Specifically, the API requires you to declare the ‘User-Agent’ key of the request header dictionary. More information can be found here and an example request header dictionary can be found in the __init__.py file in the tests folder of this module.

@param league_id (str): LeagueID in the API. String of a two-digit number corresponding to the league. ‘00’ is the NBA, ‘10’ is the WNBA, and ‘01’ is the ABA.

@param player_id (str): PlayerID in the API. String of an integer corresponding to a player ID for a given player.

@param player_id_list (str): PlayerIDList in the API. String of a comma-separated list of player IDs for player comparisons to the players given in vs_player_id_list. Valid only for the ‘playercompare’ endpoint.

@param vs_player_id_list (str): VsPlayerIDList in the API.
String of a comma-separated list of player IDs for player comparisons to the players given in player_id_list. Valid only for the ‘playercompare’ endpoint.

@param per_mode (str): PerMode in the API String indicating the type of rate stats to be returned. Valid values include:

  • ‘Totals’, ‘PerGame’, ‘MinutesPer’, ‘Per48’, ‘Per40’, ‘Per36’, ‘PerMinute’, ‘PerPossession’, ‘PerPlay’, ‘Per100Possessions’, ‘Per100Plays’

@param plus_minus (str): PlusMinus in the API. String representing a Boolean value that indicates whether the values being returned should be in plus-minus form. Valid values include:

  • ‘Y’, ‘N’

@param rank (str): Rank in the API. String representing a Boolean value that indicates whether the values being returned should be in rank form. Valid values include:

  • ‘Y’, ‘N’

@param pace_adjust (str): PaceAdjust in the API. String representing a Boolean value that indicates whether the values being returned should be pace-adjusted. Valid values include:

  • ‘Y’, ‘N’

@param measure_type (str): MeasureType in the API. String indicating the set of statistics to be returned. Valid values include:

  • ‘Base’, ‘Advanced’, ‘Misc’, ‘Four Factors’, ‘Scoring’, ‘Opponent’, ‘Usage’, ‘Defense’

@param period (str): Period in the API. String of an integer value that corresponds to a desired quarter for data to be returned. A value of ‘0’ returns data across all quarters.

@param vs_conference (str): VsConference in the API. String indicating the conference of the opposing team for data to be returned. An empty string returns data across all conferences. Valid values include:

  • ‘East’, ‘West’, ‘’

@param last_n_games (str): LastNGames in the API. String of an integer indicating the desired number of most recent games for data to be returned. A value of ‘0’ returns data across all previous games, subject to other constraints in the API call.

@param team_id (str): TeamID in the API. String of a 10-digit integer that uniquely identifies a team for which data is to be returned.

@param location (str): Location in the API. String indicating the game location for the data to be returned. An empty string returns data across both home and road games. Valid values include:

  • ‘Home’, ‘Road’, ‘’

@param outcome (str): Outcome in the API. String indicating the game outcome for the data to be returned. An empty string returns data across both wins and losses. Valid values include:

  • ‘W’, ‘L’, ‘’

@param date_from (str): DateFrom in the API. String of a date in a MM/DD/YYYY format indicating the start date for which data is to be returned.

@param date_to (str): DateTo in the API. String of a date in a MM/DD/YYYY format indicating the end date for which data is to be returned.

@param opp_team_id (str): OpponentTeamID in the API. String of a 10-digit integer that uniquely identifies an opposing team for which data is to be returned.

@param season (str): Season in the API. String of a two-year season in a YYYY-ZZ format, where the ZZ are the last two digits of the following year. For example, ‘2017-18’ is a valid value of season and represents the 2017-18 NBA season.

@param vs_division (str): VsDivision in the API. String indicating the division of the opposing team for data to be returned. An empty string returns data across all divisions. Valid values include:

  • ‘Atlantic’, ‘Central’, ‘Northwest’, ‘Pacific’, ‘Southeast’, ‘Southwest’, ‘East’, ‘West’, ‘’

The ‘East’ and ‘West’ values correspond to conferences.

@param game_segment (str): GameSegment in the API. String indicating the section of a game for data to be returned. An empty string returns data across all game segments. Valid values include:

  • ‘First Half’, ‘Overtime’, ‘Second Half’, ‘’

@param month (str): Month in the API. String of an integer corresponding to a month for data to be returned. A value of ‘0’ returns data across all months.

@param season_type (str): SeasonType in the API. String indicating the type of season for data to be returned. Valid values include:

  • ‘Regular Season’, ‘Pre Season’, ‘Playoffs’, ‘All Star’

@param season_segment (str): SeasonSegment in the API. String indicating the section of the season for data to be returned. An empty string returns data across all season segments. Valid values include:

  • ‘Pre All-Star’, ‘Post All-Star’, ‘’

@param vs_player_id (str): VsPlayerID in the API. String of an integer corresponding to a player ID for a given player.

@param player_team_id (str): PlayerTeamID in the API. String of an integer corresponding to a team ID for a given team.

@param vs_player_team_id (str): VsPlayerTeamID in the API. String of an integer corresponding to a team ID for a given team.

@param player_id_x (str): PlayerIDX in the API. String of an integer corresponding to a player ID for a given player. The x (X in the API) is an integer 1 through 5. Valid only for the ‘playersvsplayers’ endpoint.

@param vs_player_id_x (str): VsPlayerIDX in the API. String of an integer corresponding to a player ID for a given player. The x (X in the API) is an integer 1 through 5. Valid only for the ‘playersvsplayers’ endpoint.

@param rookie_year (str): RookieYear in the API. String of a two-year season in a YYYY-ZZ format, where the ZZ are the last two digits of the following year. For example, ‘2017-18’ is a valid value of rookie_year and represents the 2017-18 NBA season. This field should correspond to the rookie year of the player given.

@param context_measure (str): ContextMeasure in the API. String of an abbreviated statistic corresponding to the type of action to be included in the data returned. Valid values include:

  • ‘PTS’, ‘FGM’, ‘FGA’, ‘FG_PCT’, ‘FG3M’, ‘FG3A’, ‘FG3_PCT’, ‘PF’, ‘EFG_PCT’, ‘TS_PCT’, ‘PTS_FB’, ‘PTS_OFF_TOV’, ‘PTS_2ND_CHANCE’, ‘PF’

@param player_position (str): PlayerPosition in the API. String of a basketball position corresponding to the position of the player given. An empty string returns data across all positions played. Valid values include:

  • ‘Guard’, ‘Center’, ‘Forward’

@param game_id (str): GameID in the API. 10-digit string that represents a unique game. The format is two leading zeroes, followed by a season indicator number (‘1’ for preseason, ‘2’ for regular season, ‘4’ for the post-season), then the trailing digits of the season in which the game took place (e.g. ‘17’ for the 2017-18 season). The following 5 digits increment from ‘00001’ in order as the season progresses. For example, ‘0021600001’ is the game_id of the first game of the 2016-17 NBA regular season.

Attributes:

api_resp (dict): JSON object of the API response. The API response has three keys. The ‘resource’ key describes the type of response returned (the endpoint in this instance). The ‘parameters’ key describes the parameters provided in the API call. The ‘resultSets’ key contains the data returned in the API call.

data (dict): A dictionary of response names. Each response name is a key to a list of dictionaries containing the corresponding data.

ScoreBoard class

(additional documentation here)

class py_ball.scoreboard.ScoreBoard(headers, endpoint='scoreboard', league_id='00', game_date='12/26/2018', day_offset='0')

The ScoreBoard class contains all resources needed to use the score board API calls. stats.nba.com has the following score board API endpoints:

  • scoreboard: Live scores across the league, with series metadata and standings information.
  • scoreboardv2: Live scores across the league, with series metadata and standings information. Also, scoreboardv2 has ticket, win probability, and team leader information.

The ScoreBoard class has the following required parameters:

@param headers (dict): Dictionary of request header information
required by the API. Specifically, the API requires you to declare the ‘User-Agent’ key of the request header dictionary. More information can be found here and an example request header dictionary can be found in the __init__.py file in the tests folder of this module.

@param league_id (str): LeagueID in the API. String of a two-digit number corresponding to the league. ‘00’ is the NBA, ‘10’ is the WNBA, and ‘01’ is the ABA.

@param game_date (str): GameDate in the API. String of a date formatted as ‘MM/DD/YYYY’ representing the date for which data is desired.

@param day_offset (str): DayOffset in the API. String of an integer representing days from or before the date given in game_date for which data is desired. Positive values indicate days into the future, zero represents the current day, and negative values indicate days into the past.

Attributes:

api_resp (dict): JSON object of the API response. The API response has three keys. The ‘resource’ key describes the type of response returned (the endpoint in this instance). The ‘parameters’ key describes the parameters provided in the API call. The ‘resultSets’ key contains the data returned in the API call.

data (dict): A dictionary of response names. Each response name is a key to a list of dictionaries containing the corresponding data.

Team class

(additional documentation here)

class py_ball.team.Team(headers, endpoint='teamdashboardbyclutch', player_id='2544', league_id='00', per_mode='PerGame', plus_minus='N', rank='Y', pace_adjust='N', measure_type='Base', period='0', vs_conference='', last_n_games='0', team_id='1610612747', location='', outcome='', date_from='', date_to='', opp_team_id='0', season='2017-18', vs_division='', game_segment='', month='0', season_type='Regular Season', season_segment='', vs_player_id='201939', game_id='0011800079', group_quantity='5')

The Team class contains all resources needed to use the team-related API calls. stats.nba.com has the following team-related API endpoints:

  • teamdashboardbyclutch: Traditional and rank statistics broken down by different definitions of clutch for a team.
  • teamdashboardbygamesplits: Traditional and rank statistics broken down by different splits (half, quarter, and score differential).
  • teamdashboardbygeneralsplits: Traditional and rank statistics broken down by different splits (win/loss, location, month, pre/post All-Star, days rest).
  • teamdashboardbylastngames: Traditional and rank statistics broken down by the number of n recent games and game number bins.
  • teamdashboardbyopponent: Traditional and rank statistics broken down by opponent splits (conference, division, and individual team).
  • teamdashboardbyshootingsplits: Traditional and rank statistics broken down by shooting splits (shot distance, shot area, assisted/unassisted, shot type, and indivdual assistant).
  • teamdashboardbyteamperformance: Traditional and rank statistics broken down by team performance splits (win/loss, score differential, points for, and points against).
  • teamdashboardbyyearoveryear: Traditional and rank statistics broken down by year.
  • teamdashlineups: Traditional and plus/minus statistics for sets of lineups between sizes 2 to 5 players, inclusive.
  • teamdashptpass: Shooting statistics for passes to and from a player broken down by teammates.
  • teamdashptreb: Rebound statistics broken down by shot type, contesting players, and shot/rebound distance.
  • teamdashptshots: Shooting statistics broken down by shot type, shot clock time, number of tribbles, defender proximity, and length of touch.
  • teamgamelog: Game log statistics for a given year.
  • teaminfocommon: Team information for a given year.
  • teamplayerdashboard: Player traditional and rank statistics for a given team.
  • teamplayeronoffdetails: Team traditional and rank statistics broken down by on/off splits per player.
  • teamplayeronoffsummary: Team summary statistics broken down by on/off splits per player.
  • teamvsplayer: Team statistics versus a given opponent player broken down by several shooting related splits (shot distance and area)
  • teamyearbyyearstats: Team statistics and performance broken down by year.

The Team class has the following required parameters:

@param headers (dict): Dictionary of request header information
required by the API. Specifically, the API requires you to declare the ‘User-Agent’ key of the request header dictionary. More information can be found here and an example request header dictionary can be found in the __init__.py file in the tests folder of this module.

@param league_id (str): LeagueID in the API. String of a two-digit number corresponding to the league. ‘00’ is the NBA, ‘10’ is the WNBA, and ‘01’ is the ABA.

@param per_mode (str): PerMode in the API. String indicating the type of rate stats to be returned. Valid values include:

  • ‘Totals’, ‘PerGame’, ‘MinutesPer’, ‘Per48’, ‘Per40’, ‘Per36’, ‘PerMinute’, ‘PerPossession’, ‘PerPlay’, ‘Per100Possessions’, ‘Per100Plays’

@param plus_minus (str): PlusMinus in the API. String representing a Boolean value that indicates whether the values being returned should be in plus-minus form. Valid values include:

  • ‘Y’, ‘N’

@param rank (str): Rank in the API. String representing a Boolean value that indicates whether the values being returned should be in rank form. Valid values include:

  • ‘Y’, ‘N’

@param pace_adjust (str): PaceAdjust in the API. String representing a Boolean value that indicates whether the values being returned should be pace-adjusted. Valid values include:

  • ‘Y’, ‘N’

@param measure_type (str): MeasureType in the API. String indicating the set of statistics to be returned. Valid values include:

  • ‘Base’, ‘Advanced’, ‘Misc’, ‘Four Factors’, ‘Scoring’, ‘Opponent’, ‘Usage’, ‘Defense’

@param period (str): Period in the API. String of an integer value that corresponds to a desired quarter for data to be returned. A value of ‘0’ returns data across all quarters.

@param vs_conference (str): VsConference in the API. String indicating the conference of the opposing team for data to be returned. An empty string returns data across all conferences. Valid values include:

  • ‘East’, ‘West’, ‘’

@param last_n_games (str): LastNGames in the API. String of an integer indicating the desired number of most recent games for data to be returned. A value of ‘0’ returns data across all previous games, subject to other constraints in the API call.

@param team_id (str): TeamID in the API. String of a 10-digit integer that uniquely identifies a team for which data is to be returned.

@param location (str): Location in the API. String indicating the game location for the data to be returned. An empty string returns data across both home and road games. Valid values include:

  • ‘Home’, ‘Road’, ‘’

@param outcome (str): Outcome in the API. String indicating the game outcome for the data to be returned. An empty string returns data across both wins and losses. Valid values include:

  • ‘W’, ‘L’, ‘’

@param date_from (str): DateFrom in the API. String of a date in a MM/DD/YYYY format indicating the start date for which data is to be returned.

@param date_to (str): DateTo in the API. String of a date in a MM/DD/YYYY format indicating the end date for which data is to be returned.

@param opp_team_id (str): OpponentTeamID in the API. String of a 10-digit integer that uniquely identifies an opposing team for which data is to be returned.

@param season (str): Season in the API. String of a two-year season in a YYYY-ZZ format, where the ZZ are the last two digits of the following year. For example, ‘2017-18’ is a valid value of season and represents the 2017-18 NBA season.

@param vs_division (str): VsDivision in the API. String indicating the division of the opposing team for data to be returned. An empty string returns data across all divisions. Valid values include:

  • ‘Atlantic’, ‘Central’, ‘Northwest’, ‘Pacific’, ‘Southeast’, ‘Southwest’, ‘East’, ‘West’, ‘’

The ‘East’ and ‘West’ values correspond to conferences.

@param game_segment (str): GameSegment in the API. String indicating the section of a game for data to be returned. An empty string returns data across all game segments. Valid values include:

  • ‘First Half’, ‘Overtime’, ‘Second Half’, ‘’

@param month (str): Month in the API. String of an integer corresponding to a month for data to be returned. A value of ‘0’ returns data across all months.

@param season_type (str): SeasonType in the API. String indicating the type of season for data to be returned. Valid values include:

  • ‘Regular Season’, ‘Pre Season’, ‘Playoffs’, ‘All Star’

@param season_segment (str): SeasonSegment in the API): String indicating the section of the season for data to be returned. An empty string returns data across all season segments. Valid values include:

  • ‘Pre All-Star’, ‘Post All-Star’, ‘’

@param vs_player_id (str): VsPlayerID in the API. String of an integer corresponding to a player ID for a given player.

@param game_id (str): GameID in the API. 10-digit string that represents a unique game. The format is two leading zeroes, followed by a season indicator number (‘1’ for preseason, ‘2’ for regular season, ‘4’ for the post-season), then the trailing digits of the season in which the game took place (e.g. ‘17’ for the 2017-18 season). The following 5 digits increment from ‘00001’ in order as the season progresses. For example, ‘0021600001’ is the game_id of the first game of the 2016-17 NBA regular season.

@param group_quantity (str): GroupQuantity in the API. String of an integer indicating the number of players to include a lineup for the leaguedashlineups endpoint. The minimum value is ‘2’ and the maximum value is ‘5’.

Attributes:

api_resp (dict): JSON object of the API response. The API response has three keys. The ‘resource’ key describes the type of response returned (the endpoint in this instance). The ‘parameters’ key describes the parameters provided in the API call. The ‘resultSets’ key contains the data returned in the API call.

data (dict): A dictionary of response names. Each response name is a key to a list of dictionaries containing the corresponding data.