WQP User Guide

WATER QUALITY PORTAL USER GUIDE

Introduction

The Water Quality Data Portal (WQP) provides an easy way to access data stored in two large water quality databases. Input parameters on the form include location, site, sampling, and date parameters. The WQP can return site information (locations where samples were collected), or it can return sample results (analytical data of collected samples). Any field in the form left blank will cause a search for all parameters in that field.

Example: If a user selects US and California for the country and state respectively, but leaves the county field blank, data will be returned for all counties in California. All data will also be returned for the fields under SITE PARAMETERS and SAMPLING PARAMETERS.

The same input parameters can be used to make data retrievals using web services. For more information and examples on accessing the web services, see the Web Services Guide.

Available Databases:

NWIS (USGS) - Water-resources data collected from approximately 1.5 million sites in all 50 states, the District of Columbia, Puerto Rico, the Virgin Islands, Guam, American Samoa, and the Commonwealth of the Northern Mariana Islands. NWIS (USGS) is updated every 24 hours. Data recently added to NWIS (USGS) may not be immediately accessible through the WQP. Data are available for each location dating back to the earliest record available in the database.

WQX (EPA) - Formerly the STORET database, this is a data warehouse for water quality, biological, and physical data used by state environmental agencies, the EPA, other federal agencies, universities, private citizens, and others. WQX (EPA) is updated weekly on Thursday evening. Data recently added to WQX (EPA) may not be immediately accessible through the WQP. Data are available for each location dating back to the earliest record available in the database. Throughout the website, STORET and WQX are used interchangeably to refer to the WQX data warehouse.

Explanation of portal search parameters

The WQP can be searched through three different search options:

1. Location parameters
2. Site parameters
3. Sampling parameters

Location Parameters

Basic location parameters

Country - Use the country window to select one or multiple countries represented in the database. Parentheses after each country represent which database(s) it is represented in.

Web Services Request: Countries can be directly entered into the URL through their FIPS country code. For the United States: #countrycode=US

State - Use the state window to select one or multiple states. Parentheses after each state represent which database(s) it is represented in.

Web Services Request: States can be directly entered into the URL through their FIPS state code. For Iowa and Arizona: #statecode=US%3A04&statecode=US%3A19

County - Use the county window to select one or multiple counties from the selected state(s). Parentheses after each county represent which database(s) it is represented in.

Web Services Request: Counties can be directly entered into the URL through their FIPS county code. For Adams and Clay counties in Iowa: #countycode=US%3A19%3A003&countycode=US%3A19%3A041

Point Location - Enter latitude and longitude (decimal degrees referenced to NAD83), and radial distance (miles) to create a search area. Longitudes in the western hemisphere begin with a negative sign. Many stations outside the continental US do not have latitude and longitude referenced to NAD83 and cannot be found using these parameters.

Example: 20 miles from latitude 46.12 degrees N, longitude 89.15 degrees W would be entered as: * Distance: 20 * Latitude: 46.12 * Longitude: -89.15

Site Type - Site type indicates a natural or human-made feature affecting the hydrologic conditions measured at a site. Use the site type window to select one or multiple site types. Parentheses after each site type represent which database(s) it is represented in. Table 1 includes a definition for each available site type.

Table 1. Available site types and definitions

View Table

