hoopR • Data and Tools for Men's Basketball • hoopR

hoopR

The goal of hoopR is to provide tools for working with men’s basketball data.

It exports more than 1,300 functions:

NBA: the NBA Stats API (nba_*, about 200 functions), ESPN (espn_nba_*), the NBA G League (nbagl_*), Basketball-Reference (bref_*), RealGM (realgm_*), Fox Sports (fox_nba_*), official.nba.com officiating reports (nba_l2m(), nba_referee_assignments()), salary and mock-draft sources, and cross-source crosswalks.
Men’s college basketball: ESPN (espn_mbb_*), Ken Pomeroy’s kenpom.com (kp_*, for users with an active subscription), CollegeBasketballData (cbbd_*), Bart Torvik (torvik_*), the NCAA (ncaa_mbb_*) and Fox Sports (fox_mbb_*).
International: EuroLeague and EuroCup (euroleague_*) and about two dozen leagues and competitions, among them FIBA events (fiba_*), Spain’s ACB (acb_*), Italy’s LBA (lba_*), the VTB United League (vtb_*), Japan’s B.LEAGUE (bleague_*), Australia’s NBL (nbl_rosetta_*), Korea’s KBL (kbl_*) and China’s CBA (cba_*). See the function reference for the full list.
Loaders: load_nba_*(), load_mbb_*(), load_nba_stats_*() and load_ncaa_mbb_*() read pre-built play-by-play, box score, schedule, shot and model data from the sportsdataverse-data releases.

Data status

The load_*() functions read release assets on sportsdataverse-data. The badges below are rebuilt nightly from each producer’s latest workflow run and newest release files; idle means the sport is out of season. Full detail: sportsdataverse.org/status.

Dataset	Data updated	Through	Pipeline	Update workflows
Men’s college basketball (ESPN)
Men’s college basketball (stats.ncaa.org)
NBA (ESPN)
NBA Stats API
Conference, division and ballpark reference				—

Installation

You can install the CRAN version of hoopR with:

install.packages("hoopR")

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

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

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

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

Quick start

NBA play-by-play for a season

load_nba_pbp() covers 2002-2027; pass several seasons (or seasons = 2002:2026) to load more at once.

nba_pbp <- hoopR::load_nba_pbp(seasons = 2026)

## 642472 rows of NBA play-by-play data from 1325 games.

Men’s college basketball play-by-play for a season

load_mbb_pbp() covers 2006-2027.

mbb_pbp <- hoopR::load_mbb_pbp(seasons = 2026)

## 2915731 rows of men's college basketball play-by-play data from 6275 games.

Documentation

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

There is also a printable hoopR cheat sheet (PDF), one of a set covering every SportsDataverse package.

Breaking Changes

Full News on Releases

Companion packages

sdvplotR (0.3.0, pak::pak("sportsdataverse/sdvplotR")) adds team logos and colours to ggplot2 charts and draws shot charts from the hoopR shot loaders; see its NBA, men’s college and shot chart articles.
sportyR (2.4.5, install.packages("sportyR")) draws NBA, NCAA and FIBA courts to plot shot locations on.
wehoop is the women’s basketball companion (WNBA and women’s college basketball).
sportsdataverse-py is the Python package; most hoopR functions have a Python twin of the same name.

The SportsDataverse

hoopR 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 (@saiemgilani)

Our Contributors (they’re awesome)

Jason Lee (@theFirmAISports)
Billy Fryer
Ross Drucker (@rossdrucker9)
Vladislav Shufinskiy (@vshufinskiy)

Cheat sheet

A printable one-page reference for hoopR — the function families, the loaders, and what each one returns.

📄 Download the hoopR cheat sheet (PDF)

Free to download, print and hand out; light and dark, US Letter landscape. Every SportsDataverse package has one — browse them all at sportsdataverse.org/cheatsheets.

Code of Conduct

Please note that the hoopR 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 hoopR R package in publications, use:

BibTeX Citation

@misc{gilani_2021_hoopR,
  author = {Gilani, Saiem},
  title = {hoopR: Access Men's Basketball Play by Play Data},
  url = {https://hoopR.sportsdataverse.org},
  doi = {10.32614/CRAN.package.hoopR},
  year = {2026}
}

License

hoopR is released under the MIT License (MIT + file LICENSE); see LICENSE.md.