Skip to contents

hoopR

hoopR is an R package 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) hoopR-mbb-data data updated hoopR-mbb-data through season hoopR-mbb-data pipeline state hoopR-mbb-data daily_mbb hoopR-mbb-data mbb_models_cron
Men’s college basketball (stats.ncaa.org) ncaa-mbb-hoops-data data updated ncaa-mbb-hoops-data through season ncaa-mbb-hoops-data pipeline state ncaa-mbb-hoops-data ncaa_mbb_models
NBA (ESPN) hoopR-nba-data data updated hoopR-nba-data through season hoopR-nba-data pipeline state hoopR-nba-data daily_nba
NBA Stats API hoopR-nba-stats-data data updated hoopR-nba-stats-data through season hoopR-nba-stats-data pipeline state hoopR-nba-stats-data daily_nba_stats hoopR-nba-stats-data nba_models hoopR-nba-stats-data annual_nba_stats_draft
Conference, division and ballpark reference sdv-reference-data data updated sdv-reference-data through season sdv-reference-data pipeline state —

Installation

You can install the CRAN version of hoopR with:

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

# You can install using the pak package using the following code:
if (!requireNamespace('pak', quietly = TRUE)){
  install.packages('pak')
}
pak::pak("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.
  • 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.

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

Follow the SportsDataverse (@SportsDataverse) on X and star this repo

X Follow

GitHub stars

Star history of sportsdataverse/hoopR

Our Authors

  • Saiem Gilani (@saiemgilani) @saiemgilani

@saiemgilani

Our Contributors (they’re awesome)

  • Jason Lee (@theFirmAISports) @theFirmAISports @papagorgio23

  • Billy Fryer

  • Ross Drucker (@rossdrucker9) @rossdrucker9 @rossdrucker

  • Vladislav Shufinskiy (@vshufinskiy) @vshufinskiy @shufinskiy

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.

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}
}