R/espn_nba_team_deep.R

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

# espn_nba_team_deep.R
# Public NBA shims for deeper per-team / per-coach core-v2 endpoints.

# ---------------------------------------------------------------------------
# espn_nba_team_odds_records
# ---------------------------------------------------------------------------

#' **Get ESPN NBA Team Odds-Records (Long Format)**
#' @rdname espn_mbb_team_odds_records
#' @name espn_nba_team_odds_records
NULL
#' @title
#' **Get ESPN NBA Team Odds-Records (Long Format)**
#' @rdname espn_mbb_team_odds_records
#' @author Saiem Gilani
#' @description
#' Returns the long-format odds-records breakdown for a team in one
#' season. Each row is one (category × stat) — typical categories include
#' Money Line Overall, Money Line Home, Money Line Road, Against The
#' Spread Overall, Over/Under, etc. ESPN's coverage of this endpoint is
#' sparse; many (team × season-type) combinations return 404, in which
#' case the wrapper returns an empty tibble.
#'
#' @param team_id ESPN team identifier.
#' @param season_type Season-type id. ESPN populates odds-records mostly
#'   under `season_type = 0` (all-types aggregate), so that is the default.
#' @param ... Additional arguments; currently unused.
#' @return A long tibble with one row per (category × stat).
#'
#'    Columns as documented in the shared [espn_mbb_team_odds_records_schema] table.
#'
#' @importFrom jsonlite fromJSON
#' @importFrom dplyr as_tibble
#' @export
#' @family ESPN NBA Functions
#' @examples
#' \donttest{
#'   espn_nba_team_odds_records(team_id = 13, season = 2026)
#' }
espn_nba_team_odds_records <- function(team_id,
                                        season = most_recent_nba_season(),
                                        season_type = 0L, ...) {
  .espn_basketball_team_odds_records(league = "nba", team_id = team_id,
                                       season = season,
                                       season_type = season_type, ...)
}

# ---------------------------------------------------------------------------
# espn_nba_team_depthchart
# ---------------------------------------------------------------------------

#' **Get ESPN NBA Team Depth Chart (Long Format)**
#' @name espn_nba_team_depthchart
#' @title
#' **Get ESPN NBA Team Depth Chart (Long Format)**
#' @rdname espn_nba_team_depthchart
#' @author Saiem Gilani
#' @description
#' Returns the team's depth chart in long format, one row per
#' (position × rank × athlete). NBA-only at ESPN's core-v2.
#'
#' @param team_id ESPN team identifier.
#' @param season Season year. Defaults to most recent NBA season.
#' @param ... Additional arguments; currently unused.
#' @return A long tibble with one row per athlete depth entry.
#'
#'    \if{html}{\tabular{lll}{
#'       col_name \tab types \tab description \cr
#'       league \tab character \tab League slug. \cr
#'       team_id \tab character \tab ESPN team id. \cr
#'       season \tab integer \tab Season year. \cr
#'       depthchart_id \tab character \tab Depth chart id (typically "1"). \cr
#'       depthchart_name \tab character \tab Depth chart name. \cr
#'       position \tab character \tab Position code (\code{pg}/\code{sg}/\code{sf}/\code{pf}/\code{c}). \cr
#'       rank \tab integer \tab Depth rank (1 = starter). \cr
#'       athlete_id \tab character \tab ESPN athlete id. \cr
#'       athlete_ref \tab character \tab \verb{$ref} URL to athlete-in-season. \cr
#'       position_ref \tab character \tab \verb{$ref} URL to position resource. \cr
#'    }}
#'    \if{latex}{See the HTML help or pkgdown reference for the column table.}
#'
#' @importFrom jsonlite fromJSON
#' @importFrom dplyr as_tibble
#' @export
#' @family ESPN NBA Functions
#' @examples
#' \donttest{
#'   espn_nba_team_depthchart(team_id = 13, season = 2025)
#' }
espn_nba_team_depthchart <- function(team_id,
                                      season = most_recent_nba_season(),
                                      ...) {
  .espn_basketball_team_depthchart(league = "nba", team_id = team_id,
                                     season = season, ...)
}