Site Type	Definition
Aggregate groundwater use (NWIS, STORET)	An aggregate groundwater site type is used when it is not possible or practical to describe the specific sites as springs or as any type of well including 'multiple wells', or when water-use information is only available for the aggregate. Aggregate sites that span multiple counties should be coded with 000 as the county code, or an aggregate site can be created for each county.
Aggregate surface-water-use (NWIS, STORET)	An aggregate surface-water site type is used when it is not possible or practical to describe the specific sites as diversions, outfalls, or land application sites, or when water-use information is only available for the aggregate. Aggregate sites that span multiple counties should be coded with 000 as the county code, or an aggregate site can be created for each county.
Aggregate water use establishment (NWIS)	An aggregate class of water-using establishments or individuals that are associated with a specific geographic location and water-use category, such as all the industrial users located within a county. Identified using the national water-use category code and optionally classified using the Standard Industrial Classification (SIC) Code or North American Classification System (NAICS) Code. Used when specific information needed to create sites for the individual facilities or users is not available, or when it is not desirable to store the site-specific information in the database.
Atmosphere	A site established primarily to measure meteorological properties or atmospheric deposition.
Estuary	A coastal inlet of the sea or ocean; esp. the mouth of a river, where tide water normally mixes with stream water (modified, Webster). Salinity in estuaries typically ranges from 1 to 25 Practical Salinity Units (psu), as compared oceanic values around 35 psu.
Facility	A non-ambient location where environmental measurements are expected to be strongly influenced by current or previous activities of humans.
Glacier	Body of land ice that consists of recrystallized snow accumulated on the surface of the ground and moves slowly downslope over a period of years or centuries. Since glacial sites move, the lat-long precision for these sites is usually coarse.
Lake, Reservoir, Impoundment	An inland body of standing fresh or saline water that is generally too deep to permit submerged aquatic vegetation to take root across the entire body (cf: wetland). This site type includes an expanded part of a river, a reservoir behind a dam, and a natural or excavated depression containing a water body without surface-water inlet and/or outlet.
Land	A location on the surface of the earth that is not normally saturated with water. Land sites are appropriate for sampling vegetation, overland flow of water, or measuring land-surface properties such as temperature. (See also: Wetland).
Ocean	Site in the open ocean, gulf, or sea. (See also: Estuary).
Spring	A location at which the water table intersects the land surface, resulting in a natural flow of groundwater to the surface. Springs may be perennial, intermittent, or ephemeral.
Stream	A body of running water moving under gravity flow in a defined channel. The channel may be entirely natural, or altered by engineering practices through straightening, dredging, and (or) lining.
Subsurface	A location below the land surface, but not a well, soil hole, or excavation.
Well	A hole or shaft constructed in the earth intended to be used to locate, sample, or develop groundwater, oil, gas, or some other subsurface material.
Wetland	Land where saturation with water is the dominant factor determining the nature of soil development and the types of plant and animal communities living in the soil and on its surface (Cowardin, December 1979). Wetlands are found from the tundra to the tropics and on every continent except Antarctica. Wetlands are areas that are inundated or saturated by surface or groundwater at a frequency and duration sufficient to support, and that under normal circumstances do support, a prevalence of vegetation typically adapted for life in saturated soil conditions. Wetlands generally include swamps, marshes, bogs and similar areas. Wetlands may be forested or unforested, and naturally or artificially created.

Advanced Location Parameters

Additional search options are available in the 'Advanced' query form, including:

Bounding Box - Enter the North and South latitudes and the East and West longitudes (decimal degrees referenced to NAD83) to create a bounding box. Longitudes in the western hemisphere should begin with a negative sign.

Example: * North: 46.12 * East: -89.15 * South: 45.93 * West: -89.68

Organization ID - Identifies a unique business or company. Use the organization ID window to select one or multiple organization IDs. Type at least two characters for a list to appear. For more information on Water Quality Exchange (WQX) Organization IDs, see About WQX (EPA).

Site ID - Identifies a monitoring location by a unique name, number, or code. Use the site ID window to select one or multiple site IDs. Type at least two characters for a list to appear.

When making a web services request: IDs are displayed as: AGENCY-STATION NUMBER. If STATION NUMBER is specified but not AGENCY, "USGS" will be assigned as the default. * For NWIS (USGS) site: #siteid=USGS-301650089215300 * For WQX (EPA) site: #siteid=R10BUNKER-CUA005-5 * For multiple sites: #siteid=IN002-385000086310010&siteid=USSCS-311039092211614&siteid=USEPA-414120087304701

HUC - Identifies the hydrological unit (lists and maps of hydrologic units) up to the cataloging unit level of precision. Use the HUC ID window to select one or multiple HUC IDs. Separate multiple HUC IDs with a semicolon (";"). Select partial HUCs using trailing wildcards ("*").

