sportsreference.nhl package¶

The NHL package offers multiple modules which can be used to retrieve information and statistics for the National Hockey League, such as team names, season stats, game schedules, and boxscore metrics.

sportsreference.nhl.boxscore module¶

The Boxscore module can be used to grab information from a specific game. Metrics range from number of goals scored to the number of penalty minutes, to the save 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.nhl.boxscore import Boxscore

game_data = Boxscore('201806070VEG')
print(game_data.home_goals)  # Prints 3
print(game_data.away_goals)  # Prints 4
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.nhl.boxscore import Boxscores

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

class sportsreference.nhl.boxscore.Boxscore(uri)[source]¶

Bases: object

Detailed information about the final statistics for a game.

Stores all relevant information for a game such as the date, time, location, result, and more advanced metrics such as the number of goals scored, the number of points for a player, the amount of power play assists and much more.

Parameters:	uri (string) – The relative link to the boxscore HTML page, such as ‘201806070VEG’.

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

attendance¶: Returns an int of the game’s listed attendance.

away_assists¶: Returns an int of the number of assists the away team registered.

away_even_strength_assists¶: Returns an int of the number of assists the away team registered while at even strength.

away_even_strength_goals¶: Returns an int of the number of goals the away team scored at even strength.

away_game_winning_goals¶: Returns an int of the number of game winning goals the away team scored.

away_goals¶: Returns an int of the number of goals the away team scored.

away_penalties_in_minutes¶: Returns an int of the length of time the away team spent in the penalty box.

away_points¶: Returns an int of the number of points the away team registered.

away_power_play_assists¶: Returns an int of the number of assists the away team registered while on a power play.

away_power_play_goals¶: Returns an int of the number of goals the away team scored while on a power play.

away_save_percentage¶: Returns a float of the percentage of shots the away team saved. Percentage ranges from 0-1.

away_saves¶: Returns an int of the number of saves the away team made.

away_shooting_percentage¶: Returns a float of the away team’s shooting percentage. Percentage ranges from 0-100.

away_short_handed_assists¶: Returns an int of the number of assists the away team registered while short handed.

away_short_handed_goals¶: Returns an int of the number of goals the away team scored while short handed.

away_shots_on_goal¶: Returns an int of the number of shots on goal the away team registered.

away_shutout¶: Returns an int denoting whether or not the away team shutout the home team.

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 ‘201806070VEG’.

date¶: Returns a string of the date the game took place.

duration¶: Returns a string of the game’s duration in the format ‘H – MM’.

home_assists¶: Returns an int of the number of assists the home team registered.

home_even_strength_assists¶: Returns an int of the number of assists the home team registered while at even strength.

home_even_strength_goals¶: Returns an int of the number of goals the home team scored at even strength.

home_game_winning_goals¶: Returns an int of the number of game winning goals the home team scored.

home_goals¶: Returns an int of the number of goals the home team scored.

home_penalties_in_minutes¶: Returns an int of the length of time the home team spent in the penalty box.

home_points¶: Returns an int of the number of points the home team registered.

home_power_play_assists¶: Returns an int of the number of assists the home team registered while on a power play.

home_power_play_goals¶: Returns an int of the number of goals the home team scored while on a power play.

home_save_percentage¶: Returns a float of the percentage of shots the home team saved. Percentage ranges from 0-1.

home_saves¶: Returns an int of the number of saves the home team made.

home_shooting_percentage¶: Returns a float of the home team’s shooting percentage. Percentage ranges from 0-100.

home_short_handed_assists¶: Returns an int of the number of assists the home team registered while short handed.

home_short_handed_goals¶: Returns an int of the number of goals the home team scored while short handed.

home_shots_on_goal¶: Returns an int of the number of shots on goal the home team registered.

home_shutout¶: Returns an int denoting whether or not the home team shutout the home team.

losing_abbr¶: Returns a string of the losing team’s abbreviation, such as ‘WSH’ for the Washington Capitals.

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

time¶: Returns a string of the time the game started.

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 ‘VEG’ for the Vegas Golden Knights.

winning_name¶: Returns a string of the winning team’s name, such as ‘Vegas Golden Knights’.

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

Bases: object

Search for NHL 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 'New York
                  Rangers' (`str`),
     'home_abbr': Abbreviation for the home team, such as
                  'NYR' (`str`),
     'away_name': Name of the away team, such as 'Boston
                  Bruins' (`str`),
     'away_abbr': Abbreviation for the away team, such as
                  'BOS' (`str`),
     'boxscore': String representing the boxscore URI, such as
                 '201702040VAN' (`str`)},
    { ... },
    ...
    ]
}

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

sportsreference.nhl.boxscore.nhl_int_property_decorator(func)[source]¶

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

