Fbref

Complete list of all football reference functions

Match functions

.fbref.fb_match_data(url: str, save_html: bool = False, html_file: BeautifulSoup = None) → tuple

Extracts metadata and statistics for a given match that include Opta data. This includes summary match statistics for each team, summary stats for away team, passing, defensive, possession and goalkeeping stats

Parameters

url (str) – path of fbref match page
save_html (bool) – whether to save html file of match page. Defaults to False.
html_file (BeautifulSoup or None) – pageSoup html file of match page. Defaults to None.

Returns

match data and BeautifulSoup file of match page (optional)

Return type

(dict, dict, dict, list, dict, list, list, list, list, list, list, list, list, list, list, list, list, list, list, list, BeautifulSoup) or (dict, dict, dict, list, dict, list, list, list, list, list, list, list, list, list, list, list, list, list, list, list, BeautifulSoup)

.fbref.fb_match_defensive_actions_stats(pageSoup=None, url: str = None) → tuple

Extracts defensive action stats for each player in a given match that includes advanced data

Parameters

pageSoup (bs4 or None) – bs4 object of a match. Defaults to None.
url (str or None) – path of fbref match page. Defaults to None.

Returns

(defensive stats for home team players, defensive stats for away team players)

Return type

(list, list)

.fbref.fb_match_keeper_stats(pageSoup=None, url: str = None) → tuple

Extracts goalkeeping stats for each keeper in a given match that includes advanced data

Parameters

pageSoup (bs4 or None) – bs4 object of a match. Defaults to None.
url (str or None) – path of fbref match page. Defaults to None.

Returns

(keeper stats for home team players, keeper stats for away team players)

Return type

(list, list)

.fbref.fb_match_lineups(pageSoup=None, url: str = None) → dict

Extracts matchday squad information (formation, starters, bench) for a given match

Parameters

pageSoup (bs4 or None) – bs4 object of a match. Defaults to None.
url (str or None) – path of fbref match page. Defaults to None.

Returns

squad information

Return type

dict

.fbref.fb_match_metadata(pageSoup=None, url: str = None) → tuple

Extracts general info (teams, managers, captains, date, time, venue, attendance, score, xG) for a given match

Parameters

pageSoup (bs4 or None) – bs4 object of a match. Defaults to None.
url (str or None) – path of fbref match page. Defaults to None.

Returns

(metadata, officials)

Return type

(dict, dict)

.fbref.fb_match_misc_stats(pageSoup=None, url: str = None) → tuple

Extracts miscellaneous stats for each player in a given match that includes advanced data

Parameters

pageSoup (bs4 or None) – bs4 object of a match. Defaults to None.
url (str or None) – path of fbref match page. Defaults to None.

Returns

(miscellaneous stats for home team players, miscellaneous stats for away team players)

Return type

(list, list)

.fbref.fb_match_passing_stats(pageSoup=None, url: str = None) → tuple

Extracts passing stats for each player in a given match that includes advanced data

Parameters

pageSoup (bs4 or None) – bs4 object of a match. Defaults to None.
url (str or None) – path of fbref match page. Defaults to None.

Returns

(passing stats for home team players, passing stats for away team players)

Return type

(list, list)

.fbref.fb_match_passing_type_stats(pageSoup=None, url: str = None) → tuple

Extracts passing type stats for each player in a given match that includes advanced data

Parameters

pageSoup (bs4 or None) – bs4 object of a match. Defaults to None.
url (str or None) – path of fbref match page. Defaults to None.

Returns

(passing type stats for home team players, passing type stats for away team players)

Return type

(list, list)

.fbref.fb_match_possession_stats(pageSoup=None, url: str = None) → tuple

Extracts possession stats for each player in a given match that includes advanced data

Parameters

pageSoup (bs4 or None) – bs4 object of a match. Defaults to None.
url (str or None) – path of fbref match page. Defaults to None.

Returns

(possession stats for home team players, possession stats for away team players)

Return type

(list, list)

.fbref.fb_match_shots(pageSoup=None, url: str = None) → list

Extracts shots for a given match that includes Opta data

Parameters

pageSoup (bs4 or None) – bs4 object of a match. Defaults to None.
url (str or None) – path of fbref match page. Defaults to None.

