Package 'usfootballR'

Title: Access MLS and NWSL Play-by-Play Data
Description: A utility for working with American soccer data. A scraping and aggregating interface for ESPN's <https://www.espn.com> MLS and NWSL statistics.
Authors: Saiem Gilani [aut, cre]
Maintainer: Saiem Gilani <[email protected]>
License: MIT + file LICENSE
Version: 0.0.1
Built: 2026-10-12 15:51:16 UTC
Source: https://github.com/sportsdataverse/usfootballR

Help Index

Load .csv / .csv.gz file from a remote connection

Description

This is a thin wrapper on data.table::fread

Usage

csv_from_url(...)

Arguments

...

passed to data.table::fread

Get ESPN's MLS game data (play-by-play, team)

Description

Get ESPN's MLS game data (play-by-play, team)

Usage

espn_mls_game_all(game_id)

Arguments

game_id

Game ID

Value

A named list of dataframes: Plays, Team

Author(s)

Saiem Gilani

Examples

try(espn_mls_game_all(game_id = 598135))

Get ESPN's MLS play by play data

Description

Get ESPN's MLS play by play data

Usage

espn_mls_pbp(game_id)

Arguments

game_id

Game ID

Value

Returns a play-by-play data frame

Author(s)

Saiem Gilani

Examples

try(espn_mls_pbp(game_id = 598135))

Get MLS schedule for a specific year/date from ESPN's API

Description

Get MLS schedule for a specific year/date from ESPN's API

Usage

espn_mls_scoreboard(season)

Arguments

season

Either numeric or character

Value

Returns a tibble

Author(s)

Saiem Gilani.

Examples

# Get schedule from date 2020-08-29

  try(espn_mls_scoreboard (season = "20200829"))

Get ESPN MLS Standings

Description

Get ESPN MLS Standings

Usage

espn_mls_standings(year)

Arguments

year

Either numeric or character (YYYY)

Value

Returns a tibble

Examples

try(espn_mls_standings(year = 2021))

Get ESPN's MLS team box data

Description

Get ESPN's MLS team box data

Usage

espn_mls_team_box(game_id)

Arguments

game_id

Game ID

Value

Returns a team boxscore data frame

Author(s)

Saiem Gilani

Examples

try(espn_mls_team_box(game_id = 598135))

Get ESPN's MLS team names and ids

Description

Get ESPN's MLS team names and ids

Usage

espn_mls_teams()

Value

Returns a tibble

Author(s)

Saiem Gilani

Examples

try(espn_mls_teams())

Get ESPN's NWSL game data (play-by-play, team)

Description

Get ESPN's NWSL game data (play-by-play, team)

Usage

espn_nwsl_game_all(game_id)

Arguments

game_id

Game ID

Value

A named list of dataframes: Plays, Team

Author(s)

Saiem Gilani

Examples

try(espn_nwsl_game_all(game_id = 601833))

Get ESPN's NWSL play by play data

Description

Get ESPN's NWSL play by play data

Usage

espn_nwsl_pbp(game_id)

Arguments

game_id

Game ID

Value

Returns a play-by-play data frame

Author(s)

Saiem Gilani

Examples

try(espn_nwsl_pbp(game_id = 601833))

Get NWSL schedule for a specific year/date from ESPN's API

Description

Get NWSL schedule for a specific year/date from ESPN's API

Usage

espn_nwsl_scoreboard(season)

Arguments

season

Either numeric or character

Value

Returns a tibble

Author(s)

Saiem Gilani.

Examples

# Get schedule from date 2020-08-29

  try(espn_nwsl_scoreboard (season = "20200829"))

Get ESPN NWSL Standings

Description

Get ESPN NWSL Standings

Usage

espn_nwsl_standings(year)

Arguments

year

Either numeric or character (YYYY)

Value

Returns a tibble

Author(s)

Geoff Hutchinson

Examples

try(espn_nwsl_standings(year = 2021))

Get ESPN's NWSL team box data

Description

Get ESPN's NWSL team box data

Usage

espn_nwsl_team_box(game_id)

Arguments

game_id

Game ID

Value

Returns a team boxscore data frame

Author(s)

Saiem Gilani

Examples

try(espn_nwsl_team_box(game_id = 601833))

Get ESPN's NWSL team names and ids

Description

Get ESPN's NWSL team names and ids

Usage

espn_nwsl_teams()

Value

Returns a tibble

Author(s)

Saiem Gilani

Examples

try(espn_nwsl_teams())

Load usfootballR MLS play-by-play

Description

helper that loads multiple seasons from the data repo either into memory or writes it into a db using some forwarded arguments in the dots

Usage

load_mls_pbp(
  seasons = most_recent_mls_season(),
  ...,
  dbConnection = NULL,
  tablename = NULL
)

Arguments

seasons

