nba_bind_sets: Reduce NBA Stats API result sets

In hoopR: Access Men's Basketball Play by Play Data

Reduce NBA Stats API result sets

Description

Convenience helpers to munge hoopR's structure-faithful named-list result sets into a single tibble. hoopR's ⁠nba_*()⁠ wrappers return the endpoint's resultSets verbatim as a named list of tibbles (lossless, no munging); these reduce that list on demand, making explicit – and composable – the three reductions older scrapers tended to hard-code inside each task function.

Usage

nba_bind_sets(result_sets, tag_column = "set_name")

nba_join_sets(result_sets, join_key)

nba_nest_sets(result_sets, keep_cols, nest_col = ".data")

Arguments

result_sets	A named list of tibbles (an ⁠nba_*()⁠ return).
tag_column	Name of the origin column nba_bind_sets() adds (holds the set names). Defaults to "set_name".
join_key	Single shared column name nba_join_sets() joins the sets on.
keep_cols	Grouping key column(s) nba_nest_sets() keeps wide; every other column is nested.
nest_col	Name of the list-column nba_nest_sets() creates. Defaults to ".data".

Details

nba_bind_sets() row-binds the sets into one long tibble, tagging each row with its origin (tactic B). Use when the sets share a schema, or you simply want them stacked with an origin column (e.g. draft rounds, per-mode stat blocks). Columns absent from a given set fill with NA.

nba_join_sets() successively left-joins the sets into one wide tibble on a shared key (tactic C). Use when the sets are different facets of the same entity (e.g. player stats + team stats keyed on a game or player id).

nba_nest_sets() keeps keep_cols (plus the set name) wide and nests every other column into a list-column, preserving all data when no single flat schema can hold it (tactic D). Use for incompatible sets (e.g. a player profile's season totals + career totals + awards). Recover a set with tidyr::unnest().

All three accept a named list of tibbles – an ⁠nba_*()⁠ return, or the output of nba_stats_map_result_sets() – and return a single tibble.

Value

A single tbl_df (bound, joined, or nested).

Examples

sets <- list(
  PlayerStats = data.frame(GAME_ID = "1", PERSON_ID = c(1, 2), PTS = c(10, 20)),
  TeamStats   = data.frame(GAME_ID = "1", TEAM_ID = 99, PTS = 30)
)
nba_bind_sets(sets, tag_column = "set")          # B: row-bind + tag
nba_join_sets(sets, join_key = "GAME_ID")        # C: join/widen on a key
nba_nest_sets(sets, keep_cols = "GAME_ID")       # D: nest into a list-column

hoopR documentation built on Aug. 25, 2026, 9:07 a.m.