The Water Quality Data Portal (WQP) provides an easy way to access data stored in various large water quality databases through form-based queries as well as through standalone web services. The form interface and the web services offer equivalent input parameters and output formats. Submit a web service request to bypass the WQP form interface. For more information on the WQP input parameters and data retrievals, see the User Guide.

Submitting a Web Services Request

The WQP web services may be queried using a RESTlike (REpresentational State Transfer) technique. This method will retrieve the same data as the WQP form when the same retrieval parameters are specified. The basic building blocks for querying the services are outlined in the following series of tables. Most non-alphanumeric characters (such as punctuation) must be "url-encoded", (for example: space is "%20").

Parameters must be appended to the base Uniform Resource Locator (URL) for the RESTlike WQP web services. The base URL is constructed differently depending on the type of information being requested. There are two options - one base URL for downloading sites and one base URL for downloading results:

• Base URL for downloading sites -- http://www.waterqualitydata.us/Station/search?
• Base URL for downloading results -- http://www.waterqualitydata.us/Result/search?

Construct a RESTlike web service query by concatenating the base URL with the desired parameters and arguments (Table 1).

Construct a RESTlike web service query by concatenating the base URL with the desired parameters and arguments (Table 1). Separate multiple parameter-argument pairs with an ampersand ("&"). Unneeded web service parameters may be omitted. If no mime type is specified, the retrieval will default to WQX-XML format. Station and Result retrieval data elements are output in a consistent format and nomenclature. See the User Guide for a list of elements included in the station and result retrievals.

Table 1. URL-encoded retrieval parameters and arguments for WQP web services [parameter names are insensitive only to the leading capital letter].

REST parameter	Argument	Discussion
bbox	Western-most longitude, Southern-most latitude, Eastern-most longitude, and Northern-most longitude separated by commas, expressed in decimal degrees, WGS84, and longitudes west of Greenwich are negative. (Example: bBox=-92.8,44.2,-88.9,46.0)	These four arguments are used together to form a quadrant of the Earth's surface for locating data-collection stations. Many stations outside the continental US do not have latitude and longitude referenced to WGS84 and therefore cannot be found using these parameters. Other stations are not associated with latitude and longitude due to Homeland Security concerns.
lat	Latitude for radial search, expressed in decimal degrees,WGS84	These three arguments are used together to form a circle on the Earth's surface for locating data-collection stations. Many stations outside the continental US do not have latitude and longitude referenced to WGS84 and therefore cannot be found using these parameters.
long	Longitude for radial search, expressed in decimal degrees, WGS84
within	Distance for radial search, expressed in decimal miles
countrycode	Two-character Federal Information Processing Standard (FIPS) country code. (see domain service for available codes)	FIPS country codes were established by the National Institute of Standards, publication 5-2.
statecode	Two-character Federal Information Processing Standard (FIPS) country code, followed by a URL-encoded colon ("%3A"), followed by a two-digit FIPS state code. (see domain service for available codes)	FIPS state codes were established by the National Institute of Standards, publication 5-2.
countycode	Two-character Federal Information Processing Standard (FIPS) country code, followed by a URL-encoded colon ("%3A"), followed by a two-digit FIPS state code, followed by a URL-encoded colon ("%3A"), followed by a three-digit FIPS county code. (see domain service for available codes)	FIPS county codes were established by the National Institute of Standards, publication 5-2.
siteType	One or more case-sensitive site types, separated by semicolons. (see domain service for available site types)	Restrict retrieval to stations with specified site type (location in the hydrologic cycle). The MonitoringLocationTypeName for individual records may provide more detailed information about the type of individual stations.
organization	For USGS organization IDs, append an upper-case postal-service state abbreviation to "USGS-" to identify the USGS office managing the data collection station records. However, a few US states are serviced by one USGS office. USGS-MA = Massachusetts and Rhode Island USGS-MD = Maryland, Delaware, and the District of Columbia USGS-PR = Caribbean Islands USGS-HI = Pacific Islands (see domain service for available organization IDs)	USGS offices sometimes provide data for stations outside the political boundaries associated with the office's organization code. Use the statecode or countycode arguments to search for stations located within those political boundaries.
siteid	Concatenate an agency code, a hyphen ("-"), and a site-identification number.	Each data collection station is assigned a unique site-identification number. Other agencies often use different site identification numbers for the same stations.
huc	One or more eight-digit hydrologic units, delimited by semicolons.	Hydrologic unit codes identify surface watersheds. The lists and maps of hydrologic units are available from USGS.
sampleMedia	One or more case-sensitive sample media, separated by semicolons. (see domain service for available sample media)	Sample media are broad general classes, and may be subdivided in the retrieved data. Examine the data elements ActivityMediaName, ActivityMediaSubdivisionName, and ResultSampleFractionText for more detailed information.
characteristicType	One or more case-sensitive characteristic types (groupings) separated by semicolons. (see domain service for available characteristic types)	These groups will be expanded as part of the ongoing collaboration between USGS and USEPA.
characteristic	One or more case-sensitive characteristic names, separated by semicolons. (see domain service for available characteristic names)	Characteristic names identify different types of environmental measurements. The names are derived from the USEPA Substance Registry System (SRS). USGS uses parameter codes for the same purpose and has associated most parameters to SRS names.
pCode	One or more five-digit USGS parameter codes, separated by semicolons.
activityId	One or more case-sensitive activity IDs, separated by semicolons.	Designator that uniquely identifies an activity within an organization.
startDateLo	Date of earliest desired data-collection activity, expressed as MM-DD-YYYY	These two parameters, used together or individually, restrict the retrieval to data-collection activities within a range of dates.
startDateHi	Date of last desired data-collection activity, expressed as MM-DD-YYYY
mimeType	xml	Output format is XML compatible with WQX-Outbound schema
	xls	Output format is xls compatible with MS-Excel
	csv	Output format is comma-separated columns
	tab	Output format is tab-separated columns
	kml	Output format is KML compatible with Google Earth. This option is not available for the results service.
