Overview

This package is designed to allow users to extract various world football results and player statistics from the following popular football (soccer) data sites:

Installation

You can install the worldfootballR package from github with:

# install.packages("devtools")
devtools::install_github("JaseZiv/worldfootballR")

Usage

Package vignettes have been built to help you get started with the package.

  • For functions to extract data from FBref, see here
  • For functions to extract data from Transfermarkt, see here
  • For functions to extract data from Understat, see here
  • For functions to extract data for international matches from FBref, see here

This vignette will cover the functions to extract data from FBref.com.


Join FBref and Transfermarkt data

To be able to join data player between FBref and Transfermarkt, player_dictionary_mapping() has been created. There are over 6,100 players who have been listed for teams in the Big 5 Euro leagues on FBref since the start of the 2017-18 seasons, with all of these mapped together. This is expected to be updated and grow over time. The raw data is stored here

mapped_players <- player_dictionary_mapping()
dplyr::glimpse(mapped_players)
#> Rows: 6,300
#> Columns: 4
#> $ PlayerFBref <chr> "Aaron Connolly", "Aaron Cresswell", "Aarón Escandell", "A…
#> $ UrlFBref    <chr> "https://fbref.com/en/players/27c01749/Aaron-Connolly", "h…
#> $ UrlTmarkt   <chr> "https://www.transfermarkt.com/aaron-connolly/profil/spiel…
#> $ TmPos       <chr> "Centre-Forward", "Left-Back", "Goalkeeper", "Attacking Mi…

FBref Helper Functions

The following section will outline the various functions available to find different URLs to be able to pass through the FBref suite of functions outlined in this vignette.

League URLs

To extract the URL of any country’s league(s) (provided fbref have data for the league), use the fb_league_urls() function.

This function also accepts a tier argument. for first-tier leagues, select ‘1st’, for second-tier select ‘2nd’ and so on.

A fill list of countries available can be found in the worldfootballR_data repository and can be found here.

fb_league_urls(country = "ENG", gender = "M", season_end_year = 2021, tier = '2nd')

Team URLs

To get a list of URLs for each team in a particular season, the fb_teams_urls() function can be used:

fb_teams_urls("https://fbref.com/en/comps/9/Premier-League-Stats")

Player URLs

To get a list of player URLs for a particular team, the fb_player_urls() function can be used. The results of this output can be passed through to the player season stat functions fb_player_season_stats() and fb_player_scouting_report().

fb_player_urls("https://fbref.com/en/squads/fd962109/Fulham-Stats")

Get match urls

To get the match URLs needed to pass in to some of the match-level functions below, get_match_urls() can be used:

epl_2021_urls <- get_match_urls(country = "ENG", gender = "M", season_end_year = 2021, tier="1st")

League Season-Level Data

This section will cover the functions to aid in the extraction of season team statistics.

Get Season Team Stats

The get_season_team_stats function allows the user to return a data frame of different stat types for all teams in Domestic leagues here.

Note, some stats may not be available for all leagues. The big five European leagues should have all of these stats.

The following stat types can be selected:

  • league_table
  • league_table_home_away
  • standard
  • keeper
  • keeper_adv
  • shooting
  • passing
  • passing_types
  • goal_shot_creation
  • defense
  • possession
  • playing_time
  • misc
# function to extract season teams stats
prem_2020_shooting <- get_season_team_stats(country = "ENG", gender = "M", season_end_year = "2020", tier = "1st", stat_type = "shooting")
# to get shooting stats for the English Championship:
championship_2020_shooting <- get_season_team_stats(country = "ENG", gender = "M", season_end_year = "2020", tier = "2nd", stat_type = "shooting")

More than one league season

The get_season_team_stats function can be used to get data for multiple seasons/leagues/genders/etc.

Important to note, this function can only be used for one stat-type at a time, however all other parameters can have multiple values:

big_5_2020_possessions <- get_season_team_stats(country = c("ENG", "ESP", "ITA", "GER", "FRA"),
                                        gender = "M", season_end_year = 2020, tier = "1st", stat_type = "possession")

The Big 5 Euro Leagues

The fb_big5_advanced_season_stats() function allows users to extract data for any of the below listed stat types for all teams of the big five European leagues (EPL, La Liga, Ligue 1, Serie A, Bundesliga).

The stat types available for this function are below:

  • standard
  • shooting
  • passing
  • passing_types
  • gca
  • defense
  • possession
  • playing_time
  • misc
  • keepers
  • keepers_adv

The function also accepts a season or seasons and whether you want data for the player, or team.

Note that when selecting team_or_player="team", results will be returned for both the team’s for and against stats. To filter on this, use the Team_or_Opponent column in the resulting data frame, selecting ‘team’ if you want the team’s for stats, or ‘opponent’ if you want the team’s against stats.

big5_team_shooting <- fb_big5_advanced_season_stats(season_end_year= c(2019:2021), stat_type= "shooting", team_or_player= "team")

Match-Level Data

The following sections outlines the functions available to extract data at the per-match level

Get match results

