Skip to contents

Load Scraped Data Functions

Jason Zivkovic

2025-04-06

Source: vignettes/load-scraped-data.Rmd
load-scraped-data.Rmd

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

As at 2024-06-29, we are no longer including instructions to install from CRAN. The version pushed to CRAN is very much out of date, and with very regular updates to this library, we advise installing from GitHub only.

You can install the released version of worldfootballR 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 load scraped data from the worldfootballR_data data repository.

NOTE:

As of version 0.5.2, all FBref functions now come with a user-defined pause between page loads to address their new rate limiting. See this document for more information.

Load FBref

The following section demonstrates the different loading functions of FBref data.

Load FBref match results

To load pre-scraped match results for all years the data is available, the load_match_results() function can be used. This data is scheduled to be updated most days and a print statement will inform the user of when the data was last updated. All domestic leagues are included in the data repository.

This is the load function equivalent of fb_match_results().

eng_match_results <- load_match_results(country = "ENG", gender = c("M", "F"), season_end_year = c(2020:2022), tier = "1st")
dplyr::glimpse(eng_match_results)
#> Rows: 1,536
#> Columns: 20
#> $ Competition_Name <chr> "FA Women's Super League", "FA Women's Super League",…
#> $ Gender           <chr> "F", "F", "F", "F", "F", "F", "F", "F", "F", "F", "F"…
#> $ Country          <chr> "ENG", "ENG", "ENG", "ENG", "ENG", "ENG", "ENG", "ENG…
#> $ Season_End_Year  <int> 2020, 2020, 2020, 2020, 2020, 2020, 2020, 2020, 2020,…
#> $ Round            <chr> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, N…
#> $ Wk               <chr> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, N…
#> $ Day              <chr> "Sat", "Sat", "Sun", "Sun", "Sun", "Sun", "Sun", "Sun…
#> $ Date             <date> 2019-09-07, 2019-09-07, 2019-09-08, 2019-09-08, 2019…
#> $ Time             <chr> "15:00", "15:00", "12:30", "14:00", "14:00", "14:30",…
#> $ Home             <chr> "Manchester City", "Bristol City", "Chelsea", "Birmin…
#> $ HomeGoals        <dbl> 1, 0, 1, 0, 0, 2, 0, 2, 1, 1, 1, 0, 2, 4, 0, 0, 0, 3,…
#> $ Home_xG          <dbl> 0.5, 0.4, 1.3, 0.7, 0.5, 2.6, 0.2, 1.4, 1.6, 0.4, 1.4…
#> $ Away             <chr> "Manchester Utd", "Brighton", "Tottenham", "Everton",…
#> $ AwayGoals        <dbl> 0, 0, 0, 1, 1, 1, 2, 0, 0, 1, 0, 1, 0, 0, 1, 2, 4, 0,…
#> $ Away_xG          <dbl> 1.1, 2.1, 0.3, 0.8, 1.0, 0.8, 2.3, 1.0, 0.3, 1.7, 0.9…
#> $ Attendance       <dbl> 31213, 3041, 24564, 873, 1445, 1795, 897, 441, 996, 1…
#> $ Venue            <chr> "Etihad Stadium", "Stoke Gifford Stadium", "Stamford …
#> $ Referee          <chr> "Rebecca Welch", "Abigail Bryne", "Jack Packman", "El…
#> $ Notes            <chr> "", "", "", "", "", "", "", "", "", "", "", "", "", "…
#> $ MatchURL         <chr> "https://fbref.com/en/matches/f116cea0/Manchester-Der…

Load FBref match results for Cups and International Comps

Similarly, to load pre-scraped match results for cups and international matches in all years the data is available, the load_match_comp_results() function can be used. This data is scheduled to be updated most days and a print statement will inform the user of when the data was last updated.

The following list of competitions (comp_name) are available:

#>  [1] "AFC Asian Cup"                                               
#>  [2] "AFC Asian Cup qualification"                                 
#>  [3] "AFC Women's Asian Cup"                                       
#>  [4] "AFC Women's Asian Cup Qualification"                         
#>  [5] "Africa Cup of Nations"                                       
#>  [6] "Africa Cup of Nations qualification"                         
#>  [7] "Africa Women Cup of Nations"                                 
#>  [8] "Algarve Cup"                                                 
#>  [9] "CONCACAF Gold Cup"                                           
#> [10] "CONCACAF W Championship"                                     
#> [11] "CONMEBOL Copa América"                                       
#> [12] "Copa América Femenina"                                       
#> [13] "Copa CONMEBOL Sudamericana"                                  
#> [14] "Copa Libertadores de América"                                
#> [15] "Copa de la Liga Profesional"                                 
#> [16] "Copa del Rey"                                                
#> [17] "Coppa Italia"                                                
#> [18] "Coupe de France"                                             
#> [19] "Coupe de la Ligue"                                           
#> [20] "DFB-Pokal"                                                   
#> [21] "DFB-Pokal Frauen"                                            
#> [22] "EFL Cup"                                                     
#> [23] "FA Cup"                                                      
#> [24] "FIFA Confederations Cup"                                     
#> [25] "FIFA Women's World Cup"                                      
#> [26] "FIFA Women's World Cup Qualification (UEFA)"                 
#> [27] "FIFA World Cup"                                              
#> [28] "FIFA World Cup Qualification — AFC"                          
#> [29] "FIFA World Cup Qualification — CAF"                          
#> [30] "FIFA World Cup Qualification — CONCACAF"                     
#> [31] "FIFA World Cup Qualification — CONMEBOL"                     
#> [32] "FIFA World Cup Qualification — Inter-confederation play-offs"
#> [33] "FIFA World Cup Qualification — OFC"                          
#> [34] "FIFA World Cup Qualification — UEFA"                         
#> [35] "International Friendlies (M)"                                
#> [36] "International Friendlies (W)"                                
#> [37] "Lamar Hunt U.S. Open Cup"                                    
#> [38] "NWSL Challenge Cup"                                          
#> [39] "NWSL Fall Series"                                            
#> [40] "OFC Nations Cup"                                             
#> [41] "OFC Women's Nations Cup"                                     
#> [42] "Olympics — Women's Tournament"                               
#> [43] "SheBelieves Cup"                                             
#> [44] "UEFA Champions League"                                       
#> [45] "UEFA Conference League"                                      
#> [46] "UEFA Europa League"                                          
#> [47] "UEFA European Football Championship"                         
#> [48] "UEFA European Football Championship Qualifying"              
#> [49] "UEFA Nations League"                                         
#> [50] "UEFA Women's Champions League"                               
#> [51] "UEFA Women's Championship"                                   
#> [52] "UEFA Women's Euro Qualification"
cups <- c("FIFA Women's World Cup","FIFA World Cup")
world_cups <- load_match_comp_results(comp_name = cups)
dplyr::glimpse(world_cups)
#> Rows: 1,312
#> Columns: 20
#> $ Competition_Name <chr> "FIFA Women's World Cup", "FIFA Women's World Cup", "…
#> $ Gender           <chr> "F", "F", "F", "F", "F", "F", "F", "F", "F", "F", "F"…
#> $ Country          <chr> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, N…
#> $ Season_End_Year  <int> 1991, 1991, 1991, 1991, 1991, 1991, 1991, 1991, 1991,…
#> $ Round            <chr> "Group stage", "Group stage", "Group stage", "Group s…
#> $ Wk               <chr> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, N…
#> $ Day              <chr> "Sat", "Sun", "Sun", "Sun", "Sun", "Sun", "Tue", "Tue…
#> $ Date             <date> 1991-11-16, 1991-11-17, 1991-11-17, 1991-11-17, 1991…
#> $ Time             <chr> "20:45", "15:30", "19:45", "19:45", "19:45", "19:45",…
#> $ Home             <chr> "China PR cn", "Germany de", "Japan jp", "Chinese Tai…
#> $ HomeGoals        <dbl> 4, 4, 0, 0, 2, 3, 4, 1, 0, 0, 0, 2, 0, 0, 4, 2, 2, 0,…
#> $ Home_xG          <dbl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, N…
#> $ Away             <chr> "no Norway", "ng Nigeria", "br Brazil", "it Italy", "…
#> $ AwayGoals        <dbl> 0, 0, 1, 5, 3, 0, 0, 0, 3, 5, 8, 2, 3, 2, 1, 0, 1, 2,…
#> $ Away_xG          <dbl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, N…
#> $ Attendance       <dbl> 65000, 14000, 14000, 11000, 14000, 14000, 12000, 1200…
#> $ Venue            <chr> "Tianhe Stadium (Neutral Site)", "Jiangmen Stadium (N…
#> $ Referee          <chr> "Salvador Imperatore Marcone", "Rafael Rodriguez", "L…
#> $ Notes            <chr> "", "", "", "", "", "", "", "", "", "", "", "", "", "…
#> $ MatchURL         <chr> "https://fbref.com/en/matches/0d9e0f26/China-PR-Norwa…

Load FBref big 5 league advanced season stats

To load pre-scraped advanced stats for the big five European leagues for either teams or players, the load_fb_big5_advanced_season_stats() can be used. This data is scheduled to be updated most days and a print statement will inform the user of when the data was last updated.

This is the load function equivalent of fb_big5_advanced_season_stats().

