Football Package¶

The Football (soccer) package offers multiple modules which can be used to retrieve information and statistics for thousands of football teams around the world, such as team names, season stats, game schedules, and competition results.

Team¶

The Team module is used to grab high-level stats and information for a specific team. Information ranges from the team’s primary competition, their position and point value in the league, plus goals scored, and much more. The easiest way to instantiate a team object is to pass a squad’s 8-digit ID number to the class. Squad IDs can either be found in the sportsipy.fb.squad_ids dictionary, or by using one of the utility functions listed below.

Alternatively, the team name can be used while calling the class and the corresponding squad ID will be retrieved if possible. The following is an example of pulling information on Tottenham Hotspur.

from sportsipy.fb.team import Team

tottenham = Team('Tottenham Hotspur')  # Equivalent to Team('361ca564')
print(tottenham.league)  # Prints 'Premier League'
print(tottenham.goals_scored)  # Prints 47
print(tottenham.home_record)  # Prints 8-2-4

class sportsipy.fb.team.Team(team_id, squad_page=None)[source]¶

Bases: object

The high-level stats and information for a single professional team.

By requesting a team via either a name or squad ID, an object will be created which contains high-level information and stats for that team, if found. The information ranges from the name of their primary competition, including their point-return, position, and place, plus the number of goals they have scored, and a pointer to the team roster and schedule.

If a team cannot be identified for the given name or ID, a list of the closest matches will be returned as a dictionary instead.

Parameters:

team_id (string) – A string representing either the team’s full name, such as ‘Tottenham Hotspur’, or the team’s 8-digit squad ID, such as ‘361ca564’ for Tottenham. If a team can’t be found for the given name, a list of suggestions will be returned with corresponding squad IDs.
squad_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 Squad page for the designated year.

away_draws¶: Returns an int of the number of games the team has drawn while away during their primary competition (ie. Premier League) for the current season.

away_games¶: Returns an int of the number of games the team has played away during their primary competition (ie. Premier League).

away_losses¶: Returns an int of the number of games the team has lost while away during their primary competition (ie. Premier League) for the current season.

away_points¶: Returns an int of the number of points the team has gained while away during their primary competition (ie. Premier League) for the current season.

away_record¶: Returns a string of the team’s away record during their primary competition (ie. Premier League) for the current season in the format ‘Wins-Draws-Losses’.

away_wins¶: Returns an int of the number of games the team has won while away during their primary competition (ie. Premier League) for the current season.

country¶: Returns a string of the team’s governing country, such as ‘England’.

expected_goal_difference¶: Returns a float of the difference between the team’s expected goals scored and conceded during their primary competition (ie. Premier League).

expected_goals¶: Returns a float of the number of goals the team was expected to score during their primary competition (ie. Premier League).

expected_goals_against¶: Returns a float of the number of goals the team was expected to concede during their primary competition (ie. Premier League).

gender¶: Returns a string denoting which gender the team competes in (ie. ‘Female’).

goal_difference¶: Returns an int of the team’s goal difference during their primary competition (ie. Premier League).

goals_against¶: Returns an int of the number of goals the team has allowed during their primary competition (ie. Premier League).

goals_scored¶: Returns an int of the number of goals the team has scored during their primary competition (ie. Premier League).

home_draws¶: Returns an int of the number of games the team has drawn at home during their primary competition (ie. Premier League) for the current season.

home_games¶: Returns an int of the number of games the team has played at home during their primary competition (ie. Premier League).

home_losses¶: Returns an int of the number of games the team has lost at home during their primary competition (ie. Premier League) for the current season.

home_points¶: Returns an int of the number of points the team has gained while at home during their primary competition (ie. Premier League) for the current season.

home_record¶: Returns a string of the team’s home record during their primary competition (ie. Premier League) for the current season in the format ‘Wins-Draws-Losses’.

home_wins¶: Returns an int of the number of games the team has won at home during their primary competition (ie. Premier League) for the current season.

league¶: Returns a string of the team’s primary competition, such as ‘Premier League’.

