sportsreference.ncaab package¶

The NCAAB package offers multiple modules which can be used to retrieve information and statistics for Men’s Division I College Basketball, such as team names, season stats, game schedules, and boxscore metrics.

sportsreference.ncaab.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 blocked shots, to the assist percentage 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.ncaab.boxscore import Boxscore

game_data = Boxscore('2018-04-02-21-villanova')
print(game_data.home_points)  # Prints 79
print(game_data.away_points)  # Prints 62
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.ncaab.boxscore import Boxscores

games_today = Boxscores(datetime.today())
print(games_today.games)  # Prints a dictionary of all matchups for today

class sportsreference.ncaab.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 ‘2017-11-10-21-kansas’.

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 ‘2017-11-10-21-kansas’.

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 ‘INDIANA’ for the Indiana Hoosiers.

losing_name¶: Returns a string of the losing team’s name, such as ‘Indiana’ Hoosiers’.

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 ‘PURDUE’ for the Purdue Boilermakers.

winning_name¶: Returns a string of the winning team’s name, such as ‘Purdue Boilermakers’.

class sportsreference.ncaab.boxscore.Boxscores(date)[source]¶

Bases: object

Search for NCAAB 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, a boolean value which indicates if the game is between two Division-I teams or not, 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 'Purdue
                  Boilermakers' (`str`),
     'home_abbr': Abbreviation for the home team, such as
                  'PURDUE' (`str`),
     'away_name': Name of the away team, such as 'Indiana
                  Hoosiers' (`str`),
     'away_abbr': Abbreviation for the away team, such as
                  'INDIANA' (`str`),
     'boxscore': String representing the boxscore URI, such as
                 '2018-01-28-15-indiana' (`str`),
     'non_di': Boolean value which evaluates to True when at least
               one of the teams does not compete in NCAA
               Division-I basketball (`str`)},
    { ... },
    ...
    ]
}

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

sportsreference.ncaab.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.ncaab.schedule import Schedule

purdue_schedule = Schedule('PURDUE')
for game in purdue_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.ncaab.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.

arena¶: Returns a string of the name of the arena the game was played at.

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 game’s date, such as ‘Fri, Nov 10, 2017’.

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

game¶: Returns an int of the game’s position in the season. The first game of the season returns 1.

location¶: Returns a string constant to indicate whether the game was played at the team’s home venue, the opponent’s venue, or at a neutral site.

opponent_abbr¶: Returns a string of the opponent’s abbreviation, such as ‘PURDUE’ for the Purdue Boilermakers.

opponent_conference¶: Returns a string of the opponent’s conference, such as ‘Big Ten’ for a team participating in the Big Ten Conference. If the team is not a Division-I school, a string constant for non-majors is returned.

opponent_name¶: Returns a string of the opponent’s name, such as the ‘Purdue Boilermakers’.

opponent_rank¶: Returns a string of the opponent’s rank when the game was played and None if the team was unranked.

overtimes¶: Returns an int of the number of overtimes that were played during the game and 0 if the game finished at the end of regulation time.

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

points_for¶: 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.

season_losses¶: Returns an int of the number of games the team has lost after the conclusion of the requested game.

season_wins¶: Returns an int of the number of games the team has won after the conclusion of the requested game.

streak¶: Returns a string of the team’s win streak at the conclusion of the requested game. Streak is in the format ‘[W|L] #’ (ie. ‘W 3’ indicates a 3-game winning streak while ‘L 2’ indicates a 2-game losing streak.

time¶: Returns a string to indicate the time the game started, such as ‘9:00 pm/est’.

type¶: Returns a string constant to indicate whether the game was played during the regular season or in the post season.

class sportsreference.ncaab.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 ‘PURDUE’ for the Purdue Boilermakers. 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.ncaab.teams module¶

The Teams module exposes information for all NCAAB 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.ncaab.teams import Teams

