sportsreference.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.
sportsreference.nfl.boxscore module¶
The Boxscore module can be used to grab information from a specific game.
Metrics range from number of points scored to the number of 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 sportsreference.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 datetime import datetime
from sportsreference.nfl.boxscore import Boxscores
games_today = Boxscores(datetime.today())
print(games_today.games) # Prints a dictionary of all matchups for today
-
class
sportsreference.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’. -
attendance
¶ Returns an
int
of the game’s listed attendance.
-
away_first_downs
¶ Returns an
int
of the number of first downs the away team gained.
-
away_fourth_down_attempts
¶ Returns an
int
of the number of fourth down plays the away team attempted to convert.
-
away_fourth_down_conversions
¶ Returns an
int
of the number of fourth down plays the away team successfully converted.
-
away_fumbles
¶ Returns an
int
of the number of times the away team fumbled the ball.
-
away_fumbles_lost
¶ Returns an
int
of the number of times the away team turned the ball over as the result of a fumble.
-
away_interceptions
¶ Returns an
int
of the number of interceptions the away team threw.
-
away_net_pass_yards
¶ Returns an
int
of the net pass yards gained by the away team.
-
away_pass_attempts
¶ Returns an
int
of the number of passes that were thrown by the away team.
-
away_pass_completions
¶ Returns an
int
of the number of completed passes the away team made.
-
away_pass_touchdowns
¶ Returns an
int
of the number of passing touchdowns the away team scored.
-
away_pass_yards
¶ Returns an
int
of the number of passing yards the away team gained.
-
away_penalties
¶ Returns an
int
of the number of penalties called on the away team.
-
away_points
¶ Returns an
int
of the number of points the away team scored.
-
away_rush_attempts
¶ Returns an
int
of the number of rushing plays the away team made.
-
away_rush_touchdowns
¶ Returns an
int
of the number of rushing touchdowns the away team scored.
-
away_rush_yards
¶ Returns an
int
of the number of rushing yards the away team gained.
-
away_third_down_attempts
¶ Returns an
int
of the number of third down plays the away team attempted to convert.
-
away_third_down_conversions
¶ Returns an
int
of the number of third down plays the away team successfully converted.
-
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’.
-
away_times_sacked
¶ Returns an
int
of the number of times the away team was sacked.
-
away_total_yards
¶ Returns an
int
of the total number of yards the away team gained.
-
away_turnovers
¶ Returns an
int
of the number of times the away team turned the ball over.
-
away_yards_from_penalties
¶ Returns an
int
of the number of yards gifted as a result of penalties called on the away team.
-
away_yards_lost_from_sacks
¶ Returns an
int
of the number of yards the away team lost as the result of a sack.
-
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’.
-
date
¶ Returns a
string
of the date the game took place.
-
duration
¶ Returns a
string
of the game’s duration in the format ‘H – MM’.
-
home_first_downs
¶ Returns an
int
of the number of first downs the home team gained.
-
home_fourth_down_attempts
¶ Returns an
int
of the number of fourth down plays the home team attempted to convert.
-
home_fourth_down_conversions
¶ Returns an
int
of the number of fourth down plays the home team successfully converted.
-
home_fumbles
¶ Returns an
int
of the number of times the home team fumbled the ball.
-
home_fumbles_lost
¶ Returns an
int
of the number of times the home team turned the ball over as the result of a fumble.
-
home_interceptions
¶ Returns an
int
of the number of interceptions the home team threw.
-
home_net_pass_yards
¶ Returns an
int
of the net pass yards gained by the home team.
-
home_pass_attempts
¶ Returns an
int
of the number of passes that were thrown by the home team.
-
home_pass_completions
¶ Returns an
int
of the number of completed passes the home team made.
-
home_pass_touchdowns
¶ Returns an
int
of the number of passing touchdowns the home team scored.
-
home_pass_yards
¶ Returns an
int
of the number of passing yards the home team gained.
-
home_penalties
¶ Returns an
int
of the number of penalties called on the home team.
-
home_points
¶ Returns an
int
of the number of points the home team scored.
-
home_rush_attempts
¶ Returns an
int
of the number of rushing plays the home team made.
-
home_rush_touchdowns
¶ Returns an
int
of the number of rushing touchdowns the home team scored.
-
home_rush_yards
¶ Returns an
int
of the number of rushing yards the home team gained.
-
home_third_down_attempts
¶ Returns an
int
of the number of third down plays the home team attempted to convert.
-
home_third_down_conversions
¶ Returns an
int
of the number of third down plays the home team successfully converted.
-
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’.
-
home_times_sacked
¶ Returns an
int
of the number of times the home team was sacked.
-
home_total_yards
¶ Returns an
int
of the total number of yards the home team gained.
-
home_turnovers
¶ Returns an
int
of the number of times the home team turned the ball over.
-
home_yards_from_penalties
¶ Returns an
int
of the number of yards gifted as a result of penalties called on the home team.
-
home_yards_lost_from_sacks
¶ Returns an
int
of the number of yards the home team lost as the result of a sack.
-
losing_abbr
¶ Returns a
string
of the losing team’s abbreviation, such as ‘KAN’ for the Kansas City Chiefs.
-
losing_name
¶ Returns a
string
of the losing team’s name, such as ‘Kansas City Chiefs’.
-
stadium
¶ Returns a
string
of the name of the stadium where the game was played.
-
time
¶ Returns a
string
of the time the game started.
-
winner
¶ Returns a
string
constant indicating whether the home or away team won.
-
winning_abbr
¶ Returns a
string
of the winning team’s abbreviation, such as ‘NWE’ for the New England Patriots.
-
winning_name
¶ Returns a
string
of the winning team’s name, such as ‘New England Patriots’.
-
-
class
sportsreference.nfl.boxscore.
Boxscores
(week, year)[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.
-
games
¶ Returns a
dictionary
object representing all of the games played on the requested day. Dictionary is in the following format:{'boxscores' : [ {'home_name': Name of the home team, such as '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 'HOU' (`str`), 'boxscore': String representing the boxscore URI, such as 'SLN/SLN201807280' (`str`)}, { ... }, ... ] }
If no games were played during the requested day, the list for [‘boxscores’] will be empty.
sportsreference.nfl.schedule module¶
The Schedule module can be used to iterate over all games in a team’s schedule
to get game information such as the date, score, result, and more. Each game
also has a link to the Boxscore
class which has much more detailed
information on the game metrics.
from sportsreference.nfl.schedule import Schedule
houston_schedule = Schedule('HOU')
for game in houston_schedule:
print(game.date) # Prints the date the game was played
print(game.result) # Prints whether the team won or lost
# Creates an instance of the Boxscore class for the game.
boxscore = game.boxscore
-
class
sportsreference.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.
-
boxscore
¶ Returns an instance of the Boxscore class containing more detailed stats on the game.
-
dataframe
¶ Returns a pandas DataFrame containing all other class properties and values. The index for the DataFrame is the boxscore string.
-
dataframe_extended
¶ Returns a pandas DataFrame representing the Boxscore class for the game. This property provides much richer context for the selected game, but takes longer to process compared to the lighter ‘dataframe’ property. The index for the DataFrame is the boxscore string.
-
date
¶ Returns a
string
of the month and day the game was played, such as ‘September 7’.
-
datetime
¶ Returns a datetime object representing the date the game was played.
-
day
¶ Returns a
string
of the day of the week the game was played as a 3-letter abbreviation, such as ‘Sun’ for Sunday.
-
extra_points_attempted
¶ Returns an
int
of the number of times the team attempted to convert an extra point after scoring a touchdown.
-
extra_points_made
¶ Returns an
int
of the number of extra points the team successfully converted after scoring a touchdown.
-
field_goals_attempted
¶ Returns an
int
of the total number of times the team attempted a field goal.
-
field_goals_made
¶ Returns an
int
of the total number of field goals the team scored.
-
fourth_down_attempts
¶ Returns an
int
of the total number of fourth downs the team attempted to convert.
-
fourth_down_conversions
¶ Returns an
int
of the number of fourth downs the team successfully converted.
-
interceptions
¶ Returns an
int
of the number of interceptions the team threw.
-
location
¶ Returns a
string
constant indicating whether the game was played at home, away, or a neutral site, such as the Super Bowl.
-
opponent_abbr
¶ Returns a
string
of the opponent’s 3-letter abbreviation, such as ‘NWE’ for the New England Patriots.
-
opponent_name
¶ Returns a
string
of the opponent’s full name, such as the ‘New England Patriots’.
-
overtime
¶ Returns a boolean value that evaluates to True if the game when to overtime and False if it ended in regulation.
-
pass_attempts
¶ Returns an
int
of the number of passes the team attempted during the game.
-
pass_completion_rate
¶ Returns a
float
of the percentage of passes that were completed by the team. Percentage ranges from 0-100.
-
pass_completions
¶ Returns an
int
of the number of completed passed by the team.
-
pass_touchdowns
¶ Returns an
int
of the number of touchdowns the team scored as a result of passing plays.
-
pass_yards
¶ Returns an
int
of the number of yards the team gained as a result of passing plays.
-
pass_yards_per_attempt
¶ Returns a
float
of the average number of yards gained per passing play.
-
points_allowed
¶ Returns an
int
of the number of points allowed by the team.
-
points_scored
¶ Returns an
int
of the number of points scored by the team.
-
punt_yards
¶ Returns an
int
of the total number of yards the team punted the ball.
-
punts
¶ Returns an
int
of the number of times the team punted the ball.
-
quarterback_rating
¶ Returns a
float
of the quarterback’s rating for the game.
-
result
¶ Returns a
string
constant indicating whether the team won or lost the game.
-
rush_attempts
¶ Returns an
int
of the total number of times the team attempted a rushing play.
-
rush_touchdowns
¶ Returns an
int
of the number of touchdowns the team scored as a result of rushing plays.
-
rush_yards
¶ Returns an
int
of the total number of yards the team gain as a result of rushing plays.
-
rush_yards_per_attempt
¶ Returns a
float
of the average number of yards gained per rushing play.
-
third_down_attempts
¶ Returns an
int
of the total number of third downs the team attempted to convert.
-
third_down_conversions
¶ Returns an
int
of the number of third downs the team successfully converted.
-
time_of_possession
¶ Returns a
string
of the total time the team spent with the ball. Time is in the format ‘MM:SS’.
-
times_sacked
¶ Returns an
int
of the number of times the quarterback was sacked by the opponent.
-
type
¶ Returns a
string
constant indicating whether the game is a regular season or playoff matchup.
-
week
¶ Returns an
int
of the week number in the season, such as 1 for the first week of the regular season.
-
yards_lost_from_sacks
¶ Returns an
int
of the total number of yards lost as a result of a sack.
-
class
sportsreference.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.
-
dataframe
¶ Returns a pandas DataFrame where each row is a representation of the Game class. Rows are indexed by the boxscore string.
-
dataframe_extended
¶ Returns a pandas DataFrame where each row is a representation of the Boxscore class for every game in the schedule. Rows are indexed by the boxscore string. This property provides much richer context for the selected game, but takes longer to process compared to the lighter ‘dataframe’ property.
sportsreference.nfl.teams module¶
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 sportsreference.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)
Each Team instance contains a link to the Schedule
class which enables easy
iteration over all games for a particular team. A Pandas DataFrame can also be
queried to easily grab all stats for all games.
from sportsreference.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
-
class
sportsreference.nfl.teams.
Team
(team_data, rank, year=None)[source]¶ Bases:
object
An object containing all of a team’s season information.
Finds and parses all team stat information and identifiers, such as rank, name, and abbreviation, and sets them as properties which can be directly read from for easy reference.
Parameters: - team_data (string) – A string containing all of the rows of stats for a given team. If multiple tables are being referenced, this will be comprised of multiple rows in a single string.
- rank (int) – A team’s position in the league based on the number of points they obtained during the season.
- year (string (optional)) – The requested year to pull stats from.
-
abbreviation
¶ Returns a
string
of team’s abbreviation, such as ‘KAN’ for the Kansas City Chiefs.
-
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’.
-
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.
-
first_downs
¶ Returns an
int
of the total number of first downs the team achieved during the season.
-
first_downs_from_penalties
¶ Returns an
int
of the total number of first downs conceded as a result of penalties called on the team.
-
fumbles
¶ Returns an
int
of the total number of times the team fumbled the ball during the season.
-
games_played
¶ Returns an
int
of the number of games played during the season.
-
interceptions
¶ Returns an
int
of the total number of interceptions the team has thrown.
-
losses
¶ Returns an
int
of the number of games the team lost during the season.
-
margin_of_victory
¶ Returns a
float
of the average margin of victory per game.
-
name
¶ Returns a
string
of the team’s full name, such as ‘Kansas City Chiefs’.
-
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.
-
pass_attempts
¶ Returns an
int
of the total number of passes that were attempted.
-
pass_completions
¶ Returns an
int
of the total number of passes that were completed.
-
pass_first_downs
¶ Returns an
int
of the number of first downs the team gained from passing plays.
-
pass_net_yards_per_attempt
¶ Returns a
float
of the net yards gained per passing play including sacks.
-
pass_touchdowns
¶ Returns an
int
of the total number of touchdowns the team has scored from passing.
-
pass_yards
¶ Returns an
int
of the total number of yards the team gained from passing.
-
penalties
¶ Returns an
int
of the total number of penalties called on the team during the season.
-
percent_drives_with_points
¶ Returns a
float
of the percentage of drives that result in points for the offense. Percentage ranges from 0-100.
-
percent_drives_with_turnovers
¶ Returns a
float
of the percentage of drives that result in an offensive turnover. Percentage ranges from 0-100.
-
plays
¶ Returns an
int
of the total number of offensive plays the team has made during the season.
-
points_against
¶ Returns an
int
of the total number of points allowed during the season.
-
points_contributed_by_offense
¶ Returns a
float
of the number of expected points contributed by the offense.
-
points_difference
¶ Returns an
int
of the difference between the number of points scored and allowed during the season.
-
points_for
¶ Returns an
int
of the total number of points scored during the season.
-
rank
¶ Returns an
int
of the team’s rank based on the number of points they scored during the season.
-
rush_attempts
¶ Returns an
int
of the total number of rushing plays that were attempted.
-
rush_first_downs
¶ Returns an
int
of the total number of first downs gained from rushing plays.
-
rush_touchdowns
¶ Returns an
int
of the total number of touchdowns from rushing plays.
-
rush_yards
¶ Returns an
int
of the total number of yards that were gained from rushing plays.
-
rush_yards_per_attempt
¶ Returns a
float
of the average number of yards gained per rushing play.
-
schedule
¶ Returns an instance of the Schedule class containing the team’s complete schedule for the season.
-
simple_rating_system
¶ Returns a
float
of the team’s 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.
-
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.
-
turnovers
¶ Returns an
int
of the total number of turnovers the team committed during the season.
-
win_percentage
¶ Returns a
float
of the number of wins divided by the number of games played. Percentage ranges from 0-1.
-
wins
¶ Returns an
int
of the number of games the team won during the season.
-
yards
¶ Returns an
int
of the total number of yards the team has gained during the season.
-
yards_from_penalties
¶ Returns an
int
of the total number of yards surrendered as a result of penalties called on the team.
-
yards_per_play
¶ Returns a
float
of the average number of yards gained per play during the season.
-
class
sportsreference.nfl.teams.
Teams
(year=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. -
dataframes
¶ Returns a pandas DataFrame where each row is a representation of the Team class. Rows are indexed by the team abbreviation.
-