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

sportsreference.nba.boxscore module

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 sportsreference.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 sportsreference.nba.boxscore import Boxscores

games_today = Boxscores(datetime.today())
print(games_today.games)  # Prints a dictionary of all matchups for today
class sportsreference.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’.
away_assist_percentage

Returns a float of the percentage of the away team’s field goals that were assisted. Percentage ranges from 0-100.

away_assists

Returns an int of the total number of assists by the away team.

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.

away_blocks

Returns an int of the total number of blocks by the away team.

away_defensive_rating

Returns a float of the average number of points scored per 100 possessions by the away team.

away_defensive_rebound_percentage

Returns a float of the percentage of available defensive rebounds the away team grabbed. Percentage ranges from 0-100.

away_defensive_rebounds

Returns an int of the total number of defensive rebounds by the away team.

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.

away_field_goal_attempts

Returns an int of the total number of field goal attempts by the away team.

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.

away_field_goals

Returns an int of the total number of field goals made by the away team.

away_free_throw_attempt_rate

Returns a float of the average number of free throw attempts per field goal attempt by the away team.

away_free_throw_attempts

Returns an int of the total number of free throw attempts by the away team.

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.

away_free_throws

Returns an int of the total number of free throws made by the away team.

away_losses

Returns an int of the number of games the team has lost after the conclusion of the game.

away_minutes_played

Returns an int of the total number of minutes the team played during the game.

away_offensive_rating

Returns a float of the average number of points scored per 100 possessions by the away team.

away_offensive_rebound_percentage

Returns a float of the percentage of available offensive rebounds the away team grabbed. Percentage ranges from 0-100.

away_offensive_rebounds

Returns an int of the total number of offensive rebounds by the away team.

away_personal_fouls

Returns an int of the total number of personal fouls by the away team.

away_points

Returns an int of the number of points the away team scored.

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.

away_steals

Returns an int of the total number of steals by the away team.

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.

away_three_point_field_goal_attempts

Returns an int of the total number of three point field goal attempts by the away team.

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.

away_three_point_field_goals

Returns an int of the total number of three point field goals made by the away team.

away_total_rebound_percentage

Returns a float of the percentage of available rebounds the away team grabbed. Percentage ranges from 0-100.

away_total_rebounds

Returns an int of the total number of rebounds by the away team.

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.

away_turnover_percentage

Returns a float of the number of times the away team turned the ball over per 100 possessions.

away_turnovers

Returns an int of the total number of turnovers by the away team.

away_two_point_field_goal_attempts

Returns an int of the total number of two point field goal attempts by the away team.

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.

away_two_point_field_goals

Returns an int of the total number of two point field goals made by the away team.

away_wins

Returns an int of the number of games the team has won after the conclusion of the game.

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

date

Returns a string of the date the game took place.

home_assist_percentage

Returns a float of the percentage of the home team’s field goals that were assisted. Percentage ranges from 0-100.

home_assists

Returns an int of the total number of assists by the home team.

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.

home_blocks

Returns an int of the total number of blocks by the home team.

home_defensive_rating

Returns a float of the average number of points scored per 100 possessions by the away team.

home_defensive_rebound_percentage

Returns a float of the percentage of available defensive rebounds the home team grabbed. Percentage ranges from 0-100.

home_defensive_rebounds

Returns an int of the total number of defensive rebounds by the home team.

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.

home_field_goal_attempts

Returns an int of the total number of field goal attempts by the home team.

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.

home_field_goals

Returns an int of the total number of field goals made by the home team.

home_free_throw_attempt_rate

Returns a float of the average number of free throw attempts per field goal attempt by the home team.

home_free_throw_attempts

Returns an int of the total number of free throw attempts by the home team.

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.

home_free_throws

Returns an int of the total number of free throws made by the home team.

home_losses

Returns an int of the number of games the home team lost after the conclusion of the game.

home_minutes_played

Returns an int of the total number of minutes the team played during the game.

home_offensive_rating

Returns a float of the average number of points scored per 100 possessions by the home team.

home_offensive_rebound_percentage

Returns a float of the percentage of available offensive rebounds the home team grabbed. Percentage ranges from 0-100.

home_offensive_rebounds

Returns an int of the total number of offensive rebounds by the home team.

home_personal_fouls

Returns an int of the total number of personal fouls by the home team.

home_points

Returns an int of the number of points the home team scored.

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.

home_steals

Returns an int of the total number of steals by the home team.

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.

home_three_point_field_goal_attempts

Returns an int of the total number of three point field goal attempts by the home team.

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.

home_three_point_field_goals

Returns an int of the total number of three point field goals made by the home team.