all_season_player <- load_fb_big5_advanced_season_stats(stat_type = "defense", team_or_player = "player")
current_season_player <- load_fb_big5_advanced_season_stats(season_end_year = 2022, stat_type = "defense", team_or_player = "player")

all_season_team <- load_fb_big5_advanced_season_stats(stat_type = "defense", team_or_player = "team")
current_season_team <- load_fb_big5_advanced_season_stats(season_end_year = 2022, stat_type = "defense", team_or_player = "team")

Load FBref match shooting

load_fb_match_shooting() can be used to load pre-scraped match shooting logs from FBref. This is the load function equivalent of fb_match_shooting(). Only a handful of leagues are supported.

## 2018 - current season for EPL
epl_match_shooting <- load_fb_match_shooting(
  country = "ENG",
  gender = "M",
  tier = "1st"
)
dplyr::glimpse(epl_match_shooting)
#> Rows: 73,903
#> Columns: 23
#> $ MatchURL         <chr> "https://fbref.com/en/matches/2df9a3a1/Aston-Villa-Br…
#> $ Date             <chr> "2023-09-30", "2023-09-30", "2023-09-30", "2023-09-30…
#> $ Squad            <chr> "Aston Villa", "Aston Villa", "Aston Villa", "Aston V…
#> $ Home_Away        <chr> "Home", "Home", "Home", "Home", "Home", "Home", "Home…
#> $ Match_Half       <dbl> 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 2, 2, 2, 2,…
#> $ Minute           <chr> "11", "14", "17", "17", "21", "23", "26", "26", "37",…
#> $ Player           <chr> "Moussa Diaby", "Ollie Watkins", "Ollie Watkins", "Ol…
#> $ Player_Href      <chr> "/en/players/aeed5c06/Moussa-Diaby", "/en/players/aed…
#> $ xG               <chr> "0.03", "0.37", "0.05", "0.04", "0.09", "0.03", "0.17…
#> $ PSxG             <chr> "", "0.93", "", "", "0.39", "0.43", "0.04", "", "", "…
#> $ Outcome          <chr> "Blocked", "Goal", "Blocked", "Off Target", "Goal", "…
#> $ Distance         <chr> "31", "8", "16", "17", "15", "12", "16", "14", "26", …
#> $ `Body Part`      <chr> "Left Foot", "Left Foot", "Left Foot", "Right Foot", …
#> $ Notes            <chr> "", "", "", "", "", "", "", "", "Free kick", "Volley"…
#> $ Player_SCA_1     <chr> "", "Matty Cash", "John McGinn", "Ollie Watkins", "Ol…
#> $ Event_SCA_1      <chr> "", "Pass (Live)", "Pass (Live)", "Shot", "Take-On", …
#> $ Player_SCA_2     <chr> "", "John McGinn", "", "", "Moussa Diaby", "Nicolò Za…
#> $ Event_SCA_2      <chr> "", "Pass (Live)", "", "", "Pass (Live)", "Pass (Live…
#> $ Competition_Name <chr> "Premier League", "Premier League", "Premier League",…
#> $ Gender           <chr> "M", "M", "M", "M", "M", "M", "M", "M", "M", "M", "M"…
#> $ Country          <chr> "ENG", "ENG", "ENG", "ENG", "ENG", "ENG", "ENG", "ENG…
#> $ Tier             <chr> "1st", "1st", "1st", "1st", "1st", "1st", "1st", "1st…
#> $ Season_End_Year  <int> 2024, 2024, 2024, 2024, 2024, 2024, 2024, 2024, 2024,…

