R/espn_mbb_groups_v2.R

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

# espn_mbb_groups_v2.R
# Public MBB shims for ESPN per-season group / conference endpoints.
# (Distinct from the existing site-v2 espn_mbb_groups, which targets a
# different endpoint family — this batch wraps the core-v2 groups.)

# ---------------------------------------------------------------------------
# espn_mbb_season_groups
# ---------------------------------------------------------------------------

#' **Get ESPN MBB Season Groups Index**
#' @name espn_mbb_season_groups
NULL
#' @title
#' **Get ESPN MBB Season Groups Index**
#' @rdname espn_mbb_season_groups
#' @author Saiem Gilani
#' @description
#' Returns the list of group IDs (conferences / divisions) for one
#' (MBB season x season-type) via core-v2
#' `/seasons/{season}/types/{season_type}/groups`.
#'
#' @param season Season year. Defaults to most recent MBB season.
#' @param season_type Season-type id (2 = regular (default)).
#' @param ... Additional arguments; currently unused.
#' @return A tibble with one row per group.
#'
#'    Columns as documented in the shared [espn_mbb_season_groups_schema] table.
#'
#' @importFrom jsonlite fromJSON
#' @importFrom dplyr as_tibble
#' @export
#' @family ESPN MBB Functions
#' @examples
#' \donttest{
#'   espn_mbb_season_groups(season = 2025)
#' }
espn_mbb_season_groups <- function(season = most_recent_mbb_season(),
                                    season_type = c(2L, 3L), ...) {
  .espn_basketball_season_groups(league = "mens-college-basketball", season = season,
                                   season_type = season_type, ...)
}

# ---------------------------------------------------------------------------
# espn_mbb_season_group
# ---------------------------------------------------------------------------

#' **Get ESPN MBB Season Group Detail**
#' @name espn_mbb_season_group
#' @title
#' **Get ESPN MBB Season Group Detail**
#' @rdname espn_mbb_season_group
#' @author Saiem Gilani
#' @description
#' Returns metadata for one group (conference or division) in one
#' (MBB season x season-type), plus `$ref` URLs to its parent group,
#' children groups, member teams, and standings.
#'
#' @param group_id ESPN group identifier.
#' @param season Season year. Defaults to most recent MBB season.
#' @param season_type Season-type id (2 = regular (default)).
#' @param ... Additional arguments; currently unused.
#' @return A single-row tibble.
#'
#'    Columns as documented in the shared [espn_mbb_season_group_schema] table.
#'
#' @importFrom jsonlite fromJSON
#' @importFrom dplyr as_tibble
#' @export
#' @family ESPN MBB Functions
#' @examples
#' \donttest{
#'   espn_mbb_season_group(group_id = 5, season = 2025)
#' }
espn_mbb_season_group <- function(group_id,
                                   season = most_recent_mbb_season(),
                                   season_type = 2L, ...) {
  .espn_basketball_season_group(league = "mens-college-basketball", season = season,
                                  season_type = season_type,
                                  group_id = group_id, ...)
}

# ---------------------------------------------------------------------------
# espn_mbb_season_group_children
# ---------------------------------------------------------------------------

#' **Get ESPN MBB Season Group Children Index**
#' @name espn_mbb_season_group_children
#' @title
#' **Get ESPN MBB Season Group Children Index**
#' @rdname espn_mbb_season_group
#' @author Saiem Gilani
#' @description
#' Returns the list of child groups (e.g. divisions within a conference)
#' for one (MBB season x season-type x parent-group).
#'
#' @param season_type Season-type id (2 = regular (default)).
#' @param ... Additional arguments; currently unused.
#' @return A tibble with one row per child group.
#'
#'    Columns as documented in the shared [espn_mbb_season_group_children_schema] table.
#'
#' @importFrom jsonlite fromJSON
#' @importFrom dplyr as_tibble
#' @export
#' @family ESPN MBB Functions
#' @examples
#' \donttest{
#'   espn_mbb_season_group_children(group_id = 5, season = 2025)
#' }
espn_mbb_season_group_children <- function(group_id,
                                            season = most_recent_mbb_season(),
                                            season_type = 2L, ...) {
  .espn_basketball_season_group_children(league = "mens-college-basketball", season = season,
                                           season_type = season_type,
                                           group_id = group_id, ...)
}

# ---------------------------------------------------------------------------
# espn_mbb_season_group_teams
# ---------------------------------------------------------------------------

#' **Get ESPN MBB Season Group Teams Index**
#' @name espn_mbb_season_group_teams
#' @title
#' **Get ESPN MBB Season Group Teams Index**
#' @rdname espn_mbb_season_group
#' @author Saiem Gilani
#' @description
#' Returns the list of team IDs that belong to one group (conference or
#' division) for one (MBB season x season-type).
#'
#' @param season_type Season-type id (2 = regular (default)).
#' @param ... Additional arguments; currently unused.
#' @return A tibble with one row per team in the group.
#'
#'    Columns as documented in the shared [espn_mbb_season_group_teams_schema] table.
#'
#' @importFrom jsonlite fromJSON
#' @importFrom dplyr as_tibble
#' @export
#' @family ESPN MBB Functions
#' @examples
#' \donttest{
#'   espn_mbb_season_group_teams(group_id = 5, season = 2025)
#' }
espn_mbb_season_group_teams <- function(group_id,
                                         season = most_recent_mbb_season(),
                                         season_type = 2L, ...) {
  .espn_basketball_season_group_teams(league = "mens-college-basketball", season = season,
                                        season_type = season_type,
                                        group_id = group_id, ...)
}