teams = Teams()
for team in teams:
    print(team.name)  # Prints the team's name
    print(team.blocks)  # Prints the number of shots the team blocked

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.ncaab.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.ncaab.teams.Team(team_data, 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 full and short names, 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. year (string (optional)) – The requested year to pull stats from.

abbreviation¶: Returns a string of the team’s short name, such as ‘PURDUE’ for the Purdue Boilermakers.

assist_percentage¶: Returns a float of the percentage of field goals that were assisted. Percentage ranges from 0-100.

assists¶: Returns an int of the total number of assists during the season.

away_losses¶: Returns an int of the total number of away games the team lost during the season.

away_wins¶: Returns an int of the total number of away games the team won during the season.

block_percentage¶: Returns a float of the percentage of 2-point field goals by the opponent that were blocked. Percentage ranges from 0-100.

blocks¶: Returns an int of the total number of blocks during the season.

conference_losses¶: Returns an int of the total number of conference games the team lost during the season.

conference_wins¶: Returns an int of the total number of conference games the team won during the season.

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

effective_field_goal_percentage¶: Returns a float of the field goal percentage while giving extra weight to 3-point field goals. Percentage ranges from 0-1.

field_goal_attempts¶: Returns an int of the total number of field goal attempts during the season.

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

field_goals¶: Returns an int of the total number of field goals made during the season.

free_throw_attempt_rate¶: Returns a float of the average number of free throw attempts per field goal attempt.

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 number of free throws made divided by the number of free throw attempts during the season.

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

free_throws_per_field_goal_attempt¶: Returns a float of the number of free throws per field goal attempt.

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

home_losses¶: Returns an int of the total number of home games the team lost during the season.

home_wins¶: Returns an int of the total number of home games the team won during the season.

losses¶: Returns an int of the total number of games the team lost during the season.

minutes_played¶: Returns an int of the total number of minutes played by the team during the season.

name¶: Returns a string of the team’s full name, such as ‘Purdue Boilermakers’.

offensive_rating¶: Returns a float of the average number of points scored per 100 possessions.

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

offensive_rebounds¶: Returns an int of the total number of offensive rebounds during the season.

opp_assist_percentage¶: Returns a float of the percentage of the opponent’s field goals that were assisted. Percentage ranges from 0-100.

opp_assists¶: Returns an int of the total number of assists during the season by opponents.

opp_block_percentage¶: Returns a float of the percentage of 2-point field goals that were blocked by the opponent. Percentage ranges from 0-100.

opp_blocks¶: Returns an int of the total number of blocks during the season by opponents.

opp_effective_field_goal_percentage¶: Returns a float of the opponent’s field goal percentage while giving extra weight to 3-point field goals. Percentage ranges from 0-1.

opp_field_goal_attempts¶: Returns an int of the total number of field goal attempts during the season by opponents.

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

opp_field_goals¶: Returns an int of the total number of field goals made during the season by opponents.

opp_free_throw_attempt_rate¶: Returns a float of the average number of free throw attempts per field goal attempt by the opponent.

opp_free_throw_attempts¶: Returns an int of the total number of free throw attempts during the season by opponents.

opp_free_throw_percentage¶: Returns a float of the number of free throws made divided by the number of free throw attempts during the season by opponents.

opp_free_throws¶: Returns an int of the total number of free throws made during the season by opponents.

opp_free_throws_per_field_goal_attempt¶: Returns a float of the number of free throws per field goal attempt by the opponent.

opp_offensive_rating¶: Returns a float of the average number of points scored per 100 possessions by the opponent.

opp_offensive_rebound_percentage¶: Returns a float of the percentage of available offensive rebounds the opponent grabbed. Percentage ranges from 0-100.

opp_offensive_rebounds¶: Returns an int of the total number of offensive rebounds during the season by opponents.

opp_personal_fouls¶: Returns an int of the total number of personal fouls during the season by opponents.

opp_points¶: Returns an int of the total number of points opponents have scored during the season.

opp_steal_percentage¶: Returns a float of the percentage of possessions that ended in a steal by the opponent. Percentage ranges from 0-100.

opp_steals¶: Returns an int of the total number of steals during the season by opponents.

opp_three_point_attempt_rate¶: Returns a float of the percentage of field goal attempts from 3-point range by the opponent. Percentage ranges from 0-1.

opp_three_point_field_goal_attempts¶: Returns an int of the total number of three point field goal attempts during the season by opponents.

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

opp_three_point_field_goals¶: Returns an int of the total number of three point field goals made during the season by opponents.

opp_total_rebound_percentage¶: Returns a float of the percentage of available rebounds the opponent grabbed. Percentage ranges from 0-100.

opp_total_rebounds¶: Returns an int of the total number of rebounds during the season by opponents.

opp_true_shooting_percentage¶: Returns a float of the opponent’s true shooting percentage which considers free throws, 2-point field goals, and 3-point field goals. Percentage ranges from 0-1.

opp_turnover_percentage¶: Returns a float of the number of times the opponent turned the ball over per 100 possessions.

opp_turnovers¶: Returns an int of the total number of turnovers during the season by opponents.

pace¶: Returns a float of the average number of possessions per 40 minutes.

personal_fouls¶: Returns an int of the total number of personal fouls during the season.

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

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

simple_rating_system¶: Returns a float of the team’s average point differential compared to the strength of schedule. Higher values indicate stronger teams. An average team is denoted with 0.0. Negative numbers are comparatively worse than average.

steal_percentage¶: Returns a float of the percentage of opponent possessions that ended in a steal. Percentage ranges from 0-100.

steals¶: Returns an int of the total number of steals during the season.

strength_of_schedule¶: Returns a float of the team’s strength of schedule based on the points above and below average. An average strength of schedule is denoted with 0.0. Negative numbers are comparatively easier than average.

three_point_attempt_rate¶: Returns a float of the percentage of field goal attempts from 3-point range. Percentage ranges from 0-1.

three_point_field_goal_attempts¶: Returns an int of the total number of three point field goal attempts during the season.

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

three_point_field_goals¶: Returns an int of the total number of three point field goals made during the season.

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

total_rebounds¶: Returns an int of the total number of rebounds during the season.

true_shooting_percentage¶: Returns a float of the team’s true shooting percentage which considers free throws, 2-point field goals, and 3-point field goals. Percentage ranges from 0-1.

turnover_percentage¶: Returns a float of the number of times the team turned the ball over per 100 possessions.

turnovers¶: Returns an int of the total number of turnovers during the season.

win_percentage¶: Returns a float of the number of wins divided by the number of games played during the season. Percentage ranges from 0-1.

wins¶: Returns an int of the total number of games the team won during the season.

class sportsreference.ncaab.teams.Teams(year=None)[source]¶

Bases: object

A list of all NCAA Men’s Basketball teams and their stats in a given year.

Finds and retrieves a list of all NCAA Men’s Basketball teams from www.sports-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.