When making a web services request: * One site: #huc=01010005 * Multiple sites: #huc=01010003%3B01010004 * Partial HUCs: 010801*

FILTER RESULTS

Basic filtering parameters

Data Source - Select one or multiple databases from which the data will be retrieved. All databases are searched by default.

Date Range - Start and end dates to be used individually or together. Dates must be entered in MM-DD-YYYY format.

Sample Media - Identifies the environmental medium where a sample was taken. Use the sample media window to select one or multiple sample media types. Parentheses after each sample medium represent which database(s) it is represented in. Table 2 includes a definition for each sample medium that is available.

Table 2. Available sample media and definitions

View Table

Sample Medium	Definition
Air	Atmospheric gases.
Biological (STORET)	A biological source, including tissue, whole organisms, and whole or partial parts from animals or plants; from the WQX database.
Biological Tissue (NWIS only)	Any type of tissue that comprises either whole or parts of insects, fish, or other organisms living in an aquatic environment, animals that may or may not have been collected from a water body, or whole or parts of plants, aquatic or non-aquatic.
Habitat (STORET)	The habitat conditions at the monitoring site; physical features of the area surrounding the monitoring location site; from the WQX database.
No media (STEWARDS)	Sample medium information not available.
Other	None of the other sample media.
Sediment	Includes bottom material and suspended sediment sample media. Bottom material is a mixture of mineral and organic matter that compose the top bed deposits (usually the first few inches) underlying a body of water. Suspended sediment is sediment carried in suspension by the turbulent components of the fluid or by the Brownian movement (a law of physics).
Soil	A wet or dry substance composed of unconsolidated fine grain rock fragments (minerals) and organic material that has been modified sufficiently by physical, chemical, or biological processes to support terrestrial plant growth.
Tissue (STORET)	Any type of tissue that comprises either whole or parts of insects, fish, or other organisms living in an aquatic environment, animals that may or may not have been collected from a water body, or whole or parts of plants, aquatic or non-aquatic; from the WQX database.
Water	The physical or chemical composition of the water at the monitoring site.

Characteristic Group - Groups types of environmental measurements. Use the characteristic group window to select one or multiple characteristic groups. Parentheses after each characteristic group represent which database(s) it is represented in. A complete listing of which characteristic matches to which characteristic group is available for download.

For the time being, a user can also use the text boxes under 'Characteristic' and 'Characteristic Group' to enter additional values that may not appear in the drop-down list: this may affect some USGS data only.

View Advanced Filtering Parameters

Characteristic - Identifies types of environmental measurements. Use the characteristics window to select one or multiple characteristics. Parentheses after each characteristic represent which database(s) it is represented in. The names are derived from the WQX (EPA) Substance Registry System (SRS). USGS uses parameter codes for the same purpose and has associated most parameters to SRS names.

The nomenclature for WQX (EPA) and USGS characteristics are not identical.

Example: The WQX (EPA) lists each dissolved oxygen characteristic, while the USGS classifies dissolved oxygen under "oxygen". Consequently, users interested in retrieving dissolved oxygen data from both databases must select "dissolved oxygen" from WQX (EPA) and "oxygen" from the WQP list of characteristics. Selecting "oxygen" will return dissolved oxygen results from the USGS and all WQX (EPA) results relating to free gaseous oxygen.

Small differences in naming may cause chemically identical characteristics to be listed under different names or names that are formatted differently.

Example: 1,4-dichlorobenzene may be listed as "1,4-dichlorobenzene", "p-dichlorobenzene", or both. A user desiring all 1,4-dichlorobenzene data would need to select both names (and variants thereof) to retrieve the results.

Parameter Code - Identifies a characteristic using NWIS (USGS) codes. Use the parameter code window to select one or multiple parameter codes. Specifying a parameter code will limit the query to NWIS (USGS) only.

Tips on creating robust search filters

Search filters are made up of parameters, like statecode:

• statecode=US:27

Here, statecode is set to US:27 (The FIPS code for the state of Minnesota), which means that only records from the state of Minnesota will be returned. You can think of this as a filter or a requirement that all records in the WQP system must pass through if they are going to be returned to you.

