ceden_query: Download CEDEN data via an API

Description Usage Arguments Value Examples

View source: R/ceden_query.R

Description

This function provides an interface with CEDEN web services to perform queries and programatically download data.

Usage

1
2
3
ceden_query(service, query_parameters,
  base_URI = "https://testcedenwebservices.waterboards.ca.gov:9267",
  userName = "", password = "", errorMessages_out = TRUE)

Arguments

service

A text string representing one of the 15 CEDEN advanced query tool services. For each of the 5 categories of monitoring data (Benthic, Habitat, Tissue, Toxicity, WaterQuality), there are 3 types of data available (MonitoringStationsList, ParameterCountsList, ResultsList). For example: CEDENBenthicMonitoringStationsList

query_parameters

The query string (in plain text). This includes everything after the ?queryParams={ statement, except the closing } of the query string. For information on how to construct a query string, see the documentation for the CEDEN web services.

base_URI

The base part of the URL for all CEDEN web services (e.g.,https://cedenwebservices.waterboards.ca.gov), including a port number if required (use ":9267" if on the State Water Board network). Defaults to: https://testcedenwebservices.waterboards.ca.gov:9267

userName

The user name for your CEDEN web services account. You can enter this through the function, or if you leave this argument blank the function will look for this information in a variable called 'ceden_userName' within the environment variables defined for your account.

password

The password for your CEDEN web services account. You can enter this through the function, or if you leave this argument blank the function will look for this information in a variable called 'ceden_password' within the environment variables defined for your account.

errorMessages_out

When set to TRUE, if there is an error with the authentication or the query request (inclduing when there is simply no data returned that meets the query parameters), the function will attempt to return a data frame with information about the error (including where the error occured, the HTTP code returned, and any messages about the API response). When set to FALSE, the function will simply return NA on an error.

Value

This function returns a data frame with the data specified in the service and query_parameters arguments. On an error, the output will depend on the value of the errorMessages_out parameter.

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
All of these examples return the data to a data frame called: data.download

# This is the example provided in the CEDEN web services documentation
data.download <- ceden_query(service = 'cedenwaterqualitymonitoringstationslist', query_parameters = '"filter":[{"sampleDateMin":"1/1/2015","sampleDateMax":"4/1/2015"}],"top":1000')

# Get all of the records of E. coli monitoring in Sacramento and San Joaquin counties from 6/1/2014 through 7/1/2014
data.download <- ceden_query(service = 'cedenwaterqualityresultslist', query_parameters = '"filter":[{"county":"Sacramento","parameter":"E. coli","sampleDateMin":"6/1/2014","sampleDateMax":"7/1/2014"},{"county":"San Joaquin","parameter":"E. coli","sampleDateMin":"6/1/2014","sampleDateMax":"7/1/2014"}]')

# Get all water quality results in Sacramento from the year 2014 where the parameter name contains the name Nitrogen (note use of the wildcard /%)
data.download <- ceden_query(service = 'cedenwaterqualityresultslist', query_parameters = '"filter":[{"county":"Sacramento","parameter":"/%Nitrogen/%","sampleDateMin":"1/1/2014","sampleDateMax":"12/31/2014"}]', userName = 'user', password = 'password', base_URI = 'https://testcedenwebservices.waterboards.ca.gov')

CAWaterBoardDataCenter/cedenTools documentation built on Feb. 22, 2018, 12:50 a.m.