NBA Package¶
The NBA package offers multiple modules which can be use to retrieve information and statistics for the National Basketball Association, such as team names, season stats, game schedules, and boxscore metrics.
Boxscore¶
The Boxscore module can be used to grab information from a specific game.
Metrics range from number of points scored to the number of free throws made, to
the assist rate and much more. The Boxscore can be easily queried by passing a
boxscore’s URI on sports-reference.com which can be retrieved from the
Schedule
class (see Schedule
module below for more information on
retrieving game-specific information).
from sportsipy.nba.boxscore import Boxscore
game_data = Boxscore('201806080CLE')
print(game_data.away_points) # Prints 108
print(game_data.home_points) # Prints 85
df = game_data.dataframe # Returns a Pandas DataFrame of game metrics
The Boxscore module also contains a Boxscores
class which searches for all
games played on a particular day and returns a dictionary of matchups between
all teams on the requested day. The dictionary includes the names and
abbreviations for each matchup as well as the boxscore link if applicable.
from datetime import datetime
from sportsipy.nba.boxscore import Boxscores
games_today = Boxscores(datetime.today())
print(games_today.games) # Prints a dictionary of all matchups for today
The Boxscores
class also allows the ability to query over a range of dates
using a second optional parameter during instantiation of the class. To query a
range of dates, enter the start date as the first parameter and the inclusive
end date as the second parameter.
from datetime import datetime
from sportsipy.nba.boxscore import Boxscores
# Pulls all games between and including January 1, 2018 and January 5, 2018
games = Boxscores(datetime(2018, 1, 1), datetime(2018, 1, 5))
# Prints a dictionary of all results from January 1, 2018 and January 5,
# 2018
print(games.games)
-
class
sportsipy.nba.boxscore.
Boxscore
(uri)[source]¶ Bases:
object
Detailed information about the final statistics for a game.
Stores all relevant metrics for a game such as the date, time, location, result, and more advanced metrics such as the effective field goal rate, the true shooting percentage, the game’s pace, and much more.
- Parameters
uri (string) – The relative link to the boxscore HTML page, such as ‘201710310LAL’.
-
property
away_assist_percentage
¶ Returns a
float
of the percentage of the away team’s field goals that were assisted. Percentage ranges from 0-100.
-
property
away_assists
¶ Returns an
int
of the total number of assists by the away team.
-
property
away_block_percentage
¶ Returns a
float
of the percentage of 2-point field goals that were blocked by the away team. Percentage ranges from 0-100.
-
property
away_blocks
¶ Returns an
int
of the total number of blocks by the away team.
-
property
away_defensive_rating
¶ Returns a
float
of the average number of points scored per 100 possessions by the away team.
-
property
away_defensive_rebound_percentage
¶ Returns a
float
of the percentage of available defensive rebounds the away team grabbed. Percentage ranges from 0-100.
-
property
away_defensive_rebounds
¶ Returns an
int
of the total number of defensive rebounds by the away team.
-
property
away_effective_field_goal_percentage
¶ Returns a
float
of the away team’s field goal percentage while giving extra weight to 3-point field goals. Percentage ranges from 0-1.
-
property
away_field_goal_attempts
¶ Returns an
int
of the total number of field goal attempts by the away team.
-
property
away_field_goal_percentage
¶ Returns a
float
of the number of field goals made divided by the total number of field goal attempts by the away team. Percentage ranges from 0-1.
-
property
away_field_goals
¶ Returns an
int
of the total number of field goals made by the away team.
-
property
away_free_throw_attempt_rate
¶ Returns a
float
of the average number of free throw attempts per field goal attempt by the away team.
-
property
away_free_throw_attempts
¶ Returns an
int
of the total number of free throw attempts by the away team.
-
property
away_free_throw_percentage
¶ Returns a
float
of the number of free throws made divided by the number of free throw attempts by the away team.
-
property
away_free_throws
¶ Returns an
int
of the total number of free throws made by the away team.
-
property
away_losses
¶ Returns an
int
of the number of games the team has lost after the conclusion of the game.
-
property
away_minutes_played
¶ Returns an
int
of the total number of minutes the team played during the game.
-
property
away_offensive_rating
¶ Returns a
float
of the average number of points scored per 100 possessions by the away team.
-
property
away_offensive_rebound_percentage
¶ Returns a
float
of the percentage of available offensive rebounds the away team grabbed. Percentage ranges from 0-100.
-
property
away_offensive_rebounds
¶ Returns an
int
of the total number of offensive rebounds by the away team.
-
property
away_personal_fouls
¶ Returns an
int
of the total number of personal fouls by the away team.
-
property
away_players
¶ Returns a
list
ofBoxscorePlayer
class instances for each player on the away team.
-
property
away_points
¶ Returns an
int
of the number of points the away team scored.
-
property
away_steal_percentage
¶ Returns a
float
of the percentage of possessions that ended in a steal by the away team. Percentage ranges from 0-100.
-
property
away_steals
¶ Returns an
int
of the total number of steals by the away team.
-
property
away_three_point_attempt_rate
¶ Returns a
float
of the percentage of field goal attempts from 3-point range by the away team. Percentage ranges from 0-1.
-
property
away_three_point_field_goal_attempts
¶ Returns an
int
of the total number of three point field goal attempts by the away team.
-
property
away_three_point_field_goal_percentage
¶ Returns a
float
of the number of three point field goals made divided by the number of three point field goal attempts by the away team. Percentage ranges from 0-1.
-
property
away_three_point_field_goals
¶ Returns an
int
of the total number of three point field goals made by the away team.
-
property
away_total_rebound_percentage
¶ Returns a
float
of the percentage of available rebounds the away team grabbed. Percentage ranges from 0-100.
-
property
away_total_rebounds
¶ Returns an
int
of the total number of rebounds by the away team.
-
property
away_true_shooting_percentage
¶ Returns a
float
of the away team’s true shooting percentage which considers free throws, 2-point field goals, and 3-point field goals. Percentage ranges from 0-1.
-
property
away_turnover_percentage
¶ Returns a
float
of the number of times the away team turned the ball over per 100 possessions.
-
property
away_turnovers
¶ Returns an
int
of the total number of turnovers by the away team.
-
property
away_two_point_field_goal_attempts
¶ Returns an
int
of the total number of two point field goal attempts by the away team.
-
property
away_two_point_field_goal_percentage
¶ Returns a
float
of the number of two point field goals made divided by the number of two point field goal attempts by the away team. Percentage ranges from 0-1.
-
property
away_two_point_field_goals
¶ Returns an
int
of the total number of two point field goals made by the away team.
-
property
away_wins
¶ Returns an
int
of the number of games the team has won after the conclusion of the game.
-
property
dataframe
¶ Returns a pandas DataFrame containing all other class properties and values. The index for the DataFrame is the string URI that is used to instantiate the class, such as ‘201710310LAL’.
-
property
date
¶ Returns a
string
of the date the game took place.
-
property
home_assist_percentage
¶ Returns a
float
of the percentage of the home team’s field goals that were assisted. Percentage ranges from 0-100.
-
property
home_assists
¶ Returns an
int
of the total number of assists by the home team.
-
property
home_block_percentage
¶ Returns a
float
of the percentage of 2-point field goals that were blocked by the home team. Percentage ranges from 0-100.
-
property
home_blocks
¶ Returns an
int
of the total number of blocks by the home team.
-
property
home_defensive_rating
¶ Returns a
float
of the average number of points scored per 100 possessions by the away team.
-
property
home_defensive_rebound_percentage
¶ Returns a
float
of the percentage of available defensive rebounds the home team grabbed. Percentage ranges from 0-100.
-
property
home_defensive_rebounds
¶ Returns an
int
of the total number of defensive rebounds by the home team.
-
property
home_effective_field_goal_percentage
¶ Returns a
float
of the home team’s field goal percentage while giving extra weight to 3-point field goals. Percentage ranges from 0-1.
-
property
home_field_goal_attempts
¶ Returns an
int
of the total number of field goal attempts by the home team.
-
property
home_field_goal_percentage
¶ Returns a
float
of the number of field goals made divided by the total number of field goal attempts by the home team. Percentage ranges from 0-1.
-
property
home_field_goals
¶ Returns an
int
of the total number of field goals made by the home team.
-
property
home_free_throw_attempt_rate
¶ Returns a
float
of the average number of free throw attempts per field goal attempt by the home team.
-
property
home_free_throw_attempts
¶ Returns an
int
of the total number of free throw attempts by the home team.
-
property
home_free_throw_percentage
¶ Returns a
float
of the number of free throws made divided by the number of free throw attempts by the home team.
-
property
home_free_throws
¶ Returns an
int
of the total number of free throws made by the home team.
-
property
home_losses
¶ Returns an
int
of the number of games the home team lost after the conclusion of the game.
-
property
home_minutes_played
¶ Returns an
int
of the total number of minutes the team played during the game.
-
property
home_offensive_rating
¶ Returns a
float
of the average number of points scored per 100 possessions by the home team.
-
property
home_offensive_rebound_percentage
¶ Returns a
float
of the percentage of available offensive rebounds the home team grabbed. Percentage ranges from 0-100.
-
property
home_offensive_rebounds
¶ Returns an
int
of the total number of offensive rebounds by the home team.
-
property
home_personal_fouls
¶ Returns an
int
of the total number of personal fouls by the home team.
-
property
home_players
¶ Returns a
list
ofBoxscorePlayer
class instances for each player on the home team.
-
property
home_points
¶ Returns an
int
of the number of points the home team scored.
-
property
home_steal_percentage
¶ Returns a
float
of the percentage of possessions that ended in a steal by the home team. Percentage ranges from 0-100.
-
property
home_steals
¶ Returns an
int
of the total number of steals by the home team.
-
property
home_three_point_attempt_rate
¶ Returns a
float
of the percentage of field goal attempts from 3-point range by the home team. Percentage ranges from 0-1.
-
property
home_three_point_field_goal_attempts
¶ Returns an
int
of the total number of three point field goal attempts by the home team.
-
property
home_three_point_field_goal_percentage
¶ Returns a
float
of the number of three point field goals made divided by the number of three point field goal attempts by the home team. Percentage ranges from 0-1.
-
property
home_three_point_field_goals
¶ Returns an
int
of the total number of three point field goals made by the home team.
-
property
home_total_rebound_percentage
¶ Returns a
float
of the percentage of available rebounds the home team grabbed. Percentage ranges from 0-100.
-
property
home_total_rebounds
¶ Returns an
int
of the total number of rebounds by the home team.
-
property
home_true_shooting_percentage
¶ Returns a
float
of the home team’s true shooting percentage which considers free throws, 2-point field goals, and 3-point field goals. Percentage ranges from 0-1.
-
property
home_turnover_percentage
¶ Returns a
float
of the number of times the home team turned the ball over per 100 possessions.
-
property
home_turnovers
¶ Returns an
int
of the total number of turnovers by the home team.
-
property
home_two_point_field_goal_attempts
¶ Returns an
int
of the total number of two point field goal attempts by the home team.
-
property
home_two_point_field_goal_percentage
¶ Returns a
float
of the number of two point field goals made divided by the number of two point field goal attempts by the home team. Percentage ranges from 0-1.
-
property
home_two_point_field_goals
¶ Returns an
int
of the total number of two point field goals made by the home team.
-
property
home_wins
¶ Returns an
int
of the number of games the home team won after the conclusion of the game.
-
property
location
¶ Returns a
string
of the name of the venue where the game was played.
-
property
losing_abbr
¶ Returns a
string
of the losing team’s abbreviation, such as ‘PHO’ for the Phoenix Suns.
-
property
losing_name
¶ Returns a
string
of the losing team’s name, such as ‘Phoenix Suns’.
-
property
pace
¶ Returns a
float
of the game’s overall pace, measured by the number of possessions per 40 minutes.
-
property
summary
¶ Returns a
dictionary
with two keys, ‘away’ and ‘home’. The value of each key will be a list for each respective team’s score by order of the quarter, with the first element belonging to the first quarter, similar to the following:- {
‘away’: [23, 40, 23, 24], ‘home’: [30, 27, 34, 30]
}
-
property
winner
¶ Returns a
string
constant indicating whether the home or away team won.
-
property
winning_abbr
¶ Returns a
string
of the winning team’s abbreviation, such as ‘DET’ for the Detroit Pistons.
-
property
winning_name
¶ Returns a
string
of the winning team’s name, such as ‘Detroit Pistons’.
-
class
sportsipy.nba.boxscore.
BoxscorePlayer
(player_id, player_name, player_data)[source]¶ Bases:
sportsipy.nba.player.AbstractPlayer
Get player stats for an individual game.
Given a player ID, such as ‘hardeja01’ for James Harden, their full name, and all associated stats from the Boxscore page in HTML format, parse the HTML and extract only the relevant stats for the specified player and assign them to readable properties.
This class inherits the
AbstractPlayer
class. As a result, all properties associated withAbstractPlayer
can also be read directly from this class.As this class is instantiated from within the Boxscore class, it should not be called directly and should instead be queried using the appropriate players properties from the Boxscore class.
- Parameters
player_id (string) – A player’s ID according to basketball-reference.com, such as ‘hardeja01’ for James Harden. The player ID can be found by navigating to the player’s stats page and getting the string between the final slash and the ‘.html’ in the URL. In general, the ID is in the format ‘LLLLLFFNN’ where ‘LLLLL’ are the first 5 letters in the player’s last name, ‘FF’, are the first 2 letters in the player’s first name, and ‘NN’ is a number starting at ‘01’ for the first time that player ID has been used and increments by 1 for every successive player.
player_name (string) – A string representing the player’s first and last name, such as ‘James Harden’.
player_data (string) – A string representation of the player’s HTML data from the Boxscore page. If the player appears in multiple tables, all of their information will appear in one single string concatenated together.
-
property
dataframe
¶ Returns a
pandas DataFrame
containing all other relevant class properties and values for the specified game.
-
property
defensive_rating
¶ Returns an
int
of the player’s defensive rating as measured by the points allowed per 100 possessions.
-
property
minutes_played
¶ Returns a
float
of the number of game minutes the player was on the court for.
-
property
offensive_rating
¶ Returns an
int
of the player’s offensive rating as measured by the points produced per 100 posessions.
-
property
two_point_attempts
¶ Returns an
int
of the total number of two point field goals the player attempted during the season.
-
property
two_point_percentage
¶ Returns a
float
of the player’s two point field goal percentage during the season. Percentage ranges from 0-1.
-
property
two_pointers
¶ Returns an
int
of the total number of two point field goals the player made.
-
class
sportsipy.nba.boxscore.
Boxscores
(date, end_date=None)[source]¶ Bases:
object
Search for NBA games taking place on a particular day.
Retrieve a dictionary which contains a list of all games being played on a particular day. Output includes a link to the boxscore, and the names and abbreviations for both the home teams. If no games are played on a particular day, the list will be empty.
- Parameters
date (datetime object) – The date to search for any matches. The month, day, and year are required for the search, but time is not factored into the search.
end_date (datetime object (optional)) – Optionally specify an end date to iterate until. All boxscores starting from the date specified in the ‘date’ parameter up to and including the boxscores specified in the ‘end_date’ parameter will be pulled. If left empty, or if ‘end_date’ is prior to ‘date’, only the games from the day specified in the ‘date’ parameter will be saved.
-
property
games
¶ Returns a
dictionary
object representing all of the games played on the requested day. Dictionary is in the following format:{'date' : [ # 'date' is the string date in format 'MM-DD-YYYY' { 'home_name': Name of the home team, such as 'Phoenix Suns' (`str`), 'home_abbr': Abbreviation for the home team, such as 'PHO' (`str`), 'away_name': Name of the away team, such as 'Houston Rockets' (`str`), 'away_abbr': Abbreviation for the away team, such as 'HOU' (`str`), 'boxscore': String representing the boxscore URI, such as '201702040PHO' (`str`), 'winning_name': Full name of the winning team, such as 'Houston Rockets' (`str`), 'winning_abbr': Abbreviation for the winning team, such as 'HOU' (`str`), 'losing_name': Full name of the losing team, such as 'Phoenix Suns' (`str`), 'losing_abbr': Abbreviation for the losing team, such as 'PHO' (`str`), 'home_score': Integer score for the home team (`int`), 'away_score': Integer score for the away team (`int`) }, { ... }, ... ] }
If no games were played on ‘date’, the list for [‘date’] will be empty.
Player¶
The Player module contains an abstract base class that can be inherited by both
the BoxscorePlayer
and Player
classes in the Boxscore
and Roster
modules, respectively. All of the properties that appear in the
AbstractPlayer
class can be read from either of the two child classes
mentioned above.
-
class
sportsipy.nba.player.
AbstractPlayer
(player_id, player_name, player_data)[source]¶ Bases:
object
Get player information and stats for all seasons.
Given a player ID, such as ‘hardeja01’ for James Harden, capture all relevant stats and information like name, nationality, height/weight, career three-pointers, last season’s offensive rebounds, salary, contract amount, and much more.
By default, the class instance will return the player’s career stats, but single-season stats can be found by calling the instance with the requested season as denoted on basketball-reference.com.
- Parameters
player_id (string) – A player’s ID according to basketball-reference.com, such as ‘hardeja01’ for James Harden. The player ID can be found by navigating to the player’s stats page and getting the string between the final slash and the ‘.html’ in the URL. In general, the ID is in the format ‘LLLLLFFNN’ where ‘LLLLL’ are the first 5 letters in the player’s last name, ‘FF’, are the first 2 letters in the player’s first name, and ‘NN’ is a number starting at ‘01’ for the first time that player ID has been used and increments by 1 for every successive player.
player_name (string) – A string representing the player’s first and last name, such as ‘James Harden’.
player_data (string) – A string representation of the player’s HTML data from the Boxscore page. If the player appears in multiple tables, all of their information will appear in one single string concatenated together.
-
property
assist_percentage
¶ Returns a
float
of the percentage of field goals the player assisted while on the floor. Percentage ranges from 0-100.
-
property
assists
¶ Returns an
int
of the total number of assists the player tallied during the season.
-
property
block_percentage
¶ Returns a
float
of the percentage of opposing two-point field goal attempts that were blocked by the player while on the floor. Percentage ranges from 0-100.
-
property
blocks
¶ Returns an
int
of the total number of shots the player blocked during the season.
-
property
box_plus_minus
¶ Returns a
float
of the total number of points per 100 possessions the player contributed in comparison to an average player in the league.
-
property
defensive_rebound_percentage
¶ Returns a
float
of the percentage of available defensive rebounds the player grabbed. Percentage ranges from 0-100.
-
property
defensive_rebounds
¶ Returns an
int
of the total number of defensive rebounds the player grabbed during the season.
-
property
effective_field_goal_percentage
¶ Returns a
float
of the player’s field goal percentage while giving extra weight to 3-point field goals. Percentage ranges from 0-1.
-
property
field_goal_attempts
¶ Returns an
int
of the total number of field goals the player attempted during the season.
-
property
field_goal_percentage
¶ Returns a
float
of the player’s field goal percentage during the season. Percentage ranges from 0-1.
-
property
field_goals
¶ Returns an
int
of the total number of field goals the player scored.
-
property
free_throw_attempt_rate
¶ Returns a
float
of the number of free throw attempts per field goal attempt.
-
property
free_throw_attempts
¶ Returns an
int
of the total number of free throws the player attempted during the season.
-
property
free_throw_percentage
¶ Returns a
float
of the player’s free throw percentage during the season. Percentage ranges from 0-1.
-
property
free_throws
¶ Returns an
int
of the total number of free throws the player made during the season.
-
property
minutes_played
¶ Returns an
int
of the total number of minutes the player played.
-
property
name
¶ Returns a
string
of the players name, such as ‘James Harden’.
-
property
offensive_rebound_percentage
¶ Returns a
float
of the percentage of available offensive rebounds the player grabbed. Percentage ranges from 0-100.
-
property
offensive_rebounds
¶ Returns an
int
of the total number of offensive rebounds the player grabbed during the season.
-
property
personal_fouls
¶ Returns an
int
of the total number of personal fouls the player committed during the season.
-
property
player_id
¶ Returns a
string
of the player’s ID on sports-reference, such as ‘hardeja01’ for James Harden.
-
property
points
¶ Returns an
int
of the total number of points the player scored during the season.
-
property
steal_percentage
¶ Returns a
float
of the percentage of defensive possessions that ended with the player stealing the ball while on the floor. Percentage ranges from 0-100.
-
property
steals
¶ Returns an
int
of the total number of steals the player tallied during the season.
-
property
three_point_attempt_rate
¶ Returns a
float
of the percentage of field goals that are shot from beyond the 3-point arc. Percentage ranges from 0-1.
-
property
three_point_attempts
¶ Returns an
int
of the total number of three point field goals the player attempted during the season.
-
property
three_point_percentage
¶ Returns a
float
of the player’s three point field goal percentage during the season. Percentage ranges from 0-1.
-
property
three_pointers
¶ Returns an
int
of the total number of three point field goals the player made.
-
property
total_rebound_percentage
¶ Returns a
float
of the percentage of available rebounds the player grabbed, both offensive and defensive. Percentage ranges from 0-100.
-
property
total_rebounds
¶ Returns an
int
of the total number of offensive and defensive rebounds the player grabbed during the season.
-
property
true_shooting_percentage
¶ Returns a
float
of the player’s true shooting percentage which takes into account two and three pointers as well as free throws. Percentage ranges from 0-1.
-
property
turnover_percentage
¶ Returns a
float
of the average number of turnovers per 100 possessions by the player.
-
property
turnovers
¶ Returns an
int
of the total number of times the player turned the ball over during the season for any reason.
-
property
usage_percentage
¶ Returns a
float
of the percentage of plays the player is involved in while on the floor. Percentage ranges from 0-100.
Roster¶
The Roster module contains detailed player information, allowing each player to
be queried by their player ID using the Player
class which has detailed
information ranging from career points totals to single-season stats and player
height, weight, and nationality. The following is an example on collecting
career information for James Harden:
from sportsipy.nba.roster import Player
james_harden = Player('hardeja01')
print(james_harden.name) # Prints 'James Harden'
print(james_harden.points) # Prints Harden's career points total
# Prints a Pandas DataFrame of all relevant Harden stats per season
print(james_harden.dataframe)
print(james_harden.salary) # Prints Harden's career earnings
print(james_harden.contract) # Prints Harden's contract by yearly wages
By default, the player’s career stats are returned whenever a property is called. To get stats for a specific season, call the class instance with the season string. All future property requests will return the season-specific stats.
from sportsipy.nba.roster import Player
james_harden = Player('hardeja01') # Currently pulling career stats
print(james_harden.points) # Prints Harden's CAREER points total
# Prints Harden's points total only for the 2017-18 season.
print(james_harden('2017-18').points)
# Prints the number of games Harden played in the 2017-18 season.
print(james_harden.games_played)
After requesting single-season stats, the career stats can be requested again by calling the class without arguments or with the ‘Career’ string passed.
from sportsipy.nba.roster import Player
james_harden = Player('hardeja01') # Currently pulling career stats
# Prints Harden's points total only for the 2017-18 season.
print(james_harden('2017-18').points)
print(james_harden('Career').points) # Prints Harden's career points total
In addition, the Roster module also contains the Roster
class which can be
used to pull all players on a team’s roster during a given season and creates
instances of the Player class for each team member and adds them to a list to be
easily queried.
from sportsipy.nba.roster import Roster
houston = Roster('HOU')
for player in houston.players:
# Prints the name of all players who played for Houston in the most
# recent season.
print(player.name)
-
class
sportsipy.nba.roster.
Player
(player_id)[source]¶ Bases:
sportsipy.nba.player.AbstractPlayer
Get player information and stats for all seasons.
Given a player ID, such as ‘hardeja01’ for James Harden, capture all relevant stats and information like name, nationality, height/weight, career three-pointers, last season’s offensive rebounds, salary, contract amount, and much more.
By default, the class instance will return the player’s career stats, but single-season stats can be found by calling the instance with the requested season as denoted on basketball-reference.com.
- Parameters
player_id (string) – A player’s ID according to basketball-reference.com, such as ‘hardeja01’ for James Harden. The player ID can be found by navigating to the player’s stats page and getting the string between the final slash and the ‘.html’ in the URL. In general, the ID is in the format ‘LLLLLFFNN’ where ‘LLLLL’ are the first 5 letters in the player’s last name, ‘FF’, are the first 2 letters in the player’s first name, and ‘NN’ is a number starting at ‘01’ for the first time that player ID has been used and increments by 1 for every successive player.
-
property
and_ones
¶ Returns an
int
of the total number of times the player was fouled in the act of shooting and made the basket.
-
property
assists_per_poss
¶ Returns a
float
of the total number of assists the player tallied per 100 posessions.
-
property
birth_date
¶ Returns a
datetime
object of the day and year the player was born.
-
property
blocking_fouls
¶ Returns an
int
of the total number of blocking fouls the player committed.
-
property
blocks_per_poss
¶ Returns a
float
of the total number of shots the player blocked per 100 posessions.
-
property
center_percentage
¶ Returns an
int
of the percentage of time the player spent as a center. Percentage ranges from 0-100 and is rounded to the nearest whole number.
-
property
contract
¶ Returns a
dictionary
of the player’s contract details where the key is astring
of the season, such as ‘2018-19’, and the value is astring
of the salary, such as ‘$40,000,000’.
-
property
dataframe
¶ Returns a
pandas DataFrame
containing all other relevant class properties and values where each index is a different season plus the career stats.
-
property
defensive_box_plus_minus
¶ Returns a
float
of the number of defensive points per 100 possessions the player contributed in comparison to an average player in the league.
-
property
defensive_rebounds_per_poss
¶ Returns a
float
of the total number of defensive rebounds the player grabbed per 100 posessions.
Returns a
float
of the number of wins the player contributed to the team as a result of his defensive plays.
-
property
dunks
¶ Returns an
int
of the total number of dunks the player made during the season.
-
property
field_goal_attempts_per_poss
¶ Returns a
float
of the total number of field goals the player attempted per 100 posessions.
-
property
field_goal_perc_sixteen_foot_plus_two_pointers
¶ Returns a
float
of the player’s field goal percentage for shots that are greater than sixteen feet from the basket, but in front of or on the three point arc. Percentage ranges from 0-1.
-
property
field_goal_perc_ten_to_sixteen_feet
¶ Returns a
float
of the player’s field goal percentage for shots between ten and sixteen feet from the basket. Percentage ranges from 0-1.
-
property
field_goal_perc_three_to_ten_feet
¶ Returns a
float
of the player’s field goal percentage for shots between three and ten feet from the basket. Percentage ranges from 0-1.
-
property
field_goal_perc_zero_to_three_feet
¶ Returns a
float
of the player’s field goal percentage for shots between zero and three feet from the basket. Percentage ranges from 0-1.
-
property
field_goals_per_poss
¶ Returns a
float
of the total number of field goals the player scored per 100 posessions.
-
property
free_throw_attempts_per_poss
¶ Returns a
float
of the total number of free throws the player attempted per 100 posessions.
-
property
free_throws_per_poss
¶ Returns a
float
of the total number of free throws the player made per 100 posessions.
-
property
games_played
¶ Returns an
int
of the number of games the player participated in.
-
property
games_started
¶ Returns an
int
of the number of games the player started.
-
property
half_court_heaves
¶ Returns an
int
of the number of shots the player took from beyond mid-court.
-
property
half_court_heaves_made
¶ Returns an
int
of the number of shots the player made from beyond mid-court.
-
property
height
¶ Returns a
string
of the player’s height in the format “feet-inches”.
-
property
lost_ball_turnovers
¶ Returns an
int
of the total number of turnovers the player committed due to losing the ball.
-
property
nationality
¶ Returns a
string
constant denoting which country the player originates from.
-
property
net_plus_minus
¶ Returns a
float
of the net number of points the player contributes to the team per 100 possessions regardless of being on the floor or not.
-
property
offensive_box_plus_minus
¶ Returns a
float
of the number of offensive points per 100 possessions the player contributed in comparison to an average player in the league.
-
property
offensive_fouls
¶ Returns an
int
of the total number of offensive fouls the player committed.
-
property
offensive_rebounds_per_poss
¶ Returns a
float
of the total number of offensive rebounds the player grabbed per 100 posessions.
Returns a
float
of the number of wins the player contributed to the team as a result of his offensive plays.
-
property
on_court_plus_minus
¶ Returns a
float
of the number of points the player contributes to the team while on the court per 100 possessions.
-
property
other_turnovers
¶ Returns an
int
of the total number of all other non-passing/ dribbling turnovers the player committed.
-
property
passing_turnovers
¶ Returns an
int
of the total number of turnovers the player committed due to a bad pass.
-
property
percentage_field_goals_as_dunks
¶ Returns a
float
of the percentage of the player’s shot attempts that are dunks. Percentage ranges from 0-1.
-
property
percentage_of_three_pointers_from_corner
¶ Returns a
float
of the percentage of 3-point shots the player attempted from the corner. Percentage ranges from 0-1.
-
property
percentage_shots_three_pointers
¶ Returns a
float
of the percentage of shots the player takes from beyond the three point arc. Percentage ranges from 0-1.
-
property
percentage_shots_two_pointers
¶ Returns a
float
of the percentage of shots the player takes that are 2-pointers. Percentage ranges from 0-1.
-
property
percentage_sixteen_foot_plus_two_pointers
¶ Returns a
float
of the percentage of shots the player takes that are greater than sixteen feet from the basket, but in front of or on the three point arc. Percentage ranges from 0-1.
Returns a
float
of the percentage of shots the player takes from ten to sixteen feet from the basket. Percentage ranges from 0-1.
Returns a
float
of the percentage of shots the player takes from three to ten feet from the basket. Percentage ranges from 0-1.
Returns a
float
of the percentage of shots the player takes from zero to three feet from the basket. Percentage ranges from 0-1.
-
property
personal_fouls_per_poss
¶ Returns a
float
of the total number of personal fouls the player committed per 100 posessions.
-
property
player_efficiency_rating
¶ Returns a
float
of the player’s efficiency rating which represents the player’s relative production level. An average player in the league has an efficiency rating of 15.
-
property
point_guard_percentage
¶ Returns an
int
of the percentage of time the player spent as a point guard. Percentage ranges from 0-100 and is rounded to the nearest whole number.
-
property
points_generated_by_assists
¶ Returns an
int
of the total number of points the player generated as a result of him assisting the shooter.
-
property
points_per_poss
¶ Returns a
float
of the total number of points the player scored per 100 posessions.
-
property
position
¶ Returns a
string
constant of the player’s primary position.
-
property
power_forward_percentage
¶ Returns an
int
of the percentage of time the player spent as a power forward. Percentage ranges from 0-100 and is rounded to the nearest whole number.
-
property
salary
¶ Returns an
int
of the player’s annual salary rounded down.
-
property
season
¶ Returns a
string
of the season in the format ‘YYYY-YY’, such as ‘2017-18’. If no season was requested, the career stats will be returned for the player and the season will default to ‘Career’.
-
property
shooting_distance
¶ Returns a
float
of the average distance the player takes a shot from in feet.
-
property
shooting_fouls
¶ Returns an
int
of the total number of shooting fouls the player committed.
-
property
shooting_fouls_drawn
¶ Returns an
int
of the total number of shooting fouls the player drew during the season.
-
property
shooting_guard_percentage
¶ Returns an
int
of the percentage of time the player spent as a shooting guard. Percentage ranges from 0-100 and is rounded to the nearest whole number.
-
property
shots_blocked
¶ Returns an
int
of the total number of shots the player took that were blocked by an opposing player.
-
property
small_forward_percentage
¶ Returns an
int
of the percentage of time the player spent as a small forward. Percentage ranges from 0-100 and is rounded to the nearest whole number.
-
property
steals_per_poss
¶ Returns a
float
of the total number of steals the player tallied per 100 posessions.
-
property
take_fouls
¶ Returns an
int
of the total number of take fouls the player committed by taking a foul before the offensive player has a chance to make a shooting motion.
-
property
team_abbreviation
¶ Returns a
string
of the abbrevation for the team the player plays for, such as ‘HOU’ for James Harden.
-
property
three_point_attempts_per_poss
¶ Returns a
float
of the total number of three point field goals the player attempted per 100 posessions.
-
property
three_point_shot_percentage_from_corner
¶ Returns a
float
of the percentage of 3-pointers from the corner that went in. Percentage ranges from 0-1.
-
property
three_pointers_assisted_percentage
¶ Returns a
float
of the percentage of 3-point field goals by the player that are assisted. Percentage ranges from 0-1.
-
property
three_pointers_per_poss
¶ Returns a
float
of the total number of three point field goals the player made per 100 posessions.
-
property
total_rebounds_per_poss
¶ Returns a
float
of the total number of offensive and defensive rebounds the player grabbed per 100 posessions.
-
property
turnovers_per_poss
¶ Returns a
float
of the total number of times the player turned the ball over per 100 posessions.
-
property
two_point_attempts
¶ Returns an
int
of the total number of two point field goals the player attempted during the season.
-
property
two_point_attempts_per_poss
¶ Returns a
float
of the total number of two point field goals the player attempted per 100 posessions.
-
property
two_point_percentage
¶ Returns a
float
of the player’s two point field goal percentage during the season. Percentage ranges from 0-1.
-
property
two_pointers
¶ Returns an
int
of the total number of two point field goals the player made.
-
property
two_pointers_assisted_percentage
¶ Returns a
float
of the percentage of 2-point field goals by the player that are assisted. Percentage ranges from 0-1.
-
property
two_pointers_per_poss
¶ Returns a
float
of the total number of two point field goals the player made per 100 posessions.
-
property
value_over_replacement_player
¶ Returns a
float
of the total number of points per 100 team possessions the player contributed compared to a replacement-level player (who has an average score of -2.0). This value is prorated for an 82-game season.
-
property
weight
¶ Returns an
int
of the player’s weight in pounds.
Returns a
float
of the number of wins the player contributed to the team as a result of his offensive and defensive plays.
Returns a
float
of the number of wins the player contributed to the team per 48 minutes of playtime. An average player has a contribution of 0.100.
-
class
sportsipy.nba.roster.
Roster
(team, year=None, slim=False)[source]¶ Bases:
object
Get stats for all players on a roster.
Request a team’s roster for a given season and create instances of the Player class for each player, containing a detailed list of the players statistics and information.
- Parameters
team (string) – The team’s 3-letter abbreviation, such as ‘HOU’ for the Houston Rockets.
year (string (optional)) – The 4-digit year to pull the roster from, such as ‘2018’. If left blank, defaults to the most recent season.
slim (boolean (optional)) – Set to True to return a limited subset of player information including the name and player ID for each player as opposed to all of their respective stats which greatly reduces the time to return a response if just the names and IDs are desired. Defaults to False.
-
property
coach
¶ Returns a
string
of the coach’s name, such as “Mike D’Antoni”.
-
property
players
¶ Returns a
list
of player instances for each player on the requested team’s roster if theslim
property is False when calling the Roster class. If theslim
property is True, returns adictionary
where each key is a string of the player’s ID and each value is the player’s first and last name as listed on the roster page.
Schedule¶
The Schedule module can be used to iterate over all games in a team’s schedule
to get game information such as the date, score, result, and more. Each game
also has a link to the Boxscore
class which has much more detailed
information on the game metrics.
from sportsipy.nba.schedule import Schedule
houston_schedule = Schedule('HOU')
for game in houston_schedule:
print(game.date) # Prints the date the game was played
print(game.result) # Prints whether the team won or lost
# Creates an instance of the Boxscore class for the game.
boxscore = game.boxscore
-
class
sportsipy.nba.schedule.
Game
(game_data, playoffs=False)[source]¶ Bases:
object
A representation of a matchup between two teams.
Stores all relevant high-level match information for a game in a team’s schedule including date, time, opponent, and result.
- Parameters
game_data (string) – The row containing the specified game information.
-
property
boxscore
¶ Returns an instance of the Boxscore class containing more detailed stats on the game.
-
property
boxscore_index
¶ Returns a
string
of the URI for a boxscore which can be used to access or index a game.
-
property
dataframe
¶ Returns a pandas DataFrame containing all other class properties and values. The index for the DataFrame is the boxscore string.
-
property
dataframe_extended
¶ Returns a pandas DataFrame representing the Boxscore class for the game. This property provides much richer context for the selected game, but takes longer to process compared to the lighter ‘dataframe’ property. The index for the DataFrame is the boxscore string.
-
property
date
¶ Returns a
string
of the date the game took place at, such as ‘Wed, Oct 18, 2017’.
-
property
datetime
¶ Returns a datetime object to indicate the month, day, and year the game took place.
-
property
game
¶ Returns an
int
to indicate which game in the season was requested. The first game of the season returns 1.
-
property
location
¶ Returns a
string
constant to indicate whether the game was played in the team’s home arena or on the road.
-
property
losses
¶ Returns an
int
of the number of losses the team has in the season after the completion of the listed game.
-
property
opponent_abbr
¶ Returns a
string
of the opponent’s 3-letter abbreviation, such as ‘CHI’ for the Chicago Bulls.
-
property
opponent_name
¶ Returns a
string
of the opponent’s name, such as ‘Chicago Bulls’.
-
property
playoffs
¶ Returns a
boolean
variable which evalutes to True when the game was played in the playoffs and returns False if the game took place in the regular season.
-
property
points_allowed
¶ Returns an
int
of the number of points the team allowed during the game.
-
property
points_scored
¶ Returns an
int
of the number of points the team scored during the game.
-
property
result
¶ Returns a
string
constant to indicate whether the team won or lost the game.
-
property
streak
¶ Returns a
string
of the team’s current streak after the conclusion of the listed game, such as ‘W 3’ for a 3-game winning streak.
-
property
time
¶ Returns a
string
of the time the game started in Eastern Time, such as ‘8:01p’.
-
property
wins
¶ Returns an
int
of the number of wins the team has in the season after the completion of the listed game.
-
class
sportsipy.nba.schedule.
Schedule
(abbreviation, year=None)[source]¶ Bases:
object
An object of the given team’s schedule.
Generates a team’s schedule for the season including wins, losses, and scores if applicable.
- Parameters
abbreviation (string) – A team’s short name, such as ‘PHO’ for the Phoenix Suns.
year (string (optional)) – The requested year to pull stats from.
-
property
dataframe
¶ Returns a pandas DataFrame where each row is a representation of the Game class. Rows are indexed by the boxscore string.
-
property
dataframe_extended
¶ Returns a pandas DataFrame where each row is a representation of the Boxscore class for every game in the schedule. Rows are indexed by the boxscore string. This property provides much richer context for the selected game, but takes longer to process compared to the lighter ‘dataframe’ property.
Teams¶
The Teams module exposes information for all NBA teams including the team name and abbreviation, the number of games they won during the season, the total number of shots they’ve blocked, and much more.
from sportsipy.nba.teams import Teams
teams = Teams()
for team in teams:
print(team.name) # Prints the team's name
print(team.blocks) # Prints the team's total blocked shots
A team can also be requested directly by calling the Team
class which
returns a Team instance identical to the one in each element in the loop above.
To request a specific team, use the 3-letter abbreviation for the team while
calling Team class.
from sportsipy.nba.teams import Team
houston = Team('HOU')
Each Team instance contains a link to the Schedule
class which enables easy
iteration over all games for a particular team. A Pandas DataFrame can also be
queried to easily grab all stats for all games.
from sportsipy.nba.teams import Teams
teams = Teams()
for team in teams:
schedule = team.schedule # Returns a Schedule instance for each team
# Returns a Pandas DataFrame of all metrics for all game Boxscores for
# a season.
df = team.schedule.dataframe_extended
Lastly, each Team instance also contains a link to the Roster
class which
enables players from the team to be easily queried. Each Roster instance
contains detailed stats and information for each player on the team.
from sportsipy.nba.teams import Teams
teams = Teams()
for team in teams:
# Creates an instance of the roster class for each player on the team.
roster = team.roster
for player in roster.players:
print(player.name) # Prints the name of each player on the team.
-
class
sportsipy.nba.teams.
Team
(team_name=None, team_data=None, rank=None, year=None, season_file=None)[source]¶ Bases:
object
An object containing all of a team’s season information.
Finds and parses all team stat information and identifiers, such as rank, name, and abbreviation, and sets them as properties which can be directly read from for easy reference.
If calling directly, the team’s abbreviation needs to be passed. Otherwise, the Teams class will handle all arguments.
- Parameters
team_name (string (optional)) – The name of the team to pull if being called directly.
team_data (string (optional)) – A string containing all of the rows of stats for a given team. If multiple tables are being referenced, this will be comprised of multiple rows in a single string. Is only used when called directly from the Teams class.
rank (int (optional)) – A team’s position in the league based on the number of points they obtained during the season. Is only used when called directly from the Teams class.
year (string (optional)) – The requested year to pull stats from.
season_file (string (optional)) – Optionally specify the filename of a local file to use to pull data instead of downloading from sports-reference.com. This file should be of the Season page for the designated year.
-
property
abbreviation
¶ Returns a
string
of the team’s abbreviation, such as ‘DET’ for the Detroit Pistons.
-
property
assists
¶ Returns an
int
of the total number of field goals that were assisted.
-
property
blocks
¶ Returns an
int
of the total number of times the team blocked an opponent’s shot.
-
property
dataframe
¶ Returns a pandas DataFrame containing all other class properties and values. The index for the DataFrame is the string abbreviation of the team, such as ‘DET’.
-
property
defensive_rebounds
¶ Returns an
int
of the total number of defensive rebounds the team has grabbed.
-
property
field_goal_attempts
¶ Returns an
int
of the total number of field goals the team has attempted during the season.
-
property
field_goal_percentage
¶ Returns a
float
of the percentage of field goals made divided by the number of attempts. Percentage ranges from 0-1.
-
property
field_goals
¶ Returns an
int
of the total number of field goals the team has made during the season.
-
property
free_throw_attempts
¶ Returns an
int
of the total number of free throw attempts during the season.
-
property
free_throw_percentage
¶ Returns a
float
of the percentage of free throws made divided by the attempts. Percentage ranges from 0-1.
-
property
free_throws
¶ Returns an
int
of the total number of free throws made during the season.
-
property
games_played
¶ Returns an
int
of the total number of games the team has played during the season.
-
property
minutes_played
¶ Returns an
int
of the total number of minutes played by all players on the team during the season.
-
property
name
¶ Returns a
string
of the team’s full name, such as ‘Detroit Pistons’.
-
property
offensive_rebounds
¶ Returns an
int
of the total number of offensive rebounds the team has grabbed.
-
property
opp_assists
¶ Returns an
int
of the total number of field goals that were assisted by the opponent.
-
property
opp_blocks
¶ Returns an
int
of the total number of times the opponent blocked the team’s shot.
-
property
opp_defensive_rebounds
¶ Returns an
int
of the total number of defensive rebounds the opponent grabbed.
-
property
opp_field_goal_attempts
¶ Returns an
int
of the total number of field goals the opponents attempted during the season.
-
property
opp_field_goal_percentage
¶ Returns a
float
of the percentage of field goals made divided by the number of attempts by the opponent. Percentage ranges from 0-1.
-
property
opp_field_goals
¶ Returns an
int
of the total number of field goals the opponents made during the season.
-
property
opp_free_throw_attempts
¶ Returns an
int
of the total number of free throw attempts during the season by the opponent.
-
property
opp_free_throw_percentage
¶ Returns a
float
of the percentage of free throws made divided by the attempts by the opponent. Percentage ranges from 0-1.
-
property
opp_free_throws
¶ Returns an
int
of the total number of free throws made during the season by the opponent.
-
property
opp_offensive_rebounds
¶ Returns an
int
of the total number of offensive rebounds the opponent grabbed.
-
property
opp_personal_fouls
¶ Returns an
int
of the total number of times the opponent fouled the team.
-
property
opp_points
¶ Returns an
int
of the total number of points the team has been scored on during the season.
-
property
opp_steals
¶ Returns an
int
of the total number of times the opponent stole the ball from the team.
-
property
opp_three_point_field_goal_attempts
¶ Returns an
int
of the total number of three point field goals the opponent attempted during the season.
-
property
opp_three_point_field_goal_percentage
¶ Returns a
float
of the percentage of three point field goals made divided by the number of attempts by the opponent. Percentage ranges from 0-1.
-
property
opp_three_point_field_goals
¶ Returns an
int
of the total number of three point field goals the opponent made during the season.
-
property
opp_total_rebounds
¶ Returns an
int
of the total number of rebounds the opponent grabbed.
-
property
opp_turnovers
¶ Returns an
int
of the total number of times the opponent turned the ball over.
-
property
opp_two_point_field_goal_attempts
¶ Returns an
int
of the total number of two point field goals the opponent attempted during the season.
-
property
opp_two_point_field_goal_percentage
¶ Returns a
float
of the percentage of two point field goals made divided by the number of attempts by the opponent. Percentage ranges from 0-1.
-
property
opp_two_point_field_goals
¶ Returns an
int
of the total number of two point field goals the opponent made during the season.
-
property
personal_fouls
¶ Returns an
int
of the total number of times the team has fouled an opponent.
-
property
points
¶ Returns an
int
of the total number of points the team has scored during the season.
-
property
rank
¶ Returns an
int
of the team’s rank based on the number of points they score per game.
-
property
roster
¶ Returns an instance of the Roster class containing all players for the team during the season with all career stats.
-
property
schedule
¶ Returns an instance of the Schedule class containing the team’s complete schedule for the season.
-
property
steals
¶ Returns an
int
of the total number of times the team stole the ball from the opponent.
-
property
three_point_field_goal_attempts
¶ Returns an
int
of the total number of three point field goals the team has attempted during the season.
-
property
three_point_field_goal_percentage
¶ Returns a
float
of the percentage of three point field goals made divided by the number of attempts. Percentage ranges from 0-1.
-
property
three_point_field_goals
¶ Returns an
int
of the total number of three point field goals the team has made during the season.
-
property
total_rebounds
¶ Returns an
int
of the total number of rebounds the team has grabbed.
-
property
turnovers
¶ Returns an
int
of the total number of times the team has turned the ball over.
-
property
two_point_field_goal_attempts
¶ Returns an
int
of the total number of two point field goals the team has attempted during the season.
-
property
two_point_field_goal_percentage
¶ Returns a
float
of the percentage of two point field goals made divided by the number of attempts. Percentage ranges from 0-1.
-
property
two_point_field_goals
¶ Returns an
int
of the total number of two point field goals the team has made during the season.
-
class
sportsipy.nba.teams.
Teams
(year=None, season_file=None)[source]¶ Bases:
object
A list of all NBA teams and their stats in a given year.
Finds and retrieves a list of all NBA teams from www.basketball-reference.com and creates a Team instance for every team that participated in the league in a given year. The Team class comprises a list of all major stats and a few identifiers for the requested season.
- Parameters
year (string (optional)) – The requested year to pull stats from.
season_file (string (optional)) – Optionally specify the filename of a local file to use to pull data instead of downloading from sports-reference.com. This file should be of the Season page for the designated year.
-
property
dataframes
¶ Returns a pandas DataFrame where each row is a representation of the Team class. Rows are indexed by the team abbreviation.