Different search parameters are logically AND’ed together

When more than one different parameter is used, records must meet both requirements to be returned, meaning that the parameters are logically AND’ed together. Say, for instance, that you want all data from the state of Minnesota as well as the data from an adjoining county in the state of Wisconsin. One might consider using the following query parameters:

• statecode=US:27 - FIPS code for Minnesota
• countycode=US:55:025 - FIPS code for Dane county, Wisconsin

The web service reads this as 'Return all records where statecode=US:27 AND countycode=US:55:025'. Since records cannot be in Minnesota and also simultaneously in Dane county, Wisconsin, this search will return no data because no records can satisfy both search parameters. The system simply doesn’t work that way - it is not possible to create a query of that type.

Similarly, combining parameters for characteristicType and characteristicName are problemmatic. For example, a query including:

• characteristicType=Biological
• characteristicName=1,1-Dichloroethene (a non-biological characteristic)

will return no data because results cannot be both Biological in type and also simultaneously a non-biological characteristic.

A good rule of thumb is to not use inter-related search parameters. E.g. don’t include both a state and county because the results will either include data only from the county because the county is in the state (redundant) or will return no data because the county is not in the state (a mistake). The same is true for countrycode and statecode, characteristicType and characteristicName, and any other inter-related sets of parameters.

Multi-valued search parameters are logically OR’ed together

Most search parameters accept multiple values. When multiple values are used for the same parameter, records may meet either requirement, that is, they are logically OR’ed together. For instance:

• statecode=US:27 (Minnesota)
• statecode=US:55 (Wisconsin)

This would return data that is in either Minnesota or in Wisconsin.

Combining multi-valued and multiple search parameters

The logic is the same as described above when multiple values and multiple search parameters are combined, but the interactions can become more complicated. Here is a simple example:

• statecode=US:27 (Minnesota)
• statecode=US:26 (Michigan)
• characteristicType=Biological

To understand this search filter, first combine the multi-valued parameter using OR logic, and then combine different parameters using AND logic. For this example:

Results must be in Minnesota OR Michigan;

AND results must be of Biological type

Here is a more complex example that demonstrates what not to do:

• statecode=US:27
• statecode=US:26
• characteristicType=Biological
• countycode=US:55:025

This example is the same as above, but adds a county in Wisconsin which results in no data being returned. This is how the service reads the logic:

Results must be in Minnesota OR Michigan

AND the results must be in Dane county, Wisconsin (!!!)

AND the results must be of Biological type

As you can see, no results will meet the state and county requirement.

Writing search filters that work and are fast

Many searches fail because they time out. ‘Time out’ basically means the WQP system could not find the records quick enough before some part of the connection between you and WQP won’t wait any longer. Thus, creating a robust search filter can be the difference between getting your data and not. Below are some tips, in order of importance, for creating a performant search.

1. Constrain the data range to include only what you need. This is the most important filter optimization: If you only need data from a specific time range, specify it. For instance, add this if you only need data from one year:

startDateLo=01-01-2024

startDateHi=12-31-2024

1. Break up large queries into smaller date ranges. The WQP system is primarily organized by date, so a slow performing search can be improved by breaking them up into smaller and more quickly retrieved searches. For instance, if you need all historical data for a county but that query is failing, try fetching data in blocks. Older data (where the data is more sparse) or smaller geographic regions might work well with 5 or 10 year time blocks.

2. Allow the search filter to be less specific. In cases where a multi-parameter search is slow or fails, it may be that the search is too specific. A bit like a ‘needle in a haystack’, the system may need to look at every one of the hundreds of millions of record before it finds the one or two that meet all the filter conditions, which may take longer than the system allows. In this case, try removing some of the filter parameters (but keep the date filter!) to see if this improves the performance. This may require some downstream filtering to remove unwanted results, but might end up being quicker and easier.

DOWNLOAD THE DATA

A note on Data Type - The data are delivered in a format and nomenclature defined by the WQX-Outbound Schema.

Data Profiles - Select which profile (details on them in Section 'Explanation of dataretrievals' below) to download.