Zip	Yes	Include the parameter to stream compressed data. Compression often greatly increases throughput, thus expediting the request.
command.avoid	STORET|NWIS	By default, requests are submitted to all the data providers. However, a particular provider may be avoided via this parameter.

Web Service Request Examples

The following example REST web service request retrieves sites from Oklahoma County, Oklahoma, where Atrazine was measured in XML format.

http://www.waterqualitydata.us/Station/search?countycode=US%3A40%3A109&characteristicName=Atrazine&mimeType=xml

This REST web service request retrieves contained within a bounding box where Caffeine was measured in KML format.

http://www.waterqualitydata.us/Station/search?characteristicName=Caffeine&mimeType=kml&bBox=-92.8,44.2,-88.9,46.0

Continuing from above, this REST web service request retrieves the Caffeine sample results from sites contained within a bounding box and collected on, or after, 10-01-2006 in MS-Excel format (zipped).

http://www.waterqualitydata.us/Result/search?characteristicName=Caffeine&bBox=-92.8,44.2,-88.9,46.0&startDateLo=10-01-2006&mimeType=xls&zip=yes

Web Service Request Pre-Validation

A REST web service request may not be valid for all data providers. A web service user may perform a quick validation before submitting a request to ensure that all parameters are valid before making an expensive request for actual data. For example, the WQP mini-portal form does this before an actual data submission, and pops up a prompt to the user if problems are found.

A REST web service validation service for sites and results requests are invoked by using the exact same RESTlike URL as an actual request but using a HTTP HEAD method rather than the usual GET or POST. See the W3C specification RFC 2616 Section 9 for an explanation of HTTP methods. The exact way to invoke a URL via a HEAD request depends on your programming language, but an example is provided below for JavaScript:

function makeRequest(url) {
  	var http = new XMLHttpRequest();
  	http.open('HEAD', url, false);
  	http.send();
  	var warningHeader = http.getResponseHeader("Warning");
  	alert(warningHeader);
}

Another option is using a command line. For example, a HEAD request can be issued as:

curl -I 'http://www.waterqualitydata.us/Result/search?bBox=-92.8,44.2,-88.9,46.0&startDateLo=10-01-2011
					&mimeType=csv&characteristicName=Dissolved%20oxygen%20(DO)' 

If there are any problems, they are returned in the response via the warning header(s). See RFC 2616 Section 14 for the format of the warning header.

NOTE: The same warning header(s) and count headers are returned on the GET request as well, so it is important to issue the command with 'debug' or 'verbose' diagnostic option turned on, and then inspect the header to ensure the service is performing as expected. For example:

wget -d -O - 'http://www.waterqualitydata.us/Result/search?&bBox=-92.8,44.2,-88.9,46.0
		        &startDateLo=10-01-2011&mimeType=csv&characteristicName=Dissolved%20oxygen%20(DO)'
or 
curl -v  'http://www.waterqualitydata.us/Result/search?&bBox=-92.8,44.2,-88.9,46.0
	         &startDateLo=10-01-2011&mimeType=csv&characteristicName=Dissolved%20oxygen%20(DO)'

Either statement returns the following (indicating no NWIS results are returned):

Total-Site-Count: 170
STORET-Site-Count: 170
Warning: 299 NWIS "[characteristicName]The value of characteristicName=Dissolved 
                     oxygen (DO) is not in the list of enumerated values"

Looking Up Domain Values through Web Services

The domains for retrieval parameter arguments may vary over time, as new data are added. The domain of values for the parameter arguments may be retrieved with a REST query. Use the domain-value base URL concatenated with the parameter name and arguments as shown in Table 2.

Base URL for looking up domain values -- http://www.waterqualitydata.us/Codes/{ParameterName}

Table 2. -- Domain values web service parameters and arguments

{parameterName}	Argument	Discussion	Example
Countrycode	None	FIPS country codes	http://www.waterqualitydata.us/Codes/countrycode
Statecode	Countrycode	FIPS state codes. A FIPS country code argument is appended so that the URL ends as /statecode?countrycode=US	http://www.waterqualitydata.us/Codes/statecode?countrycode=US
Countycode	Statecode	FIPS county codes. A FIPS statecode argument is appended so that the URL ends as /countycode?statecode=US:01;US:04	http://www.waterqualitydata.us/Codes/countycode?statecode=US:01;US:04
Sitetype	None	Available site types	http://www.waterqualitydata.us/Codes/Sitetype
Organization	None	Available organization IDs	http://www.waterqualitydata.us/Codes/Organization
Samplemedia	None	Sample media	http://www.waterqualitydata.us/Codes/Samplemedia
Characteristictype	None	Characteristic types (groups)	http://www.waterqualitydata.us/Codes/Characteristictype
Characteristicname	None	Characteristic names.	http://www.waterqualitydata.us/Codes/Characteristicname