A vector of 4-digit years associated with given MLS seasons. (Min: 2002)
...

Additional arguments passed to an underlying function that writes the season data into a database (used by update_mls_db()).
dbConnection

A DBIConnection object, as returned by DBI::dbConnect()
tablename

The name of the play by play data table within the database

Value

A dataframe

Examples

try(load_mls_pbp(2021))

Load usfootballR MLS player box scores

Description

helper that loads multiple seasons from the data repo either into memory or writes it into a db using some forwarded arguments in the dots

Usage

load_mls_player_box(
  seasons = most_recent_mls_season(),
  ...,
  dbConnection = NULL,
  tablename = NULL
)

Arguments

seasons

A vector of 4-digit years associated with given MLS seasons. (Min: 2002)
...

Additional arguments passed to an underlying function that writes the season data into a database (used by update_mls_db()).
dbConnection

A DBIConnection object, as returned by DBI::dbConnect()
tablename

The name of the player box data table within the database

Value

Returns a tibble

Examples

try(load_mls_player_box(2021))

Load usfootballR MLS schedules

Description

helper that loads multiple seasons from the data repo either into memory or writes it into a db using some forwarded arguments in the dots

Usage

load_mls_schedule(
  seasons = most_recent_mls_season(),
  ...,
  dbConnection = NULL,
  tablename = NULL
)

Arguments

seasons

A vector of 4-digit years associated with given MLS seasons. (Min: 2002)
...

Additional arguments passed to an underlying function that writes the season data into a database (used by update_mls_db()).
dbConnection

A DBIConnection object, as returned by DBI::dbConnect()
tablename

The name of the schedule data table within the database

Value

Returns a tibble

Examples

try(load_mls_schedule(2021))

Load usfootballR MLS team box scores

Description

helper that loads multiple seasons from the data repo either into memory or writes it into a db using some forwarded arguments in the dots

Usage

load_mls_team_box(
  seasons = most_recent_mls_season(),
  ...,
  dbConnection = NULL,
  tablename = NULL
)

Arguments

seasons

A vector of 4-digit years associated with given MLS seasons. (Min: 2003)
...

Additional arguments passed to an underlying function that writes the season data into a database (used by update_mls_db()).
dbConnection

A DBIConnection object, as returned by DBI::dbConnect()
tablename

The name of the team box data table within the database

Value

Returns a tibble

Examples

try(load_mls_team_box(2021))

Load usfootballR NWSL play-by-play

Description

helper that loads multiple seasons from the data repo either into memory or writes it into a db using some forwarded arguments in the dots

Usage

load_nwsl_pbp(
  seasons = most_recent_nwsl_season(),
  ...,
  dbConnection = NULL,
  tablename = NULL
)

Arguments

seasons

A vector of 4-digit years associated with given NWSL seasons. (Min: 2002)
...

Additional arguments passed to an underlying function that writes the season data into a database (used by update_nwsl_db()).
dbConnection

A DBIConnection object, as returned by DBI::dbConnect()
tablename

The name of the play by play data table within the database

Value

A dataframe

Examples

try(load_nwsl_pbp(2021))

Load usfootballR NWSL player box scores

Description

helper that loads multiple seasons from the data repo either into memory or writes it into a db using some forwarded arguments in the dots

Usage

load_nwsl_player_box(
  seasons = most_recent_nwsl_season(),
  ...,
  dbConnection = NULL,
  tablename = NULL
)

Arguments

seasons

A vector of 4-digit years associated with given NWSL seasons. (Min: 2002)
...

Additional arguments passed to an underlying function that writes the season data into a database (used by update_nwsl_db()).
dbConnection

A DBIConnection object, as returned by DBI::dbConnect()
tablename

The name of the player box data table within the database

Value

Returns a tibble

Examples

try(load_nwsl_player_box(2021))

Load usfootballR NWSL schedules

Description

helper that loads multiple seasons from the data repo either into memory or writes it into a db using some forwarded arguments in the dots

Usage

load_nwsl_schedule(
  seasons = most_recent_nwsl_season(),
  ...,
  dbConnection = NULL,
  tablename = NULL
)

Arguments

seasons

A vector of 4-digit years associated with given NWSL seasons. (Min: 2002)
...

Additional arguments passed to an underlying function that writes the season data into a database (used by update_nwsl_db()).
dbConnection

A DBIConnection object, as returned by DBI::dbConnect()
tablename

The name of the schedule data table within the database

Value

Returns a tibble

Examples

try(load_nwsl_schedule(2021))

Load usfootballR NWSL team box scores

Description

helper that loads multiple seasons from the data repo either into memory or writes it into a db using some forwarded arguments in the dots

Usage

load_nwsl_team_box(
  seasons = most_recent_nwsl_season(),
  ...,
  dbConnection = NULL,
  tablename = NULL
)

Arguments