To get the match results (and additional metadata) for all leagues and comps listed here, the following function can be used:

# function to extract Serie A match results data
serieA_2020 <- get_match_results(country = "ITA", gender = "M", season_end_year = 2020, tier = "1st")

The function can also be used to return match URLs for a non-domestic league season. To use this functionality, simply leave country = '' and pass the non-domestic league URL, which can be found at https://fbref.com/en/comps/

# for international friendlies:
get_match_results(country = "", gender = "M", season_end_year = 2018, tier = "", non_dom_league_url = "https://fbref.com/en/comps/218/history/Friendlies-M-Seasons")

More than one league season

The get_match_results() function can be used to get data for multiple seasons/leagues/genders/etc also:

big_5_2020_results <- get_match_results(country = c("ENG", "ESP", "ITA", "GER", "FRA"),
                                        gender = "M", season_end_year = 2020, tier = "1st")

Get match report

This function will return similar results to that of get_match_results(), however get_match_report() will provide some additional information. It will also only provide it for a single match, not the whole season:

# function to extract match report data
liv_mci_2020 <- get_match_report(match_url = "https://fbref.com/en/matches/47880eb7/Liverpool-Manchester-City-November-10-2019-Premier-League")

Get match summaries

This function will return the main events that occur during a match, including goals, substitutions and red/yellow cards:

# function to extract match summary data
liv_mci_2020_summary <- get_match_summary(match_url = "https://fbref.com/en/matches/47880eb7/Liverpool-Manchester-City-November-10-2019-Premier-League")

Get match lineups

This function will return a dataframe of all players listed for that match, including whether they started on the pitch, or on the bench.

From version 0.2.7, this function now also returns some summary performance data for each player that played, including their position, minutes played, goals, cards, etc.

# function to extract match lineups
liv_mci_2020_lineups <- get_match_lineups(match_url = "https://fbref.com/en/matches/47880eb7/Liverpool-Manchester-City-November-10-2019-Premier-League")

Get shooting and shot creation events

The below function allows users to extract shooting and shot creation event data for a match or selected matches. The data returned includes who took the shot, when, with which body part and from how far away. Additionally, the player creating the chance and also the creation before this are included in the data.

shot_one_match <- get_match_shooting(match_url = "https://fbref.com/en/matches/a3eb7a37/Sheffield-United-Wolverhampton-Wanderers-September-14-2020-Premier-League")

test_urls_multiple <- c("https://fbref.com/en/matches/c0996cac/Bordeaux-Nantes-August-21-2020-Ligue-1",
                        "https://fbref.com/en/matches/9cbccb37/Dijon-Angers-August-22-2020-Ligue-1",
                        "https://fbref.com/en/matches/f96cd5a0/Lorient-Strasbourg-August-23-2020-Ligue-1")
shot_multiple_matches <- get_match_shooting(test_urls_multiple)

Get advanced match statistics

The get_advanced_match_stats() function allows the user to return a data frame of different stat types for matches played.

Note, some stats may not be available for all leagues. The big five European leagues should have all of these stats.

The following stat types can be selected:

  • summary
  • passing
  • passing_types
  • defense
  • possession
  • misc
  • keeper

The function can be used for either all players individually:

test_urls_multiple <- c("https://fbref.com/en/matches/c0996cac/Bordeaux-Nantes-August-21-2020-Ligue-1",
                        "https://fbref.com/en/matches/9cbccb37/Dijon-Angers-August-22-2020-Ligue-1",
                        "https://fbref.com/en/matches/f96cd5a0/Lorient-Strasbourg-August-23-2020-Ligue-1")

advanced_match_stats <- get_advanced_match_stats(match_url = test_urls_multiple, stat_type = "possession", team_or_player = "player")

Or used for the team totals for each match:

test_urls_multiple <- c("https://fbref.com/en/matches/c0996cac/Bordeaux-Nantes-August-21-2020-Ligue-1",
                        "https://fbref.com/en/matches/9cbccb37/Dijon-Angers-August-22-2020-Ligue-1",
                        "https://fbref.com/en/matches/f96cd5a0/Lorient-Strasbourg-August-23-2020-Ligue-1")

advanced_match_stats_team <- get_advanced_match_stats(match_url = test_urls_multiple, stat_type = "passing_types", team_or_player = "team")

Team-Level Data

This section will cover off the functions to get team-level data from FBref.

Match Results by team

To get all the results a team(s) has competed in for a season, the following function can be used. The resulting data frame output will include all game results, including any cup games played, and will accept either one, or many team URLs.

# for single teams:
man_city_2021_url <- "https://fbref.com/en/squads/b8fd03ef/Manchester-City-Stats"
man_city_2021_results <- get_team_match_results(man_city_url)
# get all team URLs for a league
epl_2021_team_urls <- fb_teams_urls("https://fbref.com/en/comps/9/Premier-League-Stats")
epl_2021_team_results <- get_team_match_results(team_url = team_urls)

Player-Level Data

This section will cover the functions available to aid in the extraction of player season data.

The examples provided below in a lot of cases have the actual url (player or team) passed to them, however the suite of fbref helper functions outlined in this helpers vignette could also be used.

