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.
Boxscore
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 sportsipy.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 sportsipy.nhl.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.nhl.boxscore import Boxscores
# Pulls all games between and including February 4, 2017 and February 5,
# 2017
games = Boxscores(datetime(2017, 2, 4), datetime(2017, 2, 5))
# Prints a dictionary of all results from February 4, 2017 and February 5,
# 2017
print(games.games)
- class sportsipy.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’.
- property arena
Returns a
string
of the name of the ballpark where the game was played.
- property attendance
Returns an
int
of the game’s listed attendance.
- property away_assists
Returns an
int
of the number of assists the away team registered.
- property away_even_strength_assists
Returns an
int
of the number of assists the away team registered while at even strength.
- property away_even_strength_goals
Returns an
int
of the number of goals the away team scored at even strength.
- property away_game_winning_goals
Returns an
int
of the number of game winning goals the away team scored.
- property away_goals
Returns an
int
of the number of goals the away team scored.
- property away_penalties_in_minutes
Returns an
int
of the length of time the away team spent in the penalty box.
- 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 registered.
- property away_power_play_assists
Returns an
int
of the number of assists the away team registered while on a power play.
- property away_power_play_goals
Returns an
int
of the number of goals the away team scored while on a power play.
- property away_save_percentage
Returns a
float
of the percentage of shots the away team saved. Percentage ranges from 0-1.
- property away_saves
Returns an
int
of the number of saves the away team made.
- property away_shooting_percentage
Returns a
float
of the away team’s shooting percentage. Percentage ranges from 0-100.
- property away_short_handed_assists
Returns an
int
of the number of assists the away team registered while short handed.
- property away_short_handed_goals
Returns an
int
of the number of goals the away team scored while short handed.
- property away_shots_on_goal
Returns an
int
of the number of shots on goal the away team registered.
- property away_shutout
Returns an
int
denoting whether or not the away team shutout the home team.
- 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 ‘201806070VEG’.
- property date
Returns a
string
of the date the game took place.
- property duration
MM’.
- Type
Returns a
string
of the game’s duration in the format ‘H
- property home_assists
Returns an
int
of the number of assists the home team registered.
- property home_even_strength_assists
Returns an
int
of the number of assists the home team registered while at even strength.
- property home_even_strength_goals
Returns an
int
of the number of goals the home team scored at even strength.
- property home_game_winning_goals
Returns an
int
of the number of game winning goals the home team scored.
- property home_goals
Returns an
int
of the number of goals the home team scored.
- property home_penalties_in_minutes
Returns an
int
of the length of time the home team spent in the penalty box.
- 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 registered.
- property home_power_play_assists
Returns an
int
of the number of assists the home team registered while on a power play.
- property home_power_play_goals
Returns an
int
of the number of goals the home team scored while on a power play.
- property home_save_percentage
Returns a
float
of the percentage of shots the home team saved. Percentage ranges from 0-1.
- property home_saves
Returns an
int
of the number of saves the home team made.
- property home_shooting_percentage
Returns a
float
of the home team’s shooting percentage. Percentage ranges from 0-100.
- property home_short_handed_assists
Returns an
int
of the number of assists the home team registered while short handed.
- property home_short_handed_goals
Returns an
int
of the number of goals the home team scored while short handed.
- property home_shots_on_goal
Returns an
int
of the number of shots on goal the home team registered.
- property home_shutout
Returns an
int
denoting whether or not the home team shutout the home team.
- property losing_abbr
Returns a
string
of the losing team’s abbreviation, such as ‘WSH’ for the Washington Capitals.
- property losing_name
Returns a
string
of the losing team’s name, such as ‘Washington Capitals’.
- property playoff_round
Returns a
string
denoting which round of the playoffs the game is a part of, such as ‘Western First Round’, or None if the game was played during the regular season.
- property time
Returns a
string
of the time the game started.
- 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 ‘VEG’ for the Vegas Golden Knights.
- property winning_name
Returns a
string
of the winning team’s name, such as ‘Vegas Golden Knights’.
- class sportsipy.nhl.boxscore.BoxscorePlayer(player_id, player_name, player_data)[source]
Bases:
sportsipy.nhl.player.AbstractPlayer
Get player stats for an individual game.
Given a player ID, such as ‘zettehe01’ for Henrik Zetterberg, 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 hockey-reference.com, such as ‘zettehe01’ for Henrik Zetterberg. 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 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 properties and values for the specified game.
- property decision
Returns a
string
denoting whether the goalie won or lost the game.
- property defensive_zone_start_percentage
Returns a
float
of the percentage of starts that took place in the player’s defensive zone. Percentage ranges from 0-100.
- property defensive_zone_starts
Returns an
int
of the number of starts that took place in the player’s defensive zone.
- property individual_corsi_for_events
Returns an
int
of the number of individual events that impacted the player’s Corsi For score during the game.
- property offensive_zone_starts
Returns an
int
of the number of starts that took place in the player’s offensive zone.
- property on_ice_shot_attempts_against
Returns an
int
of the Corsi Against shot attempts that occurred while the player was on the ice.
- property on_ice_shot_attempts_for
Returns an
int
of the Corsi For shot attempts that occurred while the player was on the ice.
- property shifts
Returns an
int
of the number of shifts the player had on the ice during the game.
- property time_on_ice
Returns a
string
of the total time the player has spent on ice in the format ‘MM:SS’.
- class sportsipy.nhl.boxscore.Boxscores(date, end_date=None)[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.
end_date (datetime object) – 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 '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`), 'winning_name': Full name of the winning team, such as 'New York Rangers' (`str`), 'winning_abbr': Abbreviation for the winning team, such as 'NYR' (`str`), 'losing_name': Full name of the losing team, such as 'Boston Bruins' (`str`), 'losing_abbr': Abbreviation for the losing team, such as 'BOS' (`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.nhl.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 ‘zettehe01’ for Henrik Zetterberg, capture all relevant stats and information like name, team, height/weight, career goals, single-season assits, penalty minutes, 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 sports-reference.com.
- Parameters
player_id (string) – A player’s ID according to hockey-reference.com, such as ‘zettehe01’ for Henrik Zetterberg. 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’ is the first five letters of the player’s last name, ‘ff’ is the first two letters of 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 ‘Henrik Zetterberg’.
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 assists
Returns an
int
of the number of goals the player has assisted.
- property blocks_at_even_strength
Returns an
int
of the number of shots the player blocks while at even strength.
- property corsi_for_percentage
Returns a
float
of the ‘Corsi For’ percentage, equal to corsi_for / (corsi_for + corsi_against). Percentage ranges from 0-100.
- property even_strength_assists
Returns an
int
of the number of goals the player has assisted while at even strength.
- property even_strength_goals
Returns an
int
of the number of goals the player has scored at even strength.
- property game_winning_goals
Returns an
int
of the number of game-winning goals the player has scored.
- property goals
Returns an
int
of the number of goals the player scored.
- property goals_against
Returns an
int
of the number of goals the opponent scored on the player while in goal.
- property hits_at_even_strength
Returns an
int
of the number of hits the player makes while at even strength.
- property name
Returns a
string
of the player’s name, such as ‘Henrik Zetterberg’.
- property offensive_zone_start_percentage
Returns a
float
of the percentage of faceoffs that occur in the offensive zone while the player is on ice. Percentage ranges from 0-100.
- property penalties_in_minutes
Returns an
int
of the number of minutes the player has served as a result of penalties.
- property player_id
Returns a
string
of the player’s ID on hockey-reference, such as ‘zettehe01’ for Henrik Zetterberg.
- property plus_minus
Returns an
int
representing the relative presence the player has on the outcome of the game.
- property points
Returns an
int
of the number of points the player has gained.
- property power_play_assists
Returns an
int
of the number of goals the player has assisted while on a power play.
- property power_play_goals
Returns an
int
of the number of goals the player has scored while on a power play.
- property relative_corsi_for_percentage
Returns a
float
of the player’s relative ‘Corsi For’ percentage, equal to the difference between the player’s on and off-ice Corsi For percentage.
- property save_percentage
Returns a
float
of the percentage of shots the player has saved. Percentage ranges from 0-1.
- property saves
Returns an
int
of the number of shots the player has saved while in goal.
- property shooting_percentage
Returns a
float
of the percentage of the player’s shots that go in the goal. Percentage ranges from 0-100.
- property short_handed_assists
Returns an
int
of the number of goals the player has assisted while short handed.
- property short_handed_goals
Returns an
int
of the number of goals the player has scored while short handed.
- property shots_against
Returns an
int
of the number of shots the opponent took while the player is in goal.
- property shots_on_goal
Returns an
int
of the number of shots on goal the player has made.
- property shutouts
Returns an
int
of the number of shutouts the player has registered while in goal.
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 and weight. The following is an example on collecting career information
for Henrik Zetterberg:
from sportsipy.nhl.roster import Player
zetterberg = Player('zettehe01')
print(zetterberg.name) # Prints 'Henrik Zetterberg'
print(zetterberg.points) # Prints Zetterberg's career points total
# Prints a Pandas DataFrame of all relevant Zetterberg stats per season
print(zetterberg.dataframe)
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.nhl.roster import Player
zetterberg = Player('zettehe01') # Currently pulling career stats
print(zetterberg.points) # Prints Zetterberg's CAREER points total
# Prints Zetterberg's points total only for the 2017-18 season.
print(zetterberg('2017-18').points)
# Prints the number of games Zetterberg played in the 2017-18 season.
print(zetterberg.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.nhl.roster import Player
zetterberg = Player('zettehe01') # Currently pulling career stats
# Prints Zetterberg's points total only for the 2017-18 season.
print(zetterberg('2017-18').points)
print(zetterberg('Career').points) # Prints Zetterberg'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.nhl.roster import Roster
detroit = Roster('DET')
for player in detroit.players:
# Prints the name of all players who played for Houston in the most
# recent season.
print(player.name)
- class sportsipy.nhl.roster.Player(player_id)[source]
Bases:
sportsipy.nhl.player.AbstractPlayer
Get player information and stats for all seasons.
Given a player ID, such as ‘zettehe01’ for Henrik Zetterberg, capture all relevant stats and information like name, team, height/weight, career goals, single-season assits, penalty minutes, 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 sports-reference.com.
- Parameters
player_id (string) – A player’s ID according to hockey-reference.com, such as ‘zettehe01’ for Henrik Zetterberg. 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’ is the first five letters of the player’s last name, ‘ff’ is the first two letters of 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 adjusted_assists
Returns an
int
of the adjusted number of goals the player has assisted.
- property adjusted_goals
Returns an
int
of the adjusted number of goals the player has scored.
- property adjusted_goals_against_average
Returns a
float
of the adjusted goals against average for the player while in goal.
- property adjusted_goals_created
Returns an
int
of the adjusted number of goals the player created.
- property adjusted_points
Returns an
int
of the adjusted number of points the player has gained.
- property age
Returns an
int
of the player’s age on February 1st of the season.
- property average_time_on_ice
Returns a
string
of the average time the player spends on the ice per game.
- property blocks_at_even_strength
Returns an
int
of the number of shots the player blocks while at even strength.
- property corsi_against
Returns a
float
of the player’s ‘Corsi Against’ factor at even strength, equal to shots + blocks + misses.
- property corsi_for
Returns a
float
of the player’s ‘Corsi For’ factor at even strength, equal to shots + blocks + misses.
- 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.
Returns a
float
of the player’s denensive point share, equal to the approximate number of points the player contributed to while on defense.
- property defensive_zone_start_percentage
Returns a
float
of the percentage of faceoffs that occur in the defensive zone whil the player is on ice. Percentage ranges from 0-100.
- property even_strength_goals_allowed
Returns an
int
of the number of goals the player allowed in goal while at even strength.
- property even_strength_save_percentage
Returns a
float
of the player’s save percentage while at even strength.
- property even_strength_shots_faced
Returns an
int
of the number of shots the player has faced while at even strength.
- property faceoff_losses
Returns an
int
of the number of faceoffs the player lost.
- property faceoff_percentage
Returns a
float
of the percentage of faceoffs the player wins. Percentage ranges from 0-100.
- property faceoff_wins
Returns an
int
of the number of faceoffs the player won.
- property fenwick_against
Returns an
int
of the player’s ‘Fenwick Against’ factor at even strength, equal to shots + misses.
- property fenwick_for
Returns an
int
of the player’s ‘Fenwick For’ factor at even strength, equal to shots + misses.
- property fenwick_for_percentage
Returns a
float
of the player’s ‘Fenwick For’ percentage, equal to fenwick_for / (fenwick_for + fenwick_against). Percentage ranges from 0-100.
- property games_played
Returns an
int
of the number of games the player participated in.
- property giveaways
Returns an
int
of the number of times the player gave the puck away to an opponent.
- property goal_against_percentage_relative
Returns an
int
of the player’s goals against average compared to the league average where 100 is an average player and 0 means the player saved every single shot.
Returns a
float
of the player’s point share while in goal.
- property goals_against_average
Returns a
float
of the average number of goals the opponent has scored per game while the player is in goal.
- property goals_against_on_ice
Returns an
int
of the number of times the team has been scored on while the player is on ice.
- property goals_created
Returns an
int
of the number of goals the player created, equal to (goals + assists * 0.5) * team_goals / (team_goals + team_assists * 0.5).
- property goals_for_on_ice
Returns an
int
of the number of goals the team has scored while the player is on ice.
- property goals_saved_above_average
Returns a
float
of the number of goals the player saved above the league average.
- property height
Returns a
string
of the player’s height in the format “feet-inches”.
- property league
Returns a
string
of the league the player’s team participates in.
- property losses
Returns an
int
of the number of times the team lost while the player is in goal.
- property minutes
Returns an
int
of the total number of minutes the player has spent in goal.
- property name
Returns a
string
of the player’s name, such as ‘Henrik Zetterberg’.
Returns a
float
of the player’s offensive point share, equal to the approximate number of points the player contributed to while on offense.
- property pdo
Returns a
float
of the team’s PDO while the player is on ice at even strength, equal to the team’s shooting percentage + save percentage. Percentage ranges from 0-100.
Returns a
float
of the player’s total point share, equal to the sum of the player’s offensive and defensive point share.
- property power_play_goals_against_on_ice
Returns an
int
of the total number of power play goals against while the player was on ice.
- property power_play_goals_allowed
Returns an
int
of the number of goals the player allowed in goal while on a power play.
- property power_play_goals_for_on_ice
Returns an
int
of the total number of power play goals for while the player was on ice.
- property power_play_save_percentage
Returns a
float
of the player’s save percentage while on a power play.
- property power_play_shots_faced
Returns an
int
of the number of shots the player has faced while on a power play.
- property quality_start_percentage
Returns a
float
of the percentage of the player’s starts that are considered quality starts while in goal. Percentage ranges from 0-1.
- property quality_starts
Returns an
int
of the number of quality starts the player has had, equal to starting out with an in-game save percentage greater than the player’s average save percentage for the year.
- property really_bad_starts
Returns an
int
of the number of really bad starts the player has had, equal to starting out with an in-game save percentage less than 85%.
- property relative_fenwick_for_percentage
Returns a
float
of the player’s relative ‘Fenwick For’ percentage, equal to the difference between the player’s on and off-ice Fenwick For percentage.
- property save_percentage_on_ice
Returns an
int
of the team’s save percentage while the player is on ice.
- 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_percentage_on_ice
Returns a
float
of the team’s shooting percentage while the player is on ice.
- property shootout_attempts
Returns an
int
of the number of shootouts the player attempted.
- property shootout_goals
Returns an
int
of the number of shootout goals the player scored.
- property shootout_misses
Returns an
int
of the number of shootouts the player failed to score.
- property shootout_percentage
Returns a
float
of the percentage of shootouts the player scores in. Percentage ranges from 0-100.
- property short_handed_goals_allowed
Returns an
int
of the number of goals the player allowed in goal while short handed.
- property short_handed_save_percentage
Returns a
float
of the player’s save percentage while short handed.
- property short_handed_shots_faced
Returns an
int
of the number of shots the player has faced while short handed.
- property takeaways
Returns an
int
of the number of times the player took the puck away from an opponent.
- property team_abbreviation
Returns a
string
of the team’s abbreviation, such as ‘DET’ for the Detroit Red Wings.
- property ties_plus_overtime_loss
Returns an
int
of the number of times the team has either tied or lost in overtime or a shootout while the player is in goal.
- property time_on_ice
Returns an
int
of the total time the player has spent on ice in minutes.
- property time_on_ice_even_strength
Returns a
float
of the amount of time the player spent on ice in minutes while at even strength.
- property total_goals_against_on_ice
Returns an
int
of the total number of goals against while the player was on ice.
- property total_goals_for_on_ice
Returns an
int
of the total number of goals for while the player was on ice.
- property total_shots
Returns an
int
of the total number of shots the player took regardless of them being on goal or not.
- property weight
Returns an
int
of the player’s weight in pounds.
- property wins
Returns an
int
of the number of times the team won while the player is in goal.
- class sportsipy.nhl.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 player’s statistics and information.
- Parameters
team (string) – The team’s abbreviation, such as ‘DET’ for the Detroit Red Wings.
year (string (optional)) – The 6-digit year to pull the roster from, such as ‘2017-18’. 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 ‘Jeff Blashill’.
- 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.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 sportsipy.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.
- 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 corsi_against
Returns an
int
of the Corsi Against at Even Strength metric which equals the number of shots + blocks + misses by the opponent.
- property corsi_for
Returns an
int
of the Corsi For at Even Strength metric which equals the number of shots + blocks + misses.
- property 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.
- 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 was played, such as ‘2017-10-05’.
- property datetime
Returns a datetime object to indicate the month, day, and year the game was played at.
- property faceoff_losses
Returns an
int
of the number of faceoffs the team lost at even strength.
- property faceoff_win_percentage
Returns a
float
of percentage of faceoffs the team won while at even strength. Percentage ranges from 0-100.
- property faceoff_wins
Returns an
int
of the number of faceoffs the team won at even strength.
- property fenwick_against
Returns an
int
of the Fenwick Against at Even Strength metric which equals the number of shots + misses by the opponent.
- property fenwick_for
Returns an
int
of the Fenwick For at Even Strength metric which equals the number of shots + misses.
- property 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.
- property game
Returns an
int
to indicate which game in the season was requested. The first game of the season returns 1.
- property goals_allowed
Returns an
int
of the number of goals the team allowed during the game.
- property goals_scored
Returns an
int
of the number of goals the team scored during the game.
- property location
Returns a
string
constant to indicate whether the game was played at home or away.
- property 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.
- property opp_penalties_in_minutes
Returns an
int
of the total number of minutes the opponent served for penalties.
- property opp_power_play_goals
Returns an
int
of the number of power play goals the opponent scored.
- property opp_power_play_opportunities
Returns an
int
of the number of power play opportunities the opponent had.
- property opp_short_handed_goals
Returns an
int
of the number of shorthanded goals the opponent scored.
- property opp_shots_on_goal
Returns an
int
of the total number of shots on goal the opponent registered.
- property opponent_abbr
Returns a
string
of the opponent’s 3-letter abbreviation, such as ‘NYR’ for the New York Rangers.
- property opponent_name
Returns a
string
of the opponent’s name, such as ‘New York Rangers’.
- property 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.
- property 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.
- property penalties_in_minutes
Returns an
int
of the total number of minutes the team served for penalties.
- property power_play_goals
Returns an
int
of the number of power play goals the team scored.
- property power_play_opportunities
Returns an
int
of the number of power play opportunities the team had.
- property result
Returns a
string
constant to indicate whether the team lost in regulation, lost in overtime, or won.
- property short_handed_goals
Returns an
int
of the number of shorthanded goals the team scored.
- property shots_on_goal
Returns an
int
of the total number of shots on goal the team registered.
- class sportsipy.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.
- 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 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 sportsipy.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
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.nhl.teams import Team
detroit = Team('DET')
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.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
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.nhl.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.nhl.teams.Team(team_name=None, team_data=None, rank=None, year=None, season_page=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. Is only used when called directly from the Teams class.
season_page (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 Red Wings.
- property average_age
Returns a
float
of the average age of all players on the team, weighted by their time on ice.
- 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 games_played
Returns an
int
of the total number of games the team has played in the season.
- property goals_against
Returns an
int
of the total number of goals opponents scored against the team during the season.
- property goals_for
Returns an
int
of the total number of goals a team scored during the season.
- property losses
Returns an
int
of the total number of losses the team had in the season.
- property name
Returns a
string
of the team’s full name, such as ‘Detroit Red Wings’.
- property overtime_losses
Returns an
int
of the total number of overtime losses the team had in the season.
- property pdo_at_even_strength
Returns a
float
of the PDO at even strength which equates to the shooting percentage plus the save percentage.
- property 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.
- property points
Returns an
int
of the total number of points the team gained in the season.
- property 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.
- property power_play_goals
Returns an
int
of the total number of power play goals scored.
- property power_play_goals_against
Returns an
int
of the total number of power play goals conceded.
- property power_play_opportunities
Returns an
int
of the total number of power play opportunities for a team during the season.
- property power_play_opportunities_against
Returns an
int
of the total number of power play opportunities for the opponents during the season.
- property power_play_percentage
Returns a
float
denoting the percentage of power play opportunities where the team has scored. Percentage ranges from 0-100.
- property rank
Returns an
int
of the team’s rank based on the number of points they obtained in the season.
- property roster
Returns an instance of the Roster class containing all players for the team during the season with all career stats.
- property save_percentage
Returns a
float
denoting the percentage of shots the team has saved during the season. Percentage ranges from 0-1.
- property schedule
Returns an instance of the Schedule class containing the team’s complete schedule for the season.
- property shooting_percentage
Returns a
float
denoting the percentage of shots to goals during the season. Percentage ranges from 0-100.
- property short_handed_goals
Returns an
int
of the number of short handed goals the team has scored during the season.
- property short_handed_goals_against
Returns an
int
of the number of short handed goals the team has conceded during the season.
- property shots_against
Returns an
int
of the total number of shots on goal the team’s opponents made during the season.
- property shots_on_goal
Returns an
int
of the total number of shots on goal the team made during the season.
- property 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.
- property 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.
- property total_goals_per_game
Returns a
float
for the average number of goals scored per game.
- property wins
Returns an
int
of the total number of wins the team had in the season.
- class sportsipy.nhl.teams.Teams(year=None, season_page=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.
season_page (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.