seasons

A vector of 4-digit years associated with given NWSL seasons. (Min: 2003)
...

Additional arguments passed to an underlying function that writes the season data into a database (used by update_nwsl_db()).
dbConnection

A DBIConnection object, as returned by DBI::dbConnect()
tablename

The name of the team box data table within the database

Value

Returns a tibble

Examples

try(load_nwsl_team_box(2021))

Progressively

Description

This function helps add progress-reporting to any function - given function f() and progressor p(), it will return a new function that calls f() and then (on-exiting) will call p() after every iteration.

Usage

progressively(f, p = NULL)

Arguments

f

a function to add progressr functionality to.
p

a progressor function as created by progressr::progressor()

Details

This is inspired by purrr's safely, quietly, and possibly function decorators.

Value

a function that does the same as f but it calls p() after iteration.

Load .rds file from a remote connection

Description

Load .rds file from a remote connection

Usage

rds_from_url(url)

Arguments

url

a character url

Value

a dataframe as created by readRDS()

Update or create a usfootballR play-by-play database

Description

update_mls_db() updates or creates a database with usfootballR play by play data of all completed and available games since 2002.

Usage

update_mls_db(
  dbdir = ".",
  dbname = "usfootballR_db",
  tblname = "usfootballR_mls_pbp",
  force_rebuild = FALSE,
  db_connection = NULL
)

Arguments

dbdir

Directory in which the database is or shall be located
dbname

File name of an existing or desired SQLite database within dbdir
tblname

The name of the play by play data table within the database
force_rebuild

Hybrid parameter (logical or numeric) to rebuild parts of or the complete play by play data table within the database (please see details for further information)
db_connection

A DBIConnection object, as returned by DBI::dbConnect() (please see details for further information)

Details

This function creates and updates a data table with the name tblname within a SQLite database (other drivers via db_connection) located in dbdir and named dbname. The data table combines all play by play data for every available game back to the 2002 season and adds the most recent completed games as soon as they are available for usfootballR.

The argument force_rebuild is of hybrid type. It can rebuild the play by play data table either for the whole usfootballR era (with force_rebuild = TRUE) or just for specified seasons (e.g. force_rebuild = c(2019, 2020)). Please note the following behavior:

  • force_rebuild = TRUE: The data table with the name tblname will be removed completely and rebuilt from scratch. This is helpful when new columns are added during the Off-Season.

  • force_rebuild = c(2019, 2020): The data table with the name tblname will be preserved and only rows from the 2019 and 2020 seasons will be deleted and re-added. This is intended to be used for ongoing seasons because ESPN's data provider can make changes to the underlying data during the week.

The parameter db_connection is intended for advanced users who want to use other DBI drivers, such as MariaDB, Postgres or odbc. Please note that the arguments dbdir and dbname are dropped in case a db_connection is provided but the argument tblname will still be used to write the data table into the database.

Value

Logical TRUE/FALSE

Update or create a usfootballR play-by-play database

Description

update_nwsl_db() updates or creates a database with usfootballR play by play data of all completed and available games since 2002.

Usage

update_nwsl_db(
  dbdir = ".",
  dbname = "usfootballR_db",
  tblname = "usfootballR_nwsl_pbp",
  force_rebuild = FALSE,
  db_connection = NULL
)

Arguments

dbdir

Directory in which the database is or shall be located
dbname

File name of an existing or desired SQLite database within dbdir
tblname

The name of the play by play data table within the database
force_rebuild

Hybrid parameter (logical or numeric) to rebuild parts of or the complete play by play data table within the database (please see details for further information)
db_connection

A DBIConnection object, as returned by DBI::dbConnect() (please see details for further information)

Details

This function creates and updates a data table with the name tblname within a SQLite database (other drivers via db_connection) located in dbdir and named dbname. The data table combines all play by play data for every available game back to the 2002 season and adds the most recent completed games as soon as they are available for usfootballR.

The argument force_rebuild is of hybrid type. It can rebuild the play by play data table either for the whole usfootballR era (with force_rebuild = TRUE) or just for specified seasons (e.g. force_rebuild = c(2019, 2020)). Please note the following behavior:

  • force_rebuild = TRUE: The data table with the name tblname will be removed completely and rebuilt from scratch. This is helpful when new columns are added during the Off-Season.

  • force_rebuild = c(2019, 2020): The data table with the name tblname will be preserved and only rows from the 2019 and 2020 seasons will be deleted and re-added. This is intended to be used for ongoing seasons because ESPN's data provider can make changes to the underlying data during the week.

The parameter db_connection is intended for advanced users who want to use other DBI drivers, such as MariaDB, Postgres or odbc. Please note that the arguments dbdir and dbname are dropped in case a db_connection is provided but the argument tblname will still be used to write the data table into the database.

Value

Logical TRUE/FALSE