detroit_schedule = Schedule('DET')
for game in detroit_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.nhl.schedule.Game(game_data, year)[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. year (string) – The year of the current season.

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

corsi_against¶: Returns an int of the Corsi Against at Even Strength metric which equals the number of shots + blocks + misses by the opponent.

corsi_for¶: Returns an int of the Corsi For at Even Strength metric which equals the number of shots + blocks + misses.

corsi_for_percentage¶: Returns a float of the percentage of control a team had of the puck which is calculated by the corsi_for value divided by the sum of corsi_for and corsi_against. Values greater than 50.0 indicate the team had more control of the puck than their opponent. Percentage ranges from 0-100.

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 was played, such as ‘2017-10-05’.

datetime¶: Returns a datetime object to indicate the month, day, and year the game was played at.

faceoff_losses¶: Returns an int of the number of faceoffs the team lost at even strength.

faceoff_win_percentage¶: Returns a float of percentage of faceoffs the team won while at even strength. Percentage ranges from 0-100.

faceoff_wins¶: Returns an int of the number of faceoffs the team won at even strength.

fenwick_against¶: Returns an int of the Fenwick Against at Even Strength metric which equals the number of shots + misses by the opponent.

fenwick_for¶: Returns an int of the Fenwick For at Even Strength metric which equals the number of shots + misses.

fenwick_for_percentage¶: Returns a float of the percentage of control a team had of the puck which is calculated by the fenwick_for value divided by the sum of fenwick_for and fenwick_against. Values greater than 50.0 indicate the team had more control of the puck than their opponent. Percentage ranges from 0-100.

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

goals_allowed¶: Returns an int of the number of goals the team allowed during the game.

goals_scored¶: Returns an int of the number of goals the team scored during the game.

location¶: Returns a string constant to indicate whether the game was played at home or away.

offensive_zone_start_percentage¶: Returns a float of the percentage of stats that took place in the offensive half. Value is calculated by the number of offensive zone starts divided by the sum of offensive zone starts and defensive zone starts. Percentage ranges from 0-100.

opp_penalties_in_minutes¶: Returns an int of the total number of minutes the opponent served for penalties.

opp_power_play_goals¶: Returns an int of the number of power play goals the opponent scored.

opp_power_play_opportunities¶: Returns an int of the number of power play opportunities the opponent had.

opp_short_handed_goals¶: Returns an int of the number of shorthanded goals the opponent scored.

opp_shots_on_goal¶: Returns an int of the total number of shots on goal the opponent registered.

opponent_abbr¶: Returns a string of the opponent’s 3-letter abbreviation, such as ‘NYR’ for the New York Rangers.

opponent_name¶: Returns a string of the opponent’s name, such as ‘New York Rangers’.

overtime¶: Returns an int of the number of overtimes that were played during the game, or an int constant if the game went to a shootout.

pdo¶: Returns a float of the team’s PDO at Even Strength metric which is calculated by the sum of the shooting percentage and save percentage. Percentage ranges from 0-100.

penalties_in_minutes¶: Returns an int of the total number of minutes the team served for penalties.

power_play_goals¶: Returns an int of the number of power play goals the team scored.

power_play_opportunities¶: Returns an int of the number of power play opportunities the team had.

result¶: Returns a string constant to indicate whether the team lost in regulation, lost in overtime, or won.

short_handed_goals¶: Returns an int of the number of shorthanded goals the team scored.

shots_on_goal¶: Returns an int of the total number of shots on goal the team registered.

class sportsreference.nhl.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 ‘NYR’ for the New York Rangers. 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.nhl.teams module¶

The Teams module exposes information for all NHL teams including the team name and abbreviation, the number of games they won during the season, the total number of shots on goal, and much more.

from sportsreference.nhl.teams import Teams

teams = Teams()
for team in teams:
    print(team.name)  # Prints the team's name
    print(team.shots_on_goal)  # Prints the team's total shots on goal

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.nhl.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.nhl.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 Red Wings.

average_age¶: Returns a float of the average age of all players on the team, weighted by their time on ice.

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

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

goals_against¶: Returns an int of the total number of goals opponents scored against the team during the season.

goals_for¶: Returns an int of the total number of goals a team scored during the season.

losses¶: Returns an int of the total number of losses the team had in the season.

name¶: Returns a string of the team’s full name, such as ‘Detroit Red Wings’.

overtime_losses¶: Returns an int of the total number of overtime losses the team had in the season.

pdo_at_even_strength¶: Returns a float of the PDO at even strength which equates to the shooting percentage plus the save percentage.

penalty_killing_percentage¶: Returns a float denoting the percentage of power plays that have been successfully defended without a goal being conceded. Percentage ranges from 0-100.

points¶: Returns an int of the total number of points the team gained in the season.

points_percentage¶: Returns a float denoting the percentage of points gained divided by the maximum possible points available during the season. Percentage ranges from 0-1.

power_play_goals¶: Returns an int of the total number of power play goals scored.

power_play_goals_against¶: Returns an int of the total number of power play goals conceded.

power_play_opportunities¶: Returns an int of the total number of power play opportunities for a team during the season.

power_play_opportunities_against¶: Returns an int of the total number of power play opportunities for the opponents during the season.

power_play_percentage¶: Returns a float denoting the percentage of power play opportunities where the team has scored. Percentage ranges from 0-100.

rank¶: Returns an int of the team’s rank based on the number of points they obtained in the season.

save_percentage¶: Returns a float denoting the percentage of shots the team has saved during the season. Percentage ranges from 0-1.

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

shooting_percentage¶: Returns a float denoting the percentage of shots to goals during the season. Percentage ranges from 0-100.

short_handed_goals¶: Returns an int of the number of short handed goals the team has scored during the season.

short_handed_goals_against¶: Returns an int of the number of short handed goals the team has conceded during the season.

shots_against¶: Returns an int of the total number of shots on goal the team’s opponents made during the season.

shots_on_goal¶: Returns an int of the total number of shots on goal the team made during the season.

simple_rating_system¶: Returns a float which takes into account the average goal differential vs a team’s strength of schedule. The league average evaluates to 0.0. Teams which have a positive score are comparatively stronger than average while teams with a negative score are weaker.

strength_of_schedule¶: Returns a float denoting a team’s strength of schedule, based on goals scores and conceded. Higher values result in more challenging schedules while 0.0 is an average schedule.

total_goals_per_game¶: Returns a float for the average number of goals scored per game.

wins¶: Returns an int of the total number of wins the team had in the season.

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

Bases: object

A list of all NHL teams and their stats in a given year.

Finds and retrieves a list of all NHL teams from www.hockey-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.