Returns

shots for the match

Return type

list[dict]

.fbref.fb_match_summary_stats(pageSoup=None, url: str = None) → tuple

Extracts summary statistics for each player in a given match that includes advanced data

Parameters

pageSoup (bs4 or None) – bs4 object of a match. Defaults to None.
url (str or None) – path of fbref match page. Defaults to None.

Returns

(summary stats for home team players, summary stats for away team players)

Return type

(list, list)

.fbref.fb_match_summary(pageSoup=None, url: str = None) → list

Extracts events (goals, bookings, and substitutions) from match summary for a given match

Parameters

pageSoup (bs4 or None) – bs4 object of a match. Defaults to None.
url (str or None) – path of fbref match page. Defaults to None.

Returns

events

Return type

list[dict]

.fbref.fb_match_team_stats(pageSoup=None, url: str = None) → dict

Extracts summary stats for each team in a given match

Parameters

pageSoup (bs4 or None) – bs4 object of a match. Defaults to None.
url (str or None) – path of fbref match page. Defaults to None.

Returns

summary statistics for each team

Return type

dict

League functions

.fbref.fb_league_table(url: str) → list

Returns a list of league table and basic information in a season

Parameters: url (str) – url of a season
Returns: league table
Return type: list[dict]

.fbref.fb_match_urls(url: str) → list

Returns a list of urls for matches in a season

Parameters: url (str) – url of a season
Returns: match urls for given season
Return type: list[str]

.fbref.fb_season_fixture_urls(competition_type: str = None, competition_name: str = None, country: str = None, gender: str = None, governing_body: str = None, tier: str = None, season_end_year: int = None, advanced: str = None) → pd.Series

Returns a series of urls for fixture section of a season

Parameters

competition_type (str, list, or None) –
type of competition. Defaults to None.
- Domestic Leagues - 1st Tier
- Domestic Leagues - 2nd Tier
- Domestic Leagues - 3rd Tier and Lower
- Domestic Cups
- Domestic Youth Leagues
- Club International Cups
- National Team Competitions
- National Team Qualification
competition_name (str, list, or None) – name of competition. Defaults to None.
country (str, list, or None) – country of competition. Defaults to None.
gender (str, list, or None) –
gender of competition. Defaults to None.
- M
- W
governing_body (str, list, or None) –
governing body of competition. Defaults to None.
- AFC
- CAF
- CONMEBOL
- CONCACAF
- OFC
- UEFA
- FIFA
tier – tier of competition. Defaults to None.
season_end (int, list, or None) – year at end of competition. Defaults to None.
advanced (str, list, or None) –
flag for if advanced data is available. Defaults to None.
- Y
- N

Returns

season fixture urls

Return type

series

.fbref.fb_season_urls(competition_type: str = None, competition_name: str = None, country: str = None, gender: str = None, governing_body: str = None, tier: str = None, season_end_year: int = None, advanced: str = None) → pd.Series

Returns a series of urls for overview section of a season

Parameters

competition_type (str, list, or None) –
type of competition. Defaults to None.
- Domestic Leagues - 1st Tier
- Domestic Leagues - 2nd Tier
- Domestic Leagues - 3rd Tier and Lower
- Domestic Cups
- Domestic Youth Leagues
- Club International Cups
- National Team Competitions
- National Team Qualification
competition_name (str, list, or None) – name of competition. Defaults to None.
country (str, list, or None) – country of competition. Defaults to None.
gender (str, list, or None) –
gender of competition. Defaults to None.
- M
- W
governing_body (str, list, or None) –
governing body of competition. Defaults to None.
- AFC
- CAF
- CONMEBOL
- CONCACAF
- OFC
- UEFA
- FIFA
tier – tier of competition. Defaults to None.
season_end (int, list, or None) – year at end of competition. Defaults to None.
advanced (str, list, or None) –
flag for if advanced data is available. Defaults to None.
- Y
- N

Returns

season fixture urls

Return type

series

.fbref.fb_team_advanced_keeper_stats(pageSoup=None, url: str = None) → list

Extracts advanced keeper stats for each team in a given league

Parameters