## just 2019, for multiple leagues at the same time
multiple_match_shooting_2019 <- load_fb_match_shooting(
  country = c("ITA", "FRA"),
  gender = "M",
  tier = "1st",
  season_end_year = 2019
)
dplyr::glimpse(multiple_match_shooting_2019)
#> Rows: 19,967
#> Columns: 23
#> $ MatchURL         <chr> "https://fbref.com/en/matches/2758c0c0/Chievo-Juventu…
#> $ Date             <chr> "2018-08-18", "2018-08-18", "2018-08-18", "2018-08-18…
#> $ Squad            <chr> "Chievo", "Chievo", "Chievo", "Chievo", "Chievo", "Ch…
#> $ Home_Away        <chr> "Home", "Home", "Home", "Home", "Home", "Home", "Away…
#> $ Match_Half       <dbl> 1, 1, 1, 2, 2, 2, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1,…
#> $ Minute           <chr> "15", "22", "38", "56", "67", "84", "3", "5", "6", "9…
#> $ Player           <chr> "Ivan Radovanović", "Ivan Radovanović", "Mariusz Stęp…
#> $ Player_Href      <chr> "/en/players/023937a9/Ivan-Radovanovic", "/en/players…
#> $ xG               <chr> "0.02", "0.02", "0.23", "0.79", "0.03", "0.02", "0.20…
#> $ PSxG             <chr> "", "", "0.50", "0.98", "", "", "0.19", "0.13", "", "…
#> $ Outcome          <chr> "Off Target", "Off Target", "Goal", "Goal", "Off Targ…
#> $ Distance         <chr> "30", "28", "12", "13", "28", "28", "9", "22", "10", …
#> $ `Body Part`      <chr> "Right Foot", "Right Foot", "Head", "Right Foot", "Le…
#> $ Notes            <chr> "", "", "", "", "", "", "", "", "", "", "", "", "", "…
#> $ Player_SCA_1     <chr> "Fabio Depaoli", "Fabrizio Cacciatore", "Emanuele Gia…
#> $ Event_SCA_1      <chr> "Pass (Live)", "Pass (Live)", "Pass (Live)", "Fouled"…
#> $ Player_SCA_2     <chr> "Ivan Radovanović", "Emanuele Giaccherini", "Fabrizio…
#> $ Event_SCA_2      <chr> "Pass (Live)", "Pass (Live)", "Pass (Live)", "Pass (L…
#> $ Competition_Name <chr> "Serie A", "Serie A", "Serie A", "Serie A", "Serie A"…
#> $ Gender           <chr> "M", "M", "M", "M", "M", "M", "M", "M", "M", "M", "M"…
#> $ Country          <chr> "ITA", "ITA", "ITA", "ITA", "ITA", "ITA", "ITA", "ITA…
#> $ Tier             <chr> "1st", "1st", "1st", "1st", "1st", "1st", "1st", "1st…
#> $ Season_End_Year  <int> 2019, 2019, 2019, 2019, 2019, 2019, 2019, 2019, 2019,…

Load FBref match summary

load_fb_match_summary() can be used to load pre-scraped match summaries from FBref. This is the load function equivalent of fb_match_summary(). Only a handful of leagues are supported.

## 2018 - current season for EPL
epl_match_summary <- load_fb_match_summary(
  country = "ENG",
  gender = "M",
  tier = "1st"
)
dplyr::glimpse(epl_match_summary)
#> Rows: 0
#> Columns: 0

## just 2019, for multiple leagues at the same time
multiple_match_summary_2019 <- load_fb_match_summary(
  country = c("ITA", "FRA"),
  gender = "M",
  tier = "1st",
  season_end_year = 2019
)
dplyr::glimpse(multiple_match_summary_2019)
#> Rows: 9,739
#> Columns: 33
#> $ MatchURL          <chr> "https://fbref.com/en/matches/2758c0c0/Chievo-Juvent…
#> $ League            <chr> "Serie A", "Serie A", "Serie A", "Serie A", "Serie A…
#> $ Match_Date        <chr> "2018-08-18", "2018-08-18", "2018-08-18", "2018-08-1…
#> $ Matchweek         <chr> "Serie A (Matchweek 1)", "Serie A (Matchweek 1)", "S…
#> $ Home_Team         <chr> "Chievo", "Chievo", "Chievo", "Chievo", "Chievo", "C…
#> $ Home_Formation    <chr> "4-3-3", "4-3-3", "4-3-3", "4-3-3", "4-3-3", "4-3-3"…
#> $ Home_Score        <dbl> 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 1, 1, 1, 1, 1…
#> $ Home_xG           <dbl> 1.1, 1.1, 1.1, 1.1, 1.1, 1.1, 1.1, 1.1, 1.1, 1.1, 1.…
#> $ Home_Goals        <chr> "Mariusz Stępiński · 38&rsquor; Emanuele Giaccherini…
#> $ Home_Yellow_Cards <chr> "2", "2", "2", "2", "2", "2", "2", "2", "2", "2", "2…
#> $ Home_Red_Cards    <chr> "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0…
#> $ Away_Team         <chr> "Juventus", "Juventus", "Juventus", "Juventus", "Juv…
#> $ Away_Formation    <chr> "4-2-3-1", "4-2-3-1", "4-2-3-1", "4-2-3-1", "4-2-3-1…
#> $ Away_Score        <dbl> 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 2, 2, 2, 2, 2…
#> $ Away_xG           <dbl> 3.1, 3.1, 3.1, 3.1, 3.1, 3.1, 3.1, 3.1, 3.1, 3.1, 3.…
#> $ Away_Goals        <chr> "Sami Khedira · 3&rsquor; Mattia Bani (OG) · 75&rsqu…
#> $ Away_Yellow_Cards <chr> "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0…
#> $ Away_Red_Cards    <chr> "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "0…
#> $ Game_URL          <chr> "https://fbref.com/en/matches/2758c0c0/Chievo-Juvent…
#> $ Team              <chr> "Juventus", "Chievo", "Chievo", "Juventus", "Chievo"…
#> $ Home_Away         <chr> "Away", "Home", "Home", "Away", "Home", "Away", "Hom…
#> $ Event_Time        <dbl> 3, 38, 56, 56, 60, 64, 66, 75, 78, 84, 91, 93, 95, 2…
#> $ Is_Pens           <lgl> FALSE, FALSE, FALSE, FALSE, FALSE, FALSE, FALSE, FAL…
#> $ Event_Half        <dbl> 1, 1, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 1, 1, 2, 2, 2…
#> $ Event_Type        <chr> "Goal", "Goal", "Penalty", "Substitute", "Yellow Car…
#> $ Event_Players     <chr> "Sami Khedira Assist: Giorgio Chiellini", "Mariusz S…
#> $ Score_Progression <chr> "0:1", "1:1", "2:1", "2:1", "2:1", "2:1", "2:1", "2:…
#> $ Penalty_Number    <dbl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, …
#> $ Competition_Name  <chr> "Serie A", "Serie A", "Serie A", "Serie A", "Serie A…
#> $ Gender            <chr> "M", "M", "M", "M", "M", "M", "M", "M", "M", "M", "M…
#> $ Country           <chr> "ITA", "ITA", "ITA", "ITA", "ITA", "ITA", "ITA", "IT…
#> $ Tier              <chr> "1st", "1st", "1st", "1st", "1st", "1st", "1st", "1s…
#> $ Season_End_Year   <int> 2019, 2019, 2019, 2019, 2019, 2019, 2019, 2019, 2019…

