R/espn_wbb_weeks.R

In wehoop: Access Women's Basketball Play by Play Data

# espn_wbb_weeks.R
# Public WBB shims for ESPN week + week-ranking endpoints.

# ---------------------------------------------------------------------------
# espn_wbb_season_weeks
# ---------------------------------------------------------------------------

#' **Get ESPN WBB Season Weeks Index**
#' @name espn_wbb_season_weeks
NULL
#' @title
#' **Get ESPN WBB Season Weeks Index**
#' @rdname espn_wbb_season_weeks
#' @author Saiem Gilani
#' @description
#' Returns the list of week IDs for one (WBB season x season-type). WBB
#' uses a week structure inherited from ESPN's schema, but week-level
#' rankings are populated only for college (MBB / WBB).
#'
#' @param season Season year. Defaults to most recent WBB season.
#' @param season_type Season-type id (2 = regular (default), 3 = postseason).
#' @param ... Additional arguments; currently unused.
#' @return A tibble with one row per week.
#'
#'    |col_name    |types     |description                              |
#'    |:-----------|:---------|:----------------------------------------|
#'    |league      |character |League slug.                             |
#'    |season      |integer   |Season year.                             |
#'    |season_type |integer   |Season-type id.                          |
#'    |week        |integer   |Week number (1-based).                   |
#'    |ref         |character |`$ref` URL for the week detail.          |
#'
#' @importFrom jsonlite fromJSON
#' @importFrom dplyr as_tibble
#' @export
#' @family ESPN WBB Functions
#' @examples
#' \donttest{
#'   espn_wbb_season_weeks(season = 2025)
#' }
espn_wbb_season_weeks <- function(season = most_recent_wbb_season(),
                                   season_type = c(2L, 3L), ...) {
  .espn_basketball_season_weeks(league = "womens-college-basketball", season = season,
                                  season_type = season_type, ...)
}

# ---------------------------------------------------------------------------
# espn_wbb_season_week
# ---------------------------------------------------------------------------

#' **Get ESPN WBB Season-Week Detail**
#' @name espn_wbb_season_week
#' @title
#' **Get ESPN WBB Season-Week Detail**
#' @rdname espn_wbb_season_week
#' @author Saiem Gilani
#' @description
#' Returns metadata for one week (number, start / end dates, text label,
#' and `$ref` to the per-week rankings endpoint).
#'
#' @param week Week number.
#' @param season Season year. Defaults to most recent WBB 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_basketball_season_week_schema] table.
#'
#' @importFrom jsonlite fromJSON
#' @importFrom dplyr as_tibble
#' @export
#' @family ESPN WBB Functions
#' @examples
#' \donttest{
#'   espn_wbb_season_week(week = 5, season = 2025)
#' }
espn_wbb_season_week <- function(week,
                                  season = most_recent_wbb_season(),
                                  season_type = 2L, ...) {
  .espn_basketball_season_week(league = "womens-college-basketball", season = season,
                                 season_type = season_type,
                                 week = week, ...)
}

# ---------------------------------------------------------------------------
# espn_wbb_week_rankings
# ---------------------------------------------------------------------------

#' **Get ESPN WBB Per-Week Rankings Index**
#' @name espn_wbb_week_rankings
#' @title
#' **Get ESPN WBB Per-Week Rankings Index**
#' @rdname espn_wbb_week_rankings
#' @author Saiem Gilani
#' @description
#' Returns the index of ranking sources available for one (WBB season x
#' season-type x week). Typical sources: AP Top 25 (id 1), Coaches Poll
#' (id 2). Pass an id to [espn_wbb_week_ranking()] for the ranked teams.
#'
#' @param week Week number.
#' @param season Season year. Defaults to most recent WBB season.
#' @param season_type Season-type id (2 = regular (default)).
#' @param ... Additional arguments; currently unused.
#' @return A tibble with one row per ranking source.
#'
#'    |col_name    |types     |description                              |
#'    |:-----------|:---------|:----------------------------------------|
#'    |league      |character |League slug.                             |
#'    |season      |integer   |Season year.                             |
#'    |season_type |integer   |Season-type id.                          |
#'    |week        |integer   |Week number.                             |
#'    |ranking_id  |character |ESPN ranking id.                         |
#'    |ref         |character |`$ref` URL for the ranked-teams detail.  |
#'
#' @importFrom jsonlite fromJSON
#' @importFrom dplyr as_tibble
#' @export
#' @family ESPN WBB Functions
#' @examples
#' \donttest{
#'   espn_wbb_week_rankings(week = 5, season = 2025)
#' }
espn_wbb_week_rankings <- function(week,
                                    season = most_recent_wbb_season(),
                                    season_type = 2L, ...) {
  .espn_basketball_week_rankings(league = "womens-college-basketball", season = season,
                                   season_type = season_type,
                                   week = week, ...)
}

# ---------------------------------------------------------------------------
# espn_wbb_week_ranking
# ---------------------------------------------------------------------------

#' **Get ESPN WBB Per-Week Ranking Detail**
#' @name espn_wbb_week_ranking
#' @title
#' **Get ESPN WBB Per-Week Ranking Detail**
#' @rdname espn_wbb_week_ranking
#' @author Saiem Gilani
#' @description
#' Returns the long-format ranked teams for one (season x season-type x
#' week x ranking-source). Typically 25 rows for WBB (AP Top 25).
#'
#' @param ranking_id Ranking source id (1 = AP, 2 = Coaches, etc.).
#' @param week Week number.
#' @param season Season year. Defaults to most recent WBB season.
#' @param season_type Season-type id (2 = regular (default)).
#' @param ... Additional arguments; currently unused.
#' @return A tibble with one row per ranked team (typically 25).
#'
#'    Columns as documented in the shared [espn_basketball_week_ranking_schema] table.
#'
#' @importFrom jsonlite fromJSON
#' @importFrom dplyr as_tibble
#' @export
#' @family ESPN WBB Functions
#' @examples
#' \donttest{
#'   espn_wbb_week_ranking(ranking_id = 1, week = 5, season = 2025)
#' }
espn_wbb_week_ranking <- function(ranking_id, week,
                                   season = most_recent_wbb_season(),
                                   season_type = 2L, ...) {
  .espn_basketball_week_ranking(league = "womens-college-basketball", season = season,
                                  season_type = season_type,
                                  week = week,
                                  ranking_id = ranking_id, ...)
}