Add stats API

New features should include all of the following work:

• Create the read_waterdata_statistics file (or some other name?). File should:

  • Create function
  • Create Roxygen (parameters, examples, etc).

• Add deprecate notice to corresponding NWISstat function

• Comment out or delete deprecated NWIS examples

• Replace any readNWISstat tests with new waterdata function

• Create new tests in tests/testthat folder for unique situations

• Add example to read_waterdata_functions.Rmd vignette

• Update Status.Rmd vignette

• Update dataRetrieval.Rmd vignette

• Update tutorial.Rmd vignette

• Update NEWS

• Update _pkgdown.yml

• Check if README needs to be updated

• Update version (for development, only bump up last 4 digits)

• Create PR for "develop" branch on GitHub

• Create and merge MR for "develop" branch on code.usgs.gov. This will generate development version of documentation.

Simple text code I was messing with:

library(httr2)

"https://api.waterdata.usgs.gov/statistics/v0/observationIntervals?approval_status=approved&computation_type=arithmetic_mean&computation_type=maximum&computation_type=median&county_code=US%3A42%3A103&mime_type=application%2Fjson&page_size=1000&parameter_code=00095"

base_stat_url <- httr2::request("https://api.waterdata.usgs.gov/statistics/") |> 
  httr2::req_url_path_append("v0") 

interval_url <- base_stat_url |> 
  httr2::req_url_path_append("observationIntervals") 

normal_url <- base_stat_url |> 
  httr2::req_url_path_append("observationNormals") 

interval_url2 <- dataRetrieval:::explode_query(interval_url, POST = FALSE,
                                               x = list(approval_status = "approved",
                                                        computation_type = c("arithmetic_mean", "maximum"),
                                                        page_size = 1000,
                                                        county_code = "US:42:103",
                                                        parameter_code = "00095",
                                                        mime_type = "application/json"))

return_list <- dataRetrieval:::walk_pages(interval_url2, 1000)
# or
# resp <- httr2::req_perform(interval_url2)
# body <- httr2::resp_body_string(resp)
# out_list <- sf::read_sf(body)

library(data.table)
return_list$data_return <- I(list(vector(mode = "list", length = 3)))

for(i in 1:nrow(return_list)){
  x <- jsonlite::parse_json(return_list$data[i])
  z <- data.frame(rbindlist(x))
  zz <- rbindlist(lapply(z$values, \(i) data.frame(t(i))), fill=T)
  return_list$data_return[[i]] <- zz
}

Notes:

1. we don't want to add more dependencies if possible, so would need to figure out how to do it without data.tables
2. walk_pages won't work out of the box for multiple pages (which it does have). So we'll need to look into if it's easier to write a new function (or figure out if httr2::req_perform_iterative can be used as-is) or add some complexity to walk_pages.
3. The output format can be reconsidered, like would it make more sense to have a huge (repetitive) data frame?
4. Re-write https://water.code-pages.usgs.gov/dataRetrieval/articles/statsServiceMap.html ?

https://api.waterdata.usgs.gov/statistics/v0/docs#/read_interval_observations/read_observation_intervals_statistics_v0_observationIntervals_get