Get period of record daily data — read_waterdata_daily

Using the STAC Water Data service, get full period of record returns for daily data. The most recent data may be missing, but can be retrieved using read_waterdata_daily.

Usage

read_waterdata_daily_por(
  monitoring_location_id = NA_character_,
  county_name = NA_character_,
  state_name = NA_character_,
  site_type = NA_character_,
  site_type_code = NA_character_,
  hydrologic_unit_code = NA_character_,
  bbox = NA,
  time_series_id = NA_character_,
  parameter_code = NA_character_,
  start_time = NA_character_,
  end_time = NA_character_,
  approval_status = NA_character_,
  statistic_id = NA_character_,
  ...,
  site_limits = 1000,
  memory_MB_limit = 1000
)

Arguments

monitoring_location_id

Each monitoring location in the USGS data base has a unique 8- to 15-digit identification number.

county_name

The name of the county or county equivalent (parish, borough, etc.) in which the monitoring location is located. [A list of codes is available at https://api.waterdata.usgs.gov/ogcapi/v1/collections/counties/items.

state_name

The name of the state or state equivalent in which the monitoring location is located.

site_type

A description of the hydrologic setting of the monitoring location. A list of codes is available at https://api.waterdata.usgs.gov/ogcapi/v1/collections/site-types/items.

site_type_code

A code describing the hydrologic setting of the monitoring location. A list of codes is available at https://api.waterdata.usgs.gov/ogcapi/v1/collections/site-types/items.

hydrologic_unit_code

The hydrologic unit code (HUC) for the monitoring location. Supports prefix matching — querying with a shorter HUC (e.g. "04") matches all locations within that hydrologic region.

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).

time_series_id

A unique identifier representing a single time series. This corresponds to the id field in the time-series-metadata endpoint.

Multiple time_series_ids can be requested as a character vector.

parameter_code

Parameter codes are 5-digit codes used to identify the constituent measured and the units of measure. A complete list of parameter codes and associated groupings can be found at https://api.waterdata.usgs.gov/ogcapi/v1/collections/parameter-codes/items.

Multiple parameter_codes can be requested as a character vector.

start_time

Earliest time returned

end_time

Latest time returned

approval_status

Some of the data that you have obtained from this U.S. Geological Survey database may not have received Director's approval. Any such data values are qualified as provisional and are subject to revision. Provisional data are released on the condition that neither the USGS nor the United States Government may be held liable for any damages resulting from its use. This field reflects the approval status of each record, and is either "Approved", meaining processing review has been completed and the data is approved for publication, or "Provisional" and subject to revision. For more information about provisional data, go to https://waterdata.usgs.gov/provisional-data-statement/.

statistic_id

A code corresponding to the statistic an observation represents. Example codes include 00001 (max), 00002 (min), and 00003 (mean). A complete list of codes and their descriptions can be found at https://api.waterdata.usgs.gov/ogcapi/v1/collections/statistic-codes/items.

Multiple statistic_ids can be requested as a character vector.

...

Not used.

site_limits

Set a limit to how many sites will be returned

memory_MB_limit

If the returned data is roughly bigger than this argument, then the function will error out. Increasing this value will allow bigger queries to be retrieved. from the STAC search.

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, time = c("2024-01-01", NA) will return all data starting at 2024-01-01. 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 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


# \donttest{

df <- read_waterdata_daily_por(
    monitoring_location_id = "USGS-0208458892"
)
#> Requesting:
#> https://api.waterdata.usgs.gov/ogcapi/v1/collections/combined-metadata/items?f=json&lang=en-US&monitoring_location_id=USGS-0208458892&data_type=Daily%20values&limit=50000
#> Remaining requests this hour:1998 
nrow(df)
#> [1] 81366

# Multiple sites:
df_2 <- read_waterdata_daily_por(
    monitoring_location_id = c("USGS-01435000", "USGS-05406360")
)
#> Requesting:
#> https://api.waterdata.usgs.gov/ogcapi/v1/collections/combined-metadata/items?f=json&lang=en-US&monitoring_location_id=USGS-01435000,USGS-05406360&data_type=Daily%20values&limit=50000
#> Remaining requests this hour:1994 
nrow(df_2)
#> [1] 108984

# Multiple sites, limited parameter_codes:
df_3 <- read_waterdata_daily_por(
    monitoring_location_id = c("USGS-01435000", "USGS-05406360"),
    parameter_code = c("00060", "00065")
)
#> Requesting:
#> https://api.waterdata.usgs.gov/ogcapi/v1/collections/combined-metadata/items?f=json&lang=en-US&monitoring_location_id=USGS-01435000,USGS-05406360&parameter_code=00060,00065&data_type=Daily%20values&limit=50000
#> Remaining requests this hour:1979 
nrow(df_3)
#> [1] 32114
range(df_3$time)
#> [1] "1937-11-01" "2026-11-04"

# Multiple sites, limited parameter_codes, limited time:
df_4 <- read_waterdata_daily_por(
    monitoring_location_id = c("USGS-01435000", "USGS-05406360"),
    parameter_code = c("00060", "00065"),
    start_time = as.POSIXct("1960-01-01", tz = "UTC"),
    approval_status = "Approved"
)
#> Requesting:
#> https://api.waterdata.usgs.gov/ogcapi/v1/collections/combined-metadata/items?f=json&lang=en-US&monitoring_location_id=USGS-01435000,USGS-05406360&parameter_code=00060,00065&data_type=Daily%20values&limit=50000
#> Remaining requests this hour:1971 
nrow(df_4)
#> [1] 24463
range(df_4$time)
#> [1] "1960-01-01" "2025-11-23"

# HUCs
df_huc <- read_waterdata_daily_por(
    hydrologic_unit_code = "07090002",
    parameter_code = "00060"
)
#> Requesting:
#> https://api.waterdata.usgs.gov/ogcapi/v1/collections/combined-metadata/items?f=json&lang=en-US&parameter_code=00060&data_type=Daily%20values&hydrologic_unit_code=07090002&limit=50000
#> Remaining requests this hour:1951 

df_ts_id <- read_waterdata_daily_por(
    time_series_id = c("5dac1dd9ef6c404a86f98bf922badd36",
                       "40ccf2569ec54edbbf1f0a1717be1ba1")
)
#> Requesting:
#> https://api.waterdata.usgs.gov/ogcapi/v1/collections/combined-metadata/items?f=json&lang=en-US&data_type=Daily%20values&id=5dac1dd9ef6c404a86f98bf922badd36,40ccf2569ec54edbbf1f0a1717be1ba1&limit=50000
#> Remaining requests this hour:1363 

# }