header_tag.html

Skip to contents

USGS Samples Data

Source: R/read_USGS_samples.R
read_USGS_samples.Rd

This function creates the call and gets the data for discrete water quality samples data service described at https://waterdata.usgs.gov/download-samples.

Usage

read_USGS_samples(
  monitoringLocationIdentifier = NA,
  siteTypeCode = NA,
  boundingBox = NA,
  hydrologicUnit = NA,
  activityMediaName = NA,
  characteristicGroup = NA,
  characteristic = NA,
  characteristicUserSupplied = NA,
  activityStartDateLower = NA,
  activityStartDateUpper = NA,
  countryFips = NA,
  stateFips = NA,
  countyFips = NA,
  projectIdentifier = NA,
  recordIdentifierUserSupplied = NA,
  siteTypeName = NA,
  usgsPCode = NA,
  pointLocationLatitude = NA,
  pointLocationLongitude = NA,
  pointLocationWithinMiles = NA,
  dataType = "results",
  dataProfile = NA,
  tz = "UTC"
)

Arguments

monitoringLocationIdentifier

A monitoring location identifier has two parts: the agency code and the location number, separated by a dash (-). Location identifiers should be separated with commas, for example: AZ014-320821110580701, CAX01-15304600, USGS-040851385. Location numbers without an agency prefix are assumed to have the prefix USGS.

siteTypeCode

Site type code query parameter. See available options by running check_param("sitetype")$typeCode.

boundingBox

North and South are latitude values; East and West are longitude values. A vector of 4 (west, south, east, north) is expected. An example would be: c(-92.8, 44.2, -88.9, 46.0).

hydrologicUnit

Hydrologic Unit Codes (HUCs) identify physical areas within the US that drain to a certain portion of the stream network. This filter accepts values containing 2, 4, 6, 8, 10 or 12 digits.

activityMediaName

Sample media refers to the environmental medium that was sampled or analyzed.

characteristicGroup

Characteristic group is a broad category describing the sample. See available options by running check_param("characteristicgroup")$characteristicGroup.

characteristic

Characteristic is a specific category describing the sample. See available options by running check_param("characteristics")$characteristicName.

characteristicUserSupplied

Observed property is the USGS term for the constituent sampled and the property name gives a detailed description of what was sampled. Observed property is mapped to characteristicUserSupplied and replaces the parameter name and pcode USGS previously used to describe discrete sample data. Find more information in the Observed Properties and Parameter Codes section of the Code Dictionary found here: https://waterdata.usgs.gov/code-dictionary/.

activityStartDateLower

The service will return records with dates earlier than the value entered for activityStartDateUpper. Can be an R Date object, or a string with format YYYY-MM-DD. The logic is inclusive, i.e. it will also return records that match the date.

activityStartDateUpper

The service will return records with dates later than the value entered for activityStartDateLower. Can be an R Date object, or a string with format YYYY-MM-DD. The logic is inclusive, i.e. it will also return records that match the date.

countryFips

Country query parameter. Do not set redundant parameters. If another query parameter contains the country information, leave this parameter set to the default NA. See available options by running check_param("countries"), where the "id" field contains the value to use in the countryFips input.

stateFips

State query parameter. To get a list of available state fips, run check_param("states"). The "fips" can be created using the function stateCdLookup - for example: stateCdLookup("WI", "fips"). FIPs codes for states take the format: CountryAbbrev:StateNumber, like US:55 for Wisconsin.

countyFips

County query parameter. To get a list of available counties, run check_param("counties"). The "Fips" can be created using the function countyCdLookup - for example: countyCdLookup("WI", "Dane", "fips") for Dane County, WI. FIPs codes for counties take the format: CountryAbbrev:StateNumber:CountyNumber, like US:55:025 for Dane County, WI.

projectIdentifier

Project identifier query parameter. This information would be needed from prior project information.

recordIdentifierUserSupplied

Record identifier, user supplied identifier. This information would be needed from the data supplier.

siteTypeName

Site type name query parameter. See available options by running check_param("sitetype")$typeName.

usgsPCode

USGS parameter code. See available options by running check_param("characteristics")$parameterCode.

pointLocationLatitude

Latitude for a point/radius query (decimal degrees). Must be used with pointLocationLongitude and pointLocationWithinMiles.

pointLocationLongitude

Longitude for a point/radius query (decimal degrees). Must be used with pointLocationLatitude and pointLocationWithinMiles.

pointLocationWithinMiles

Radius for a point/radius query. Must be used with pointLocationLatitude and pointLocationLongitude

dataType

Options include: "Results", "Monitoring locations", "Activities", "Projects", and "Organizations".

dataProfile

Profile depends on type. Options for "results" dataType are: "fullphyschem", "basicphyschem", "fullbio", "basicbio", "narrow", "resultdetectionquantitationlimit", "labsampleprep", "count". Options for "locations" are: "site" and "count". Options for "activities" are "sampact", "actmetric", "actgroup", and "count". Options for "projects" are: "project" and "projectmonitoringlocationweight". Options for "organizations" are: "organization" and "count".

tz

character to set timezone attribute of datetime. Default is UTC (properly accounting for daylight savings times based on the data's provided tz_cd column). Possible values include "America/New_York","America/Chicago", "America/Denver","America/Los_Angeles", "America/Anchorage","America/Honolulu","America/Jamaica","America/Managua", "America/Phoenix", and "America/Metlakatla"

Examples


# \donttest{
ph_data <- read_USGS_samples(
               monitoringLocationIdentifier = "USGS-04074950",
               characteristicUserSupplied = "pH, water, unfiltered, field",
               activityStartDateUpper = "2000-01-01",
               dataProfile = "narrow")
#> Function in development, use at your own risk.
#> GET:https://api.waterdata.usgs.gov/samples-data/results/narrow?mimeType=text%2Fcsv&monitoringLocationIdentifier=USGS-04074950&characteristicUserSupplied=pH%2C%20water%2C%20unfiltered%2C%20field&activityStartDateUpper=2000-01-01
               
nameToUse <- "pH"
pHData <- read_USGS_samples(monitoringLocationIdentifier = "USGS-04024315", 
                         characteristic = nameToUse)
#> Function in development, use at your own risk.
#> No profile specified, defaulting to 'fullphyschem'
#> Possible values are: 
#> fullphyschem, basicphyschem, fullbio, basicbio, narrow, resultdetectionquantitationlimit, labsampleprep, count
#> GET:https://api.waterdata.usgs.gov/samples-data/results/fullphyschem?mimeType=text%2Fcsv&monitoringLocationIdentifier=USGS-04024315&characteristic=pH
#> Waiting 2s for throttling delay ■■■■■■■■■■■■■■■                 
#> Waiting 2s for throttling delay ■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■  
ncol(pHData)
#> [1] 183
attr(pHData, "url")
#> [1] "https://api.waterdata.usgs.gov/samples-data/results/fullphyschem?mimeType=text%2Fcsv&monitoringLocationIdentifier=USGS-04024315&characteristic=pH"
attr(pHData, "queryTime")
#> [1] "2025-02-10 20:02:12 UTC"

summary_data <- read_USGS_samples(monitoringLocationIdentifier = "USGS-04024315", 
                               dataType = "projects")
#> Function in development, use at your own risk.
#> No profile specified, defaulting to 'project'
#> Possible values are: 
#> project, projectmonitoringlocationweight
#> GET:https://api.waterdata.usgs.gov/samples-data/projects/project?mimeType=text%2Fcsv&monitoringLocationIdentifier=USGS-04024315

# }