Load FBref advanced match stats

load_fb_advanced_match_stats() can be used to load pre-scraped match summaries from FBref. This is the load function equivalent of fb_advanced_match_stats(). Not all leagues and stat types are supported.

## 2018 - current season for EPL
epl_summary_player_match_stats <- load_fb_advanced_match_stats(
  country = "ENG",
  gender = "M",
  tier = "1st",
  stat_type = "summary",
  team_or_player = "player"
)
dplyr::glimpse(epl_summary_player_match_stats)
#> Rows: 7,246
#> Columns: 58
#> $ MatchURL           <chr> "https://fbref.com/en/matches/cc5b4244/Manchester-U…
#> $ League             <chr> "Premier League", "Premier League", "Premier League…
#> $ Match_Date         <chr> "2024-08-16", "2024-08-16", "2024-08-16", "2024-08-…
#> $ Matchweek          <chr> "Premier League (Matchweek 1)", "Premier League (Ma…
#> $ Home_Team          <chr> "Manchester United", "Manchester United", "Manchest…
#> $ Home_Formation     <chr> "4-2-3-1", "4-2-3-1", "4-2-3-1", "4-2-3-1", "4-2-3-…
#> $ Home_Score         <chr> "1", "1", "1", "1", "1", "1", "1", "1", "1", "1", "…
#> $ Home_xG            <dbl> 2.4, 2.4, 2.4, 2.4, 2.4, 2.4, 2.4, 2.4, 2.4, 2.4, 2…
#> $ Home_Goals         <chr> "Joshua Zirkzee · 87&rsquor;", "Joshua Zirkzee · 87…
#> $ Home_Yellow_Cards  <chr> "2", "2", "2", "2", "2", "2", "2", "2", "2", "2", "…
#> $ Home_Red_Cards     <chr> "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "…
#> $ Away_Team          <chr> "Fulham", "Fulham", "Fulham", "Fulham", "Fulham", "…
#> $ Away_Formation     <chr> "4-2-3-1", "4-2-3-1", "4-2-3-1", "4-2-3-1", "4-2-3-…
#> $ Away_Score         <chr> "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "…
#> $ Away_xG            <dbl> 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0…
#> $ Away_Goals         <chr> "", "", "", "", "", "", "", "", "", "", "", "", "",…
#> $ Away_Yellow_Cards  <chr> "3", "3", "3", "3", "3", "3", "3", "3", "3", "3", "…
#> $ Away_Red_Cards     <chr> "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "…
#> $ Game_URL           <chr> "https://fbref.com/en/matches/cc5b4244/Manchester-U…
#> $ Team               <chr> "Manchester United", "Manchester United", "Manchest…
#> $ Home_Away          <chr> "Home", "Home", "Home", "Home", "Home", "Home", "Ho…
#> $ Player             <chr> "Bruno Fernandes", "Marcus Rashford", "Amad Diallo"…
#> $ Player_Href        <chr> "/en/players/507c7bdf/Bruno-Fernandes", "/en/player…
#> $ Player_Num         <chr> "8", "10", "16", "17", "7", "11", "37", "39", "18",…
#> $ Nation             <chr> "POR", "ENG", "CIV", "ARG", "ENG", "NED", "ENG", "S…
#> $ Pos                <chr> "FW,AM", "LW", "RW", "RW", "AM", "FW", "DM", "DM", …
#> $ Age                <chr> "29-343", "26-290", "22-036", "20-046", "25-219", "…
#> $ Min                <chr> "90", "90", "60", "30", "60", "30", "83", "7", "90"…
#> $ Gls                <chr> "0", "0", "0", "0", "0", "1", "0", "0", "0", "0", "…
#> $ Ast                <chr> "0", "0", "0", "1", "0", "0", "0", "0", "0", "0", "…
#> $ PK                 <chr> "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "…
#> $ PKatt              <chr> "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "…
#> $ Sh                 <chr> "6", "0", "0", "2", "1", "1", "1", "0", "3", "0", "…
#> $ SoT                <chr> "3", "0", "0", "0", "1", "1", "0", "0", "0", "0", "…
#> $ CrdY               <chr> "0", "0", "0", "0", "1", "0", "0", "0", "0", "0", "…
#> $ CrdR               <chr> "0", "0", "0", "0", "0", "0", "0", "0", "0", "0", "…
#> $ Touches            <chr> "70", "43", "36", "19", "23", "12", "55", "4", "77"…
#> $ Tkl                <chr> "2", "0", "1", "1", "3", "0", "3", "0", "4", "2", "…
#> $ Int                <chr> "0", "1", "2", "0", "0", "0", "5", "0", "1", "1", "…
#> $ Blocks             <chr> "0", "1", "0", "0", "0", "1", "0", "0", "5", "1", "…
#> $ xG_Expected        <dbl> 1.2, 0.0, 0.0, 0.7, 0.3, 0.1, 0.0, 0.0, 0.2, 0.0, 0…
#> $ npxG_Expected      <dbl> 1.2, 0.0, 0.0, 0.7, 0.3, 0.1, 0.0, 0.0, 0.2, 0.0, 0…
#> $ xAG_Expected       <dbl> 0.0, 0.7, 0.1, 0.2, 0.1, 0.0, 0.0, 0.0, 1.0, 0.0, 0…
#> $ SCA_SCA            <chr> "2", "1", "1", "3", "3", "1", "1", "0", "5", "1", "…
#> $ GCA_SCA            <chr> "0", "0", "0", "1", "0", "0", "0", "0", "1", "0", "…
#> $ Cmp_Passes         <chr> "43", "22", "28", "10", "11", "8", "37", "4", "44",…
#> $ Att_Passes         <chr> "60", "30", "33", "11", "15", "9", "41", "4", "57",…
#> $ Cmp_percent_Passes <dbl> 71.7, 73.3, 84.8, 90.9, 73.3, 88.9, 90.2, 100.0, 77…
#> $ PrgP_Passes        <chr> "6", "2", "1", "0", "1", "1", "5", "0", "4", "3", "…
#> $ Carries_Carries    <chr> "50", "34", "22", "11", "16", "6", "39", "3", "46",…
#> $ PrgC_Carries       <chr> "7", "2", "0", "2", "0", "0", "0", "0", "0", "1", "…
#> $ Att_Take_Ons       <chr> "1", "6", "1", "2", "2", "0", "5", "0", "1", "1", "…
#> $ Succ_Take_Ons      <chr> "1", "0", "1", "0", "0", "0", "4", "0", "0", "1", "…
#> $ Competition_Name   <chr> "Premier League", "Premier League", "Premier League…
#> $ Gender             <chr> "M", "M", "M", "M", "M", "M", "M", "M", "M", "M", "…
#> $ Country            <chr> "ENG", "ENG", "ENG", "ENG", "ENG", "ENG", "ENG", "E…
#> $ Tier               <chr> "1st", "1st", "1st", "1st", "1st", "1st", "1st", "1…
#> $ Season_End_Year    <int> 2025, 2025, 2025, 2025, 2025, 2025, 2025, 2025, 202…