manager¶: Returns a string of the full name of the team’s manager, such as ‘José Mourinho’.

name¶: Returns a string of the team’s full name, such as ‘Tottenham Hotspur’.

points¶: Returns an int of the number of points the team has gained in their primary competition (ie. Premier League).

position¶: Returns an int of the team’s place in the table (ie. 1 for first) for the current season in their primary competition (ie. Premier League).

record¶: Returns a string of the team’s record during their primary competition (ie. Premier League) for the current season in the format ‘Wins-Draws-Losses’.

roster¶: Returns an instance of the Roster class containing instances of every player on the team.

schedule¶: Returns an instance of the Schedule class containing the team’s complete schedule for the season.

season¶: Returns a string of the season’s year(s) in the format YYYY or YYYY-YYYY. For example, ‘2020’ or ‘2019-2020’.

squad_id¶: Returns a string of the team’s squad ID according to sports-reference.com, such as ‘361ca564’ for Tottenham Hotspur.

Schedule¶

The Schedule module can be used to iterate over all games in a team’s schedule to get high-level game information such as the date, score, result, and more. Either the full team name or, preferably, the team’s 8-digit squad ID can be used to pull a specific team’s schedule. The following is an example of pulling the schedule and iterating over the games for Tottenham Hotspur.

from sportsipy.fb.schedule import Schedule

tottenham_schedule = Schedule('Tottenham Hotspur')
print(len(tottenham_schedule))  # Prints 52 for the total number of games
for game in tottenham_schedule:
    print(game.datetime)  # Prints the datetime for each game
    print(game.goals_scored)  # Prints the number of goals the team scored
    print(game.captain)  # Prints the primary captain's name for the game

The Schedule module can also be accessed from the Team class.

from sportsipy.fb.team import Team

tottenham = Schedule('Tottenham Hotspur')
for game in tottenham.schedule:
    print(game.datetime)  # Prints the datetime for each game

class sportsipy.fb.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, week, opponent, and score.

Parameters:	game_data (string) – The row containing the specified game information.

attendance¶: Returns an int of the recorded attendance at the game.

captain¶: Returns a string representing the captain’s name, such as ‘Harry Kane’.

captain_id¶: Returns a string of the captain’s unique ID on fbref.com, such as ‘21a66f6a’ for Harry Kane.

competition¶: Returns a string of the competitions name, such as ‘Premier League’ or ‘Champions Lg’.

dataframe¶: Returns a pandas DataFrame containing all other class properties and values. The index for the DataFrame is the match report ID.

date¶: Returns a string of the date the game was played in the format ‘YYYY-MM-DD’.

datetime¶: Returns a datetime object representing the date and time the match started. If the time is not present, the default time of midnight on the given day will be used instead.

day¶: Returns a string of the day of the week the game was played on.

expected_goals¶: Returns a float of the number of goals the team was expected to score based on the quality of shots taken.

expected_goals_against¶: Returns a float of the number of goals the team was expected to concede based on the quality of shots taken.

formation¶: Returns a string of the formation the team started with during the game, such as ‘4-4-2’.

goals_against¶: Returns an int of the number of goals the team conceded.

goals_for¶: Returns an int of the number of goals the team scored.

match_report¶: Returns a string of the 8-digit match ID for the game.

matchweek¶: Returns a string of the matchweek the game was played in, such as ‘Matchweek 1’ or ‘Group Stage’.

notes¶: Returns a string of any notes that might be included with the game.

opponent¶: Returns a string of the opponents name, such as ‘Arsenal’.

opponent_id¶: Returns a string of the opponents squad ID, such as ‘18bb7c10’ for Arsenal.

referee¶: Returns a string of the first and last name of the referee for the match.

result¶: Returns a string constant representing if the team won (‘Win’), drew (‘Draw’), or lost (‘Loss’).

shootout_against¶: Returns an int of the number of penalties the team conceded if the game went to a shootout after normal play.

shootout_scored¶: Returns an int of the number of penalties the team scored if the game went to a shootout after normal play.