pageSoup (bs4 or None) – bs4 object of a team. Defaults to None.
url (str or None) – path of fbref team page. Defaults to None.

Returns

(advanced keeper stats for each team, advanced keeper stats against each team)

Return type

(list, list)

.fbref.fb_team_data(url: str, html_file: BeautifulSoup = None) → tuple

Extracts statistics of each team. This includes summary, shooting, passing, defensive, possession, possession, playing time, and goalkeeping stats

Parameters

url (str) – path of fbref stats page
html_file (BeautifulSoup or None) – pageSoup html file of fbref stats page. Defaults to None.

Returns

team data

Return type

(list, list, list, list, list, list, list, list, list, list, list, list, list, list, list, list, list, list, list, list, list, list)

.fbref.fb_team_defensive_actions_stats(pageSoup=None, url: str = None) → tuple

Extracts defensive action stats for each team in a given league

Parameters

pageSoup (bs4 or None) – bs4 object of a team. Defaults to None.
url (str or None) – path of fbref team page. Defaults to None.

Returns

(defensive action stats for each team, defensive action stats against each team)

Return type

(list, list)

.fbref.fb_team_goal_sca_stats(pageSoup=None, url: str = None) → tuple

Extracts shot and goal creating actions stats for each team in a given league

Parameters

pageSoup (bs4 or None) – bs4 object of a team. Defaults to None.
url (str or None) – path of fbref team page. Defaults to None.

Returns

(shot and goal creating actions stats for each team, shot and goal creating actions stats against each team)

Return type

(list, list)

.fbref.fb_team_keeper_stats(pageSoup=None, url: str = None) → tuple

Extracts keeper stats for each team in a given league

Parameters

pageSoup (bs4 or None) – bs4 object of a team. Defaults to None.
url (str or None) – path of fbref team page. Defaults to None.

Returns

(keeper stats for each team, keeper stats against each team)

Return type

(list, list)

.fbref.fb_team_misc_stats(pageSoup=None, url: str = None) → tuple

Extracts miscellaneous stats for each team in a given league

Parameters

pageSoup (bs4 or None) – bs4 object of a team. Defaults to None.
url (str or None) – path of fbref team page. Defaults to None.

Returns

(miscellaneous stats for each team, miscellaneous stats against each team)

Return type

(list, list)

.fbref.fb_team_passing_stats(pageSoup=None, url: str = None) → tuple

Extracts passing stats for each team in a given league

Parameters

pageSoup (bs4 or None) – bs4 object of a team. Defaults to None.
url (str or None) – path of fbref team page. Defaults to None.

Returns

(passing stats for each team, passing stats against each team)

Return type

(list, list)

.fbref.fb_team_passing_type_stats(pageSoup=None, url: str = None) → tuple

Extracts passing type stats for each team in a given league

Parameters

pageSoup (bs4 or None) – bs4 object of a team. Defaults to None.
url (str or None) – path of fbref team page. Defaults to None.

Returns

(passing type stats for each team, passing type stats against each team)

Return type

(list, list)

.fbref.fb_team_playing_time_stats(pageSoup=None, url: str = None) → tuple

Extracts playing time stats for each team in a given league

Parameters

pageSoup (bs4 or None) – bs4 object of a team. Defaults to None.
url (str or None) – path of fbref team page. Defaults to None.

Returns

(playing time stats for each team, playing time stats against each team)

Return type

(list, list)

.fbref.fb_team_possession_stats(pageSoup=None, url: str = None) → tuple

Extracts possession stats for each team in a given league

Parameters

pageSoup (bs4 or None) – bs4 object of a team. Defaults to None.
url (str or None) – path of fbref team page. Defaults to None.

Returns

(possession stats for each team, possession stats against each team)

Return type

(list, list)

.fbref.fb_team_shooting_stats(pageSoup=None, url: str = None) → tuple

Extracts shooting stats for each team in a given league

Parameters

pageSoup (bs4 or None) – bs4 object of a team. Defaults to None.
url (str or None) – path of fbref team page. Defaults to None.

Returns

(shooting stats for each team, shooting stats against each team)

Return type

(list, list)

.fbref.fb_team_summary_stats(pageSoup=None, url: str = None) → tuple