Get Player Scouting Report

The fb_player_scouting_report() function takes in two inputs;

  • player_url - the URL of the player’s main page
  • pos_versus which can return the player’s comparison against players in their “primary”, OR “secondary” position

and returns the full scouting report for the player selected.

As of version 0.3.6, the function now returns the scouting report of ALL available periods, not just the “Last 365 Days”. As a result, there is now an additional column called scouting_period. This column should be used to filter out the period/season you want the scouting report for:

# TO GET THE LAST 365 DAYS REPORT:
scout <- fb_player_scouting_report(player_url = "https://fbref.com/en/players/d70ce98e/Lionel-Messi",
                                   pos_versus = "primary") %>% 
               dplyr::filter(scouting_period == "Last 365 Days")
dplyr::glimpse(fb_player_scouting_report(player_url = "https://fbref.com/en/players/d70ce98e/Lionel-Messi", pos_versus = "primary"))
#> Rows: 745
#> Columns: 8
#> $ Player          <chr> "Lionel Messi", "Lionel Messi", "Lionel Messi", "Lione…
#> $ Versus          <chr> "Forwards", "Forwards", "Forwards", "Forwards", "Forwa…
#> $ StatGroup       <chr> "Standard", "Standard", "Standard", "Standard", "Stand…
#> $ Statistic       <chr> "Goals", "Assists", "Non-Penalty Goals", "Penalty Kick…
#> $ Per90           <dbl> 0.88, 0.24, 0.80, 0.08, 0.16, 0.08, 0.00, 0.69, 0.56, …
#> $ Percentile      <dbl> 98, 84, 98, 74, 86, 70, 58, 96, 92, 98, 98, 98, 99, 99…
#> $ BasedOnMinutes  <dbl> 3393, 3393, 3393, 3393, 3393, 3393, 3393, 3393, 3393, …
#> $ scouting_period <chr> "Last 365 Days", "Last 365 Days", "Last 365 Days", "La…
dplyr::glimpse(fb_player_scouting_report(player_url = "https://fbref.com/en/players/d70ce98e/Lionel-Messi", pos_versus = "secondary"))
#> Rows: 745
#> Columns: 8
#> $ Player          <chr> "Lionel Messi", "Lionel Messi", "Lionel Messi", "Lione…
#> $ Versus          <chr> "Att Mid / Wingers", "Att Mid / Wingers", "Att Mid / W…
#> $ StatGroup       <chr> "Standard", "Standard", "Standard", "Standard", "Stand…
#> $ Statistic       <chr> "Goals", "Assists", "Non-Penalty Goals", "Penalty Kick…
#> $ Per90           <dbl> 0.88, 0.24, 0.80, 0.08, 0.16, 0.08, 0.00, 0.69, 0.56, …
#> $ Percentile      <dbl> 99, 75, 99, 87, 92, 74, 58, 99, 99, 92, 99, 99, 99, 99…
#> $ BasedOnMinutes  <dbl> 3393, 3393, 3393, 3393, 3393, 3393, 3393, 3393, 3393, …
#> $ scouting_period <chr> "Last 365 Days", "Last 365 Days", "Last 365 Days", "La…

Get Player Season Stats

The fb_player_season_stats() function allows for the extraction of season totals for selected player URLs and stat_type.

The stat_types available for use in this function are below:

  • standard
  • shooting
  • passing
  • passing_types
  • gca
  • defense
  • possession
  • playing_time
  • misc
  • keeper
  • keeper_adv
mo_shooting <- fb_player_season_stats("https://fbref.com/en/players/e342ad68/Mohamed-Salah", stat_type = 'shooting')

multiple_playing_time <- fb_player_season_stats(player_url = c("https://fbref.com/en/players/d70ce98e/Lionel-Messi",
                                                "https://fbref.com/en/players/dea698d9/Cristiano-Ronaldo"),
                                 stat_type = "playing_time")

The Big 5 Euro League Players

The fb_big5_advanced_season_stats() function allows users to extract data for any of the below listed stat types for all players of the big five European leagues (EPL, La Liga, Ligue 1, Serie A, Bundesliga).

The stat types available for this function are below:

  • standard
  • shooting
  • passing
  • passing_types
  • gca
  • defense
  • possession
  • playing_time
  • misc
  • keepers
  • keepers_adv

The function also accepts a season or seasons and whether you want data for the player, or team.

big5_player_possession <- fb_big5_advanced_season_stats(season_end_year= 2021, stat_type= "possession", team_or_player= "player")

Player Match Logs

The fb_player_match_logs() function allows the user to return a data frame of the match logs of different stat types for a player’s matches played in a season.

The following stat types can be selected, depending on the player’s position (ie a striker probably won’t have “keepers” stats):

  • summary
  • keepers
  • passing
  • passing_types
  • gca
  • defense
  • possession
  • misc
ederson_summary <- fb_player_match_logs("https://fbref.com/en/players/3bb7b8b4/Ederson", season_end_year = 2021, stat_type = 'summary')