home_total_rebound_percentage

Returns a float of the percentage of available rebounds the home team grabbed. Percentage ranges from 0-100.

home_total_rebounds

Returns an int of the total number of rebounds by the home team.

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.

home_turnover_percentage

Returns a float of the number of times the home team turned the ball over per 100 possessions.

home_turnovers

Returns an int of the total number of turnovers by the home team.

home_two_point_field_goal_attempts

Returns an int of the total number of two point field goal attempts by the home team.

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.

home_two_point_field_goals

Returns an int of the total number of two point field goals made by the home team.

home_wins

Returns an int of the number of games the home team won after the conclusion of the game.

location

Returns a string of the name of the venue where the game was played.

losing_abbr

Returns a string of the losing team’s abbreviation, such as ‘PHO’ for the Phoenix Suns.

losing_name

Returns a string of the losing team’s name, such as ‘Phoenix Suns’.

pace

Returns a float of the game’s overall pace, measured by the number of possessions per 40 minutes.

winner

Returns a string constant indicating whether the home or away team won.

winning_abbr

Returns a string of the winning team’s abbreviation, such as ‘DET’ for the Detroit Pistons.

winning_name

Returns a string of the winning team’s name, such as ‘Detroit Pistons’.

class sportsreference.nba.boxscore.Boxscores(date)[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.
games

Returns a dictionary object representing all of the games played on the requested day. Dictionary is in the following format:

{'boxscores' : [
    {'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`)},
    { ... },
    ...
    ]
}

If no games were played during the requested day, the list for [‘boxscores’] will be empty.

sportsreference.nba.schedule module

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 sportsreference.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 sportsreference.nba.schedule.Game(game_data)[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.
assists

Returns an int of the total number of assists by the team.

blocks

Returns an int of the total number of blocks by the team.

boxscore

Returns an instance of the Boxscore class containing more detailed stats on the game.

dataframe

Returns a pandas DataFrame containing all other class properties and values. The index for the DataFrame is the boxscore string.

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.

date

Returns a string of the date the game took place at, such as ‘Wed, Oct 18, 2017’.

datetime

Returns a datetime object to indicate the month, day, and year the game took place.

field_goal_attempts

Returns an int of the total number of field goal attempts by the team.

field_goal_percentage

Returns a float of the number of field goals made divided by the total number of field goal attempts by the team. Percentage ranges from 0-1.

field_goals

Returns an int of the total number of field goals made by the team.

free_throw_attempts

Returns an int of the total number of free throw attempts by the team.

free_throw_percentage

Returns a float of the number of free throws made divided by the number of free throw attempts by the team.

free_throws

Returns an int of the total number of free throws made by the team.

game

Returns an int to indicate which game in the season was requested. The first game of the season returns 1.

location

Returns a string constant to indicate whether the game was played in the team’s home arena or on the road.

offensive_rebounds

Returns an int of the total number of offensive rebounds by the team.

opp_assists

Returns an int of the total number of assists by the opponent.

opp_blocks

Returns an int of the total number of blocks by the opponent.

opp_field_goal_attempts

Returns an int of the total number of field goal attempts by the opponent.

opp_field_goal_percentage

Returns a float of the number of field goals made divided by the total number of field goal attempts by the opponent. Percentage ranges from 0-1.

opp_field_goals

Returns an int of the total number of field goals made by the opponent.

opp_free_throw_attempts

Returns an int of the total number of free throw attempts by the opponent.

opp_free_throw_percentage

Returns a float of the number of free throws made divided by the number of free throw attempts by the opponent.

opp_free_throws

Returns an int of the total number of free throws made by the opponent.

opp_offensive_rebounds

Returns an int of the total number of offensive rebounds by the opponent.

opp_personal_fouls

Returns an int of the total number of personal fouls by the opponent.

opp_steals

Returns an int of the total number of steals by the opponent.

opp_three_point_field_goal_attempts

Returns an int of the total number of three point field goal attempts by the opponent.

opp_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 opponent. Percentage ranges from 0-1.

opp_three_point_field_goals

Returns an int of the total number of three point field goals made by the opponent.

opp_total_rebounds

Returns an int of the total number of rebounds by the opponent.

opp_turnovers

Returns an int of the total number of turnovers by the opponent.

opponent_abbr

Returns a string of the opponent’s 3-letter abbreviation, such as ‘CHI’ for the Chicago Bulls.

personal_fouls

Returns an int of the total number of personal fouls by the team.

points_allowed

Returns an int of the number of points the team allowed during the game.

points_scored

Returns an int of the number of points the team scored during the game.

result

Returns a string constant to indicate whether the team won or lost the game.

steals

Returns an int of the total number of steals by the team.

three_point_field_goal_attempts

Returns an int of the total number of three point field goal attempts by the team.

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 team. Percentage ranges from 0-1.

three_point_field_goals

Returns an int of the total number of three point field goals made by the team.

total_rebounds

Returns an int of the total number of rebounds by the team.

turnovers

Returns an int of the total number of turnovers by the team.

class sportsreference.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.
dataframe

Returns a pandas DataFrame where each row is a representation of the Game class. Rows are indexed by the boxscore string.

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.

sportsreference.nba.teams module

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

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 sportsreference.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
class sportsreference.nba.teams.Team(team_data, rank, year=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.

Parameters:
  • team_data (string) – 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.
  • rank (int) – A team’s position in the league based on the number of points they obtained during the season.
  • year (string (optional)) – The requested year to pull stats from.
abbreviation

Returns a string of the team’s abbreviation, such as ‘DET’ for the Detroit Pistons.

assists

Returns an int of the total number of field goals that were assisted.

blocks

Returns an int of the total number of times the team blocked an opponent’s shot.

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

defensive_rebounds

Returns an int of the total number of defensive rebounds the team has grabbed.

field_goal_attempts

Returns an int of the total number of field goals the team has attempted during the season.

field_goal_percentage

Returns a float of the percentage of field goals made divided by the number of attempts. Percentage ranges from 0-1.

field_goals

Returns an int of the total number of field goals the team has made during the season.

free_throw_attempts

Returns an int of the total number of free throw attempts during the season.

free_throw_percentage

Returns a float of the percentage of free throws made divided by the attempts. Percentage ranges from 0-1.

free_throws

Returns an int of the total number of free throws made during the season.

games_played

Returns an int of the total number of games the team has played during the season.

minutes_played

Returns an int of the total number of minutes played by all players on the team during the season.

name

Returns a string of the team’s full name, such as ‘Detroit Pistons’.

offensive_rebounds

Returns an int of the total number of offensive rebounds the team has grabbed.

opp_assists

Returns an int of the total number of field goals that were assisted by the opponent.

opp_blocks

Returns an int of the total number of times the opponent blocked the team’s shot.

opp_defensive_rebounds

Returns an int of the total number of defensive rebounds the opponent grabbed.

opp_field_goal_attempts

Returns an int of the total number of field goals the opponents attempted during the season.

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.

opp_field_goals

Returns an int of the total number of field goals the opponents made during the season.

opp_free_throw_attempts

Returns an int of the total number of free throw attempts during the season by the opponent.

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.

opp_free_throws

Returns an int of the total number of free throws made during the season by the opponent.

opp_offensive_rebounds

Returns an int of the total number of offensive rebounds the opponent grabbed.

opp_personal_fouls

Returns an int of the total number of times the opponent fouled the team.

opp_points

Returns an int of the total number of points the team has been scored on during the season.

opp_steals

Returns an int of the total number of times the opponent stole the ball from the team.

opp_three_point_field_goal_attempts

Returns an int of the total number of three point field goals the opponent attempted during the season.

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.

opp_three_point_field_goals

Returns an int of the total number of three point field goals the opponent made during the season.

opp_total_rebounds

Returns an int of the total number of rebounds the opponent grabbed.

opp_turnovers

Returns an int of the total number of times the opponent turned the ball over.

opp_two_point_field_goal_attempts

Returns an int of the total number of two point field goals the opponent attempted during the season.

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.

opp_two_point_field_goals

Returns an int of the total number of two point field goals the opponent made during the season.

personal_fouls

Returns an int of the total number of times the team has fouled an opponent.

points

Returns an int of the total number of points the team has scored during the season.

rank

Returns an int of the team’s rank based on the number of points they score per game.

schedule

Returns an instance of the Schedule class containing the team’s complete schedule for the season.

steals

Returns an int of the total number of times the team stole the ball from the opponent.

three_point_field_goal_attempts

Returns an int of the total number of three point field goals the team has attempted during the season.

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.

three_point_field_goals

Returns an int of the total number of three point field goals the team has made during the season.

total_rebounds

Returns an int of the total number of rebounds the team has grabbed.

turnovers

Returns an int of the total number of times the team has turned the ball over.

two_point_field_goal_attempts

Returns an int of the total number of two point field goals the team has attempted during the season.

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.

two_point_field_goals

Returns an int of the total number of two point field goals the team has made during the season.

class sportsreference.nba.teams.Teams(year=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.
dataframes

Returns a pandas DataFrame where each row is a representation of the Team class. Rows are indexed by the team abbreviation.