# ---------------------------------------------------------------------------
# espn_nba_team_season_roster
# ---------------------------------------------------------------------------

#' **Get ESPN NBA Team Roster (Per-Season, core-v2)**
#' @name espn_nba_team_season_roster
#' @title
#' **Get ESPN NBA Team Roster (Per-Season, core-v2)**
#' @rdname espn_mbb_team_season_roster
#' @author Saiem Gilani
#' @description
#' Returns the per-season team roster as a tibble of athlete IDs from
#' `seasons/{y}/teams/{id}/athletes`. Distinct from [espn_nba_team_roster()]
#' which targets a site-v2 endpoint optimized for the current season; this
#' core-v2 variant is era-correct and available back to ESPN's earliest
#' season for each league.
#'
#' @param team_id ESPN team identifier.
#' @param ... Additional arguments; currently unused.
#' @return A tibble with one row per athlete on the season roster.
#'
#'    Columns as documented in the shared [espn_mbb_team_season_roster_schema] table.
#'
#' @importFrom jsonlite fromJSON
#' @importFrom dplyr as_tibble
#' @export
#' @family ESPN NBA Functions
#' @examples
#' \donttest{
#'   espn_nba_team_season_roster(team_id = 13, season = 2025)
#' }
espn_nba_team_season_roster <- function(team_id,
                                         season = most_recent_nba_season(),
                                         ...) {
  .espn_basketball_team_season_roster(league = "nba", team_id = team_id,
                                        season = season, ...)
}

# ---------------------------------------------------------------------------
# espn_nba_coach_season
# ---------------------------------------------------------------------------

#' **Get ESPN NBA Coach-in-Season Detail**
#' @name espn_nba_coach_season
#' @title
#' **Get ESPN NBA Coach-in-Season Detail**
#' @rdname espn_mbb_coach_season
#' @author Saiem Gilani
#' @description
#' Per-season coach detail (name, birth info, `$ref`s to team/college/
#' person). ESPN's coverage of this endpoint is sparse; many
#' (coach × season) combinations return 404.
#'
#' @param coach_id ESPN coach identifier.
#' @param ... Additional arguments; currently unused.
#' @return A single-row tibble.
#'
#'    Columns as documented in the shared [espn_mbb_coach_season_schema] table.
#'
#' @importFrom jsonlite fromJSON
#' @importFrom dplyr as_tibble
#' @export
#' @family ESPN NBA Functions
#' @examples
#' \donttest{
#'   espn_nba_coach_season(coach_id = 52120, season = 2025)
#' }
espn_nba_coach_season <- function(coach_id,
                                   season = most_recent_nba_season(),
                                   ...) {
  .espn_basketball_coach_season(league = "nba", coach_id = coach_id,
                                  season = season, ...)
}
# ---------------------------------------------------------------------------
# espn_nba_team_record_detail
# ---------------------------------------------------------------------------

#' **Get ESPN NBA Team Record Detail (Long Format)**
#' @rdname espn_mbb_team_record_detail
#' @name espn_nba_team_record_detail
NULL
#' @title
#' **Get ESPN NBA Team Record Detail (Long Format)**
#' @rdname espn_mbb_team_record_detail
#' @author Saiem Gilani
#' @description
#' Returns one team's record detail in long format: one row per stat in
#' the record's `stats[]` array. Use [espn_nba_team_record()] to enumerate
#' available `record_id` values per team-season (overall / home / away /
#' conference + per-opponent breakdowns).
#'
#' @param team_id ESPN team identifier.
#' @param season Season year (numeric).
#' @param season_type Integer season type: 1 = preseason, 2 = regular (default),
#'   3 = postseason.
#' @param ... Additional arguments; currently unused.
#' @return A long tibble.
#' @export
#' @family ESPN NBA Functions
#' @examples
#' \donttest{
#'   espn_nba_team_record_detail(team_id = 13, season = 2024, record_id = 0)
#' }
espn_nba_team_record_detail <- function(team_id, season, record_id,
                                          season_type = 2L, ...) {
  .espn_basketball_team_record_detail(league = "nba",
                                        team_id = team_id,
                                        season = season,
                                        record_id = record_id,
                                        season_type = season_type, ...)
}