USGS - science for a changing world

National Water Information System (NWIS) Water-Quality Web Services

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-MA = Massachusetts and Rhode Island,
  • USGS-MD = Maryland, Delaware, and the District of Columbia.
  • USGS-PR = Carribean islands
  • USGS-HI = Pacific islands.
(See domain service.)
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:

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=xml

This 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.0

Continuing 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=yes

Domain 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:04
Please 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.

Accessibility FOIA Privacy Policies and Notices Data Disclaimer Provisional Data Statement

Take Pride in America logo USA.gov logo U.S. Department of the Interior | U.S. Geological Survey
URL: http://qwwebservices.usgs.gov/technical-documentation.html
Page Contact Information: GS-W-QWWebServicesHelp@usgs.gov
Page Last Modified: Mon Aug 4 08:10:10 CDT 2008