sportsreference.ncaaf package¶
The NCAAF package offers multiple modules which can be used to retrieve information and statistics for Division-I College Football, such as team names, season stats, game schedules, and boxscore metrics.
sportsreference.ncaaf.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 pass yards, to the
yards from penalties 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.ncaaf.boxscore import Boxscore
game_data = Boxscore('2018-01-08-georgia')
print(game_data.home_points) # Prints 23
print(game_data.away_points) # Prints 26
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.ncaaf.boxscore import Boxscores
games_today = Boxscores(datetime.today())
print(games_today.games) # Prints a dictionary of all matchups for today
-
class
sportsreference.ncaaf.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 fumbles 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 ‘2018-01-08-georgia’. -
away_first_downs
¶ Returns an
int
of the number of first downs the away team gained.
-
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_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_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.
-
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 ‘2018-01-08-georgia’.
-
date
¶ Returns a
string
of the date the game took place.
-
home_first_downs
¶ Returns an
int
of the number of first downs the home team gained.
-
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_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_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.
-
losing_abbr
¶ Returns a
string
of the losing team’s abbreviation, such as ‘GEORGIA’ for the Georgia Bulldogs.
-
losing_name
¶ Returns a
string
of the losing team’s name, such as ‘Georgia’.
-
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 ‘ALABAMA’ for the Alabama Crimson Tide.
-
winning_name
¶ Returns a
string
of the winning team’s name, such as ‘Alabama’.
-
-
class
sportsreference.ncaaf.boxscore.
Boxscores
(date)[source]¶ Bases:
object
Search for NCAAF 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, a boolean value which indicates if the game is between two Division-I teams or not, and the names and abbreviations for both the home teams. If no games are played on a particular day, the list will be empty.
Parameters: date (datetime object) – The date to search for any matches. The month, day, and year are required for the search, but time is not factored into the search. -
games
¶ Returns a
dictionary
object representing all of the games played on the requested day. Dictionary is in the following format:{'boxscores' : [ {'home_name': Name of the home team, such as 'Purdue Boilermakers' (`str`), 'home_abbr': Abbreviation for the home team, such as 'PURDUE' (`str`), 'away_name': Name of the away team, such as 'Indiana Hoosiers' (`str`), 'away_abbr': Abbreviation for the away team, such as 'INDIANA' (`str`), 'boxscore': String representing the boxscore URI, such as '2017-09-09-michigan' (`str`), 'non_di': Boolean value which evaluates to True when at least one of the teams does not compete in NCAA Division-I football (`str`)}, { ... }, ... ] }
If no games were played during the requested day, the list for [‘boxscores’] will be empty.
-
sportsreference.ncaaf.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.ncaaf.schedule import Schedule
purdue_schedule = Schedule('PURDUE')
for game in purdue_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.ncaaf.schedule.
Game
(game_data)[source]¶ Bases:
object
A representation of a matchup between two teams.
Stores all relevant high-level match information for a game in a team’s schedule including date, time, opponent, and result.
Parameters: game_data (string) – The row containing the specified game information. -
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 date the game was played, such as ‘Sep 2, 2017’.
-
datetime
¶ Returns a datetime object of the month, day, year, and time the game was played. If the game doesn’t include a time, the default value of ‘00:00’ will be used.
-
day_of_week
¶ Returns a
string
of the 3-letter abbreviation of the day of the week the game was played on, such as ‘Sat’ for Saturday.
-
game
¶ Returns an
int
to indicate which game in the season was requested. The first game of the season returns 1.
-
location
¶ Returns a
string
constant to indicate whether the game was played at home, away, or in a neutral location.
-
losses
¶ Returns an
int
of the number of games the team has lost so far in the season at the conclusion of the requested game.
-
opponent_abbr
¶ Returns a
string
of the opponent’s abbreviation, such as ‘PURDUE’ for the Purdue Boilermakers.
-
opponent_conference
¶ Returns a
string
of the conference the team participates in, such as ‘Big Ten’ for the Big Ten Conference. If a team does not compete in Division-I, a string constant for the non-major school will be returned.
-
opponent_name
¶ Returns a
string
of the opponent’s name, such as ‘Purdue Boilermakers’ for the Purdue Boilermakers.
-
opponent_rank
¶ Returns an
int
of the opponent’s rank at the time the game was played.
-
points_against
¶ Returns an
int
of the number of points the team allowed during the game.
-
points_for
¶ Returns an
int
of the number of points the team scored during the game.
-
rank
¶ Returns an
int
of the team’s rank at the time the game was played.
-
result
¶ Returns a
string
constant to indicate whether the team won or lost the game.
-
streak
¶ Returns a
string
of the team’s winning streak at the conclusion of the requested game. Streaks are listed in the format ‘[W|L] #’ (ie. ‘W 3’ for a 3-game winning streak and ‘L 2’ for a 2-game losing streak).
-
time
¶ Returns a
string
of the time the game started, such as ‘12 – 00 PM’.
-
wins
¶ Returns an
int
of the number of games the team has won so far in the season at the conclusion of the requested game.
-
-
class
sportsreference.ncaaf.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 ‘MICHIGAN’ for the Michigan Wolverines.
- 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.ncaaf.teams module¶
The Teams module exposes information for all NCAAF teams including the team name and abbreviation, the number of games they won during the season, the total number of pass yards, and much more.
from sportsreference.ncaaf.teams import Teams
teams = Teams()
for team in teams:
print(team.name) # Prints the team's name
print(team.pass_yards) # Prints the team's total passing yards
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.ncaaf.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.ncaaf.teams.
Team
(team_data, 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 full and short names, 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.
- year (string (optional)) – The requested year to pull stats from.
-
abbreviation
¶ Returns a
string
of the team’s short name, such as ‘PURDUE’ for the Purdue Boilermakers.
-
conference_losses
¶ Returns an
int
of the total number of conference games the team lost during the season.
-
conference_win_percentage
¶ Returns a
float
of the percentage of conference wins divided by the number of conference games played during the season. Percentage ranges from 0-1.
-
conference_wins
¶ Returns an
int
of the total number of conference games the team won during the season.
-
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 ‘PURDUE’.
-
first_downs
¶ Returns a
float
of the total number of first downs achieved per game.
-
first_downs_from_penalties
¶ Returns a
float
of the average number of first downs from an opponent’s penalties per game.
-
fumbles_lost
¶ Returns a
float
of the average number of fumbles per game.
-
games
¶ Returns an
int
of the total number of games the team has played during the season.
-
interceptions
¶ Returns a
float
of the average number of interceptions thrown per game.
-
losses
¶ Returns an
int
of the total number of games the team lost during the season.
-
name
¶ Returns a
string
of the team’s full name, such as ‘Purdue Boilermakers’.
-
pass_attempts
¶ Returns a
float
of the average number of passes that are attempted per game.
-
pass_completion_percentage
¶ Returns a
float
of the percentage of completed passes per game. Percentage ranges from 0-100.
-
pass_completions
¶ Returns a
float
of the average number of completed passes per game.
-
pass_first_downs
¶ Returns a
float
of the average number of first downs from passing plays per game.
-
pass_touchdowns
¶ Returns a
float
of the average number of passing touchdowns scored per game.
-
pass_yards
¶ Returns a
float
of the average number of yards gained from passing per game.
-
penalties
¶ Returns the average number of penalties conceded per game.
-
plays
¶ Returns a
float
of the average number of offensive plays per game.
-
points_against_per_game
¶ Returns a
float
of the average number of points conceded per game.
-
points_per_game
¶ Returns a
float
of the average number of points scored by the team per game.
-
rush_attempts
¶ Returns a
float
of the average number of rushing plays per game.
-
rush_first_downs
¶ Returns a
float
of the average number of first downs from rushing plays per game.
-
rush_touchdowns
¶ Returns a
float
of the average number of rushing touchdowns scored per game.
-
rush_yards
¶ Returns a
float
of the average number of yards gained from rushing per game.
-
rush_yards_per_attempt
¶ Returns a
float
of the average number of yards gained per rushing attempt per game.
-
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 the average margin of victory and the strength of schedule. An average team is denoted with 0.0 while a negative score indicates a comparatively weak team.
-
strength_of_schedule
¶ Returns a
float
of the team’s strength of schedule based on the number of points above or below average. An average difficulty schedule is denoted with 0.0 while a negative score indicates a comparatively easy schedule.
-
turnovers
¶ Returns a
float
of the average number of turnovers per game.
-
win_percentage
¶ Returns a
float
of the percentage of wins divided by the number of games played during the season. Percentage ranges from 0-1.
-
wins
¶ Returns an
int
of the total number of games the team won during the season.
-
yards
¶ Returns a
float
of the average number of yards gained per game.
-
yards_from_penalties
¶ Returns a
float
of the average number of yards gained from an opponent’s penalties per game.
-
yards_per_play
¶ Returns a
float
of the average number of yards gained per play.
-
class
sportsreference.ncaaf.teams.
Teams
(year=None)[source]¶ Bases:
object
A list of all NCAA Men’s Football teams and their stats in a given year.
Finds and retrieves a list of all NCAA Men’s Football teams from www.sports-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.
-