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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

property attendance: Returns an int of the recorded attendance at the game.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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