time¶: Returns a string of the time the game started in 24-hour format, local to the home venue.

venue¶: Returns a string constant representing if the team played at home (‘Home’), on the road (‘Away’), or at a neutral site (‘Neutral’).

class sportsipy.fb.schedule.Schedule(team_id, doc=None)[source]¶

Bases: object

An object of the given team’s schedule.

Generates a team’s schedule for the season including wins, losses, draws, and scores if applicable.

Parameters:	team_id (string) – The team’s 8-digit squad ID or the team’s name, such as ‘Tottenham Hotspur’. doc (PyQuery object (optional)) – If passed to the class instantiation, this will be used to pull all information instead of making another request to the website. If the document is not provided, it will be pulled during a later step.

Roster¶

The Roster module contains detailed player information for every player on a team’s roster, allowing each player to be queried by either their name or their unique player ID. Every player instantiates the SquadPlayer class which includes further individual statistics, such as goals, shots, assists, playtime, and much more. The following is an example on pulling the roster for Tottenham Hotspur and querying stats:

from sportsipy.fb.roster import Roster

tottenham = Roster('Tottenham Hotspur')
for player in tottenham:
    print(player.name)  # Prints the name of each player on the roster
    print(player.goals)  # Prints the number of goals the player scored
    print(player.assists)  # Prints the number of assists for the player

A specific player can also be called from a Roster instance instead of iterating through every member of the team by using either the player’s name or unique player ID:

from sportsipy.fb.roster import Roster

tottenham = Roster('Tottenham Hotspur')
harry_kane = tottenham('Harry Kane')  # Pulls Harry Kane's stats
print(harry_kane.goals)  # Prints Harry's goals
print(harry_kane.assists)  # Prints Harry's assists