File Format - Choose a file format to download the result set. The available formats are listed and described in Table 3.

Table 3. Available file formats

View Table

File Format	Description
Comma-separated	Output format is comma-separated columns.

Explanation of data retrievals

Water monitoring data are organized in a format and nomenclature defined by the WQX- Schema. This schema represents the way the data are stored in the Water Quality Exchange database, which is in .xml format. The data are converted to a tabular format - comma-separated, Microsoft Excel, and tab-separated - for public delivery.

Data Profiles

There are hundreds of different data elements in the WQX 3.0 schema, which would make downloading all of them in a single file challenging to use and time-consuming to download. To make it easier for users to obtain only the subset of data elements in which they are interested, the data are grouped according to the type of data they describe, such as physical/chemical results data and metadata. These data elements grouped together for download are called Profiles. Some Profiles contain only metadata (e.g. site data or project data), while some contain results-level data, such as the ‘Sample Results’ Profiles. The results-level Profiles were designed to include the core data and metadata required for many common use cases such that additional Profiles are not required; however, each Profile contains a core set of data elements that enable joining individual tables together if needed. Note: For users who are interested in obtaining every bit of data for a particular site or group of sites, it may be necessary to download multiple Profiles. There is not a single Profile available for accessing every element of the WQX 3.0 schema.

Under "DOWNLOAD DATA", the data can be retrieved for the following profiles:

• Organization - Provides information about the organization(s) that have data matching the query. This includes the physical location, organization website, and contact information. Size: ~35 columns.
• Monitoring Location - Also referred to as Site or Station, this profile provides detailed information about queried monitoring locations, including geographic information such as latitude and longitude, administrative and/or tribal information such as State and County, hydrologic boundary information such as Hydrologic Unit Code (HUC) and drainage area, site type(s), and metadata related to an aquifer or groundwater borehole. Links to related attachment files, when available, are also included. Size: > 50 columns.
• Project - Provides information about the Project(s) with data matching a query. This includes information on the sampling design and quality assurance documents, when available. Links to related attachments files are also included when available. Size: ~10 columns.
• Project Monitoring Location Weighting - Provides details about how monitoring locations may be weighted by the data submitter . Size: ~10 columns.
• Full Physical/Chemical - Provides sample results and associated metadata for all physical and chemical measures, including chemical contaminants observed in biological tissues or toxicity testing. This comprehensive data profile includes metadata about the Project, Monitoring Location, Activity, sample preparation and analytical methods, laboratory information and data quality. Links to related attachment files are also included when available. Size: >175 columns.
• Basic Physical/Chemical - Provides sample results and associated metadata for the queried physical and chemical measures, including chemical contaminants observed in biological tissues or toxicity testing. This streamlined data profile includes the most commonly reported metadata useful for interpretation of the results, including information about the Project, Location, Activity, and analytical method. Size: ~100 columns.
• Full Biological - Provides sample results and a comprehensive suite of associated metadata for the queried biological, physical, and chemical measures. Includes taxonomic and counts data in addition to metadata about the Project, Location, Activity, sample preparation and analytical methods, laboratory information and data quality. Note: this profile does not include data elements necessary to determine toxicity; see instead “Full Physical/Chemical" profile. Size: >200 columns.
• Basic Biological - Provides sample results and associated metadata for the queried biological, physical and chemical measures, and includes taxonomic information and counts data. It also includes the most commonly reported metadata information useful for interpretation of biological results, including some basic Project, Location, and Activity information. Note: this profile does not include data elements necessary to determine toxicity; see instead “Full Physical/Chemical” profile. Size: ~120 columns.
• Narrow - Provides sample results for all biological, physical and chemical measures queried with a reduced subset of the most critical and commonly reported metadata fields. Includes minimal information about the project, location, activity, results, and analytical methods. Size: ~60 columns.
• Sampling Activity - Provides information about a field visit. Includes detailed information on the location and collection methods, as well as sample-level information related to toxicity testing and biological assemblage sampled. Data in this profile can be joined to results data using the activity identifier. Size: > 90 columns.
• Sampling Activity Group - Provides metadata for linking related sampling activities. This grouping may be used by data providers to enable grouping of sample results with QA samples, for example. Size: ~ 6 columns.
• Sampling Activity Metric - Provides habitat, biological, and other metrics that have been calculated using multiple data inputs from observed or measured data. These metrics are indicators used to quantify ecological properties such as habitat quality and biodiversity. Includes location and some activity metadata as well as comprehensive metric information such as metric names, definitions, calculations, references, and index identifiers, where applicable. Size: >40 columns.
• Biological Habitat Index - This profile can include information for other indexes and not just those related to biological habitat assessments. Provides habitat, biological or other index scores calculated from habitat metrics or other measures. Includes location metadata as well as comprehensive index and citation information. Size: ~40 columns.
• Result Detection Quantitation Limit - Provides detailed information on the detection limits for individual measured constituents in a query. Includes location information as well as the result identifier to enable joining to sample results. Detection quantitation limit data indicate the constituent concentration that, when processed through the complete method, produces a signal that is statistically different from a blank. There can be multiple detection quantitation limit types per result. Size: >30 columns.
• Laboratory Sample Preparation - Provides detailed metadata about the methods used by a laboratory to prepare a sample for analysis. Includes information on the start and end date and time, sample qualifier type, method description, and dilution factor. Data in this profile can be joined to results data using the laboratory sample preparation identifier. Size: ~10 columns.

