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.

Beta

Thank you for trying the new WQX3.0 profiles. This website is a beta version of our future user interface. Additional profiles and site functionality are coming, so please visit this page often to see new and improved data offerings. Please be aware that this beta product may experience performance issues.
We appreciate your feedback and suggestions as you try these new services. Please contact us at WQX@epa.gov to provide your input.

WQP Web Services Guide

Introduction

The Water Quality Data Portal (WQP) provides easy access to data stored in two large water quality databases (WQX and NWIS) 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.

Software packages are available that make it easier for R and Python users to use the WQP web services for retrieving data. The USGS supports and maintains dataRetrieval for R users and dataretrieval-python for Python users. These packages do the heavy lifting to download data and convert it into a familiar and usable format. The packages can download data from the WQP and from a number of USGS web services. Check out these resources to access and start using the data retrieval packages:

  • CRAN - Download current R dataRetrieval release
  • GitHub - Download most up-to-date R source code (may contain bugs)
  • Tutorial - Learn how to use R dataRetrieval
  • GitHub - Download most up-to-date Python source code (may contain bugs); the documentation includes instructions on how to download the current release using pip or Conda.

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 site data and associated metadata: https://www.waterqualitydata.us/wqx3/Station/search?
  • Base URL for downloading results: https://www.waterqualitydata.us/wqx3/Result/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 ("&"). 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 ampersands (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, separated by ampersands. 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 ampersands (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 ampersands (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 ampersands (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 ampersands.
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 csv Output format is comma-separated columns.
providers STORET|NWIS| By default, requests are submitted to all the data providers. However, a particular provider may be specified using this parameter.
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, csv format:

https://www.waterqualitydata.us/wqx3/Station/search?statecode=US%3A40&countycode=US%3A40%3A109&characteristicName=Atrazine&mimeType=csv&providers=NWIS&providers=STORET

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

https://www.waterqualitydata.us/wqx3/Station/search?statecode=US%3A56&characteristicType=Nutrient&mimeType=csv&providers=NWIS&providers=STORET

Example: REST web service request to retrieve the complete physical and chemical metadata for Caffeine sample results from sites contained within a bounding box, csv format:

https://www.waterqualitydata.us/wqx3/Result/search?bBox=-92.8%2C44.2%2C-88.9%2C46&characteristicName=Caffeine&mimeType=csv&dataProfile=fullPhysChem&providers=NWIS&providers=STORET

Queries Using POST

We are in the process of adding the functionality to support POST requests and will add information about creating POST requests when this functionality has been implemented.

New WQX 3.0 Feature: Retrieve Request Status Receipt

The wqx3 web service enables temporary access to query metadata after a query has completed. This new status receiptfeature allows users to obtain data on the total number of counts and per-provider (NWIS and WQX) counts in a query, which can be used to verify that a download was successful.

Here is an example using curl:

curl -v -o "download.csv" "https://www.waterqualitydata.us/montage-svs-a/data/Result/search?providers=STORET&siteid=PYRAMIDLAKE-TRMPD&startDateHi=01-01-2010&startDateLo=01-01-2005&dataProfile=narrow"

The request is downloaded to a file called "download.csv". There is a bunch of output, including this line showing the 'wqp-request-id' header:

wqp-request-id: b6c9a6d6-f093-4ada-9ce9-035824a79ce4

Now make a request to the status service with that id:

curl "https://www.waterqualitydata.us/montage-svs-a/data/status/b6c9a6d6-f093-4ada-9ce9-035824a79ce4"

What comes back includes total counts and counts for the individual services.

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

Using ArcGIS Online to map Water Quality Portal Sites

Station data from the Water Quality Portal can be imported to ArcGIS Online. To get started, create a query using the Advanced form and copy the Station Web Service query at the bottom of the form.

Adding WQP Stations data from the Web (Classic Map viewer)

  • In your ArcGIS Online account, Open a Classic Map Viewer.
  • Click the “Add” dropdown and select “Add Layer from Web”.
  • Select “A CSV File” from the file type dropdown and paste the WQP Station Query URL that was generated by your search.
  • Edit the URL instructions to read “mimetype=csv” and click the “ADD LAYER” button. A pop-up will ask you to identify the latitude and longitude fields in the data.
  • Scroll down the data fields to correctly identify “LatitudeMeasure” and “LongitudeMeasure” as the respective fields.
  • Select “ADD LAYER” again and the stations should appear in the map.

Example Station call (csv)

Here is an an example station call for all stations with data in Prince George County, Maryland: 'https://www.waterqualitydata.us/wqx3/Result/search?statecode=US%3A24&countycode=US%3A24%3A033&mimeType=csv&providers=NWIS&providers=STORET'

You can follow these same instructions to import any of the other WQP profile services simply by following the same conventions of mimetype. You can find additional information for building calls in our web services documentation above.