## just 2019, for multiple leagues at the same time
multiple_defense_player_match_stats_2019 <- load_fb_advanced_match_stats(
  country = c("ITA", "FRA"),
  gender = "M",
  tier = "1st",
  season_end_year = 2019,
  stat_type = "defense",
  team_or_player = "player"
)
dplyr::glimpse(multiple_defense_player_match_stats_2019)
#> Rows: 21,107
#> Columns: 57
#> $ MatchURL               <chr> "https://fbref.com/en/matches/2758c0c0/Chievo-J…
#> $ League                 <chr> "Serie A", "Serie A", "Serie A", "Serie A", "Se…
#> $ Match_Date             <chr> "2018-08-18", "2018-08-18", "2018-08-18", "2018…
#> $ Matchweek              <chr> "Serie A (Matchweek 1)", "Serie A (Matchweek 1)…
#> $ Home_Team              <chr> "Chievo", "Chievo", "Chievo", "Chievo", "Chievo…
#> $ Home_Formation         <chr> "4-3-3", "4-3-3", "4-3-3", "4-3-3", "4-3-3", "4…
#> $ Home_Score             <chr> "2", "2", "2", "2", "2", "2", "2", "2", "2", "2…
#> $ Home_xG                <dbl> 1.1, 1.1, 1.1, 1.1, 1.1, 1.1, 1.1, 1.1, 1.1, 1.…
#> $ Home_Goals             <chr> "Mariusz Stępiński · 38&rsquor; Emanuele Giacch…
#> $ Home_Yellow_Cards      <chr> "2", "2", "2", "2", "2", "2", "2", "2", "2", "2…
#> $ Home_Red_Cards         <chr> "0", "0", "0", "0", "0", "0", "0", "0", "0", "0…
#> $ Away_Team              <chr> "Juventus", "Juventus", "Juventus", "Juventus",…
#> $ Away_Formation         <chr> "4-2-3-1", "4-2-3-1", "4-2-3-1", "4-2-3-1", "4-…
#> $ Away_Score             <chr> "3", "3", "3", "3", "3", "3", "3", "3", "3", "3…
#> $ Away_xG                <dbl> 3.1, 3.1, 3.1, 3.1, 3.1, 3.1, 3.1, 3.1, 3.1, 3.…
#> $ Away_Goals             <chr> "Sami Khedira · 3&rsquor; Mattia Bani (OG) · 75…
#> $ Away_Yellow_Cards      <chr> "0", "0", "0", "0", "0", "0", "0", "0", "0", "0…
#> $ Away_Red_Cards         <chr> "0", "0", "0", "0", "0", "0", "0", "0", "0", "0…
#> $ Game_URL               <chr> "https://fbref.com/en/matches/2758c0c0/Chievo-J…
#> $ Team                   <chr> "Chievo", "Chievo", "Chievo", "Chievo", "Chievo…
#> $ Home_Away              <chr> "Home", "Home", "Home", "Home", "Home", "Home",…
#> $ Player                 <chr> "Mariusz Stępiński", "Filip Đorđević", "Emanuel…
#> $ Player_Href            <chr> "/en/players/7b536033/Mariusz-Stepinski", "/en/…
#> $ Player_Num             <chr> "9", "20", "17", "27", "56", "22", "8", "4", "2…
#> $ Nation                 <chr> "POL", "SRB", "ITA", "ITA", "FIN", "NGA", "SRB"…
#> $ Pos                    <chr> "FW", "FW", "LW", "RW", "LM", "LM", "CM", "RM",…
#> $ Age                    <chr> "23-098", "30-324", "33-105", "21-116", "31-249…
#> $ Min                    <chr> "65", "25", "90", "90", "77", "13", "90", "90",…
#> $ Tkl_Tackles            <chr> "1", "1", "0", "8", "0", "1", "0", "2", "2", "6…
#> $ TklW_Tackles           <chr> "1", "0", "0", "4", "0", "0", "0", "1", "1", "4…
#> $ Def.3rd_Tackles        <int> 0, 1, 0, 4, 0, 1, 0, 2, 2, 3, 2, 0, 0, 0, 0, 0,…
#> $ Mid.3rd_Tackles        <int> 1, 0, 0, 4, 0, 0, 0, 0, 0, 3, 0, 0, 0, 0, 0, 1,…
#> $ Att.3rd_Tackles        <int> 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,…
#> $ Tkl_Challenges         <chr> "0", "0", "0", "3", "0", "0", "0", "1", "2", "2…
#> $ Att_Challenges         <chr> "2", "1", "2", "4", "2", "0", "1", "1", "4", "2…
#> $ Tkl_percent_Challenges <dbl> 0, 0, 0, 75, 0, NA, 0, 100, 50, 100, 100, NA, N…
#> $ Lost_Challenges        <chr> "2", "1", "2", "1", "2", "0", "1", "0", "2", "0…
#> $ Blocks_Blocks          <chr> "0", "1", "0", "0", "1", "0", "0", "2", "2", "0…
#> $ Sh_Blocks              <chr> "0", "1", "0", "0", "0", "0", "0", "1", "1", "0…
#> $ Pass_Blocks            <chr> "0", "0", "0", "0", "1", "0", "0", "1", "1", "0…
#> $ Int                    <chr> "0", "0", "0", "2", "1", "0", "1", "2", "0", "2…
#> $ Tkl.Int                <int> 1, 1, 0, 10, 1, 1, 1, 4, 2, 8, 3, 2, 0, 0, 0, 1…
#> $ Clr                    <chr> "1", "0", "1", "7", "2", "1", "0", "0", "4", "7…
#> $ Err                    <chr> "0", "0", "0", "0", "0", "0", "0", "0", "0", "0…
#> $ Competition_Name       <chr> "Serie A", "Serie A", "Serie A", "Serie A", "Se…
#> $ Gender                 <chr> "M", "M", "M", "M", "M", "M", "M", "M", "M", "M…
#> $ Country                <chr> "ITA", "ITA", "ITA", "ITA", "ITA", "ITA", "ITA"…
#> $ Tier                   <chr> "1st", "1st", "1st", "1st", "1st", "1st", "1st"…
#> $ Season_End_Year        <int> 2019, 2019, 2019, 2019, 2019, 2019, 2019, 2019,…
#> $ Def.3rd_Tackles.1      <int> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA,…
#> $ Mid.3rd_Tackles.1      <int> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA,…
#> $ Att.3rd_Tackles.1      <int> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA,…
#> $ Tkl.Int.1              <int> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA,…
#> $ `Def 3rd_Tackles`      <dbl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA,…
#> $ `Mid 3rd_Tackles`      <dbl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA,…
#> $ `Att 3rd_Tackles`      <dbl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA,…
#> $ `Tkl+Int`              <dbl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA,…