Download the WQX 3.0 outbound schema

As part of the upgrade from WQX 2 to WQX 3.0, we made numerous improvements to the data. These changes come from the dedicated efforts of a WQX3.0 Working Group, which consisted of WQX data users and staff from the EPA and USGS. They reflect many hours spent evaluating earlier versions of profiles and making changes to improve the data usability. In addition, focused user testing was conducted on the draft profiles to ensure that the changes were meeting users' needs. Here is a list of the major changes:

1. More metadata fields are being delivered to the public
2. Added more site-level data to Results profiles to reduce or eliminate the need for downloading additional profiles
3. Shortened the field names for the data elements to make them easier to read and understand

The complete outbound schema is available for download here. This file provides the new names for each WQX data element, definitions, and the mapping of each name to the .xml formatted WQX 3.0 schema.

For users who are accustomed to the data as it appears in the version 2 profiles, we also created a version of the WQX 3.0 outbound schema with cross-references to the data elements of the version 2 profiles, which is available here.

Additionally, a tab-separated metadata file containing descriptions for each field name in the outbound schema files can be downloaded here.

Download Water Quality Exchange allowable value lists and definitions

Download Water Quality Exchange (WQX) domain value lists

Interpreting USGS data retrieved from the Water Quality Portal

The USGS sourced data available on the Water Quality Portal may include data that have not received Director's approval and as such are provisional and subject to revision. The data are released on the condition that neither the USGS nor the United States Government may be held liable for any damages resulting from its authorized or unauthorized use. USGS endeavors to ensure the accuracy of all water-quality data provided to the public. As part of our efforts to improve the timeliness and relevance of our data-collection efforts, provisional data are provided which may not have been reviewed. The majority of results are not changed during the review process, but errors do occur. The result status indicator is provided to guide data users. Results are initially coded with a result status of provisional. After review by a project hydrologist, the result status is usually changed to accepted. Laboratory results are initially reviewed at the laboratory and subsequently by the hydrologist. Sometimes, comprehensive reviews of quality-assurance data cause revisions to previously reviewed data, therefore an accepted status does not guarantee that results will never be updated.

Cite the Water Quality Portal

General Portal citations should use the following:

• Water Quality Portal. Washington (DC): National Water Quality Monitoring Council, United States Geological Survey (USGS), Environmental Protection Agency (EPA); 2021. https://doi.org/10.5066/P9QRKUVJ.

Citations for specific datasets should use this format:

• National Water Quality Monitoring Council, YYYY, Water Quality Portal, accessed mm, dd, yyyy, hyperlink_for_query, https://doi.org/10.5066/P9QRKUVJ.