R/readNWISsite.R

In USGS-R/dataRetrieval: Retrieval Functions for USGS and EPA Hydrology and Water Quality Data

#' USGS Site File Data Retrieval
#'
#' Imports data from USGS site file site. This function gets data from here: \url{https://waterservices.usgs.gov/}
#'
#' @param siteNumbers character USGS site number (or multiple sites).  This is usually an 8 digit number
#' @keywords data import USGS web service
#' @return A data frame with at least the following columns:
#' \tabular{lll}{
#' Name \tab Type \tab Description \cr
#' agency_cd \tab character \tab The NWIS code for the agency reporting the data\cr
#' site_no \tab character \tab The USGS site number \cr
#'  station_nm \tab character \tab Site name \cr
#'  site_tp_cd \tab character \tab Site type \cr
#'  lat_va \tab numeric \tab DMS latitude \cr
#'  long_va \tab numeric \tab DMS longitude \cr
#'  dec_lat_va \tab numeric \tab Decimal latitude \cr
#'  dec_long_va \tab numeric \tab Decimal longitude \cr
#'  coord_meth_cd  \tab character \tab Latitude-longitude method \cr
#'  coord_acy_cd \tab character \tab Latitude-longitude accuracy \cr
#'  coord_datum_cd \tab character \tab Latitude-longitude datum \cr
#'  dec_coord_datum_cd \tab character \tab Decimal Latitude-longitude datum \cr
#'  district_cd \tab character \tab District code \cr
#'  state_cd \tab character \tab State code \cr
#'  county_cd \tab character \tab County code \cr
#'  country_cd \tab character \tab Country code \cr
#'  land_net_ds \tab character \tab Land net location description \cr
#'  map_nm \tab character \tab Name of location map \cr
#'  map_scale_fc \tab character \tab Scale of location map \cr
#'  alt_va \tab numeric \tab Altitude of Gage/land surface \cr
#'  alt_meth_cd \tab character \tab Method altitude determined \cr
#'  alt_acy_va  \tab numeric \tab Altitude accuracy \cr
#'  alt_datum_cd \tab character \tab Altitude datum \cr
#'  huc_cd \tab character \tab Hydrologic unit code \cr
#'  basin_cd \tab character \tab Drainage basin code \cr
#'  topo_cd \tab character \tab Topographic setting code \cr
#'  instruments_cd \tab character \tab Flags for instruments at site \cr
#'  construction_dt \tab character \tab Date of first construction \cr
#'  inventory_dt \tab character \tab Date site established or inventoried \cr
#'  drain_area_va \tab numeric \tab Drainage area \cr
#'  contrib_drain_area_va \tab numeric \tab Contributing drainage area \cr
#'  tz_cd  \tab character \tab Time Zone abbreviation \cr
#'  local_time_fg \tab character \tab Site honors Daylight Savings Time \cr
#'  reliability_cd \tab character \tab Data reliability code \cr
#'  gw_file_cd \tab character \tab Data-other GW files \cr
#'  nat_aqfr_cd \tab character \tab National aquifer code \cr
#'  aqfr_cd \tab character \tab Local aquifer code \cr
#'  aqfr_type_cd \tab character \tab Local aquifer type code \cr
#'  well_depth_va \tab numeric \tab Well depth \cr
#'  hole_depth_va \tab numeric \tab Hole depth \cr
#'  depth_src_cd \tab character \tab Source of depth data \cr
#'  project_no \tab character \tab Project number \cr
#' }
#'
#' There are also several useful attributes attached to the data frame:
#' \tabular{lll}{
#' Name \tab Type \tab Description \cr
#' url \tab character \tab The url used to generate the data \cr
#' queryTime \tab POSIXct \tab The time the data was returned \cr
#' comment \tab character \tab Header comments from the RDB file \cr
#' }
#' @export
#' @examplesIf is_dataRetrieval_user()
#' \donttest{
#'
#' siteINFO <- readNWISsite("05114000")
#' siteINFOMulti <- readNWISsite(c("05114000", "09423350"))
#' }
readNWISsite <- function(siteNumbers) {
  siteNumber <- paste(siteNumbers, collapse = ",")
  names(siteNumber) <- "site"
  urlSitefile <- drURL("site",
    Access = pkg.env$access,
    siteOutput = "Expanded", format = "rdb"
  )
  urlSitefile <- appendDrURL(urlSitefile, arg.list = siteNumber)

  data <- importRDB1(urlSitefile, asDateTime = FALSE)
  # readr needs multiple lines to convert to anything but characters:
  data[grep("_va", names(data))][data[grep("_va", names(data))] == "."] <- NA

  data[, grep("_va", names(data))] <- sapply(data[, grep("_va", names(data))], as.numeric)

  return(data)
}