R/mlb_game_pace.R

In baseballr: Acquiring and Analyzing Baseball Data

#' @rdname mlb_game_pace
#' @title **Retrieve game pace metrics for major and minor league**
#' @param season Year for which to return information (*Required*).
#' @param team_ids The team_id(s) for which to return information.
#' @param league_ids The league_id(s) for which to return information.
#' @param sport_ids The sport_id(s) for which to return information.
#' @param game_type The game_type for which to return information.
#' @param venue_ids Venue directorial information based venue_id. 
#' @param org_type pace of game metrics based on team ('T'), league ('L') or sport('S')
#' @param start_date Date of first game for which you want data.
#' Format must be in MM/DD/YYYY format.
#' @param end_date Date of last game for which you want data.
#' Format must be in MM/DD/YYYY format.
#' @return Returns a tibble with the following columns
#'
#'   |col_name                                            |types     |description                                       |
#'   |:---------------------------------------------------|:---------|:-------------------------------------------------|
#'   |hits_per9inn                                        |numeric   |Hits per 9 innings.                               |
#'   |runs_per9inn                                        |numeric   |Runs per 9 innings.                               |
#'   |pitches_per9inn                                     |numeric   |Pitches per 9 innings.                            |
#'   |plate_appearances_per9inn                           |numeric   |Plate appearances per 9 innings.                  |
#'   |hits_per_game                                       |numeric   |Hits per game.                                    |
#'   |runs_per_game                                       |numeric   |Runs per game.                                    |
#'   |innings_played_per_game                             |numeric   |Innings played per game.                          |
#'   |pitches_per_game                                    |numeric   |Pitches per game.                                 |
#'   |pitchers_per_game                                   |numeric   |Pitchers used per game.                           |
#'   |plate_appearances_per_game                          |numeric   |Plate appearances per game.                       |
#'   |total_game_time                                     |character |Total game time (HHH:MM:SS).                      |
#'   |total_innings_played                                |numeric   |Total innings played.                             |
#'   |total_hits                                          |integer   |Total hits.                                       |
#'   |total_runs                                          |integer   |Total runs.                                       |
#'   |total_plate_appearances                             |integer   |Total plate appearances.                          |
#'   |total_pitchers                                      |integer   |Total pitchers used.                              |
#'   |total_pitches                                       |integer   |Total pitches thrown.                             |
#'   |total_games                                         |integer   |Total games.                                      |
#'   |total7inn_games                                     |integer   |Total 7-inning games.                             |
#'   |total9inn_games                                     |integer   |Total 9-inning games.                             |
#'   |total_extra_inn_games                               |integer   |Total extra-inning games.                         |
#'   |time_per_game                                       |character |Average time per game (HH:MM:SS).                 |
#'   |time_per_pitch                                      |character |Average time per pitch (HH:MM:SS).                |
#'   |time_per_hit                                        |character |Average time per hit (HH:MM:SS).                  |
#'   |time_per_run                                        |character |Average time per run (HH:MM:SS).                  |
#'   |time_per_plate_appearance                           |character |Average time per plate appearance (HH:MM:SS).     |
#'   |time_per9inn                                        |character |Average time per 9 innings (HH:MM:SS).            |
#'   |time_per77plate_appearances                         |character |Average time per 77 plate appearances.            |
#'   |total_extra_inn_time                                |character |Total extra-inning time (HHH:MM:SS).              |
#'   |time_per7inn_game                                   |character |Average time per 7-inning game (HH:MM:SS).        |
#'   |time_per7inn_game_without_extra_inn                 |character |Average time per 7-inning game excl. extras.      |
#'   |total7inn_games_scheduled                           |integer   |Total 7-inning games scheduled.                   |
#'   |total7inn_games_without_extra_inn                   |integer   |Total 7-inning games without extra innings.       |
#'   |total9inn_games_without_extra_inn                   |integer   |Total 9-inning games without extra innings.       |
#'   |total9inn_games_scheduled                           |integer   |Total 9-inning games scheduled.                   |
#'   |hits_per_run                                        |numeric   |Hits per run.                                     |
#'   |pitches_per_pitcher                                 |numeric   |Pitches per pitcher.                              |
#'   |season                                              |character |Season (YYYY).                                    |
#'   |total9inn_games_completed_early                     |integer   |9-inning games completed early.                   |
#'   |total7inn_games_completed_early                     |integer   |7-inning games completed early.                   |
#'   |sport_id                                            |integer   |MLB sport ID.                                     |
#'   |sport_code                                          |character |Sport code (e.g. mlb, aaa).                       |
#'   |sport_link                                          |character |MLB Stats API relative sport link.                |
#'   |pr_portal_calculated_fields_total7inn_games         |integer   |Portal-calculated total 7-inning games.           |
#'   |pr_portal_calculated_fields_total9inn_games         |integer   |Portal-calculated total 9-inning games.           |
#'   |pr_portal_calculated_fields_total_extra_inn_games   |integer   |Portal-calculated total extra-inning games.       |
#'   |pr_portal_calculated_fields_time_per7inn_game       |character |Portal-calculated time per 7-inning game.         |
#'   |pr_portal_calculated_fields_time_per9inn_game       |character |Portal-calculated time per 9-inning game.         |
#'   |pr_portal_calculated_fields_time_per_extra_inn_game |character |Portal-calculated time per extra-inning game.     |
#'
#' @importFrom jsonlite fromJSON
#' @importFrom tidyr spread
#' @importFrom tibble tibble
#' @importFrom stringr str_sub
#' @export
#' @examples \donttest{
#'   try(mlb_game_pace(season = 2021, start_date = "09/14/2021", end_date = "09/16/2021"))
#' }

mlb_game_pace <- function(season, 
                          league_ids = NULL, 
                          sport_ids = NULL, 
                          team_ids = NULL,
                          game_type = NULL, 
                          venue_ids = NULL,  
                          org_type = NULL,
                          start_date = NULL,
                          end_date = NULL) {
  
  mlb_endpoint <- mlb_stats_endpoint(glue::glue("v1/gamePace"))
  query_params <- list(
    season = season, 
    leagueId = league_ids,
    teamIds = team_ids,
    sportIds = sport_ids,
    gameType = game_type,
    venueIds = venue_ids, 
    orgType = org_type,
    startDate = start_date,
    endDate = end_date
  )
  mlb_endpoint <- httr2::url_modify_query(mlb_endpoint, !!!query_params)
  
  game_pace <- NULL
  tryCatch(
    expr = {
      resp <- mlb_endpoint |> 
        mlb_api_call() |> 
        jsonlite::toJSON() |> 
        jsonlite::fromJSON(flatten = TRUE)
      game_pace <- resp$sports |> 
        as.data.frame() |> 
        janitor::clean_names() |>
        make_baseballr_data("MLB Game Pace data from MLB.com",Sys.time())
    },
    error = function(e) {
      cli::cli_alert_danger("{Sys.time()}: Invalid arguments provided")
    },
    finally = {
    }
  )
  return(game_pace)
}