class sportsipy.fb.roster.Roster(squad_id, doc=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 for the season.

Parameters:	squad_id (string) – The team’s 8-digit squad ID or the team’s name, such as ‘361ca564’ or ‘Tottenham Hotspur’. doc (PyQuery object (optional)) – If passed to the class instantiation, this will be used to pull all information instead of making another request to the website. If the document is not provided, it will be pulled during a later step.

class sportsipy.fb.roster.SquadPlayer(player_data, player_id)[source]¶

Bases: object

Get player information and stats.

Given a player ID and data, capture all relevant stats and information for the player including name, nationality, goals, assists, expected goal difference, nutmegs, and much more.

Parameters:	player_data (PyQuery object) – A PyQuery object containing all fields of information for a single player, represented as one long row by concatenating all tables which hold values for the requested player. player_id (string) – A `string` representation of the player’s unique 8-digit ID as shown on fbref.com.

age¶: Returns an int of the player’s age as of August 1 for winter leagues and February 1 for summer leagues for the given season.

assists¶: Returns an int of the number of goals the player has assisted.

assists_minus_expected¶: Returns a float of the number of assists the player registered minus the actual number of assists the player tallied.

assists_per_90¶: Returns a float of the number of goals the player has assisted per 90 minutes on the field.

attempted_dribbles¶: Returns an int of the number of times the player has attempted a dribble.

average_goal_kick_length¶: Returns a float of the average pass length for goal kicks in yards for a keeper.

average_keeper_action_outside_penalty_distance¶: Returns a float of the average distance from goal in yards a keeper performed a defensive action outside the penalty area.

average_keeper_pass_length¶: Returns a float of the average pass length for a keeper in yards excluding goal kicks.

clean_sheet_percentage¶: Returns a float of the percentage of games a keeper has participated in that resulted in a clean sheet.

clean_sheets¶: Returns an int of the number of clean sheets a keeper has registered.

corner_kick_goals_against¶: Returns an int of the number of goals a keeper conceded as a result of an opponent’s corner kick.

corner_kicks¶: Returns an int of the number of corner kicks the player has taken.

crosses¶: Returns an int of the number of times the player has crossed the ball.

dataframe¶: Returns a pandas DataFame containing all other class properties and values. The index for the DataFrame is the player ID.

draws¶: Returns an int of the number of games a keeper has drawn.

dribble_success_rate¶: Returns a float of the percentage of attempted dribbles the player has successfully completed. Percentage ranges from 0-100.

dribblers_contested¶: Returns an int of the number of opponents who were attempting a dribble that the player contested.

dribblers_tackled¶: Returns an int of the number of opponents who were attempting a dribble that the player tackled.

expected_assists¶: Returns a float of the number of goals the player was expected go assist based on the quality and quantity of teammate shots taken.

expected_assists_per_90¶: Returns a float of the player’s expected assists per 90 minutes played.

expected_goal_difference¶: Returns a float of the difference between expected team goals scored and conceded while the player was on the pitch.

expected_goal_difference_per_90¶: Returns a float of the difference between expected team goals scored and conceded while the player was on the pitch, per 90 minutes.

expected_goals¶: Returns a float of the number of goals the player was expected to score based on the quality and quantity of shots taken.

expected_goals_against_on_pitch¶: Returns a float of the number of goals the team was expected to concede while the player was on the pitch.

expected_goals_and_assists_non_penalty_per_90¶: Returns a float of the player’s expected non-penalty goals and assists per 90 minutes played.

expected_goals_and_assists_per_90¶: Returns a float of the player’s expected goals and assists per 90 minutes played.

expected_goals_non_penalty¶: Returns a float of the number of non-penalty goals the player was expected to score based on the quality and quantity of shots taken.

expected_goals_non_penalty_per_90¶: Returns a float of the player’s expected non-penalty goals per 90 minutes played.

expected_goals_non_penalty_per_shot¶: Returns a float of the nuber of non-penalty goals the player was expected to score per shot.

expected_goals_on_pitch¶: Returns a float of the number of goals the team was expected to score while the player was on the pitch.

expected_goals_per_90¶: Returns a float of the player’s expected goals per 90 minutes played.

final_third_passes¶: Returns an int of the number of passes the player made into the final third.

fouls_committed¶: Returns an int of the number of fouls the player has committed.

fouls_drawn¶: Returns an int of the number of fouls the player has been the victim of.

free_kick_goals_against¶: Returns an int of the number of goals a keeper conceded as a result of an opponent’s free kick.

free_kick_passes¶: Returns an int of the number of passes the player made from a free kick.

free_kick_shots¶: Returns an int of the number of shots the player has taken from free kicks.

goal_difference_on_pitch¶: Returns an int of the team’s goal difference while the player is on the field.

goal_difference_on_pitch_per_90¶: Returns a float of the team’s average goal difference while the player is on the field, per 90 minutes played.

goal_kick_launch_percentage¶: Returns a float of the percentage of goal kicks a keeper has launched further than 40 yards. Percentage ranges from 0-100.

goal_kicks_attempted¶: Returns an int of the number of goal kicks a keeper attempted.

goals¶: Returns an int of the number of goals the player has scored.

goals_against¶: Returns an int of the number of goals a keeper has conceded.

goals_against_on_pitch¶: Returns an int of the number of goals the team has conceded while the player was on the field.

goals_against_per_90¶: Returns a float of the number of goals a keeper has coneceded per 90 minutes played.

goals_and_assists_non_penalty_per_90¶: Returns a float of the number of non-penalty goals the player has either scored or assisted per 90 minutes on the field.

goals_and_assists_per_90¶: Returns a float of the number of goals the player has either scored or assisted per 90 minutes on the field.

goals_minus_expected¶: Returns a float of the number of goals scored minus the number of goals the player was expected to score.

goals_non_penalty_per_90¶: Returns a float of the number of non-penalty goals the player has scored per 90 minutes on the field.

goals_per_90¶: Returns a float of the number of goals the player has scored per 90 minutes on the field.

goals_per_shot¶: Returns a float of the average number of goals scored per shot taken by the player.

goals_per_shot_on_target¶: Returns a float of the average number of goals scored per shot on target by the player.

goals_scored_on_pitch¶: Returns an int of the number of goals the team has scored while the player was on the field.

interceptions¶: Returns an int of the number of times the player has intercepted the ball.

keeper_actions_outside_penalty_area¶: Returns an int of the number of defensive actions a keeper made outside the penalty area.

keeper_actions_outside_penalty_area_per_90¶: Returns a float of the number of defensive actions a keeper made outside the penalty area per 90 minutes played.

keeper_passes_attempted¶: Returns an int of the number of non-goal kick passes a keeper attempted.

key_passes¶: Returns an int of the number of passes the player made that directly lead to a shot.

launch_completion_percentage¶: Returns a float of the percentage of passes longer than 40 yards a keeper completed. Percentage ranges from 0-100.

launch_percentage¶: Returns a float of the percentage of passes a keeper makes longer than 40 yards excluding goal kicks. Percentage ranges from 0-100.

launches_attempted¶: Returns an int of the number of passes longer than 40 yards a keeper attempted.

launches_completed¶: Returns an int of the number of passes longer than 40 yards a keeper completed.

left_foot_passes¶: Returns an int of the number of passes the player made with their left foot.

long_pass_completion¶: Returns a float of the player’s overall pass completion rating for passes greater than 25 yards. Percentage ranges from 0-100.

long_passes_attempted¶: Returns an int of the total number of passes greater than 25 yards the player has attempted.

long_passes_completed¶: Returns an int of the total number of passes greater than 25 yards the player has completed.

losses¶: Returns an int of the number of games a keeper has lost.

matches_played¶: Returns an int of the number of matches the player has participated in.

medium_pass_completion¶: Returns a float of the player’s overall pass completion rating for passes between 5 and 25 yards. Percentage ranges from 0-100.

medium_passes_attempted¶: Returns an int of the total number of passes between 5 and 25 yards the player has attempted.

medium_passes_completed¶: Returns an int of the total number of passes between 5 and 25 yards the player has completed.

minutes¶: Returns an int of the number of minutes the player has spent on the field in all competitions.

minutes_per_match¶: Returns an int of the average number of minutes the player played per match.

minutes_per_start¶: Returns an int of the number of minutes the player plays on average per game started.

minutes_per_sub¶: Returns an int of the average number of minutes the player has played per game after coming in as a sub.

minutes_played_percentage¶: Returns a float of the percentage of time the player has been on the field for all games the team participated in. Percentage ranges from 0-100.

name¶: Returns a string of the player’s full name, such as ‘Harry Kane’.

nationality¶: Returns a string of the player’s home country, such as ‘England’.

net_difference_on_pitch_per_90¶: Returns a float of the team’s goal difference while the player is on the pitch minus the team’s goal difference while the player is off the pitch, per 90 minutes.

net_expected_goal_difference_per_90¶: Returns a float of the team’s expected goal difference while the player is on the pitch minus the team’s exepcted goal difference while the player is off the pitch, per 90 minutes.

nineties_played¶: Returns a float of number of the number of minutes the player has played divided by 90.

non_penalty_minus_expected_non_penalty¶: Returns a float of the number of non-penalty goals scored minus the number of non-penalty goals the player was expected to score.

nutmegs¶: Returns an int of the number of opponents the player has nutmegged.

offsides¶: Returns an int of the number of times the player has been called offside.

opponent_cross_attempts¶: Returns an int of the number of crosses a keeper has faced.

opponent_cross_stop_percentage¶: Returns a float of the percentage of crosses the keeper has successfully stopped. Percentage ranges from 0-100.

opponent_cross_stops¶: Returns an int of the number of crosses a keeper has successfully stopped.

own_goals¶: Returns an int of the number of own goals the player has conceded.

own_goals_against¶: Returns an int of the number of own goals the team scored on a keeper.

pass_completion¶: Returns a float of the player’s overall pass completion rating. Percentage ranges from 0-100.

passes_attempted¶: Returns an int of the total number of passes the player has attempted.

passes_completed¶: Returns an int of the total number of passes the player has completed.

penalty_area_crosses¶: Returns an int of the number of non-set piece crosses the player made into the penalty area.

penalty_area_passes¶: Returns an int of the number of passes the player made into the opposing penalty area.

penalty_kick_attempts¶: Returns an int of the number of penalty kicks the player has attempted.

penalty_kicks¶: Returns an int of the number of penalty kicks the player has scored during regular play.

penalty_kicks_allowed¶: Returns an int of the number of penalty kicks a keeper has conceded during regular play.

penalty_kicks_attempted¶: Returns an int of the number of penalty kicks a keeper has faced during regular play.

penalty_kicks_conceded¶: Returns an int of the number of times the player has conceded a penalty kick to the opposition.

penalty_kicks_missed¶: Returns an int of the number of penalty kicks a keeper has faced where the opponent missed the goal.

penalty_kicks_saved¶: Returns an int of the number of penalty kicks a keeper has saved during regular play.

penalty_kicks_won¶: Returns an int of the number of times the player has won a penalty kick for the team.

player_id¶: Returns a string of the player’s 8-digit ID, such as ‘21a66f6a’ for Harry Kane.

players_dribbled_past¶: Returns an int of the number of opponents the player dribbled past.

points_per_match¶: Returns a float of the average number of points the team has gained per game in which the player participated.

position¶: Returns a string of the player’s primary position(s). Multiple positions are separated by commas.

post_shot_expected_goals¶: Returns a float of the number of goals a keeper was expected to concede.

post_shot_expected_goals_minus_allowed¶: Returns a float of the number of goals a keeper was expected to concede minus the number of goals they actually conceded.

post_shot_expected_goals_minus_allowed_per_90¶: Returns a float of the number of goals a keeper was expected to concede minus the number of goals they actually conceded, per 90 minutes played.

post_shot_expected_goals_per_shot¶: Returns a float of the number of goals a keeper was expected to concede per shot faced.

red_cards¶: Returns an int of the number of red cards the player has accumulated during the season.

right_foot_passes¶: Returns an int of the number of passes the player made with their right foot.

save_percentage¶: Returns a float of the percentage of shots the keeper saved. Percentage ranges from 0-1.

saves¶: Returns an int of the number of shots a keeper has saved.

short_pass_completion¶: Returns a float of the player’s overall pass completion rating for passes under 5 yards. Percentage ranges from 0-100.

short_passes_attempted¶: Returns an int of the total number of passes under 5 yards the player has attempted.

short_passes_completed¶: Returns an int of the total number of passes under 5 yards the player has completed.

shots¶: Returns an int of the number of shots the player has taken.

shots_on_target¶: Returns an int of the number of shots on target the player has taken.

shots_on_target_against¶: Returns an int of the number of shots on target a keeper has faced.

shots_on_target_per_90¶: Returns a float of the number of shots on target the player has taken per 90 minutes played.

shots_on_target_percentage¶: Returns a float of the percentage of shots taken by the player that were on target. Percentage ranges from 0-100.

shots_per_90¶: Returns a float of the number of shots the player has taken per 90 minutes played.

soft_reds¶: Returns an int of the number of games where the player received two yellow cards, resulting in a red, or a “soft red”.

starts¶: Returns an int of the number of games the player has started.

subs¶: Returns an int of the number of times the player has come on as a sub.

successful_dribbles¶: Returns an int of the number of dribbles the player has completed successfully.

tackle_percentage¶: Returns a float of the percentage of opposing dribblers the player has successfully tackled. Percentage ranges from 0-100.

tackles_won¶: Returns an int of the number of tackles the player has won.

through_balls¶: Returns an int of the number of passes the player made between the last line of defenders into open space.

throw_ins¶: Returns an int of the number of throw-ins the player took.

throws_attempted¶: Returns an int of the number of throws a keeper attempted.

times_dribbled_past¶: Returns an int of the number of times the player has been dribbled past.

unused_sub¶: Returns an int of the number of times the player was an unused sub and spent the entirety of the game on the bench.

wins¶: Returns an int of the number of games a keeper has won.

yellow_cards¶: Returns an int of the number of yellow cards the player has accumulated during the season.