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, WGS84, 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 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, 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 can not be found using these parameters. |
| Long | long | longitude for radial search, expressed in decimal degrees, WGS84 | |
| 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-character Federal Information Processing Standard (FIPS) country code, followed by a URL-encoded colon ("%3A"), followed Two-digit FIPS state code (See domain service.) | FIPS state codes were established by the National Institute of Standards, publication 5-2. |
| Countycode | countycode | Two-character 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 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. Use the domain-value base URL concatenated with the parameter name and add arguments as shown in table 3.
Example Queries:
http://qwwebservices.usgs.gov/Codes/Organization
Returns all the organization codes for which there is data. No arguments are required or allowed.
http://qwwebservices.usgs.gov/Codes/countycode?statecode=US:01
Returns all the counties in the US state 01 (Alabama).
http://qwwebservices.usgs.gov/Codes/countycode?statecode=US:01;US:04
Returns all the counties in the US states 01 & 04 (Alabama and Arizona). Note that lists are separated with a ';'.
Note that the entire allowable domain may be greater than the list retrieved by this service, since the domain value service queries the USGS database to determine the domain values that are used. For instance, if there were no sites in a particular state, that state would not be returned in the Statecode results.
Table 3.--Domain values web service parameters and arguments
| Parameter Name | Argument | Discussion |
|---|---|---|
| Organization (Example) | none | USGS organization codes |
| Countrycode (Example) | none | FIPS country codes. |
| Statecode (Example) | countrycode | FIPS state codes.
A FIPS countrycode argument is appended so that the
url ends as /statecode?countrycode=US |
| Countycode (Example) | statecode | FIPS county codes.
A FIPS statecode argument is appended so that the url ends as
/countycode?statecode=US:01;US:04Please note the usage of the complete FIPS state code which includes a country and state separated by a ':'. Multiple states are separated by a ';'. |
| SiteType (Example) | none | Site types |
| SampleMedia (Example) | none | Sample media |
| CharacteristicType (Example) | none | Characteristic types (groups) |
| CharacteristicName (Example) | none | Characteristic names |
Compatibility Notes
Prior versions of these services did not support the presence of a leading FIPS country code for the "Statecode" or "Countycode" parameter values. For compatibility the current implementation of these services will allow "Statecode" and "Countycode" parameter values without a leading FIPS country code. If the leading FIPS country code is missing from a "Statecode" or "Countycode" parameter value, a FIPS country code "US" will be prepended for queries.Station and Result Service Data Elements
The station and result web service requests output elements that are consistent in format and nomenclature. Station service output elements and definitions are listed in Table 4. Result service output elements and definitions are listed in Table 5.
Table 4.--Site Retrieval Elements and Definitions
[From the WQX-Outbound
2.0 schema documentation.]
| Site Retrieval Element | Definition |
|---|---|
| OrganizationIdentifier | A designator used to uniquely identify a unique business establishment within a context. |
| OrganizationFormalName | The legal designator (i.e. formal name) of an organization. |
| MonitoringLocationIdentifier | A designator used to describe the unique name, number, or code assigned to identify the monitoring location. |
| MonitoringLocationName | The designator specified by the sampling organization for the site at which sampling or other activities are conducted. |
| MonitoringLocationTypeName | The descriptive name for a type of monitoring location. |
| MonitoringLocationDescriptionText | Text description of the monitoring location. |
| HUCEightDigitCode | The 8 digit federal code used to identify the hydrologic unit of the monitoring location to the cataloging unit level of precision. |
| DrainageAreaMeasure/MeasureValue | The drainage basin of a lake, stream, wetland, or estuary site. |
| DrainageAreaMeasure/MeasureUnitCode | The code that represents the unit for measuring the item. |
| ContributingDrainageAreaMeasure/MeasureValue | The contributing drainage area of a lake, stream, wetland, or estuary site. |
| ContributingDrainageAreaMeasure/MeasureUnitCode | The code that represents the unit for measuring the item. |
| LatitudeMeasure | The measure of the angular distance on a meridian north or south of the equator. |
| LongitudeMeasure | The measure of the angular distance on a meridian east or west of the prime meridian. |
| SourceMapScaleNumeric | The number that represents the proportional distance on the ground for one unit of measure on the map or photo. |
| HorizontalAccuracyMeasure/MeasureValue | The horizontal measure of the relative accuracy of the latitude and longitude coordinates" |
| HorizontalAccuracyMeasure/MeasureUnitCode | The code that represents the unit for measuring the item. |
| HorizontalCollectionMethodName | The name that identifies the method used to determine the latitude and longitude coordinates for a point on the earth. |
| HorizontalCoordinateReferenceSystemDatumName | The name that describes the reference datum used in determining latitude and longitude coordinates. |
| VerticalMeasure/MeasureValue | The measure of elevation (i.e., the altitude), above or below a reference datum. |
| VerticalMeasure/MeasureUnitCode | The code that represents the unit for measuring the item. |
| VerticalAccuracyMeasure/MeasureValue | The vertical measure of the relative accuracy of the latitude and longitude coordinates. |
| VerticalAccuracyMeasure/MeasureUnitCode | The code that represents the unit for measuring the item. |
| VerticalCollectionMethodName | The name that identifies the method used to collect the vertical measure (i.e. the altitude) of a reference point. |
| VerticalCoordinateReferenceSystemDatumName | The name of the reference datum used to determine the vertical measure (i.e., the altitude). |
| CountryCode | A code designator used to identify a primary geopolitical unit of the world. |
| StateCode | A code designator used to identify a principal administrative subdivision of the United States, Canada, or Mexico. |
| CountyCode | A code designator used to identify a U.S. county or county equivalent. |
| AquiferName | Name of the aquifer in which the well is completed. |
| FormationTypeText | Name of the primary formation or soils unit, in which the well is completed. |
| AquiferTypeName | The type of aquifer. |
| ConstructionDateText | Date of construction when well was completed. May be year only. |
| WellDepthMeasure/MeasureValue | Depth below land surface datum (LSD) to the bottom of the hole on completion of drilling. |
| WellDepthMeasure/MeasureUnitCode | The code that represents the unit for measuring the item. |
| WellHoleDepthMeasure/MeasureValue | Depth below land surface datum (LSD) to the bottom of the hole on completion of drilling. |
| WellHoleDepthMeasure/MeasureUnitCode | The code that represents the unit for measuring the item. |
Table 5.--Result Retrieval Elements and Definitions
[From the WQX-Outbound
2.0 schema documentation.]
| Result Retrieval Element | Definition |
|---|---|
| OrganizationIdentifier | A designator used to uniquely identify a unique business establishment within a context. |
| OrganizationFormalName | The legal designator (i.e. formal name) of an organization. |
| ActivityIdentifier | Designator that uniquely identifies an activity within an organization. |
| ActivityTypeCode | The text describing the type of activity. |
| ActivityMediaName | Name or code indicating the environmental medium where the sample was taken. |
| ActivityMediaSubdivisionName | Name or code indicating the environmental matrix as a subdivision of the sample media. |
| ActivityStartDate | The calendar date on which the field activity was started. |
| ActivityStartTime/Time | The measure of clock time when the field activity began. |
| ActivityStartTime/TimeZoneCode | The time zone for which the time of day is reported. Any of the longitudinal divisions of the earth's surface in which a standard time is kept. |
| ActivityEndDate | The calendar date when the field activity was completed. |
| ActivityEndTime/Time | The measure of clock time when the field activity ended. |
| ActivityEndTime/TimeZoneCode | The time zone for which the time of day is reported. Any of the longitudinal divisions of the earth's surface in which a standard time is kept. |
| ActivityDepthHeightMeasure/MeasureValue | A measurement of the vertical location (measured from a reference point) at which an activity occurred. |
| ActivityDepthHeightMeasure/MeasureUnitCode | The code that represents the unit for measuring the item. |
| ActivityDepthAltitudeReferencePointText | The reference used to indicate the datum or reference used to establish the depth/altitude of an activity. |
| ActivityTopDepthHeightMeasure/MeasureValue | A measurement of the upper vertical location of a vertical location range (measured from a reference point) at which an activity occurred. |
| ActivityTopDepthHeightMeasure/MeasureUnitCode | The code that represents the unit for measuring the item. |
| ActivityBottomDepthHeightMeasure/MeasureValue | A measurement of the lower vertical location of a vertical location range (measured from a reference point) at which an activity occurred. |
| ActivityBottomDepthHeightMeasure/MeasureUnitCode | The code that represents the unit for measuring the item. |
| ProjectIdentifier | A designator used to uniquely identify a data collection project within a context of an organization. |
| ActivityConductingOrganizationText | A name of the Organization conducting an activity. |
| MonitoringLocationIdentifier | A designator used to describe the unique name, number, or code assigned to identify the monitoring location. |
| ActivityCommentText | General comments concerning the activity. |
| SampleAquifer | A code that designates the aquifer associated with ground-water samples. |
| HydrologicCondition | Hydrologic condition is the hydrologic condition that is represented by the sample collected (i.e. – normal, falling, rising, peak stage). |
| HydrologicEvent | A hydrologic event that is represented by the sample collected (i.e. - storm, drought, snowmelt). |
| SampleCollectionMethod/MethodIdentifier | The identification number or code assigned by the method publisher. |
| SampleCollectionMethod/MethodIdentifierContext | Identifies the source or data system that created or defined the identifier. |
| SampleCollectionMethod/MethodName | The title that appears on the method from the method publisher. |
| SampleCollectionEquipmentName | The name for the equipment used in collecting the sample. |
| ResultDetectionConditionText | The textual descriptor of a result. |
| CharacteristicName | The object, property, or substance which is evaluated or enumerated by either a direct field measurement, a direct field observation, or by laboratory analysis of material collected in the field. |
| ResultSampleFractionText | The text name of the portion of the sample associated with results obtained from a physically-partitioned sample. |
| ResultMeasureValue | The reportable measure of the result for the chemical, microbiological or other characteristic being analyzed. |
| ResultMeasure/MeasureUnitCode | The code that represents the unit for measuring the item. |
| ResultStatusIdentifier | Indicates the acceptability of the result with respect to QA/QC criteria. |
| StatisticalBaseCode | The code for the method used to calculate derived results. |
| ResultValueTypeName | A name that qualifies the process which was used in the determination of the result value (e.g., actual, estimated, calculated). |
| ResultWeightBasisText | The name that represents the form of the sample or portion of the sample which is associated with the result value (e.g., wet weight, dry weight, ash-free dry weight). |
| ResultTimeBasisText | The period of time (in days) over which a measurement was made. For example, BOD can be measured as 5 day or 20 day BOD. |
| ResultTemperatureBasisText | The name that represents the controlled temperature at which the sample was maintained during analysis, e.g. 25 deg BOD analysis. |
| ResultParticleSizeBasisText | User defined free text describing the particle size class for which the associated result is defined. |
| PrecisionValue | A measure of mutual agreement among individual measurements of the same property usually under prescribed similar conditions. |
| ResultCommentText | Free text with general comments concerning the result. |
| USGSPCode | 5-digit number used in the US Geological Survey computerized data system, National Water Information System (NWIS), to uniquely identify a specific constituent. |
| SubjectTaxonomicName | The name of the organism from which a tissue sample was taken. |
| SampleTissueAnatomyName | The name of the anatomy from which a tissue sample was taken. |
| ResultAnalyticalMethod/MethodIdentifier | The identification number or code assigned by the method publisher. |
| ResultAnalyticalMethod/MethodIdentifierContext | Identifies the source or data system that created or defined the identifier. |
| ResultAnalyticalMethod/MethodName | The title that appears on the method from the method publisher. |
| MethodDescriptionText | A brief summary that provides general information about the method. |
| LaboratoryName | The name of Lab responsible for the result. |
| AnalysisStartDate | The calendar date on which the analysis began. |
| ResultLaboratoryCommentText | Remarks which further describe the laboratory procedures which produced the result. |
| DetectionQuantitationLimitTypeName | Text describing the type of detection or quantitation level used in the analysis of a characteristic. |
| DetectionQuantitationLimitMeasure/MeasureValue | Constituent concentration that, when processed through the complete method, produces a signal that is statistically different from a blank. |
| DetectionQuantitationLimitMeasure/MeasureUnitCode | The code that represents the unit for measuring the item. |
| PreparationStartDate | The calendar date when the preparation/extraction of the sample for analysis began. |
