Technical Documentation of USGS Water-Quality Web Services
These USGS web services for water-quality data are interoperable with corresponding web services provided by the US Environmental Protection Agency. The services are interoperable in the sense that the the outputs are consistent in format and nomenclature, and compliant with the WQX-Outbound 2.0 schema. (EPA output is compliant with the WQX 2.0 schema. WQX 2.0 data elements are a subset of WQX-Outbound.)
The USGS web services may be queried using either the Simple Object Access Protocol (SOAP version 1.1) or the Representational State Transfer (REST) techniques. Either method will retrieve the same data when the the same retrieval parameters are specified. The basic building blocks for querying the services are similar (table 1), although the query techniques differ. Most non-alphanumeric characters (such as punctuation) must be "url-encoded", (for example: space is "%20").
Table 1.--Uniform Resource Locators (URL) for the web services
[Users of REST services
append URL-encoded retrieval parameters to the base URL. WSDL = Web-service Definition Language. Users
of SOAP services send retrieval parameters using an XML-formatted message.]
| Web Service | Base URL [parameters must be appended to the REST URLs] | Purpose |
|---|---|---|
| Station | REST http://qwwebservices.usgs.gov/Station/search?
SOAP http://qwwebservices.usgs.gov/Station WSDL http://qwwebservices.usgs.gov/Station?wsdl | Retrieves data-collection station data |
| Result | REST http://qwwebservices.usgs.gov/Result/search?
SOAP http://qwwebservices.usgs.gov/Result WSDL http://qwwebservices.usgs.gov/Result?wsdl | Retrieves water-quality result data |
| Domain values | REST http://qwwebservices.usgs.gov/Codes/ | Retrieves choice lists for web-service arguments |
Station and Result service query parameters
The same parameters (with one exception) may be used with either the station and result service. For example, if characteristic "Atrazine" and a county are specified, the station service will return all stations where Atrazine was measured in the county. If the same parameters are supplied to the result service, all atrazine measurements in the county are returned.
The SOAP web services only return XML-formatted data. However, the REST services can return compressed or uncompressed data in a variety of optional formats. Therefore, the REST services support two additional parameters: zip and mimeType, that allow specification of compression and an output format of XML, comma-separated values, Excel, tab-delimited values, or (for the station service only) Keyhole Markup Language.
Construct a REST-like web-service query by concatenating the REST base URL with the desired parameters and arguments (table 2). Separate multiple parameter-argument pairs with an ampersand ("&"). Unneeded web-service parameters may be omitted.
Table 2.--Station and Result web-service parameters and arguments
[The
parameter names for SOAP are case-sensitive, but REST parameter names are only
insensitive to the leading capital letter.]
| SOAP parameter | REST parameter | Argument | Discussion |
|---|---|---|---|
| BBox | bBox | Western-most latitude Southern-most latitude Eastern-most longitude Northern-most longitude separated by commas, expressed in decimal degrees, NAD83, 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 NAD83 and therefore can not be found using these parameters. Other stations are not associated with latitude and longitude due to Homeland Security concerns. |
| Lat | lat | latitude for radial search, expressed in decimal degrees, NAD83 | 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 NAD83 and therefore can not be found using these parameters. |
| Long | long | longitude for radial search, expressed in decimal degrees, NAD83 | |
| Within | within | distance for radial search, expressed in decimal miles | |
| SiteType | siteType | One or more case-sensitive site types, separated by semicolons (See domain service.) | Restrict retrieval to stations with the 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 | organization | 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 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. |
| Statecode | statecode | Two-digit Federal Information Processing Standard (FIPS) state code (See domain service.) | FIPS state codes were established by the National Institute of Standards, publication 5-2. |
| Countycode | countycode | Two-digit FIPS state code, followed by a URL-encoded colon, ("%3A"), followed by the three-digit FIPS county code (See domain service.) | FIPS county codes were established by the National Institute of Standards, publication 5-2. |
| Siteid | siteid | Concatenate an agency code, a hyphen ("-"), and a USGS site-identification number. Specify multiple sites in a list delimited by semicolons (";"). If agency code is omitted, agency code defaults to "USGS". | Each data-collection station is assigned a unique site-identification number by USGS. Other agencies often use different site-identification numbers for the same stations where USGS conducts measurements. |
| Huc | huc | One or more eight-digit hydrologic units, delimited by semicolons. (See domain service.) | Hydrologic-unit codes identify surface watersheds. The lists and maps of hydrologic units are available from USGS. |
| SampleMedia | sampleMedia | One or more case-sensitive sample media, separated by semicolons. (See domain service.) | 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 | characteristicType | One or more case-sensitive characteristic types (groupings) separated by semicolons. (See domain service.) | These groups will be expanded as part of the ongoing collaboration between USGS and USEPA. |
| CharacteristicName | characteristicName | One or more case-sensitive characteristic names, separated by semicolons. (See domain service.) | 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 | pCode | One or more five-digit USGS parameter codes separated by semicolons | |
| StartDateLo | 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 | startDateHi | Date of last desired data-collection activity, expressed as MM-DD-YYYY | |
| Not available | mimeType | xml | Output format is XML compatible with WQX-Outbound schema |
| xls | Output format is XML 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. | ||
| Not available | zip (may be replaced by gzip in the future) | yes | Include the parameter to stream compressed data. Compression often greatly increases throughput, thus expediting the request. |
Error Messages
There may be several reasons why no results are returned. When the web service is slow or not operating, then queries will take a long or indeterminate amount of time to return output. More commonly, an XML error message will be returned with details from the web service that attempt to diagnose the cause. For example, the request http://qwwebservices.usgs.gov/Station/search?characteristicName=Caffeine&mimeType=xls&zip=yes&bBox=44,1333,33,35 returns the error message:
Your search for stations
in bounding box (w,s,e,n) having results
on characteristic(s) Caffeine
resulted in the following errors --
bounding box north parameter 35.0 must be > south parameter 1333.0;
bounding box east parameter 33.0 must be > west parameter 44.0
The message details will change with different errors and as the logic for detecting causes is refined. The message includes the name of the requested service and the web-service parameters that were used in the query. Other reasons why no results are returned include:
- No data met the retrieval criterion.
- The wrong format was used to specify arguments, especially for dates.
- An argument was specified that is not within the domain for the associated parameter.
Examples
The following example REST web-service request retrieves in an XML format sites from Oklahoma county, Oklahoma where Atrazine was measured.
http://qwwebservices.usgs.gov/Station/search?countycode=40%3A109&characteristicName=Atrazine&mimeType=xmlThis REST web-service request retrieves in KML format sites contained within a bounding box where Caffeine was measured.
http://qwwebservices.usgs.gov/Station/search?characteristicName=Caffeine&mimeType=kml&bBox=-92.8,44.2,-88.9,46.0Continuing from above, this REST web-service request retrieves in MS-Excel format (zipped) the Caffeine sample results from sites contained within a bounding box and collected on or after 10-01-2006.
http://qwwebservices.usgs.gov/Result/search?characteristicName=Caffeine&bBox=-92.8,44.2,-88.9,46.0&startDateLo=10-01-2006&mimeType=xls&zip=yesDomain Values Service
The domains for retrieval-parameter arguments may vary with time, as new data are added, and USGS and USEPA negotiate new agreements. The domain of USGS values for the web-service arguments may be retrieved with a REST query. (The entire allowable domain may be greater than the list retrieved by this service, because the service queries the USGS database to determine the domain values that are used.) Use the domain-value base URL concatenated with a parameter (table 3). Add an argument for the CountyCode query.
Table 3.--Domain values web service parameters and arguments
| Parameter | Argument | Discussion |
|---|---|---|
| Organization (XML) | none | USGS organization codes |
| Statecode (XML) | none | FIPS state codes |
| Countycode (XML) | ?parentValues=55;40 | FIPS county codes. The "parentValues" argument specifies which states' (codes) counties should be listed. The example query (to the left) retrieves the county codes and names for Wisconsin (55) and Oklahoma (40). |
| SiteType (XML) | none | Site types |
| SampleMedia (XML) | none | Sample media |
| CharacteristicType (XML) | none | Characteristic types (groups) |
| CharacteristicName (XML) | none | Characteristic names |
