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 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.boxscore.nfl_int_property_sub_index(func)[source]

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 sportsreference.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 sportsreference.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 sportsreference.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 sportsreference.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 sportsreference.nfl.roster.Player(player_id)[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.
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.

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

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.

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.

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.

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.

assists_on_tackles

Returns an int of the number of assist the player made on tackles.

attempted_passes

Returns an int of the number of passes the player attempted.

birth_date

Returns a datetime object of the day and year the player was born.

blocked_punts

Returns an int of the number of the player’s punts that have been blocked.

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.

completed_passes

Returns an int of the number of completed passes the player threw.

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.

dataframe

Returns a pandas DataFrame containing all other relevant class properties and values where each index is a different season plus the career stats.

espn_qbr

Returns a float of the player’s Total Quarterback Rating according to ESPN.

extra_point_percentage

Returns a float of the percentage of extra points the player made. Percentage ranges from 0-100.

extra_points_attempted

Returns an int of the number of extra points the player attempted.

extra_points_made

Returns an int of the number of extra points the player made.

field_goal_percentage

Returns a float of the percentage of field goals the player made. Percentage ranges from 0-100.

field_goals_attempted

Returns an int of the total number of field goals the player attempted from any distance.

field_goals_made

Returns an int of the total number of field goals the player made from any distance.

fifty_plus_yard_field_goal_attempts

Returns an int of the number of field goals the player attempted from fifty or more yards out.

fifty_plus_yard_field_goals_made

Returns an int of the number of field goals the player made from fifty or more yards out.

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.

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.

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.

fumbles

Returns an int of the number of times the player fumbled the ball.

fumbles_forced

Returns an int of the number of times the player forced a fumble.

fumbles_recovered

Returns an int of the number of fumbles the player has recovered.

fumbles_recovered_for_touchdown

Returns an int of the number of touchdowns the player has scored after recovering a fumble.

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.

games

Returns an int of the number of games the player participated in.

games_started

Returns an int of the number of games the player started.

height

Returns a string of the player’s height in the format “feet-inches”.

interception_percentage

Returns a float of the percentage of passes the player throws that are intercepted. Percentage ranges from 0-100.

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.

interceptions

Returns an int of the number of times the player intercepted a pass.

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

interceptions_thrown

Returns an int of the number of interceptions the player has thrown.

kickoff_return_touchdown

Returns an int of the number of kickoffs the player returned for a touchdown.

kickoff_return_yards

Returns an int of the amount of yards the player gained while returning a kickoff.

kickoff_returns

Returns an int of the number of kickoffs the player returned.

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.

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.

longest_field_goal_made

Returns an int of the longest field goal the player made.

longest_interception_return

Returns an int of the most yards the player has returned after intercepting a pass.

longest_kickoff_return

Returns an int of the highest number of yards the player has gained while returning a kickoff.

longest_pass

Returns an int of the longest completed pass the player threw.

longest_punt

Returns an int of the longest punt the player has kicked.

longest_punt_return

Returns an int of the highest number of yards the player has gained while returning a punt.

longest_reception

Returns an int of the highest number of yards the player gained as a result of a single reception.

longest_rush

Returns an int of the highest number of yards the player gained during a single rushing attempt.

name

Returns a string of the player’s name, such as ‘Drew Brees’.

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.

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

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.

passes_defended

Returns an int of the number of passes the player has defended as a defensive player.

passing_completion

Returns a float of the percentage of passes that were caught by a receiver. Percentage ranges from 0-100.

passing_touchdown_percentage

Returns a float of the percentage of total passes that are touchdowns. Percentage ranges from 0-100.

passing_touchdowns

Returns an int of the number of touchdowns passes the player has thrown.

passing_yards

Returns an int of the number of yards receivers have gained as a result of the player’s passes.

passing_yards_per_attempt

Returns a float of the number of yards gained per passing attempt.

player_id

Returns a string of the player’s ID on pro-football-reference, such as ‘BreeDr00’ for Drew Brees.

position

Returns a string of the player’s primary position.

punt_return_touchdown

Returns an int of the number of punts the player returned for a touchdown.

punt_return_yards

Returns an int of the amount of yards the player gained while returning a punt.

punt_returns

Returns an int of the number of times a player returned a punt.

punts

Returns an int of the number of times the player punted the ball.

qb_record

Returns a string of the player’s quarterback record as a starter in the format ‘W-L-T’.

quarterback_rating

Returns a float of the player’s quarterback rating.

receiving_touchdowns

Returns an int of the number of touchdowns the player scored after receiving a pass.

receiving_yards

Returns an int of the number of receiving yards the player gained.

receiving_yards_per_game

Returns a float of the acerage number of receiving yards the player gains per game.

receiving_yards_per_reception

Returns a float of the average number of yards the player gained per reception.

receptions

Returns an int of the number of receptions the player made.

receptions_per_game

Returns a float of the average number of receptions the player makes per game.

rush_attempts

Returns an int of the number of rushing plays the player attempted.

rush_attempts_per_game

Returns a float of the average number of rushing attempts the player made per game.

rush_touchdowns

Returns an int of the number of rushing touchdowns the player scored.

rush_yards

Returns an int of the number of rushing yards the player gained.

rush_yards_per_attempt

Returns a float of the average number of yards gained per rushing attempt.

rush_yards_per_game

Returns a float of the average number of rushing yards gained per game.

rushing_and_receiving_touchdowns

Returns an int of the combined number of rushing and receiving touchdowns the player scored.

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.

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.

sacks

Returns a float of the number of times the player sacked a quarterback.

safeties

Returns an int of the number of safeties the player has scored.

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

tackles

Returns an int of the number of tackles the player made.

team_abbreviation

Returns a string of the team’s abbreviation, such as ‘NOR’ for the New Orleans Saints.

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.

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.

times_pass_target

Returns an int of the number of times the player was the target of a pass.

times_sacked

Returns an int of the number of times the player was sacked as a quarterback.

total_punt_yards

Returns an int of the total number of yards the player has punted the ball.

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.

touches

Returns an int of the combined number of rushing attempts and receptions the player had.

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.

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.

weight

Returns an int of the player’s weight in pounds.

yards_from_scrimmage

Returns an int of the total number of yards gained from scrimmage for both rushing and receiving.

yards_lost_to_sacks

Returns an int of the number of yards lost as a result of sacks.

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.

yards_per_completed_pass

Returns a float of the number of yards gained per completed pass.

yards_per_game_played

Returns a float of the number of passing yards gained per gamed.

yards_per_kickoff_return

Returns a float of the average number of yards the player returned per kickoff.

yards_per_punt

Returns a float of the average distance the player punts the ball.

yards_per_punt_return

Returns a float of the average number of yards the player returned per punt.

yards_per_touch

Returns a float of the average number of yards gained per rushing attempt and/or reception.

yards_recovered_from_fumble

Returns an int of the number of yards the player gained after recovering a fumble.

yards_returned_from_interception

Returns an int of the number of yards the player returned after intercepting a pass.

class sportsreference.nfl.roster.Roster(team, year=None)[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.
players

Returns a list of player instances for each player on the requested team’s roster.

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

boxscore_index

Returns a string of the URI for a boxscore which can be used to access or index a 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.

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

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

roster

Returns an instance of the Roster class containing all players for the team during the season with all career stats.

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.