NFL Package
The NFL package offers multiple modules which can be used to retrieve information and statistics for the National Football 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 points scored to the number of passing yards, to
the number of yards lost from sacks 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.nfl.boxscore import Boxscore
game_data = Boxscore('201802040nwe')
print(game_data.home_points) # Prints 33
print(game_data.away_points) # Prints 41
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 sportsipy.nfl.boxscore import Boxscores
games_today = Boxscores(1, 2017)
# Prints a dictionary of all matchups for week 1 of 2017
print(games_today.games)
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 sportsipy.nfl.boxscore import Boxscores
# Pulls all games from weeks 7 and 8 in 2017
games = Boxscores(7, 2017, 8)
# Prints a dictionary of all games from weeks 7 and 8 in 2017
print(games.games)
- class sportsipy.nfl.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 yards from sacks, a team’s passing completion, rushing touchdowns and much more.
- Parameters
uri (string) – The relative link to the boxscore HTML page, such as ‘201802040nwe’.
- property attendance
Returns an
int
of the game’s listed attendance.
- property away_abbreviation
Returns a
string
of the away team’s abbreviation, such as ‘NWE’.
- property away_first_downs
Returns an
int
of the number of first downs the away team gained.
- property away_fourth_down_attempts
Returns an
int
of the number of fourth down plays the away team attempted to convert.
- property away_fourth_down_conversions
Returns an
int
of the number of fourth down plays the away team successfully converted.
- property away_fumbles
Returns an
int
of the number of times the away team fumbled the ball.
- property away_fumbles_lost
Returns an
int
of the number of times the away team turned the ball over as the result of a fumble.
- property away_interceptions
Returns an
int
of the number of interceptions the away team threw.
- property away_net_pass_yards
Returns an
int
of the net pass yards gained by the away team.
- property away_pass_attempts
Returns an
int
of the number of passes that were thrown by the away team.
- property away_pass_completions
Returns an
int
of the number of completed passes the away team made.
- property away_pass_touchdowns
Returns an
int
of the number of passing touchdowns the away team scored.
- property away_pass_yards
Returns an
int
of the number of passing yards the away team gained.
- property away_penalties
Returns an
int
of the number of penalties called on the away team.
- property away_players
Returns a
list
ofBoxscorePlayer
class instances for each player on the away team.
- property away_points
Returns an
int
of the number of points the away team scored.
- property away_rush_attempts
Returns an
int
of the number of rushing plays the away team made.
- property away_rush_touchdowns
Returns an
int
of the number of rushing touchdowns the away team scored.
- property away_rush_yards
Returns an
int
of the number of rushing yards the away team gained.
- property away_third_down_attempts
Returns an
int
of the number of third down plays the away team attempted to convert.
- property away_third_down_conversions
Returns an
int
of the number of third down plays the away team successfully converted.
- property away_time_of_possession
Returns a
string
of the amount of time the home team had possession of the football in the format ‘MM:SS’.
- property away_times_sacked
Returns an
int
of the number of times the away team was sacked.
- property away_total_yards
Returns an
int
of the total number of yards the away team gained.
- property away_turnovers
Returns an
int
of the number of times the away team turned the ball over.
- property away_yards_from_penalties
Returns an
int
of the number of yards gifted as a result of penalties called on the away team.
- property away_yards_lost_from_sacks
Returns an
int
of the number of yards the away team lost as the result of a sack.
- 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 ‘201802040nwe’.
- property date
Returns a
string
of the date the game took place.
- property datetime
Returns a
datetime
object of the date and time the game took place.
- property duration
MM’.
- Type
Returns a
string
of the game’s duration in the format ‘H
- property home_abbreviation
Returns a
string
of the home team’s abbreviation, such as ‘KAN’.
- property home_first_downs
Returns an
int
of the number of first downs the home team gained.
- property home_fourth_down_attempts
Returns an
int
of the number of fourth down plays the home team attempted to convert.
- property home_fourth_down_conversions
Returns an
int
of the number of fourth down plays the home team successfully converted.
- property home_fumbles
Returns an
int
of the number of times the home team fumbled the ball.
- property home_fumbles_lost
Returns an
int
of the number of times the home team turned the ball over as the result of a fumble.
- property home_interceptions
Returns an
int
of the number of interceptions the home team threw.
- property home_net_pass_yards
Returns an
int
of the net pass yards gained by the home team.
- property home_pass_attempts
Returns an
int
of the number of passes that were thrown by the home team.
- property home_pass_completions
Returns an
int
of the number of completed passes the home team made.
- property home_pass_touchdowns
Returns an
int
of the number of passing touchdowns the home team scored.
- property home_pass_yards
Returns an
int
of the number of passing yards the home team gained.
- property home_penalties
Returns an
int
of the number of penalties called on the home team.
- property home_players
Returns a
list
ofBoxscorePlayer
class instances for each player on the home team.
- property home_points
Returns an
int
of the number of points the home team scored.
- property home_rush_attempts
Returns an
int
of the number of rushing plays the home team made.
- property home_rush_touchdowns
Returns an
int
of the number of rushing touchdowns the home team scored.
- property home_rush_yards
Returns an
int
of the number of rushing yards the home team gained.
- property home_third_down_attempts
Returns an
int
of the number of third down plays the home team attempted to convert.
- property home_third_down_conversions
Returns an
int
of the number of third down plays the home team successfully converted.
- property home_time_of_possession
Returns a
string
of the amount of time the home team had possession of the football in the format ‘MM:SS’.
- property home_times_sacked
Returns an
int
of the number of times the home team was sacked.
- property home_total_yards
Returns an
int
of the total number of yards the home team gained.
- property home_turnovers
Returns an
int
of the number of times the home team turned the ball over.
- property home_yards_from_penalties
Returns an
int
of the number of yards gifted as a result of penalties called on the home team.
- property home_yards_lost_from_sacks
Returns an
int
of the number of yards the home team lost as the result of a sack.
- property losing_abbr
Returns a
string
of the losing team’s abbreviation, such as ‘KAN’ for the Kansas City Chiefs.
- property losing_name
Returns a
string
of the losing team’s name, such as ‘Kansas City Chiefs’.
- property over_under
Returns a
string
of the listed over under, and the actual result.
- property roof
Returns a
string
of the stadium type and whether or not the game was played outdoors.
- property stadium
Returns a
string
of the name of the stadium where the game was played.
- property summary
Returns a
dictionary
with two keys, ‘away’ and ‘home’. The value of each key will be a list for each respective team’s score by order of the quarter, with the first element belonging to the first quarter, similar to the following:- {
‘away’: [0, 7, 3, 14], ‘home’: [7, 7, 3, 0]
}
- property surface
Returns a
string
of the type of field the game was played on.
- property time
Returns a
string
of the time the game started.
- property vegas_line
Returns a
string
of the Vegas Line including the projected winner and the spread.
- property weather
Returns a
string
of the weather reading at kickoff.
- 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 ‘NWE’ for the New England Patriots.
- property winning_name
Returns a
string
of the winning team’s name, such as ‘New England Patriots’.
- property won_toss
Returns a
string
of the team that won the coin toss, such as ‘Chiefs’.
- class sportsipy.nfl.boxscore.BoxscorePlayer(player_id, player_name, player_data)[source]
Bases:
sportsipy.nfl.player.AbstractPlayer
Get player stats for an individual game.
Given a player ID, such as ‘BreeDr01’ for Drew Brees, 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 pro-football-reference.com, such as ‘BreeDr00’ for Drew Brees. The player ID can be found by navigating to the player’s stats page and getting the string between the final slash and the ‘.htm’ in the URL. In general, the ID is in the format ‘LlllFfNN’ where ‘Llll’ are the first 4 letters in the player’s last name with the first letter capitalized, ‘Ff’ are the first 2 letters in the player’s first name where the first letter is capitalized, and ‘NN’ is a number starting at ‘00’ 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 ‘David Blough’.
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 average_kickoff_return_yards
Returns a
float
of the average number of yards the player returned a kickoff for.
- property combined_tackles
Returns an
int
of the number of solo and assisted tackles the player made.
- property dataframe
Returns a
pandas DataFrame
containing all other relevant class properties and values for the specified game.
- property fumbles_lost
Returns an
int
of the number of times the player fumbled the ball and the opponent recovered the ball.
- property quarterback_hits
Returns an
int
of the number of times the player hit the quarterback.
- property solo_tackles
Returns an
int
of the number of solo tackles the player made during the game.
- property tackles_for_loss
Returns an
int
of the number of times the player tackles an opponent for a loss on the play.
- property yards_lost_from_sacks
Returns an
int
of the total number of yards the player lost after being sacked by the opponent.
- class sportsipy.nfl.boxscore.Boxscores(week, year, end_week=None)[source]
Bases:
object
Search for NFL 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
week (int) – The week number to pull games from.
year (int) – The 4-digit year to pull games from.
end_week (int (optional)) – Optionally specify an end week to iterate until. All boxscores starting from the week specified in the ‘week’ parameter up to and including the boxscores specified in the ‘end_week’ parameter will be pulled. If left empty, or if ‘end_week’ is prior to ‘week’, 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:{'week' : [ # 'week' is the string week in format 'W-YYYY' { 'home_name': Name of the home team, such as 'Kansas City Chiefs' (`str`), 'home_abbr': Abbreviation for the home team, such as 'KAN' (`str`), 'away_name': Name of the away team, such as 'Houston Texans' (`str`), 'away_abbr': Abbreviation for the away team, such as 'HTX' (`str`), 'boxscore': String representing the boxscore URI, such as 'SLN/SLN201807280' (`str`), 'winning_name': Full name of the winning team, such as 'Kansas City Chiefs' (`str`), 'winning_abbr': Abbreviation for the winning team, such as 'KAN' (`str`), 'losing_name': Full name of the losing team, such as 'Houston Texans' (`str`), 'losing_abbr': Abbreviation for the losing team, such as 'HTX' (`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 ‘week’, the list for [‘week’] 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.nfl.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 ‘BreeDr00’ for Drew Brees, capture all relevant stats and information like name, team, height/weight, career starts, single season pasing yards, sacks, 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 pro-football-reference.com.
- Parameters
player_id (string) – A player’s ID according to pro-football-reference.com, such as ‘BreeDr00’ for Drew Brees. The player ID can be found by navigating to the player’s stats page and getting the string between the final slash and the ‘.htm’ in the URL. In general, the ID is in the format ‘LlllFfNN’ where ‘Llll’ are the first 4 letters in the player’s last name with the first letter capitalized, ‘Ff’ are the first 2 letters in the player’s first name where the first letter is capitalized, and ‘NN’ is a number starting at ‘00’ 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 ‘Drew Brees’.
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_on_tackles
Returns an
int
of the number of assist the player made on tackles.
- property attempted_passes
Returns an
int
of the number of passes the player attempted.
- property completed_passes
Returns an
int
of the number of completed passes the player threw.
- property extra_points_attempted
Returns an
int
of the number of extra points the player attempted.
- property extra_points_made
Returns an
int
of the number of extra points the player made.
- property field_goals_attempted
Returns an
int
of the total number of field goals the player attempted from any distance.
- property field_goals_made
Returns an
int
of the total number of field goals the player made from any distance.
- property fumbles
Returns an
int
of the number of times the player fumbled the ball.
- property fumbles_forced
Returns an
int
of the number of times the player forced a fumble.
- property fumbles_recovered
Returns an
int
of the number of fumbles the player has recovered.
- property fumbles_recovered_for_touchdown
Returns an
int
of the number of touchdowns the player has scored after recovering a fumble.
- property interceptions
Returns an
int
of the number of times the player intercepted a pass.
- property interceptions_returned_for_touchdown
Returns an
int
of the number of touchdowns the player has scored after intercepting a pass. Commonly referred to as a ‘Pick-6’.
- property interceptions_thrown
Returns an
int
of the number of interceptions the player has thrown.
- property kickoff_return_touchdown
Returns an
int
of the number of kickoffs the player returned for a touchdown.
- property kickoff_return_yards
Returns an
int
of the amount of yards the player gained while returning a kickoff.
- property kickoff_returns
Returns an
int
of the number of kickoffs the player returned.
- property longest_interception_return
Returns an
int
of the most yards the player has returned after intercepting a pass.
- property longest_kickoff_return
Returns an
int
of the highest number of yards the player has gained while returning a kickoff.
- property longest_pass
Returns an
int
of the longest completed pass the player threw.
- property longest_punt
Returns an
int
of the longest punt the player has kicked.
- property longest_punt_return
Returns an
int
of the highest number of yards the player has gained while returning a punt.
- property longest_reception
Returns an
int
of the highest number of yards the player gained as a result of a single reception.
- property longest_rush
Returns an
int
of the highest number of yards the player gained during a single rushing attempt.
- property name
Returns a
string
of the player’s name, such as ‘Drew Brees’.
- property passes_defended
Returns an
int
of the number of passes the player has defended as a defensive player.
- property passing_touchdowns
Returns an
int
of the number of touchdowns passes the player has thrown.
- property passing_yards
Returns an
int
of the number of yards receivers have gained as a result of the player’s passes.
- property player_id
Returns a
string
of the player’s ID on pro-football-reference, such as ‘BreeDr00’ for Drew Brees.
- property punt_return_touchdown
Returns an
int
of the number of punts the player returned for a touchdown.
- property punt_return_yards
Returns an
int
of the amount of yards the player gained while returning a punt.
- property punt_returns
Returns an
int
of the number of times a player returned a punt.
- property punts
Returns an
int
of the number of times the player punted the ball.
- property quarterback_rating
Returns a
float
of the player’s quarterback rating.
- property receiving_touchdowns
Returns an
int
of the number of touchdowns the player scored after receiving a pass.
- property receiving_yards
Returns an
int
of the number of receiving yards the player gained.
- property receptions
Returns an
int
of the number of receptions the player made.
- property rush_attempts
Returns an
int
of the number of rushing plays the player attempted.
- property rush_touchdowns
Returns an
int
of the number of rushing touchdowns the player scored.
- property rush_yards
Returns an
int
of the number of rushing yards the player gained.
- property sacks
Returns a
float
of the number of times the player sacked a quarterback.
- property times_pass_target
Returns an
int
of the number of times the player was the target of a pass.
- property times_sacked
Returns an
int
of the number of times the player was sacked as a quarterback.
- property total_punt_yards
Returns an
int
of the total number of yards the player has punted the ball.
- property yards_per_punt
Returns a
float
of the average distance the player punts the ball.
- property yards_per_punt_return
Returns a
float
of the average number of yards the player returned per punt.
- property yards_recovered_from_fumble
Returns an
int
of the number of yards the player gained after recovering a fumble.
- property yards_returned_from_interception
Returns an
int
of the number of yards the player returned after intercepting a pass.
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 touchdowns to single-season stats and player
height, weight, and nationality. The following is an example on collecting
career information for Drew Brees.
from sportsipy.nfl.roster import Player
brees = Player('BreeDr00')
print(brees.name) # Prints 'Drew Brees'
print(brees.passing_yards) # Prints Brees' career passing yards
# Prints a Pandas DataFrame of all relevant stats per season for Brees
print(brees.dataframe)
By default, the player’s career stats are returned whenever a property is called. To get stats for a specific team, call the class instance with the season string. All future property requests will return the season-specific stats.
from sportsipy.nfl.roster import Player
brees = Player('BreeDr00') # Currently pulling career stats
print(brees.passing_yards) # Prints Brees' CAREER passing yards total
# Prints Brees' passing yards total only for the 2017 season
print(brees('2017').passing_yards)
# Prints Brees' passing touchdowns for the 2017 season only
print(brees.passing_touchdowns)
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.nfl.roster import Player
brees = Player('BreeDr00') # Currently pulling career stats
# Prints Brees' passing yards total only for the 2017 season
print(brees('2017').passing_yards)
print(brees('Career').passing_yards) # Prints Brees' career passing yards
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.nfl.roster import Roster
saints = Roster('NOR')
for player in saints.players:
# Prints the name of all players who played for the New Orleans Saints
# in the most recent season.
print(player.name)
- class sportsipy.nfl.roster.Player(player_id)[source]
Bases:
sportsipy.nfl.player.AbstractPlayer
Get player information and stats for all seasons.
Given a player ID, such as ‘BreeDr00’ for Drew Brees, capture all relevant stats and information like name, team, height/weight, career starts, single season pasing yards, sacks, 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 pro-football-reference.com.
- Parameters
player_id (string) – A player’s ID according to pro-football-reference.com, such as ‘BreeDr00’ for Drew Brees. The player ID can be found by navigating to the player’s stats page and getting the string between the final slash and the ‘.htm’ in the URL. In general, the ID is in the format ‘LlllFfNN’ where ‘Llll’ are the first 4 letters in the player’s last name with the first letter capitalized, ‘Ff’ are the first 2 letters in the player’s first name where the first letter is capitalized, and ‘NN’ is a number starting at ‘00’ for the first time that player ID has been used and increments by 1 for every successive player.
- property adjusted_net_yards_per_attempt_index
Returns an
int
comparing players by the net average adjusted yards gained per attempt where 100 denotes an average player in this category and higher numbers are better.
- property adjusted_net_yards_per_pass_attempt
Returns a
float
of the adjusted net yards gained per pass attempt, equal to (pass_yards - sack_yards + (20 * pass_touchdowns) - (45 * interceptions)) / (pass_attempts + times_sacked).
- property adjusted_yards_per_attempt
Returns a
float
of the adjusted number of yards gained per passing attempt, equal to (yards + 20 * pass_touchdowns - 45 * interceptions) / pass_attempts.
- property adjusted_yards_per_attempt_index
Returns an
int
comparing players by the average adjusted yards gained per attempt where 100 denotes an average player in this category and higher numbers are better.
- property all_purpose_yards
Returns an
int
of the number of all-purpose yards the player has gained from receptions, rushes, and kickoff and punt returns.
- property approximate_value
Returns an
int
of the player’s approximate value which is a singular number used to compare players across seasons and positions, but is only intended to be a rough estimate.
- property assists_on_tackles
Returns an
int
of the number of assist the player made on tackles.
- property attempted_passes
Returns an
int
of the number of passes the player attempted.
- property birth_date
Returns a
datetime
object of the day and year the player was born.
- property blocked_punts
Returns an
int
of the number of the player’s punts that have been blocked.
- property catch_percentage
Returns a
float
of the percentage of passes the player caught while being the target of a pass. Percentage ranges from 0-100.
- property completed_passes
Returns an
int
of the number of completed passes the player threw.
- property completion_percentage_index
Returns an
int
comparing players by their passing completion percentage where 100 denotes an average player in this category and higher numbers are better.
- property dataframe
Returns a
pandas DataFrame
containing all other relevant class properties and values where each index is a different season plus the career stats.
- property drop_percentage
Returns a
float
of the percentage of passes the player has dropped. Percentage ranges from 0-100.
- property dropped_passes
Returns an
int
of the number of times the player has dropped a pass.
- property espn_qbr
Returns a
float
of the player’s Total Quarterback Rating according to ESPN.
- property extra_point_percentage
Returns a
float
of the percentage of extra points the player made. Percentage ranges from 0-100.
- property extra_points_attempted
Returns an
int
of the number of extra points the player attempted.
- property extra_points_made
Returns an
int
of the number of extra points the player made.
- property field_goal_percentage
Returns a
float
of the percentage of field goals the player made. Percentage ranges from 0-100.
- property field_goals_attempted
Returns an
int
of the total number of field goals the player attempted from any distance.
- property field_goals_made
Returns an
int
of the total number of field goals the player made from any distance.
- property fifty_plus_yard_field_goal_attempts
Returns an
int
of the number of field goals the player attempted from fifty or more yards out.
- property fifty_plus_yard_field_goals_made
Returns an
int
of the number of field goals the player made from fifty or more yards out.
- property first_downs_receiving
Returns an
int
of the number of first downs the player has gained from pass attempts.
- property first_downs_rushing
Returns an
int
of the number of first downs the player has gained from rush attempts.
- property fourth_quarter_comebacks
Returns an
int
of the number of times the player has lead a team to victory or a tie as a quarterback while the team trailed at the beginning of the fourth quarter by scoring at the end of a drive.
- property fourty_to_fourty_nine_yard_field_goal_attempts
Returns an
int
of the number of field goals the player attempted from fourty to fourty-nine yards out.
- property fourty_to_fourty_nine_yard_field_goals_made
Returns an
int
of the number of field goals the player made from fourty to fourty-nine yards out.
- property fumbles
Returns an
int
of the number of times the player fumbled the ball.
- property fumbles_forced
Returns an
int
of the number of times the player forced a fumble.
- property fumbles_recovered
Returns an
int
of the number of fumbles the player has recovered.
- property fumbles_recovered_for_touchdown
Returns an
int
of the number of touchdowns the player has scored after recovering a fumble.
- property game_winning_drives
Returns an
int
of the number of times the player has lead a drive that resulted in a score in the fourth quarter while the team was trailing.
- property games
Returns an
int
of the number of games the player participated in.
- property games_started
Returns an
int
of the number of games the player started.
- property height
Returns a
string
of the player’s height in the format “feet-inches”.
- property interception_percentage
Returns a
float
of the percentage of passes the player throws that are intercepted. Percentage ranges from 0-100.
- property interception_percentage_index
Returns an
int
comparing players by the percentage of their passes that are intercepted where 100 denotes an average player in this category and higher numbers are better.
- property interceptions
Returns an
int
of the number of times the player intercepted a pass.
- property interceptions_returned_for_touchdown
Returns an
int
of the number of touchdowns the player has scored after intercepting a pass. Commonly referred to as a ‘Pick-6’.
- property interceptions_thrown
Returns an
int
of the number of interceptions the player has thrown.
- property kickoff_return_touchdown
Returns an
int
of the number of kickoffs the player returned for a touchdown.
- property kickoff_return_yards
Returns an
int
of the amount of yards the player gained while returning a kickoff.
- property kickoff_returns
Returns an
int
of the number of kickoffs the player returned.
- property less_than_nineteen_yards_field_goal_attempts
Returns an
int
of the number of field goals the player attempted from nineteen or fewer yards out.
- property less_than_nineteen_yards_field_goals_made
Returns an
int
of the number of field goals the player made from nineteen or fewer yards out.
- property longest_field_goal_made
Returns an
int
of the longest field goal the player made.
- property longest_interception_return
Returns an
int
of the most yards the player has returned after intercepting a pass.
- property longest_kickoff_return
Returns an
int
of the highest number of yards the player has gained while returning a kickoff.
- property longest_pass
Returns an
int
of the longest completed pass the player threw.
- property longest_punt
Returns an
int
of the longest punt the player has kicked.
- property longest_punt_return
Returns an
int
of the highest number of yards the player has gained while returning a punt.
- property longest_reception
Returns an
int
of the highest number of yards the player gained as a result of a single reception.
- property longest_rush
Returns an
int
of the highest number of yards the player gained during a single rushing attempt.
- property net_yards_per_attempt_index
Returns an
int
comparing players by the net average yards gained per attempt where 100 denotes an average player in this category and higher numbers are better.
- property net_yards_per_pass_attempt
Returns a
float
of the net yards gained per pass attempt, equal to (pass_yards - sack_yards) / (pass_attempts + times_sacked).
- property passer_rating_index
Returns an
int
comparing players by their quarterback rating where 100 denotes an average player in this category and higher numbers are better.
- property passes_defended
Returns an
int
of the number of passes the player has defended as a defensive player.
- property passing_completion
Returns a
float
of the percentage of passes that were caught by a receiver. Percentage ranges from 0-100.
- property passing_touchdown_percentage
Returns a
float
of the percentage of total passes that are touchdowns. Percentage ranges from 0-100.
- property passing_touchdowns
Returns an
int
of the number of touchdowns passes the player has thrown.
- property passing_yards
Returns an
int
of the number of yards receivers have gained as a result of the player’s passes.
- property passing_yards_per_attempt
Returns a
float
of the number of yards gained per passing attempt.
- property position
Returns a
string
of the player’s primary position.
- property punt_return_touchdown
Returns an
int
of the number of punts the player returned for a touchdown.
- property punt_return_yards
Returns an
int
of the amount of yards the player gained while returning a punt.
- property punt_returns
Returns an
int
of the number of times a player returned a punt.
- property punts
Returns an
int
of the number of times the player punted the ball.
- property qb_record
Returns a
string
of the player’s quarterback record as a starter in the format ‘W-L-T’.
- property quarterback_rating
Returns a
float
of the player’s quarterback rating.
- property receiving_broken_tackles
Returns an
int
of the number of tackles the player has broken after catching a pass.
- property receiving_touchdowns
Returns an
int
of the number of touchdowns the player scored after receiving a pass.
- property receiving_yards
Returns an
int
of the number of receiving yards the player gained.
- property receiving_yards_after_catch
Returns an
int
of the total number of yards the player has gained after catching a pass.
- property receiving_yards_after_catch_per_reception
Returns a
float
of the number of yards the player gains on average after catching a pass.
- property receiving_yards_before_catch
Returns an
int
of the total number of yards the player has gained prior to catching a pass.
- property receiving_yards_before_catch_per_reception
Returns a
float
of the number of yards the player gains on average prior to catching a pass.
- property receiving_yards_per_game
Returns a
float
of the acerage number of receiving yards the player gains per game.
- property receiving_yards_per_reception
Returns a
float
of the average number of yards the player gained per reception.
- property receptions
Returns an
int
of the number of receptions the player made.
- property receptions_per_broken_tackle
Returns a
float
of the number of receptions the player made per broken tackle.
- property receptions_per_game
Returns a
float
of the average number of receptions the player makes per game.
- property rush_attempts
Returns an
int
of the number of rushing plays the player attempted.
- property rush_attempts_per_broken_tackle
Returns a
float
of the number of tackles the player broke per rush.
- property rush_attempts_per_game
Returns a
float
of the average number of rushing attempts the player made per game.
- property rush_broken_tackles
Returns an
int
of the number of tackles the player broke while rushing.
- property rush_touchdowns
Returns an
int
of the number of rushing touchdowns the player scored.
- property rush_yards
Returns an
int
of the number of rushing yards the player gained.
- property rush_yards_after_contact
Returns an
int
of the total number of yards the player has gained after receiving contact on a rush.
- property rush_yards_after_contact_per_attempt
Returns a
float
of the number of yards the player gains on average after receiving contact on a rush.
- property rush_yards_before_contact
Returns an
int
of the total number of yards the player has gained prior to receiving contact on a rush.
- property rush_yards_before_contact_per_attempt
Returns a
float
of the number of yards the player gains on average prior to receiving contact on a rush.
- property rush_yards_per_attempt
Returns a
float
of the average number of yards gained per rushing attempt.
- property rush_yards_per_game
Returns a
float
of the average number of rushing yards gained per game.
- property rushing_and_receiving_touchdowns
Returns an
int
of the combined number of rushing and receiving touchdowns the player scored.
- property sack_percentage
Returns a
float
of the percentage of times sacked during a passing attempt, equal to times_sacked / (pass_attempts + times_sacked). Percentage ranges from 0-100.
- property sack_percentage_index
Returns an
int
comparing players by the percentage of plays that end in the player being sacked where 100 denotes an average player in this category and higher numbers are better.
- property sacks
Returns a
float
of the number of times the player sacked a quarterback.
- property safeties
Returns an
int
of the number of safeties the player has scored.
- property season
Returns a
string
of the season in the format ‘YYYY’, such as ‘2017’. If no season was requested, the career stats will be returned for the player and the season will default to ‘Career’.
- property tackles
Returns an
int
of the number of tackles the player made.
- property team_abbreviation
Returns a
string
of the team’s abbreviation, such as ‘NOR’ for the New Orleans Saints.
- property thirty_to_thirty_nine_yard_field_goal_attempts
Returns an
int
of the number of field goals the player attempted from thirty to thirty-nine yards out.
- property thirty_to_thirty_nine_yard_field_goals_made
Returns an
int
of the number of field goals the player made from thirty to thirty-nine yards out.
- property times_pass_target
Returns an
int
of the number of times the player was the target of a pass.
- property times_sacked
Returns an
int
of the number of times the player was sacked as a quarterback.
- property total_punt_yards
Returns an
int
of the total number of yards the player has punted the ball.
- property touchdown_percentage_index
Returns an
int
comparing players by the percentage of their passes that result in a touchdown where 100 denotes an average player in this category and higher numbers are better.
- property touches
Returns an
int
of the combined number of rushing attempts and receptions the player had.
- property twenty_to_twenty_nine_yard_field_goal_attempts
Returns an
int
of the number of field goals the player attempted from twenty to twenty-nine yards out.
- property twenty_to_twenty_nine_yard_field_goals_made
Returns an
int
of the number of field goals the player made from twenty to twenty-nine yards out.
- property weight
Returns an
int
of the player’s weight in pounds.
- property yards_from_scrimmage
Returns an
int
of the total number of yards gained from scrimmage for both rushing and receiving.
- property yards_lost_to_sacks
Returns an
int
of the number of yards lost as a result of sacks.
- property yards_per_attempt_index
Returns an
int
comparing players by the average number of yards gained per attempt where 100 denotes an average player in this category and higher numbers are better.
- property yards_per_completed_pass
Returns a
float
of the number of yards gained per completed pass.
- property yards_per_game_played
Returns a
float
of the number of passing yards gained per gamed.
- property yards_per_kickoff_return
Returns a
float
of the average number of yards the player returned per kickoff.
- property yards_per_punt_return
Returns a
float
of the average number of yards the player returned per punt.
- property yards_per_touch
Returns a
float
of the average number of yards gained per rushing attempt and/or reception.
- property yards_recovered_from_fumble
Returns an
int
of the number of yards the player gained after recovering a fumble.
- property yards_returned_from_interception
Returns an
int
of the number of yards the player returned after intercepting a pass.
- class sportsipy.nfl.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 ‘NOR’ for the New Orleans Saints.
year (string (optional)) – The 4-digit year to pull the roster from, such as ‘2017’. 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 ‘Sean Payton’.
- 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.nfl.schedule import Schedule
houston_schedule = Schedule('HTX')
for game in houston_schedule:
print(game.date) # Prints the date the game was played
print(game.result) # Prints whether the team won or lost
# Creates an instance of the Boxscore class for the game.
boxscore = game.boxscore
- class sportsipy.nfl.schedule.Game(game_data, game_type, 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’s information.
game_type (string) – A constant to denote whether a game took place in the regular season or in the playoffs.
year (string) – The year as a 4-digit string. Note that this is the year that the bulk of the season took place. For example the Super Bowl for the 2017 season took place in early Feburary 2018, but 2017 should be passed as that was the year the bulk of the season was played in.
- property boxscore
Returns an instance of the Boxscore class containing more detailed stats on the game.
- property boxscore_index
Returns a
string
of the URI for a boxscore which can be used to access or index a game.
- property dataframe
Returns a pandas DataFrame containing all other class properties and values. The index for the DataFrame is the boxscore string.
- property dataframe_extended
Returns a pandas DataFrame representing the Boxscore class for the game. This property provides much richer context for the selected game, but takes longer to process compared to the lighter ‘dataframe’ property. The index for the DataFrame is the boxscore string.
- property date
Returns a
string
of the month and day the game was played, such as ‘September 7’.
- property datetime
Returns a datetime object representing the date the game was played.
- property day
Returns a
string
of the day of the week the game was played as a 3-letter abbreviation, such as ‘Sun’ for Sunday.
- property extra_points_attempted
Returns an
int
of the number of times the team attempted to convert an extra point after scoring a touchdown.
- property extra_points_made
Returns an
int
of the number of extra points the team successfully converted after scoring a touchdown.
- property field_goals_attempted
Returns an
int
of the total number of times the team attempted a field goal.
- property field_goals_made
Returns an
int
of the total number of field goals the team scored.
- property fourth_down_attempts
Returns an
int
of the total number of fourth downs the team attempted to convert.
- property fourth_down_conversions
Returns an
int
of the number of fourth downs the team successfully converted.
- property interceptions
Returns an
int
of the number of interceptions the team threw.
- property location
Returns a
string
constant indicating whether the game was played at home, away, or a neutral site, such as the Super Bowl.
- property opponent_abbr
Returns a
string
of the opponent’s 3-letter abbreviation, such as ‘NWE’ for the New England Patriots.
- property opponent_name
Returns a
string
of the opponent’s full name, such as the ‘New England Patriots’.
- property overtime
Returns a
boolean
value that evaluates to True if the game when to overtime and False if it ended in regulation.
- property pass_attempts
Returns an
int
of the number of passes the team attempted during the game.
- property pass_completion_rate
Returns a
float
of the percentage of passes that were completed by the team. Percentage ranges from 0-100.
- property pass_completions
Returns an
int
of the number of completed passed by the team.
- property pass_touchdowns
Returns an
int
of the number of touchdowns the team scored as a result of passing plays.
- property pass_yards
Returns an
int
of the number of yards the team gained as a result of passing plays.
- property pass_yards_per_attempt
Returns a
float
of the average number of yards gained per passing play.
- property points_allowed
Returns an
int
of the number of points allowed by the team.
- property points_scored
Returns an
int
of the number of points scored by the team.
- property punt_yards
Returns an
int
of the total number of yards the team punted the ball.
- property punts
Returns an
int
of the number of times the team punted the ball.
- property quarterback_rating
Returns a
float
of the quarterback’s rating for the game.
- property result
Returns a
string
constant indicating whether the team won or lost the game. NFL games may end in a tie if the score is even at the end of OT. If a game has no result (canceled, yet to be played, etc.) returnNone
.
- property rush_attempts
Returns an
int
of the total number of times the team attempted a rushing play.
- property rush_touchdowns
Returns an
int
of the number of touchdowns the team scored as a result of rushing plays.
- property rush_yards
Returns an
int
of the total number of yards the team gain as a result of rushing plays.
- property rush_yards_per_attempt
Returns a
float
of the average number of yards gained per rushing play.
- property third_down_attempts
Returns an
int
of the total number of third downs the team attempted to convert.
- property third_down_conversions
Returns an
int
of the number of third downs the team successfully converted.
- property time_of_possession
Returns a
string
of the total time the team spent with the ball. Time is in the format ‘MM:SS’.
- property times_sacked
Returns an
int
of the number of times the quarterback was sacked by the opponent.
- property type
Returns a
string
constant indicating whether the game is a regular season or playoff matchup.
- property week
Returns an
int
of the week number in the season, such as 1 for the first week of the regular season.
- property yards_lost_from_sacks
Returns an
int
of the total number of yards lost as a result of a sack.
- class sportsipy.nfl.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 ‘NWE’ for the New England Patriots.
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 MLB teams including the team name and abbreviation, the number of games they won during the season, the average margin of victory, and much more.
from sportsipy.nfl.teams import Teams
teams = Teams()
for team in teams:
print(team.name) # Prints the team's name
# Prints the team's average margin of victory
print(team.margin_of_victory)
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.nfl.teams import Team
kansas = Team('KAN')
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.nfl.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.nfl.teams import Teams
for team in Teams():
roster = team.roster # Gets each team's roster
for player in roster.players:
print(player.name) # Prints each players name on the roster
- class sportsipy.nfl.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.
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 team’s abbreviation, such as ‘KAN’ for the Kansas City Chiefs.
- 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 ‘KAN’.
- property defensive_simple_rating_system
Returns a
float
of the team’s defensive strength according to the simple rating system. An average team is denoted with 0.0 and a negative score is a comparatively weaker team.
- property first_downs
Returns an
int
of the total number of first downs the team achieved during the season.
- property first_downs_from_penalties
Returns an
int
of the total number of first downs conceded as a result of penalties called on the team.
- property fumbles
Returns an
int
of the total number of times the team fumbled the ball during the season.
- property games_played
Returns an
int
of the number of games played during the season.
- property interceptions
Returns an
int
of the total number of interceptions the team has thrown.
- property losses
Returns an
int
of the number of games the team lost during the season.
- property margin_of_victory
Returns a
float
of the average margin of victory per game.
- property name
Returns a
string
of the team’s full name, such as ‘Kansas City Chiefs’.
- property offensive_simple_rating_system
Returns a
float
of the team’s offensive strength according to the simple rating system. An average team is denoted with 0.0 and a negative score is a comparatively weaker team.
- property pass_attempts
Returns an
int
of the total number of passes that were attempted.
- property pass_completions
Returns an
int
of the total number of passes that were completed.
- property pass_first_downs
Returns an
int
of the number of first downs the team gained from passing plays.
- property pass_net_yards_per_attempt
Returns a
float
of the net yards gained per passing play including sacks.
- property pass_touchdowns
Returns an
int
of the total number of touchdowns the team has scored from passing.
- property pass_yards
Returns an
int
of the total number of yards the team gained from passing.
- property penalties
Returns an
int
of the total number of penalties called on the team during the season.
- property percent_drives_with_points
Returns a
float
of the percentage of drives that result in points for the offense. Percentage ranges from 0-100.
- property percent_drives_with_turnovers
Returns a
float
of the percentage of drives that result in an offensive turnover. Percentage ranges from 0-100.
- property plays
Returns an
int
of the total number of offensive plays the team has made during the season.
- property points_against
Returns an
int
of the total number of points allowed during the season.
- property points_contributed_by_offense
Returns a
float
of the number of expected points contributed by the offense.
- property points_difference
Returns an
int
of the difference between the number of points scored and allowed during the season.
- property points_for
Returns an
int
of the total number of points scored during the season.
- property post_season_result
Returns a
string constant
denoting how far the team made it in the post-season.
- property rank
Returns an
int
of the team’s rank based on the number of points they scored during 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 rush_attempts
Returns an
int
of the total number of rushing plays that were attempted.
- property rush_first_downs
Returns an
int
of the total number of first downs gained from rushing plays.
- property rush_touchdowns
Returns an
int
of the total number of touchdowns from rushing plays.
- property rush_yards
Returns an
int
of the total number of yards that were gained from rushing plays.
- property rush_yards_per_attempt
Returns a
float
of the average number of yards gained per rushing play.
- property schedule
Returns an instance of the Schedule class containing the team’s complete schedule for the season.
- property simple_rating_system
Returns a
float
of the team’s relative strength based on average margin of victory plus strength of schedule. An average team is denoted with 0.0 and a negative score is a comparatively weaker team.
- property strength_of_schedule
Returns a
float
of the team’s strength of schedule. An average difficulty schedule is denoted with a 0.0 and a negative number is comparatively easier than average.
- property turnovers
Returns an
int
of the total number of turnovers the team committed during the season.
- property win_percentage
Returns a
float
of the number of wins divided by the number of games played. Percentage ranges from 0-1.
- property wins
Returns an
int
of the number of games the team won during the season.
- property yards
Returns an
int
of the total number of yards the team has gained during the season.
- property yards_from_penalties
Returns an
int
of the total number of yards surrendered as a result of penalties called on the team.
- property yards_per_play
Returns a
float
of the average number of yards gained per play during the season.
- class sportsipy.nfl.teams.Teams(year=None, season_page=None)[source]
Bases:
object
A list of all NFL teams and their stats in a given year.
Finds and retrieves a list of all NFL teams from www.pro-football-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.