Skip to main content
U.S. flag

An official website of the United States government

Official websites use .gov
A .gov website belongs to an official government organization in the United States.

Secure .gov websites use HTTPS
A lock ( or https:// means you’ve safely connected to the .gov website. Share sensitive information only on official, secure websites.

WQP Web Services Guide

Introduction

The Water Quality Data Portal (WQP) provides easy access to data stored in three large water quality databases (WQX, NWIS, STEWARDS) through a web-based form interface as well as standalone web services. Both the form interface and the web services use the same input parameters (filters) and produce the same output formats. The web service enables programmatic access to WQP data and metadata without manually interacting with the form interface.

You can use the WQP web services to quickly and easily access data and metadata available on the Water Quality Portal. URL queries are constructed in a standard format and outputs are delivered in a number of user-defined formats.

For more information on the WQP input parameters (filters) and data downloads, see the WQP User Guide.

What Are Web Services?

APIs (Application Programming Interface) and Web Services are tools that enable communication between two networked devices or pieces of software using standardized methods. They are implemented in almost all of our mobile device applications that we use on a daily basis. They allow data from one system to be easily used by a second system without requiring the second system to locally store the data, which is especially beneficial when we are dealing with big data sets. In fact, common software packages including Excel and R are starting to come pre-packaged with the ability to use these services.

While APIs and Web Services provide similar functions, the types of communication they allow differs:

  • An API allows two applications to communicate by creating shared rules and conventions. These can be used with a network connection, but there are also APIs that do not involve a network connection.

  • A web service is a type of API that allows one computer to communicate data to another computer in a standardized way. While all web services are APIs, not all API's are web services.

The WQP web services are implemented using the 'https' protocol using REST, which provides a flexible and scalable approach for constructing standardized URL statements.

Click here to learn more about the basics of APIs, or check out this Github page for details about how APIs are implemented within the USGS and across the federal government.

Accessing Data Programmatically Through Web Services

Web services provide a public resource which users can also enhance with their own custom scripts.

One resource created by the USGS is an R-based software package called dataRetrieval, which makes it easier for R users to use the WQP web services. dataRetrieval does the heavy lifting to download data and convert it into a familiar and usable format. dataRetrevial can download data from the WQP and from a number of USGS NWIS services. To learn more about dataRetrieval, please check out these resources:

  • CRAN - Download current release
  • GitHub - Download most up-to-date source code (may contain bugs)
  • Tutorial - Learn how to use dataRetrieval

How to Generate Web Services Requests

You can retrieve the same data using Web Services that you can with the WQP User Interface (advanced form). Query basics are outlined in the following series of tables. Most non-alphanumeric characters (such as punctuation) must be "url-encoded", (for example: space is "%20").

Constructing a Request:

Every request starts with a base URL: the base URL will vary depending on the type of information requested:

  • Base URL for downloading project data: https://www.waterqualitydata.us/data/Project/search?
  • Base URL for downloading site data and associated metadata: https://www.waterqualitydata.us/data/Station/search?
  • Base URL for downloading results: https://www.waterqualitydata.us/data/Result/search?
  • Base URL for downloading result detection quantitation limit data: https://www.waterqualitydata.us/data/ResultDetectionQuantitationLimit/search?
  • Base URL for downloading activity data: https://www.waterqualitydata.us/data/Activity/search?
  • Base URL for downloading activity metric data: https://www.waterqualitydata.us/data/ActivityMetric/search?
  • Base URL for downloading biological metric data: https://www.waterqualitydata.us/data/BiologicalMetric/search?
  • Base URL for downloading project monitoring location weighting data: https://www.waterqualitydata.us/data/ProjectMonitoringLocationWeighting/search?

Construct a query by concatenating the base URL with the desired parameters and arguments,as shown in Table 1. At least one parameter-argument pair must be specified. Separate multiple parameter-argument pairs with an ampersand ("&"). For downloads, if no file format (mime type) is specified, the retrieval will default to WQX-XML format. See the WQP User Guide for a list of elements included in the result retrievals.

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

Expand Table
REST parameter Argument Discussion
bBox Western-most longitude, Southern-most latitude, Eastern-most longitude, and Northern-most longitudeseparated 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 (allowable values). FIPS country codes were established by the National Institute of Standards, publication 10-4.
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. (allowable values). 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. (allowable values). FIPS county codes were established by the National Institute of Standards, publication 6-4.
siteType One or more case-sensitive site types, separated by semicolons (allowable values). 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 (allowable values). (USGS-MA = Massachusetts and Rhode Island, USGS-MD = Maryland, Delaware, and the District of Columbia, USGS-PR = Caribbean Islands, USGS-HI = Pacific Islands). 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 (allowable values). 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 (allowable values). These groups will be expanded as part of the ongoing collaboration between USGS and USEPA.
characteristicName One or more case-sensitive characteristic names, separated by semicolons (allowable values). 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. This is the default format, and if a mimeType is not specified, the data will be in XML format.
xlsx Output format is xlsx compatible with MS-Excel 2007 and greater.
csv Output format is comma-separated columns.
tsv|tab Output format is tab-separated columns.
geojson Output format is GeoJSON (JavaScript Object Notation).
kml Output format is KML compatible with Google Earth. This option is not available for the results service.
kmz Output format is kmz, a compressed form of 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. Kml files will be returned in the kml-specific zip format, .kmz.
providers EPA|NWIS|STEWARDS By default, requests are submitted to all the data providers. However, a particular provider may be specified using this parameter.
sorted yes|no By default, tabular data are sorted by organization, monitoringLocationID, and (for results) activityID. However, sorting increases response time significantly, sometimes by orders of magnitude. If you are doing your own sorting after download, set sorted=no. For large downloads (over 5 million rows) sorting is disabled by default to ensure reasonable response times. XML requests are always sorted to accommodate the WQX data schema.
dataProfile biological Only affects results endpoint at this time. The biological dataProfile returns an extended set of columns that further describe biological data.

Example Web Service Requests

To try out the following examples of REST web service requests, copy and paste into a web browser.

Example: REST web service request to retrieve sites from Oklahoma County, Oklahoma, where Atrazine was measured in XML format, zipped:

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

Example: REST web service request to retrieve sites contained within a bounding box where Caffeine was measured in KML format, zipped:

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

Example: REST web service request to retrieve stream sites located in the state of Wyoming (USA) where parameters of the characteristicType Nutrient were measured, in GeoJSON format:

https://www.waterqualitydata.us/data/Station/search?countrycode=US&statecode=US%3A56&siteType=Stream&characteristicType=Nutrient&mimeType=geojson

Example: REST web service request to retrieve Caffeine sample results from sites contained within a bounding box and collected on, or after, 10-01-2006 in MS-Excel format, zipped:

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

Queries Using POST

In certain situations when very long requests are submitted - for example, when querying data for a large list of sites - GET requests can fail due to limits in the allowable length of the request. These requests can instead be completed using http POST. POST requests should be submitted with a JSON-formatted payload.

Here's an example JSON object, including an organization ID and three site ID's:

{ "organization": ["WIDNR_WQX"], "siteid": ["WIDNR_WQX-133003", "WIDNR_WQX-133398", "WIDNR_WQX-133486"] }

An example using curl with these data looks like this:

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/zip' -d '{"organization":["WIDNR_WQX"],"siteid":["WIDNR_WQX-133003","WIDNR_WQX-133398","WIDNR_WQX-133486"]} \ ' 'https://www.waterqualitydata.us/data/Station/search?mimeType=csv&zip=yes'

The --header argument lists metadata for the web service and ensures that the correct information is received and returned. If there are any problems with the request, they are returned in the response via the warning header(s). See RFC 2616 Section 14 for the format of the warning header.

Retrieving Summary Data Using the WQP Summary Web Service

Among the web service offerings is also a summary service, which enables users to obtain summary-level information on a data set of interest. This can be useful for evaluating the number and types of data available for particular sites or date ranges. It can also make it quicker and easier to generate summary tables for reports and publications.

  • Base URL for the summary service: https://www.waterqualitydata.us/data/summary/monitoringLocation/search?

There are two main types of downloads based on the dataProfile selected: periodOfRecord or summaryMonitoringLocation.

  • periodOfRecord: For the queried sites and specific period of record, provides site-level organization and spatial data and annual summaries of total # results (equivalent to total number of records) and total # activities (equivalent to total number of collection events) for each queried characteristicName (i.e. water quality measurement).

  • summaryMonitoringLocation: For the queried sites and specific period of record, provides site-level organization and spatial data and the total # results (equivalent to total number of records) and total # activities (equivalent to total number of collection events) for all queried characteristicName's combined. Output is in a GeoJSON format only: be sure to specify mimeType=geojson in these queries.

Construct a query by concatenating the base URL with the desired parameters and arguments,as shown in Table 2. At least one parameter-argument pair is required. Separate multiple parameter-argument pairs with an ampersand ("&"). For downloads, if no file format (mime type) is specified, the retrieval will default to .csv format.

Example: Summary service request to retrieve annual summary counts from the most recent 5 years of Nutrient data from sites in Benton County, Arkansas in csv format, zipped:

https://www.waterqualitydata.us/data/summary/monitoringLocation/search?countycode=US%3A05%3A007&characteristicType=Nutrient&mimeType=csv&zip=yes&dataProfile=periodOfRecord&summaryYears=5

Example: Summary service request to retrieve total counts from the most recent 5 years of Nutrient data from sites in Benton County, Arkansas in GeoJSON format, zipped:

https://www.waterqualitydata.us/data/summary/monitoringLocation/search?countycode=US%3A05%3A007&characteristicType=Nutrient&zip=yes&dataProfile=summaryMonitoringLocation&summaryYears=5&mimeType=geojson

Table 2. URL-encoded retrieval parameters and arguments for WQP web services.

Expand Table
REST parameter Argument Discussion
bBox Western-most longitude, Southern-most latitude, Eastern-most longitude, and Northern-most longitudeseparated 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.
characteristicName One or more case-sensitive characteristic names, separated by semicolons. *NOTE: Using this parameter in conjunction with the parameter characteristicType can result in unexpected behavior, particularly when multiple arguments for characteristicType are specified. Combining the two parameters in a single query is not recommended. Characteristic names identify different measurement parameters. The names are derived from the USEPA Substance Registry System. A current list of available characteristicName values can be downloaded here.
characteristicType One or more case-sensitive characteristic types (groupings) separated by semicolons (allowable values). A current list of available characteristicType values can be downloaded here.
countrycode Two-character Federal Information Processing Standard (FIPS) country code (allowable values). FIPS country codes were established by the National Institute of Standards, publication 10-4.
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. (allowable values). FIPS county codes were established by the National Institute of Standards, publication 6-4.
dataProfile summaryMonitoringLocation|periodOfRecord The type of metadata included in the summary data set. This is not the same as the WQX-curated data profiles. summaryMonitoringLocation generates a GeoJSON file that can be imported into mapping software. If not specified, defaults to summaryMonitoringLocation.
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.
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
mimeType csv|geojson Default output format is .csv. Can also be output in GeoJSON format (JavaScript Object Notation).
nldiurl URL The navigation query from NLDI for a list of sites.
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 (allowable values). (USGS-MA = Massachusetts and Rhode Island, USGS-MD = Maryland, Delaware, and the District of Columbia, USGS-PR = Caribbean Islands, USGS-HI = Pacific Islands). 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.
providers STORET|NWIS|STEWARDS For EPA (and other WQX submissions), use STORET. For USGS, use NWIS. For USDA/NRCS, use STEWARDS. Defaults to all data providers.
siteid Concatenate an agency code (e.g. "USGS"), 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.
siteType One or more case-sensitive site types, separated by semicolons (allowable values. Restrict retrieval to stations with specified site type (habitat or component of the hydrologic cycle).
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. (allowable values). FIPS state codes were established by the National Institute of Standards, publication 5-2.
summaryYears all|1|5 Target date range for summary data: most recent 1 year, 5 years, or all years available. Default=all.
within Distance for radial search, expressed in decimal miles
zip yes|no Include the parameter to stream compressed data. Compression often greatly increases throughput, thus expediting the request.
Considerations

  1. Query parameters are case-sensitive. For example, the waterqualitydata.us service refers to the nitrogen analyte as 'Nitrogen': searching for 'nitrogen' will not produce the expected result. For each of the available input parameters listed in Table 2, there may be up to tens of thousands of potential values: we recommend using one of the two following approaches to determine the correct parameter values to input.

    a. Construct a similar query in the Advanced form of the Water Quality Portal website. From the Results box containing the URL, copy and paste the parameters and argument values into your summary service query, excluding the dataProfile parameter-argument pair, which differs from the dataProfile options for the summary web service. Below is an example screenshot from the Water Quality Portal. The shaded area denotes the section that can be copied and pasted into the summary service URL. The crossed out section indicates the dataProfile, which should be replaced with one of the two allowable options for the summary service, as mentioned above and in Table 2. Illustration of using the Results URL in the WQP web interface for constructing a summary services URL. b. Download the full list of allowable parameter values, available on a per-parameter basis. Links are provided in Table 2.

  2. Use caution when specifying a parameter that is nested within another parameter (e.g. characteristicName and characteristicType; county and state). Queries that combine nested parameters can lead to unexpected behavior, particularly when more than one argument for one or more parameters is specified. Combining nested parameters with multiple arguments for a given parameter is therefore not recommended. For example, the following query parameters used in combination may not produce the expected result:

characteristicType=Nutrient&characteristicType=Physical&characteristicName=Nitrogen&characteristicName=Temperature

Using Open Geospatial Consortium Services to map Water Quality Portal sites based on Water Quality Portal Parameters

The Water Quality Portal has an endpoint for generating OGC-Compliant Geospatial web services. At this time, Web Mapping Service (WMS) version 1.3.0 and Web Feature Service (WFS) version 2.0.0 are supported. The service is a customized version of the WMS and WFS services provided by Geoserver. To get started, check out the Geoserver WMS Reference and WFS Reference.

The base URL for both the WMS and WFS services is: https://www.waterqualitydata.us/ogcservices/{wms|wfs}

Use web mapping tools, such as Leaflet or Openlayers, to easily connect to these web map services. GIS tools such as ArcGIS and QGIS also connect to these web maps services.

WFS and WMS services require an additional parameter, called "SearchParams", which is a URL-encoded version of the WQP search parameters. The service supports calls up to up to 250,000 sites. Calls that return large numbers of sites will take longer to load for the first time, as a cache is populated; subsequent responses will be much quicker. The cache is cleared after new data are loaded to the portal (once a day, at night).

At this time, we support WMS GetMap, WMS GetFeatureInfo, and WMS GetLegendGraphic.

WMS Getmap

  • For detailed information on constructing a WMS getmap request, refer to the GetMap documentation at the Geoserver site.
  • Here is an example GetMap Request for stream sites that have samples for atrazine: https://www.waterqualitydata.us/ogcservices/wms?SERVICE=WMS&REQUEST=GetMap&VERSION=1.1.1&LAYERS=wqp_sites&STYLES=wqp_sources&FORMAT=image%2Fpng&TRANSPARENT=true&HEIGHT=256&WIDTH=256&SEARCHPARAMS=countrycode%3AUS%3BcharacteristicName%3AAtrazine&SRS=EPSG%3A3857&BBOX=-15028131.257091932,-7.081154551613622e-10,-10018754.171394622,5009377.085697313

Looking Up Domain Values Through Web Services

The allowable values for each query variable (referred to as domain values) may change over time as new values are added. There is a web service request that allows you to look up which values are allowed for a query parameter.

A list of parameter names and arguments to use for these web service requests is shown in Table 3.

Base URL for looking up domain values: https://www.waterqualitydata.us/Codes/{endpointName}?{parameter}

You must provide at least one argument in the web service call. If you want all domain values, you can just specify the mimetype (e.g. mimeType=json).

Table 3. Domain values web service parameters and arguments

Expand Table
{endpointName} REST parameter Argument Discussion Example
Common parameters for all domain values web services mimeType xml|json returns either XML or json. Default is xml https://waterqualitydata.us/Codes/characteristicname?text=ph&pagesize=20&pagenumber=1&mimeType=json
pagenumber page number (1,2 etc) allows for results to be paginated (especially useful for endpoints with many valid responses, allows for infinite scrolling). Use along with pagesize
pagesize e.g. 20 number of results to return per page
text e.g. ph text to match to endpoint results. This is straight string matching. When the text parameter is used, the results are returned sorted by length
Endpoints with unique query parameters in addition to common query parameters
countrycode FIPS country codes
statecode countrycode A FIPS country code (e.g. US) FIPS state codes. A FIPS country code argument is appended so that the URL ends as /statecode?countrycode=US https://www.waterqualitydata.us/Codes/statecode?countrycode=US
countycode statecode A FIPS statecode (e.g. statecode=US:01;US:04) FIPS county codes. A FIPS statecode argument is appended so that the URL ends as /countycode?statecode=US:01;US:04 https://www.waterqualitydata.us/Codes/countycode?statecode=US:01;US:04
Sitetype Available site types https://www.waterqualitydata.us/Codes/Sitetype?mimeType=json
Organization Available organization IDs https://www.waterqualitydata.us/Codes/Organization?mimeType=xml
Samplemedia Sample media https://www.waterqualitydata.us/Codes/Samplemedia?mimeType=xml
Characteristictype Characteristic types (groups) https://www.waterqualitydata.us/Codes/Characteristictype?mimeType=xml
Characteristicname Characteristic names. A good choice for using paginated results so that hundreds of results are not returned https://www.waterqualitydata.us/Codes/Characteristicname?mimeType=xml
providers The names of the Data Sources for the Water Quality Portal https://www.waterqualitydata.us/Codes/providers?mimeType=xml