CollegeBasketballData (CBD) Endpoints

The cbbd_*() functions wrap the CollegeBasketballData API, the men’s college basketball sibling of CollegeFootballData (which cfbfastR wraps with cfbd_*). They cover the full v1 endpoint surface — games, play-by-play, substitutions, team/player statistics, lineups, ratings, rankings, betting lines, recruiting, the transfer portal, the NBA draft, and reference data for teams, venues and conferences.

Every wrapper returns a tidy hoopR_data tibble and prints its usage with the shared hoopR theming.

Registering an API key

The CollegeBasketballData API requires a free Bearer-token API key. Request one at collegebasketballdata.com/key, then store it as the CBBD_API_KEY environment variable. The easiest way is to add it to your .Renviron file:

usethis::edit_r_environ()
# add this line, save, and restart R:
# CBBD_API_KEY = XXXX-YOUR-API-KEY-HERE-XXXXX

For one-off use within a single session:

Sys.setenv(CBBD_API_KEY = "XXXX-YOUR-API-KEY-HERE-XXXXX")

Confirm the key is detected and inspect the registration help:

library(hoopR)

has_cbbd_key()
#> [1] TRUE

?register_cbbd

Reference data: conferences, teams, venues

Start with the lookups you will use to filter the other endpoints. The id values returned here are the CollegeBasketballData ids consumed elsewhere; source_id holds the matching ESPN id.

# Conferences (and historical membership)
cbbd_conferences()
cbbd_conferences_history(conference = "ACC")

# Teams for a season, and a single team's roster
cbbd_teams(conference = "ACC", season = 2024)
cbbd_teams_roster(season = 2024, team = "Duke")

# Venues
cbbd_venues()

Games and box scores

cbbd_games() returns the schedule/results; the *_teams and *_players variants return team- and player-level box scores. cbbd_scoreboard() returns live and same-day games (so it is empty in the off-season).

games <- cbbd_games(season = 2024, team = "Duke")
games

cbbd_games_media(season = 2024, team = "Duke")    # broadcast info
cbbd_games_teams(season = 2024, team = "Duke")    # team box scores
cbbd_games_players(season = 2024, team = "Duke")  # player box scores

cbbd_scoreboard(conference = "ACC")

Most by-id endpoints take a CollegeBasketballData game_id from cbbd_games():

game_id <- games$id[1]

Play-by-play

Pull play-by-play by game, by player, by team, by date, or by tournament. Pass shooting_plays_only = TRUE to restrict to shot events.

cbbd_plays_game(game_id = game_id)
cbbd_plays_team(season = 2024, team = "Duke")
cbbd_plays_player(player_id = 160, season = 2024)
cbbd_plays_date(date = "2024-02-01T00:00:00.000Z")
cbbd_plays_tournament(tournament = "NCAA", season = 2024)

# Reference: the list of play types
cbbd_play_types()

Substitutions

cbbd_substitutions_game(game_id = game_id)
cbbd_substitutions_team(season = 2024, team = "Duke")
cbbd_substitutions_player(player_id = 160, season = 2024)

Team and player statistics

Season aggregates for teams and players, plus dedicated shooting splits and a team leaderboard. Nested statistic objects are flattened into prefixed columns (e.g. team_stats_*, field_goals_*).

cbbd_stats_team_season(season = 2024, team = "Duke")
cbbd_stats_team_leaderboard(season = 2024)
cbbd_stats_team_shooting_season(season = 2024, team = "Duke")

cbbd_stats_player_season(season = 2024, team = "Duke")
cbbd_stats_player_shooting_season(season = 2024, team = "Duke")

Lineups

Five-player lineup stats for a team-season or a single game.

cbbd_lineups_team(season = 2024, team = "Duke")
cbbd_lineups_game(game_id = game_id)

Ratings and rankings

cbbd_ratings_srs(season = 2024)        # Simple Rating System
cbbd_ratings_adjusted(season = 2024)   # adjusted offensive/defensive efficiency
cbbd_ratings_elo(season = 2024)        # Elo

cbbd_rankings(season = 2024, poll_type = "ap")

Betting lines

cbbd_lines(season = 2024, team = "Duke")
cbbd_lines_providers()

Recruiting and the transfer portal

cbbd_recruiting_players(year = 2024)
cbbd_recruiting_teams(year = 2024)
cbbd_recruiting_portal(year = 2024)

NBA draft

cbbd_draft_teams()
cbbd_draft_positions()
cbbd_draft_picks(year = 2024)

Where to go next

Browse the full function reference under the CollegeBasketballData (CBD) section of the reference index.
Each wrapper’s help page (?cbbd_games, ?cbbd_plays_game, …) documents its parameters and the columns it returns.
Inspect your remaining API usage and rate limits in the response headers from the CollegeBasketballData API.

Saiem Gilani