% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/read_waterdata_ratings.R
\name{read_waterdata_ratings}
\alias{read_waterdata_ratings}
\title{Get USGS Rating Curve Data}
\usage{
read_waterdata_ratings(
  monitoring_location_id = NA_character_,
  file_type = c("exsa", "base", "corr"),
  file_path = tempdir(),
  bbox = NA,
  datetime = NA_character_,
  ...,
  limit = 10000,
  download_and_parse = TRUE
)
}
\arguments{
\item{monitoring_location_id}{A unique identifier representing a single
monitoring location. Monitoring location IDs are created by combining the
agency code of the agency responsible for the monitoring location (e.g. USGS)
with the ID number of the monitoring location (e.g. 02238500), separated by
a hyphen (e.g. USGS-02238500).}

\item{file_type}{Rating file time. Could be any of "exsa", "corr", or "base".
If \code{file_type} is "base" then the columns are
INDEP, typically the gage height, in feet; DEP, typically the streamflow,
in cubic feet per second; and STOR, where "*" indicates that the pair are
a fixed point of the rating curve. If \code{file_type} is "exsa" then an
additional column, SHIFT, is included that indicates the current shift in
the rating for that value of INDEP. If \code{file_type} is "corr" then the
columns are INDEP, typically the gage height, in feet; CORR, the correction
for that value; and CORRINDEP, the corrected value for CORR.}

\item{file_path}{Path to save the rating curve rdb files. The
default is \code{tempdir()}, which will wipe out the files.}

\item{bbox}{Only features that have a geometry that intersects the bounding
box are selected.The bounding box is provided as four or six numbers, depending
on whether the coordinate reference system includes a vertical axis (height or
depth). Coordinates are assumed to be in crs 4326. The expected format is a numeric
vector structured: c(xmin,ymin,xmax,ymax).
Another way to think of it is c(Western-most longitude,
Southern-most latitude, Eastern-most longitude, Northern-most longitude).}

\item{datetime}{Only return items that have a temporal property that
intersects this value. Either a date-time or an interval, open or closed.
See Details below.}

\item{\dots}{Not used.}

\item{limit}{Limits the number of results that are included in each page of
the response (capped at the default 10,000).}

\item{download_and_parse}{Logical to define whether or not to download, parse,
and return a list of data frames with rating curve data (\code{TRUE}), or to return
just a list of available rating curve files (\code{FALSE}). Default is \code{TRUE}.}
}
\value{
List of data frames which contain the requested rating curves.
}
\description{
Reads current rating table for an active USGS streamgages. More information
can be found at https://api.waterdata.usgs.gov/docs/stac/.
}
\details{
You can also use a vector of length 2 for any time queries (such as time
or last_modified). The first value is the starting date (or datetime),
the second value is the ending date(or datetime).
NA's within the vector indicate a half-bound date.
For example, \code{time = c("2024-01-01", NA)} will return all data starting
at 2024-01-01.
\code{time = c(NA, "2024-01-01")} will return all data from the beginning of
the timeseries until 2024-01-01.
By default, time is assumed UTC, although time zone attributes
will be accommodated. As an example, setting \code{time = as.POSIXct(c("2021-01-01 12:00:00",
"2021-01-01 14:00"), tz = "America/New_York")} will request data that between
noon and 2pm eastern time on 2021-01-01.
All time values RETURNED from the service are UTC with the exception of
daily data, which returns time values in local dates.
}
\examples{
\dontshow{if (is_dataRetrieval_user()) withAutoprint(\{ # examplesIf}

\donttest{

monitoring_location_id <- c("USGS-01104475", "USGS-01104460")
ratings_exsa <- read_waterdata_ratings(
      monitoring_location_id = monitoring_location_id,
      file_type = "exsa")

head(ratings_exsa[["USGS-01104475.exsa.rdb"]])
comment(ratings_exsa[["USGS-01104475.exsa.rdb"]])[1:15]

ratings_corr <- read_waterdata_ratings(
      monitoring_location_id = monitoring_location_id,
      file_type = "corr")

head(ratings_corr[["USGS-01104460.corr.rdb"]])
comment(ratings_corr[["USGS-01104460.corr.rdb"]])[1:15]

rating_2 <- read_waterdata_ratings(
      monitoring_location_id = monitoring_location_id,
      file_type = c("corr", "exsa"))
names(rating_2)

bbox <- c(-95.00, 40.0, -92.0, 42)

bbox_query <- read_waterdata_ratings(bbox = bbox,
                                     download_and_parse = FALSE)
length(bbox_query)
recent_query <- read_waterdata_ratings(bbox = bbox,
                                       datetime = c(Sys.Date()-7, NA),
                                       download_and_parse = FALSE)
length(recent_query)
}
\dontshow{\}) # examplesIf}
}
