Functions to Access MLS and NWSL Play by Play Data • usfootballR

The goal of usfootballR is to make American soccer data easy to work with in R. The package has functions to access live play-by-play and box score data from ESPN with shot locations when available.

A scraping and aggregating interface for ESPN’s MLS and NWSL statistics. It provides users with the capability to access the API’s game play-by-plays, box scores, standings and results to analyze the data for themselves.

Data freshness and pipeline status for every SportsDataverse dataset: sportsdataverse.org/status.

Installation

You can install the latest build from R-universe with:

install.packages("usfootballR", repos = c("https://sportsdataverse.r-universe.dev", getOption("repos")))

You can install the development version of usfootballR from GitHub with:

if (!requireNamespace("pak", quietly = TRUE)) install.packages("pak")
pak::pak("sportsdataverse/usfootballR")
# or, with remotes:
# if (!requireNamespace("remotes", quietly = TRUE)) install.packages("remotes")
# remotes::install_github("sportsdataverse/usfootballR")

Quick start

library(usfootballR)

# MLS play-by-play for a season, from the SportsDataverse data repo
mls_pbp <- load_mls_pbp(2021)

# NWSL schedule for a season
nwsl_schedule <- load_nwsl_schedule(2021)

# Live from ESPN: the MLS scoreboard for a date, and the NWSL standings
espn_mls_scoreboard(season = "20200829")
espn_nwsl_standings(year = 2021)

Documentation

For more information on the package and function reference, please see the usfootballR documentation website.

Breaking Changes

Full News on Releases

Companion packages

sportyR: draws MLS and NWSL pitches in ggplot2 (geom_soccer()) to plot shot locations on.
sdvplotR: team logo plots in ggplot2, gt and reactable across the SportsDataverse leagues.

The SportsDataverse

usfootballR is part of the SportsDataverse, a set of open-source packages for sports data.

Package	Sport / Scope
cfbfastR	College football
hoopR	Men’s basketball (NBA and NCAA)
wehoop	Women’s basketball (WNBA and NCAA)
fastRhockey	Hockey (NHL and PWHL)
baseballr	Baseball (MLB, MiLB, NCAA)
softballR	College softball
oddsapiR	Sports betting odds
recruitR	College football recruiting
usfootballR	US soccer
cfbseedR · cfb4th	CFB playoff simulation · fourth-down decisions
cfbplotR · sdvplotR · sportyR	Logos, colors, tables · playing surfaces
sportsdataverse-R	Umbrella R metapackage
sportsdataverse-py · sportsdataverse.js	Python and Node.js

See the full ecosystem at sportsdataverse.org.

Follow the SportsDataverse on X and star this repo

Our Authors

Saiem Gilani

Code of Conduct

Please note that the usfootballR project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.

Citations

To cite the usfootballR R package in publications, use:

BibTeX Citation

@misc{gilani_2021_usfootballR,
  author = {Saiem Gilani},
  title = {usfootballR: The SportsDataverse's R Package for MLS and NWSL Data.},
  url = {https://usfootballR.sportsdataverse.org},
  year = {2021}
}

usfootballR