Extracts summary stats for each team in a given league

Parameters

pageSoup (bs4 or None) – bs4 object of a team. Defaults to None.
url (str or None) – path of fbref team page. Defaults to None.

Returns

(summary stats for each team, summary stats against each team)

Return type

(list, list)

Player functions

.fbref.fb_player_scouting_report(pageSoup=None, url: str = None, player_url: str = None, comp_league: str = None, position_comp: str = 'Primary') → dict

Extracts scouting report for a given player

Parameters

pageSoup (bs4 or None) – bs4 object of a player’s scouting report. Defaults to None.
url (str or None) – path of fbref scouting report page. Defaults to None.
player_url (str or None) – path of fbref player page. Defaults to None.
comp_league (str or None) – name of comparison league. Defaults to None.
position_comp (str) – primary or secondary position. Defaults to “Primary”.

Returns

complete scouting report for a player

Return type

dict

.fbref.fb_player_match_logs_data(season_end: str, player_id: str) → dict

Extracts scouting report for a given player

Parameters

season_end (str) – ending year of a season
player_id (str) – unique identifier for a player

Returns

match logs for a player in a given season

Return type

dict[list]

.fbref.fb_player_match_logs_defensive_actions(pageSoup=None, season_end: str = None, player_id: str = None) → dict

Retrieves a players defensive actions match log for a given season

Parameters

pageSoup (bs4 or None) – bs4 object of a players defensive actions match log page. Defaults to None.
season_end (str) – ending year of a season
player_id (str) – unique identifier for a player

Returns

defensive actions match log for a player in a given season

Return type

list

.fbref.fb_player_match_logs_gca_sca(pageSoup=None, season_end: str = None, player_id: str = None) → dict

Retrieves a players goal and shot creating actions match log for a given season

Parameters

pageSoup (bs4 or None) – bs4 object of a players goal and shot creating actions match log page. Defaults to None.
season_end (str) – ending year of a season
player_id (str) – unique identifier for a player

Returns

goal and shot creating actions match log for a player in a given season

Return type

list

.fbref.fb_player_match_logs_misc(pageSoup=None, season_end: str = None, player_id: str = None) → dict

Retrieves a players miscellaneous match log for a given season

Parameters

pageSoup (bs4 or None) – bs4 object of a players miscellaneous match log page. Defaults to None.
season_end (str) – ending year of a season
player_id (str) – unique identifier for a player

Returns

miscellaneous match log for a player in a given season

Return type

list

.fbref.fb_player_match_logs_passing(pageSoup=None, season_end: str = None, player_id: str = None) → dict

Retrieves a players passing match log for a given season

Parameters

pageSoup (bs4 or None) – bs4 object of a players passing match log page. Defaults to None.
season_end (str) – ending year of a season
player_id (str) – unique identifier for a player

Returns

passing match log for a player in a given season

Return type

list

.fbref.fb_player_match_logs_passing_types(pageSoup=None, season_end: str = None, player_id: str = None) → dict

Retrieves a players passing type match log for a given season

Parameters

pageSoup (bs4 or None) – bs4 object of a players passing type match log page. Defaults to None.
season_end (str) – ending year of a season
player_id (str) – unique identifier for a player

Returns

passing type match log for a player in a given season

Return type

list

.fbref.fb_player_match_logs_possession(pageSoup=None, season_end: str = None, player_id: str = None) → dict

Retrieves a players possession match log for a given season

Parameters

pageSoup (bs4 or None) – bs4 object of a players possession match log page. Defaults to None.
season_end (str) – ending year of a season
player_id (str) – unique identifier for a player

Returns

possession match log for a player in a given season

Return type

list

.fbref.fb_player_match_logs_summary(pageSoup=None, season_end: str = None, player_id: str = None) → dict

Retrieves a players summary match log for a given season

Parameters

pageSoup (bs4 or None) – bs4 object of a players summary match log page. Defaults to None.
season_end (str) – ending year of a season
player_id (str) – unique identifier for a player

Returns

summary match log for a player in a given season

Return type

list

Team functions

.fbref.fb_team_player_advanced_keeper_stats(pageSoup=None, url: str = None) → list

Extracts advanced keeper stats for each player in a given team

Parameters

pageSoup (bs4 or None) – bs4 object of a team. Defaults to None.
url (str or None) – path of fbref team page. Defaults to None.

Returns

goalkeeper stats for each player

Return type

list[dict]

.fbref.fb_team_player_data(url: str, html_file: BeautifulSoup = None) → tuple

Extracts statistics of each player for a given team. This includes summary, passing, defensive, possession, possession, playing time, and goalkeeping stats

Parameters

url (str or None) – path of fbref team page. Defaults to None.
html_file (BeautifulSoup or None) – pageSoup html file of fbref team page. Defaults to None.

Returns

player stats

Return type

(list, list, list, list, list, list, list, list, list, list, list)

.fbref.fb_team_player_defensive_actions_stats(pageSoup=None, url: str = None) → list

Extracts defensive action stats for each player in a given team

Parameters

pageSoup (bs4 or None) – bs4 object of a team. Defaults to None.
url (str or None) – path of fbref team page. Defaults to None.

Returns

defensive stats for each player

Return type

list[dict]

.fbref.fb_team_player_goal_sca_stats(pageSoup=None, url: str = None) → list

Extracts shot and goal creating actions for each player in a given team

Parameters

pageSoup (bs4 or None) – bs4 object of a team. Defaults to None.
url (str or None) – path of fbref team page. Defaults to None.

Returns

shot and goal creating actions for each player

Return type

list[dict]

.fbref.fb_team_player_keeper_stats(pageSoup=None, url: str = None) → list

Extracts basic keeper stats for each player in a given team

Parameters

pageSoup (bs4 or None) – bs4 object of a team. Defaults to None.
url (str or None) – path of fbref team page. Defaults to None.

Returns

goalkeeper stats for each player

Return type

list[dict]

.fbref.fb_team_player_misc_stats(pageSoup=None, url: str = None) → list

Extracts miscellaneous stats for rach player in a given team

Parameters

pageSoup (bs4 or None) – bs4 object of a team. Defaults to None.
url (str or None) – path of fbref team page. Defaults to None.

Returns

miscellaneous stats for each player

Return type

list[dict]

.fbref.fb_team_player_passing_stats(pageSoup=None, url: str = None) → list

Extracts passing stats for each player in a given team

Parameters

pageSoup (bs4 or None) – bs4 object of a team. Defaults to None.
url (str or None) – path of fbref team page. Defaults to None.

Returns

passing stats for each player

Return type

list[dict]

.fbref.fb_team_player_passing_type_stats(pageSoup=None, url: str = None) → list

Extracts passing type stats for each player in a given team

Parameters

pageSoup (bs4 or None) – bs4 object of a team. Defaults to None.
url (str or None) – path of fbref team page. Defaults to None.

Returns

passing type stats for each player

Return type

list[dict]

.fbref.fb_team_player_playing_time_stats(pageSoup=None, url: str = None) → list

Extracts playing time stats for each player in a given team

Parameters

pageSoup (bs4 or None) – bs4 object of a team. Defaults to None.
url (str or None) – path of fbref team page. Defaults to None.

Returns

playing time for each player

Return type

list[dict]

.fbref.fb_team_player_possession_stats(pageSoup=None, url: str = None) → list

Extracts possession stats for each player in a given team

Parameters

pageSoup (bs4 or None) – bs4 object of a team. Defaults to None.
url (str or None) – path of fbref team page. Defaults to None.

Returns

possession stats for each player

Return type

list[dict]

.fbref.fb_team_player_shooting_stats(pageSoup=None, url: str = None) → list

Extracts shooting stats for each player in a given team

Parameters

pageSoup (bs4 or None) – bs4 object of a team. Defaults to None.
url (str or None) – path of fbref team page. Defaults to None.

Returns

shooting stats for each player

Return type

list[dict]

.fbref.fb_team_player_summary_stats(pageSoup=None, url: str = None) → list

Extracts summary stats for each player in a given team

param pageSoup

bs4 object of a team. Defaults to None.

type pageSoup

bs4 or None

param url

path of fbref team page. Defaults to None.

type url

str or None

return

summary stats for each player

rtype

list[dict]