Load Understat

The following section demonstrates the different loading functions of Understat data.

Load League Shots

To be able to rapidly load pre-collected chooting locations for whole leagues, the load_understat_league_shots() functions is now available. Supported leagues on Understat are:

  • “EPL”
  • “La liga”
  • “Bundesliga”
  • “Serie A”
  • “Ligue 1”
  • “RFPL”

This is effectively the loading equivalent of the understat_league_season_shots() function, however rather than needing to be scraped a season at a time, this data loads rapidly for all seasons for the selected league since the 2014/15 seasons.

serie_a_shot_locations <- load_understat_league_shots(league = "Serie A")
dplyr::glimpse(serie_a_shot_locations)
#> Rows: 107,584
#> Columns: 22
#> $ league          <chr> "Serie_A", "Serie_A", "Serie_A", "Serie_A", "Serie_A",…
#> $ id              <dbl> 41439, 41444, 41445, 41446, 41451, 41452, 41461, 41462…
#> $ minute          <dbl> 2, 5, 7, 8, 19, 24, 76, 76, 0, 3, 3, 3, 5, 10, 15, 15,…
#> $ result          <chr> "MissedShots", "OwnGoal", "SavedShot", "MissedShots", …
#> $ X               <dbl> 0.845, 0.009, 0.896, 0.875, 0.813, 0.780, 0.780, 0.867…
#> $ Y               <dbl> 0.641, 0.539, 0.373, 0.661, 0.180, 0.374, 0.499, 0.520…
#> $ xG              <dbl> 0.009113184, 0.000000000, 0.019183254, 0.042726491, 0.…
#> $ player          <chr> "Maxi López", "Cristiano Biraghi", "Ezequiel Schelotto…
#> $ h_a             <chr> "h", "h", "h", "h", "h", "h", "h", "h", "a", "a", "a",…
#> $ player_id       <dbl> 1188, 1164, 3873, 1188, 1336, 3873, 716, 1188, 3848, 1…
#> $ situation       <chr> "OpenPlay", "FromCorner", "OpenPlay", "SetPiece", "Fro…
#> $ season          <dbl> 2014, 2014, 2014, 2014, 2014, 2014, 2014, 2014, 2014, …
#> $ shotType        <chr> "Head", "OtherBodyPart", "Head", "RightFoot", "LeftFoo…
#> $ match_id        <dbl> 5149, 5149, 5149, 5149, 5149, 5149, 5149, 5149, 5149, …
#> $ home_team       <chr> "Chievo", "Chievo", "Chievo", "Chievo", "Chievo", "Chi…
#> $ away_team       <chr> "Juventus", "Juventus", "Juventus", "Juventus", "Juven…
#> $ home_goals      <dbl> 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, …
#> $ away_goals      <dbl> 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, …
#> $ date            <chr> "2014-08-30 17:00:00", "2014-08-30 17:00:00", "2014-08…
#> $ player_assisted <chr> "Cristiano Biraghi", NA, "Nicolas Frey", "Ezequiel Sch…
#> $ lastAction      <chr> "Cross", "CrossNotClaimed", "Cross", "Pass", "Pass", "…
#> $ home_away       <chr> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA…