Understat

class ScraperFC.understat.Understat

Bases: object

Gets all of the match links for the chosen league season

Parameters:

  • year (str) – See the Understat year parameter docs for details.

  • league (str) – See the src/ScraperFC/comps.yaml file for all available competitions and which modules can be used to scrape them.

Returns:

List of match links of the chosen league season

Return type:

list[str]

Gets Understat URL of the chosen league season.

Parameters:

  • year (str) – See the Understat year parameter docs for details.

  • league (str) – See the src/ScraperFC/comps.yaml file for all available competitions and which modules can be used to scrape them.

Raises:

  • TypeError – If any of the parameters are the wrong type

  • InvalidLeagueException – If the league is not a valid league for this module.

  • InvalidYearException – If the year is not a valid year for this league.

Returns:

URL to the Understat page of the chosen league season.

Return type:

str

Gets all of the team links for the chosen league season

Parameters:

  • year (str) – See the Understat year parameter docs for details.

  • league (str) – See the src/ScraperFC/comps.yaml file for all available competitions and which modules can be used to scrape them.

Returns:

List of team links of the chosen league season

Return type:

list[str]

get_valid_seasons(league: str) → list[str]

Returns valid season strings for the chosen league.

Parameters:

league (str) – See the src/ScraperFC/comps.yaml file for all available competitions and which modules can be used to scrape them.

Raises:

InvalidLeagueException – If the league is not a valid league for this module.

Returns:

List of valid year strings for this league

Return type:

list[str]

scrape_all_teams_data(year: str, league: str, as_df: bool = False) → dict

Scrapes data for all teams in the given league season.

Parameters:

  • year (str) – See the Understat year parameter docs for details.

  • league (str) – See the src/ScraperFC/comps.yaml file for all available competitions and which modules can be used to scrape them.

  • as_df (bool) – If True, each team’s data will be returned as dataframes. If False, return dicts. Defaults to False.

Returns:

Dictionary of team data, where each key is a team link and the value is a dict of team data.

Return type:

dict

scrape_home_away_tables(year: str, league: str, normalize: bool = False) → None

Deprecated. Use scrape_league_tables() instead.

scrape_league_tables(year: str, league: str) → tuple[DataFrame, DataFrame, DataFrame]

Scrapes the league table for the chosen league season.

Parameters:

  • year (str) – See the Understat year parameter docs for details.

  • league (str) – See the src/ScraperFC/comps.yaml file for all available competitions and which modules can be used to scrape them.

Returns:

Tuple of league table, home table, and away table DataFrames

Return type:

tuple[pd.DataFrame, pd.DataFrame, pd.DataFrame]

scrape_match(link: str, as_df: bool = False) → tuple[dict | DataFrame, dict | DataFrame, dict | DataFrame]

Scrapes a single match from Understat.

Parameters:

  • link (str) – URL to the match

  • as_df (bool) – If True, will return the data as DataFrames. If False, data will be returned as dicts. Defaults to False.

Raises:

TypeError – If any of the parameters are the wrong type

Returns:

Tuple of (shots_data, match_info, rosters_data)

Return type:

tuple[dict | pd.DataFrame, dict | pd.DataFrame, dict | pd.DataFrame]

scrape_matches(year: str, league: str, as_df: bool = False) → dict

Scrapes all of the matches from the chosen league season.

Gathers all match links from the chosen league season and then calls scrape_match() on each one.

Parameters:

  • year (str) – See the Understat year parameter docs for details.

  • league (str) – See the src/ScraperFC/comps.yaml file for all available competitions and which modules can be used to scrape them.

  • as_df (bool) – If True, the data for each match will be returned as DataFrames. If False, individual match data will be returned as dicts. Defaults to False.

Returns:

Dictionary of match data, where each key is a match link and the value is a dict of match data.

Return type:

dict

scrape_season_data(year: str, league: str) → tuple[dict, dict, dict]

Scrapes data for chosen Understat league season.

Parameters:

  • year (str) – See the Understat year parameter docs for details.

  • league (str) – See the src/ScraperFC/comps.yaml file for all available competitions and which modules can be used to scrape them.

Returns:

Tuple of (matches_data, teams_data, players_data)

Return type:

tuple[dict, dict, dict]

scrape_shot_xy(year: str, league: str, as_df: bool = False) → None

Deprecated. Use scrape_matches() instead.

scrape_team_data(team_link: str, as_df: bool = False) → tuple[dict | DataFrame, dict | DataFrame, dict | DataFrame]

Scrapes team data from a team’s Understat link

Note that for Understat, team links are season-specific.

Parameters:

  • team_link (str) – URL to the team’s Understat page

  • as_df (bool) – If True, data will be returned as dataframes. If False, dicts. Defaults to False.

Returns:

Tuple of (matches_data, team_data, player_data)

Raises:

TypeError – If any of the parameters are the wrong type

Return type:

tuple[dict | pd.DataFrame, dict | pd.DataFrame, dict | pd.DataFrame]