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.
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 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 sportsipy.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 sportsipy.ncaaf.boxscore import Boxscores
games_today = Boxscores(datetime.today())
print(games_today.games) # Prints a dictionary of all matchups for today
The Boxscores
class also allows the ability to query over a range of dates
using a second optional parameter during instantiation of the class. To query a
range of dates, enter the start date as the first parameter and the inclusive
end date as the second parameter.
from datetime import datetime
from sportsipy.ncaaf.boxscore import Boxscores
# Pulls all games between and including August 30, 2017 and August 31, 2017
games = Boxscores(datetime(2017, 8, 30), datetime(2017, 8, 31))
# Prints a dictionary of all results from August 30, 2017 and August 31,
# 2017
print(games.games)
- class sportsipy.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’.
- property away_first_downs
Returns an
int
of the number of first downs the away team gained.
- 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_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_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 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’.
- property date
Returns a
string
of the date the game took place.
- property home_first_downs
Returns an
int
of the number of first downs the home team gained.
- 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_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_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 losing_abbr
Returns a
string
of the losing team’s abbreviation, such as ‘GEORGIA’ for the Georgia Bulldogs.
- property losing_name
Returns a
string
of the losing team’s name, such as ‘Georgia’.
- 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 time
Returns a
string
of the time the game started.
- property winner
Returns a
string
constant indicating whether the home or away team won.
- property winning_abbr
Returns a
string
of the winning team’s abbreviation, such as ‘ALABAMA’ for the Alabama Crimson Tide.
- property winning_name
Returns a
string
of the winning team’s name, such as ‘Alabama’.
- class sportsipy.ncaaf.boxscore.BoxscorePlayer(player_id, player_name, player_data)[source]
Bases:
sportsipy.ncaaf.player.AbstractPlayer
Get player stats for an individual game.
Given a player ID, such as ‘david-blough-1’ for David Blough, 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 sports-reference.com, such as ‘david-blough-1’ for David Blough. The player ID can be found by navigating to the player’s stats page and getting the string between the final slash and the ‘.html’ in the URL. In general, the ID is in the format ‘first-last-n’ where ‘first’ is the player’s first name, ‘last’ is the player’s last name, and ‘n’ is a number starting at 1 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 gained per attempted kickoff return.
- property average_punt_return_yards
Returns a
float
of the average number of yards the player gained per attempted punt return.
- property dataframe
Returns a
pandas DataFrame
containing all other relevant class properties and value for the specified game.
- property extra_point_percentage
Returns a
float
of the percentage of attempted extra points the player made. Percentage ranges from 0-100.
- property extra_points_attempted
Returns an
int
of the total number of extra points the player attempted.
- property field_goal_percentage
Returns a
float
of the percentage of attempted 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.
- property kickoff_return_yards
Returns an
int
of the total number of yards the player gained while the player attempted to return a kickoff.
- property kickoff_returns
Returns an
int
of the number of kickoffs the player attempted to return.
- property pass_yards_per_attempt
Returns a
float
of the average number of yards the player gained per pass attempt.
- property points_kicking
Returns an
int
of the total number of points the player gained from kicking field goals or extra points.
- property punt_return_yards
Returns an
int
of the total number of yards the player gained while the player attempted to return a punt.
- property punt_returns
Returns an
int
of the number of punts the player attempted to return.
- property punting_yards
Returns an
int
of the total number of yards the player punted the ball.
- property punting_yards_per_attempt
Returns a
float
of the average number of yards the player punted per attempt.
- property punts
Returns an
int
of the number of times the player punted the ball.
- class sportsipy.ncaaf.boxscore.Boxscores(date, end_date=None)[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.
end_date (datetime object) – Optionally specify an end date to iterate until. All boxscores starting from the date specified in the ‘date’ parameter up to and including the boxscores specified in the ‘end_date’ parameter will be pulled. If left empty, or if ‘end_date’ is prior to ‘date’, only the games from the day specified in the ‘date’ parameter will be saved.
- property games
Returns a
dictionary
object representing all of the games played on the requested day. Dictionary is in the following format:{'date' : [ # 'date' is the string date in format 'MM-DD-YYYY' { 'home_name': Name of the home team, such as '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 '2018-01-28-15-indiana' (`str`), 'non_di': Boolean value which evaluates to True when at least one of the teams does not compete in NCAA Division-I basketball (`bool`), 'top_25': Boolean value which evaluates to True when at least one of the teams is ranked in the AP Top 25 polls (`bool`), 'winning_name': Full name of the winning team, such as 'Purdue Boilermakers' (`str`), 'winning_abbr': Abbreviation for the winning team, such as 'PURDUE' (`str`), 'losing_name': Full name of the losing team, such as 'Indiana Hoosiers' (`str`), 'losing_abbr': Abbreviation for the losing team, such as 'INDIANA' (`str`), 'home_score': Integer score for the home team (`int`), 'home_rank': Integer representing the home team's rank (`int`), 'away_score': Integer score for the away team (`int`), 'away_rank': Integer representing the away team's rank (`int`) }, { ... }, ... ] }
If no games were played on ‘date’, the list for [‘date’] will be empty.
Conferences
The Conference module allows conferences to be pulled for any season using the
Conferences
class. Accessing the class properties exposes various
dictionaries containing the team and conference abbreviations as well as other
information. To get a list of conference abbreviations for each team, query the
team_conference
property.
from sportsipy.ncaaf.conferences import Conferences
conferences = Conferences()
# Prints a dictionary of the team abbreviation as a key and conference
# abbreviation as the value.
print(conferences.team_conference)
The conferences
property can also be queried to provide more details on the
teams in every conference.
from sportsipy.ncaab.conferences import Conferences
conferences = Conferences()
# Prints a dictionary where each key is the conference abbreviation and
# each value is a dictionary containing the full conference name as well as
# another dictionary of all teams in the conference, including name and
# abbreviation for each team.
print(conferences.conferences)
- class sportsipy.ncaaf.conferences.Conference(conference_abbreviation, year=None, ignore_missing=False)[source]
Bases:
object
Find teams that participated in a particular conference.
Create a dictionary which includes the names and abbreviations for all teams that participated in a conference during a given year.
- Parameters
conference_abbreviation (string) – A string of the requested conference’s abbreviation, such as ‘big-12’.
year (string (optional)) – A string of the requested year to pull conference information from. Defaults to the most recent season.
ignore_missing (boolean (optional)) – A boolean which, when True, doesn’t throw an error if the requested conference has an incomplete or empty page on www.sports-reference.com, preventing the parsing from completing successfully.
- property teams
Returns a
dictionary
of team names and abbreviations where each key is astring
of the team abbreviation and each value is astring
of the full team name.
- class sportsipy.ncaaf.conferences.Conferences(year=None, ignore_missing=False)[source]
Bases:
object
Get all conferences and teams for a season.
Retrieve a list of all conferences and teams that participated in the conference for each team in the season. The included properties allow flexibility in queries to either get the conference abbreviation for a given team, or get more detailed information including all teams for each conference.
- Parameters
year (string (optional)) – A string of the requested year to pull conferences from. Defaults to the most recent season.
ignore_missing (boolean (optional)) – A boolean which, when True, doesn’t throw an error if the any conference has an incomplete or empty page on www.sports-reference.com, preventing the parsing from completing successfully.
- property conferences
Returns a
dictionary
of conference names and abbreviations where each key is astring
of the abbreviation and each value is adictionary
containing the full conference name and anotherdictionary
with individual team information. The overall dictionary is in the following structure:{ abbreviation, ie 'big-12' (str): { 'name': Full conference name, such as 'Big 12 Conference' (str), 'teams': { team abbreviation, such as 'kansas' (str): Full team name, such as 'Kansas' (str), ... } }, ... }
- property team_conference
Returns a
dictionary
of conference abbreviations for each team where each key is astring
of the team abbreviation and each value is astring
of the conference abbreviation.
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.ncaaf.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 ‘david-blough-1’ for David Blough, 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 sports-reference.com.
- Parameters
player_id (string) – A player’s ID according to sports-reference.com, such as ‘david-blough-1’ for David Blough. The player ID can be found by navigating to the player’s stats page and getting the string between the final slash and the ‘.html’ in the URL. In general, the ID is in the format ‘first-last-n’ where ‘first’ is the player’s first name in lowercase, ‘last’ is the player’s last name in lowercase, and ‘n’ is a number starting at ‘1’ 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 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 assists_on_tackles
Returns an
int
of the number of assists the player made on tackles.
- property completed_passes
Returns an
int
of the number of completed passes the player threw.
- property extra_point_percentage
Returns a
float
of the percentage (0.0 to 100.0) of extra points the player made.
- property extra_points_attempted
Returns an
int
of the total 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 (0.0 to 100.0) of field goals the player made from any distance.
- 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_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_touchdowns
Returns an
int
of the number of kickoffs the player returned for a touchdown.
- property name
Returns a
string
of the player’s name, such as ‘David Blough’.
- property pass_attempts
Returns an
int
of the number of passes the player attempted.
- 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_touchdowns
Returns an
int
of the number of touchdowns passes the player has thrown.
- property passing_yards
Returns an
int
of the total number of yards the player gained from passing the ball.
- property passing_yards_per_attempt
Returns a
float
of the number of yards gained per passing attempt.
- property player_id
Returns a
string
of the player’s ID on sports-reference, such as ‘david-blough-1’ for David Blough.
- property plays_from_scrimmage
Returns an
int
of the combined number of rushing attempts and receptions the player had.
- property punt_return_touchdowns
Returns an
int
of the number of punts the player returned for a touchdown.
- 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 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 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 rush_yards_per_attempt
Returns a
float
of the average number of yards gained per rushing attempt.
- property rushing_and_receiving_touchdowns
Returns an
int
of the combined number of rushing and receiving touchdowns the player scored.
- property sacks
Returns a
float
of the number of times the player sacked a quarterback.
- property solo_tackles
Returns an
int
of the number of tackles the player made by himself.
- property tackles_for_loss
Returns a
float
of the number of tackles for a loss the player made.
- property total_tackles
Returns an
int
of the number of tackles the player made.
- property yards_from_scrimmage
Returns an
int
of the total number of yards gained from scrimmage for both rushing and receiving.
- property yards_from_scrimmage_per_play
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_interceptions
Returns an
int
of the number of yards the player returned after intercepting a pass.
- property yards_returned_per_interception
Returns a
float
of the average number of yards the player returns after intercepting a pass.
Rankings
The Rankings module include the Rankings
class which can be used to easily
query the NCAA Men’s Division-I Football rankings published by the Associated
Press on a week-by-week basis. Different formats can be referenced, ranging from
a lightweight dictionary of the most recent rankings containing only the team
abbreviation and rank, to a much larger dictionary of all rankings for an entire
season with results including full team name and abbreviation, current rank,
week number, previous rank, and movement.
from sportsipy.ncaaf.rankings import Rankings
rankings = Rankings()
# Prints a dictionary of just the team abbreviation and rank for the current
# week.
print(rankings.current)
# Prints more detailed information including previous rank, full name, and
# movement for all teams for the current week.
print(rankings.current_extended)
# Prints detailed information for all teams for all weeks where rankings
# have been published for the requested season.
print(rankings.complete)
- class sportsipy.ncaaf.rankings.CFPRankings(year=None)[source]
Bases:
object
Get all College Football Playoff (CFP) rankings on a week-by-week basis.
Grab a list of the official College Football Playoff rankings once available to easily determine the latest standings in the race to the College Football Playoffs. The results expose the current and previous rankings as well as the movement for each team in the list.
- Parameters
year (string (optional)) – A string of the requested year to pull rankings from. Defaults to the most recent season.
- property complete
Returns a
dictionary
where each key is a week number as anint
and each value is alist
ofdictionaries
containing the CFP rankings for each week. Within each list is a dictionary of team information such as name, abbreviation, rank, and more. Note that the list might not necessarily be in the same order as the rankings.The overall dictionary has the following structure:
{ week number, ie 16 (int): [ { 'abbreviation': Team's abbreviation, such as 'PURDUE' (str), 'name': Team's full name, such as 'Purdue' (str), 'rank': Team's rank for the current week (int), 'week': Week number for the results, such as 16 (int), 'date': Date the rankings were released, such as '2017-12-03'. Can also be 'Final' for the final rankings or 'Preseason' for preseason rankings (str), 'previous': The team's previous rank, if applicable (str), 'change': The amount the team moved up or down the rankings. Moves up the ladder have a positive number while drops yield a negative number and teams that didn't move have 0 (int) }, ... ], ... }
- property current
Returns a
dictionary
of the most recent rankings from the Associated Press where each key is astring
of the team’s abbreviation and each value is anint
of the team’s rank for the current week.
- property current_extended
Returns a
list
ofdictionaries
of the most recent CFP rankings. The list is ordered in terms of the ranking so the #1 team will be in the first element and the #25 team will be the last element. Each dictionary has the following structure:{ 'abbreviation': Team's abbreviation, such as 'PURDUE' (str), 'name': Team's full name, such as 'Purdue' (str), 'rank': Team's rank for the current week (int), 'week': Week number for the results, such as 19 (int), 'date': Date the rankings were released, such as '2017-03-01'. Can also be 'Final' for the final rankings or 'Preseason' for preseason rankings (str), 'previous': The team's previous rank, if applicable (str), 'change': The amount the team moved up or down the rankings. Moves up the ladder have a positive number while drops yield a negative number and teams that didn't move have 0 (int) }
- class sportsipy.ncaaf.rankings.Rankings(year=None)[source]
Bases:
object
Get all Associated Press (AP) rankings on a week-by-week basis.
Grab a list of the rankings published by the Associated Press to easily query the hierarchy of teams each week. The results expose the current and previous rankings as well as the movement for each team in the list.
- Parameters
year (string (optional)) – A string of the requested year to pull rankings from. Defaults to the most recent season.
- property complete
Returns a
dictionary
where each key is a week number as anint
and each value is alist
ofdictionaries
containing the AP rankings for each week. Within each list is a dictionary of team information such as name, abbreviation, rank, and more. Note that the list might not necessarily be in the same order as the rankings.The overall dictionary has the following structure:
{ week number, ie 16 (int): [ { 'abbreviation': Team's abbreviation, such as 'PURDUE' (str), 'name': Team's full name, such as 'Purdue' (str), 'rank': Team's rank for the current week (int), 'week': Week number for the results, such as 16 (int), 'date': Date the rankings were released, such as '2017-12-03'. Can also be 'Final' for the final rankings or 'Preseason' for preseason rankings (str), 'previous': The team's previous rank, if applicable (str), 'change': The amount the team moved up or down the rankings. Moves up the ladder have a positive number while drops yield a negative number and teams that didn't move have 0 (int) }, ... ], ... }
- property current
Returns a
dictionary
of the most recent rankings from the Associated Press where each key is astring
of the team’s abbreviation and each value is anint
of the team’s rank for the current week.
- property current_extended
Returns a
list
ofdictionaries
of the most recent AP rankings. The list is ordered in terms of the ranking so the #1 team will be in the first element and the #25 team will be the last element. Each dictionary has the following structure:{ 'abbreviation': Team's abbreviation, such as 'PURDUE' (str), 'name': Team's full name, such as 'Purdue' (str), 'rank': Team's rank for the current week (int), 'week': Week number for the results, such as 19 (int), 'date': Date the rankings were released, such as '2017-03-01'. Can also be 'Final' for the final rankings or 'Preseason' for preseason rankings (str), 'previous': The team's previous rank, if applicable (str), 'change': The amount the team moved up or down the rankings. Moves up the ladder have a positive number while drops yield a negative number and teams that didn't move have 0 (int) }
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 David Blough.
from sportsipy.ncaaf.roster import Player
blough = Player('david-blough-1')
print(blough.name) # Prints 'David Blough'
print(blough.passing_yards) # Prints Blough's career passing yards
# Prints a Pandas DataFrame of all relevant stats per season for Blough
print(blough.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.ncaaf.roster import Player
blough = Player('david-blough-1') # Currently pulling career stats
print(blough.passing_yards) # Prints Blough's CAREER passing yards total
# Prints Blough's passing yards total only for the 2017 season
print(blough('2017').passing_yards)
# Prints Blough's passing touchdowns for the 2017 season only
print(blough.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.ncaaf.roster import Player
blough = Player('david-blough-1') # Currently pulling career stats
# Prints Blough's passing yards total only for the 2017 season
print(blough('2017').passing_yards)
print(blough('Career').passing_yards) # Prints Blough's 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.ncaaf.roster import Roster
boilermakers = Roster('PURDUE')
for player in boilermakers.players:
# Prints the name of all players who played for the Purdue Boilermakers
# in the most recent season.
print(player.name)
- class sportsipy.ncaaf.roster.Player(player_id)[source]
Bases:
sportsipy.ncaaf.player.AbstractPlayer
Get player information and stats for all seasons.
Given a player ID, such as ‘david-blough-1’ for David Blough, 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 sports-reference.com.
- Parameters
player_id (string) – A player’s ID according to sports-reference.com, such as ‘david-blough-1’ for David Blough. The player ID can be found by navigating to the player’s stats page and getting the string between the final slash and the ‘.html’ in the URL. In general, the ID is in the format ‘first-last-n’ where ‘first’ is the player’s first name in lowercase, ‘last’ is the player’s last name in lowercase, and ‘n’ is a number starting at ‘1’ for the first time that player ID has been used and increments by 1 for every successive player.
- 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 assists_on_tackles
Returns an
int
of the number of assists the player made on tackles.
- property completed_passes
Returns an
int
of the number of completed passes the player threw.
- 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 extra_points_made
Returns an
int
of the number of extra points the player made.
- property field_goals_made
Returns an
int
of the total number of field goals the player made from any distance.
- 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 games
Returns an
int
of the number of games the player participated in.
- property height
Returns a
string
of the player’s height in the format “feet-inches”.
- 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_touchdowns
Returns an
int
of the number of kickoffs the player returned for a touchdown.
- property other_touchdowns
Returns an
int
of the total number of all other types of touchdowns the player has scored.
- property pass_attempts
Returns an
int
of the number of passes the player attempted.
- 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_touchdowns
Returns an
int
of the number of touchdowns passes the player has thrown.
- property passing_yards
Returns an
int
of the total number of yards the player gained from passing the ball.
- property plays_from_scrimmage
Returns an
int
of the combined number of rushing attempts and receptions the player had.
- property points
Returns an
int
of the number of points the player has scored.
- property position
Returns a
string
of the player’s primary position.
- property punt_return_touchdowns
Returns an
int
of the number of punts the player returned for a touchdown.
- 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 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 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 rush_yards_per_attempt
Returns a
float
of the average number of yards gained per rushing attempt.
- property rushing_and_receiving_touchdowns
Returns an
int
of the combined number of rushing and receiving touchdowns the player scored.
- 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 solo_tackles
Returns an
int
of the number of tackles the player made by himself.
- property tackles_for_loss
Returns a
float
of the number of tackles for a loss the player made.
- property team_abbreviation
Returns a
string
of the team’s abbreviation, such as ‘PURDUE’ for the Purdue Boilermakers.
- property total_tackles
Returns an
int
of the number of tackles the player made.
- property total_touchdowns
Returns an
int
of the total number of touchdowns the player has scored.
- property two_point_conversions
Returns an
int
of the number of two point conversions the player has scored.
- 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_from_scrimmage_per_play
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_interceptions
Returns an
int
of the number of yards the player returned after intercepting a pass.
- property yards_returned_per_interception
Returns a
float
of the average number of yards the player returns after intercepting a pass.
- property year
Returns a
string
of the player’s class designation, such as’FR’ for freshmen.
- class sportsipy.ncaaf.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 ‘PURDUE’ for the Purdue Boilermakers.
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 ‘Jeff Brohm’.
- 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.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 sportsipy.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.
- 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 date the game was played, such as ‘Sep 2, 2017’.
- property 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.
- property 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.
- property game
Returns an
int
to indicate which game in the season was requested. The first game of the season returns 1.
- property location
Returns a
string
constant to indicate whether the game was played at home, away, or in a neutral location.
- property 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.
- property opponent_abbr
Returns a
string
of the opponent’s abbreviation, such as ‘PURDUE’ for the Purdue Boilermakers.
- property 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.
- property opponent_name
Returns a
string
of the opponent’s name, such as ‘Purdue Boilermakers’ for the Purdue Boilermakers.
- property opponent_rank
Returns an
int
of the opponent’s rank at the time the game was played.
- property points_against
Returns an
int
of the number of points the team allowed during the game.
- property points_for
Returns an
int
of the number of points the team scored during the game.
- property rank
Returns an
int
of the team’s rank at the time the game was played.
- property result
Returns a
string
constant to indicate whether the team won or lost the game.
- property 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).
- property time
00 PM’.
- Type
Returns a
string
of the time the game started, such as ‘12
- property 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 sportsipy.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.
- 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 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 sportsipy.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
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 team’s abbreviation while calling the Team
class.
from sportsipy.ncaaf.teams import Team
purdue = Team('PURDUE')
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.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
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.ncaaf.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.ncaaf.teams.Team(team_name=None, team_data=None, team_conference=None, year=None, season_page=None, offensive_stats=None, defensive_stats=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.
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.
team_conference (string (optional)) – A string of the team’s conference abbreviation, such as ‘big-12’.
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.
offensive_stats (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 Offensive Stats page for the designated year.
defensive_stats (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 Defensive Stats page for the designated year.
- property abbreviation
Returns a
string
of the team’s short name, such as ‘PURDUE’ for the Purdue Boilermakers.
- property conference
Returns a
string
of the team’s conference abbreviation, such as ‘big-12’ for the Big 12 Conference.
- property conference_losses
Returns an
int
of the total number of conference games the team lost during the season.
- property 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.
- property conference_wins
Returns an
int
of the total number of conference games the team won during the season.
- 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 ‘PURDUE’.
- property first_downs
Returns a
float
of the total number of first downs achieved per game.
- property first_downs_from_penalties
Returns a
float
of the average number of first downs from an opponent’s penalties per game.
- property fumbles_lost
Returns a
float
of the average number of fumbles per game.
- property games
Returns an
int
of the total number of games the team has played during the season.
- property interceptions
Returns a
float
of the average number of interceptions thrown per game.
- property losses
Returns an
int
of the total number of games the team lost during the season.
- property name
Returns a
string
of the team’s full name, such as ‘Purdue Boilermakers’.
- property opponents_first_downs
Returns a
float
of the opponents’ total number of first downs achieved per game.
- property opponents_first_downs_from_penalties
Returns a
float
of the opponents’ average number of first downs from an opponent’s penalties per game.
- property opponents_fumbles_lost
Returns a
float
of the opponents’ average number of fumbles per game.
- property opponents_interceptions
Returns a
float
of the opponents’ average number of interceptions thrown per game.
- property opponents_pass_attempts
Returns a
float
of the opponents’ average number of passes that are attempted per game.
- property opponents_pass_completion_percentage
Returns a
float
of the opponents’ percentage of completed passes per game. Percentage ranges from 0-100.
- property opponents_pass_completions
Returns a
float
of the opponents’ average number of completed passes per game.
- property opponents_pass_first_downs
Returns a
float
of the opponents’ average number of first downs from passing plays per game.
- property opponents_pass_touchdowns
Returns a
float
of the opponents’ average number of passing touchdowns scored per game.
- property opponents_pass_yards
Returns a
float
of the opponents’ average number of yards gained from passing per game.
- property opponents_penalties
Returns a
float
of the opponents’ average number of penalties conceded per game.
- property opponents_plays
Returns a
float
of the opponents’ average number of offensive plays per game.
- property opponents_rush_attempts
Returns a
float
of the opponents’ average number of rushing plays per game.
- property opponents_rush_first_downs
Returns a
float
of the opponents’ average number of first downs from rushing plays per game.
- property opponents_rush_touchdowns
Returns a
float
of the opponents’ average number of rushing touchdowns scored per game.
- property opponents_rush_yards
Returns a
float
of the opponents’ average number of yards gained from rushing per game.
- property opponents_rush_yards_per_attempt
Returns a
float
of the opponents’ average number of yards gained per rushing attempt per game.
- property opponents_turnovers
Returns a
float
of the opponents’ average number of turnovers per game.
- property opponents_yards
Returns a
float
of the opponents’ average number of yards gained per game.
- property opponents_yards_from_penalties
Returns a
float
of the opponents’ average number of yards gained from an opponent’s penalties per game.
- property opponents_yards_per_play
Returns a
float
of the opponents’ average number of yards gained per play.
- property pass_attempts
Returns a
float
of the average number of passes that are attempted per game.
- property pass_completion_percentage
Returns a
float
of the percentage of completed passes per game. Percentage ranges from 0-100.
- property pass_completions
Returns a
float
of the average number of completed passes per game.
- property pass_first_downs
Returns a
float
of the average number of first downs from passing plays per game.
- property pass_touchdowns
Returns a
float
of the average number of passing touchdowns scored per game.
- property pass_yards
Returns a
float
of the average number of yards gained from passing per game.
- property penalties
Returns a
float
of the average number of penalties conceded per game.
- property plays
Returns a
float
of the average number of offensive plays per game.
- property points_against_per_game
Returns a
float
of the average number of points conceded per game.
- property points_per_game
Returns a
float
of the average number of points scored by the team per game.
- 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 a
float
of the average number of rushing plays per game.
- property rush_first_downs
Returns a
float
of the average number of first downs from rushing plays per game.
- property rush_touchdowns
Returns a
float
of the average number of rushing touchdowns scored per game.
- property rush_yards
Returns a
float
of the average number of yards gained from rushing per game.
- property rush_yards_per_attempt
Returns a
float
of the average number of yards gained per rushing attempt per game.
- 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 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.
- property 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.
- property turnovers
Returns a
float
of the average number of turnovers per game.
- property 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.
- property wins
Returns an
int
of the total number of games the team won during the season.
- property yards
Returns a
float
of the average number of yards gained per game.
- property yards_from_penalties
Returns a
float
of the average number of yards gained from an opponent’s penalties per game.
- property yards_per_play
Returns a
float
of the average number of yards gained per play.
- class sportsipy.ncaaf.teams.Teams(year=None, season_page=None, offensive_stats=None, defensive_stats=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.
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.
offensive_stats (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 Offensive Stats page for the designated year.
defensive_stats (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 Defensive Stats 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.