This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Site Service

The USGS has information about millions of sites: locations where hydrologic (water) data is or has been collected. There are thousands of real-time alone. The site service allows you to find relevant sites of interest using a number of flexible filters, and provides key metadata about each site as well as optional information on the type of data collected at the site and the data collection period.

1 - Site Service Frequently Asked Questions

Common questions about the site service

How do I retrieve just real-time sites?

Real-time sites are USGS hydrologic sites that regularly transmit automated measurements and observations. Currently there is no perfect mechanism for retrieving real-time sites. In particular &hasDataTypeCd=rt will not return only real-time sites, since rt is an alias for instantaneous values (iv). The NWIS Mapper uses an approach that shows “active” sites. However, active sites have different meanings depending on whether they serve automated (time-series) data or are regularly visited by humans for collecting data manually (discrete data). For real-time sites, users are usually interested in automated record stations. Thus combining this with a list of “active” sites that have been operational over a recent time period helps flag those sites that recorded traffic recently. This is close to being a list of current real-time sites. For example, to retrieve all active sites for Rhode Island in a Google Maps format that have recorded observations in the last week, use: https://waterservices.usgs.gov/nwis/site/?format=mapper&stateCd=ri&period=P1W&outputDataTypeCd=iv .

Is this service available as a Web Feature service?

Not in the format, but The USGS will be rolling out a number of new services to provide monitoring location metadata in the coming months and years.

How do I integrate your site service with commercial mapping services, like Google Maps?

For other mapping services, consult their application programming interfaces (APIs). Most mapping applications can map geographic data in a Keyhole Markup Language (KML) format. Using &format=ge for Google Earth and &format=gm for Google Maps will probably work with Yahoo, Microsoft and other public mapping services because they are KML-friendly.

What is a period of record?*

This is the time period that the site was actively maintained and used. Ideally, it is a period of contiguous time to the present, but sites may be discontinued for a while due to lack of funding or are seasonally affected by the weather. Note that sites where discrete (manual) measurements were made are not “active” in the traditional sense, unless automated equipment is collocated at the site. However they do represent dates when data was collected at the site. A site’s period of record may be further refined to show periods of record for different data types, for example a time range for collecting daily values and discrete water quality measurements.

How do I use the service to determine a list of sites that were removed?

Data collected at a site is always maintained as a matter of record. Sometimes a site is removed from public display. Unfortunately, there is no way to get a list of these sites from the service other than to keep your own copy and compare changes. Note that the modifiedSince argument effectively only shows new sites and sites where site information has changed.

What new features are planned for the site service?

Aside from the web feature service, which is likely to be a separate service, the following improvements are anticipated: Excel 2007 output, search by site name, polygons of enclosed sites, and minimum bounding rectangles. These features are expected in 2014 or 2015.

2 - Site Service Details

The service allows searches for USGS sites and site information using a variety of flexible filters. Output formats include tab-delimited and KML formats (used with Google Earth and Google Maps).

Site Web Service

You can use this service to retrieve information about the millions of hydrologic sites with data served by the USGS. This service provides USGS water data in the legacy RDB (tab-delimited) format that are currently available from the USGS Water Data for the Nation site External Link, as well as in a Google Maps and Google Earth friendly formats. More media types will follow after technical issues are resolved.

How the service works

  • This is a REST-friendly service, which means it is URL accessible and can be run from a browser
  • The service can return information about one or more sites in one request
  • Data for historical, as well as currently active sites are available, including period of record information that describes the kinds of data collected at the site and date ranges when these data were collected.

With hundreds of thousands of sites across the nation, the amount of data available is very large. No one user is allowed to download all of the data with a single call. The service has consequently been designed and engineered to facilitate common mass queries, defaulting to returning a narrower set of data. You are encouraged to make your queries efficient too, mindful that many others need access to the data at the same time. Always specify the minimum amount of data you need in your request, using built in filters and date ranges to the maximum extent possible.

Testing the service

Probably the best way to learn how to use the service is to try it out!

The USGS provides this tool that allows you to generate syntactically correct calls to the service. You can even run the query live in your browser. The XML output may look somewhat strange if you are new to XML. When you have perfected your query you can copy and paste the URL into your application to get the precise data you need.

Test the service now

Enabling gzip compression

Typically data is downloaded as plain text via Hypertext Transfer Protocol (HTTP). However, gzip compression is supported by this service. Use of gzip compression may markedly speed up acquisition of data, particularly on large queries. It also is a more efficient use of USGS servers, so we appreciate when you are thoughtful enough to use it. Whether you can receive the data in gzip compressed formats depends on the capabilities of your client. Web browsers support gzip compression natively, but most regular users will use specialized utility programs like wget and curl to acquire data. If you can handle gzip compression, please place the following string into your HTTP request headers: Accept-Encoding: gzip, compress

curl and wget are typically used to download data. They may be configured to use gzip compression if the server will accept it. You may also explicitly have to tell it to use gzip compression. If so these tips should work:

  • curl: try adding the argument: -H 'Accept-Encoding: gzip,deflate'
  • wget: try adding the argument: --header="Accept-Encoding: gzip"

gzip files are typically returned as a file with a .gz file suffix unless you instruct your program to uncompress it. See the gzip man page for instructions on uncompressing .gz files.

Output

A web feature service is planned.

The most “data rich” format that is currently supported is the legacy USGS RDB (tab-delimited) format. The RDB format is documented here , and consists of a number of header comments that include column description information, followed by the relevant data. Fields are separated by invisible tab characters; records are separated with new line characters.

# US Geological Survey
#
# The Site File stores location and general information about ground water,
# surface water, and meteorological sites for sites in USA.
#
# File-format description: http://waterdata.usgs.gov/nwis/?tab_delimited_format_info
# Automated-retrieval info: http://waterdata.usgs.gov/nwis/?automated_retrieval_info
#
# Contact: gs-w_waterdata_support@usgs.gov
# retrieved: 2011-01-13 10:27:06 EST (nwisvatestws01)
#
# The following selected fields are included in this output:
# agency_cd -- Agency
# site_no -- Site identification number
# station_nm -- Site name
# site_tp_cd -- Site type
# dec_lat_va -- Decimal latitude
# dec_long_va -- Decimal longitude
# coord_acy_cd -- Latitude-longitude accuracy
# dec_coord_datum_cd -- Decimal Latitude-longitude datum
# alt_va -- Altitude of Gage/land surface
# alt_acy_va -- Altitude accuracy
# alt_datum_cd -- Altitude datum
#
agency_cd site_no station_nm site_tp_cd dec_lat_va dec_long_va coord_acy_cd dec_coord_datum_cd alt_va alt_acy_va alt_datum_cd 5s 15s 50s 7s 16s 16s 1s 10s 8s 3s 10s
USGS 01646500 POTOMAC RIVER NEAR WASH, DC LITTLE FALLS PUMP STA ST 38.94977778 -77.12763889 S NAD83 37.95 .01 NGVD29

Figure 1. Example of RDB output

The service also outputs in formats compatible with Google Earth and Google Maps by returning data in Keyhole Markup Language (KML) optimized for these mapping services. This allows you to show USGS sites on these and similar mapping products.

The Mapper format is a legacy XML format used by the USGS to support its National Water Information System Mapper product. However, these output formats contain minimal information about a site.

Many output formats from this service are straightforward and easy to understand. Google Map and Google Earth formats, for example, display minimal information for a site because they are intended to be used to show sites on a map. The RDB format can offer voluminous information that can be hard to understand and interpret.

Understanding site-level data

To interpret the RDB formats, you have to understand the meaning of the column headers in the output. Understanding basic site data is generally straightforward. In RDB, the column headers are described in comment lines that begin with a #.

  • The first non comment line is a header line, followed by a line that describes the kind of data and the maximum size of data in that field (5s for a 5-character string, for example)
  • The line after the header line are data lines. station_nm for example is POTOMAC RIVER NEAR WASH, DC LITTLE FALLS PUMP STA ST. This can be inferred because it is the third tab-delimited column in the header line, and the first data line contains this text in the third tab-position. If you don’t understand what station_nm is, the comments near the top of the file explain it should be interpreted as Site Name.
  • In some outputs you will see repetition of comment and header lines after various data lines. Each of these blocks describes data immediately below it.

Understanding period of record output

Period of record information can be especially confusing. Period of record information describes what data was collected at a site for what time periods. Consider this partial output for this query . The data is tab-delimited and will line up by column if imported into a spreadsheet, but it hard to show on a web page. Items below have been bolded to show associations between headers and their data:

# end_date -- End date
# count_nu -- Record count
#
agency_cd site_no station_nm site_tp_cd dec_lat_va dec_long_va coord_acy_cd dec_coord_datum_cd alt_va alt_acy_va alt_datum_cd data_type_cd parm_cd stat_cd loc_nm medium_grp_cd parm_grp_cd srs_id access_cd begin_date end_date count_nu
5s 15s 50s 7s 16s 16s 1s 10s 8s 3s 10s 2s 5s 5s 30s 3s 3s 5n 4n 20d 20d 5n
USGS 01646500 POTOMAC RIVER NEAR WASH, DC LITTLE FALLS PUMP STA ST 38.94977778 -77.12763889 S NAD83 37.95 .01 NGVD29 dv 00010 00003 wat 1645597 0 1988-10-01 2011-04-08 7856

Figure 2. Period of Record output

There is a story here. Looked at the bolded text in the example:

  • data_type_cd is associated with a value of “dv”. “dv” stands for daily values. So this site collects or collected daily values.
  • parm_cd is the USGS parameter code defined here . 00010 corresponds to water temperature in degrees Celsius. So now we know this site this site collects daily values for water temperature.
  • stat_cd stands for statistics code defined here . 00003 corresponds to mean, so now we know this site collects daily values for water temperature published as a mean (average) value for the day.
  • begin_date means the date that this information started to be collected, which was October 1, 1988.
  • end_date means end date and is April 8, 2011. If the site is active, this date will usually be the last full day. In short, mean water temperature is still being collected, so there is a continuous record for this kind of data since October 1, 1988 through April 8, 2011.
  • count_nu is count number, or the number of mean daily values that are available for water temperature for this site, which is 7856, presumably one for each day from October 1, 1988 through April 8, 2011.

Starting late February 2024, the Site Service will stop retrieving new water quality samples/results data or updates to existing data for queries using hasDataTypeCd=qw.

Based on this information, an application might want to programatically start another application to fetch the daily value data using the Daily Values web service.

When GML is available as an output format, data will be encapsulated in XML tags but have similar names, so similar logic will apply.

Where to find USGS code information

Error codes

Since this system uses Hypertext Transfer Protocol (HTTP), any application errors are reported in the HTTP headers. This means that when writing applications, it is important to first examine the HTTP status code that is returned in the HTTP response. The application server will return the error code along with a message describing the error in the event there is a problem. Programmers should always check the HTTP response code and if not a 200 handle the response as an exception. Among the status codes you may see:

HTTP Error CodeHTTP Error Code DescriptionExplanation
200OKThe request was successfully executed and some data should have been returned.
304Not_ModifiedThis indicates your request was redirected using the proper URL. This may occur if the "path" of your URL is not fully qualified. Ideally a / is placed before the ? in the URL. Adding in this slash may make this go away. However, the request should still be processed. If this becomes annoying, you may also be able to tell your client program to automatically follow redirects.
400Bad_RequestThis often occurs if the URL arguments are inconsistent. An accompanying error should describe why the request was bad. Reasons include:
  • Using startDT and endDT with the period argument.
  • Mixing startDt and endDt arguments where startDt includes a time zone and endDt does not
403Access_ForbiddenThis should only occur if for some reason the USGS has blocked your Internet Protocol (IP) address from using the service. This can happen if we believe that your use of the service is so excessive that it is seriously impacting others using the service. To get unblocked, send us the URL you are using along with your client's IP using this form. We may require changes to your query and frequency of use in order to give you access to the service again.
404Not_FoundReturned if and only if the query expresses a combination of elements where data do not exist. For multi-site queries, if any data are found, it is returned for those site/parameters/date ranges where there are data. Conditions that would return a 404 Not Found include:
  • The site number(s) are invalid
  • The site number(s) are valid but the requested parameter(s) are not served for these sites
  • No values exist for the requested date range. For example, a gage might be down for a period of time due to storm damage when it would normally have data.
500Internal_Server_ErrorIf you see this, it means there is a problem with the web service itself. It usually means the application server is down unexpectedly. This could be caused by a host of conditions but changing your query will not solve this problem. The application support team has to fix it. Most of these errors are quickly detected and the support team is notified if they occur.
503Service_UnavailableThe server is currently unable to handle the request due to a temporary overloading or maintenance of the server. The implication is that this is a temporary condition which will be alleviated after some delay.

Using the Web Service with Adobe Flex or the Flex API

Adobe Flex requires our server have a crossdomain.xml file indicating those domains that can access our web service using Adobe Flex. We are adding these on a case by case basis. If you need to access the service using Adobe Flex or the Flex API, please contact us using this form and indicate the domain of the server that will access the service.

CORS Support

This service supports the Cross-Origin Resource Sharing (CORS) specification. CORS permits browser-based asynchronous access to the service even though content originates from a server different than the one serving the web page. Otherwise the browser’s security controls would not allow content to come from USGS servers. Most, but not all browsers, support CORS. Some frameworks, like jQuery through the Ajax crossDomain setting, support CORS automatically.

URL Format

The URL must always be in this format:

https://waterservices.usgs.gov/nwis/site/?<arguments>

where <arguments> are one or more HTTP GET parameter names and values based on the information below.

Specifying the URL Arguments

You specify the arguments that go in <arguments>.

  • Each URL argument name is followed by an equal sign followed by one or more values for that argument. Where multiple values are allowed for the same argument, you can separate values with commas.
  • URL arguments are separated by ampersands (&)
  • The order of the URL arguments does not matter
  • If a URL argument name does not match one of the names below, a HTTP 400 error is triggered.

Here is an example of a valid URL that should return data:

https://waterservices.usgs.gov/nwis/site/?site=01646500

URL argument names and URL argument values can be in upper, lower or mixed case. They will all be handled correctly. All of the following will yield the same result:

URL argument conventions

The following conventions are used below to document URL argument values:

arg1=[ a {,x | ,y} | b | c,d,...]

  • square brackets [] are used to show a set of possible choices, with the pipe symbol | delineating exclusive choices. You must select one and only one of these choices.
  • curved brackets {} are used to show optional elements. They also may be delineated with | indicating exclusive choices. If used, you may select one and only one of these choices.
  • ... indicates more than item may be specified if items are delineated by commas. Note the limitation on the maximum number of argument values allowed below.

In the above example, these would be the allowed legal values:

  • arg1=a
  • arg1=a,x
  • arg1=a,y
  • arg1=b
  • arg1=c
  • arg1=c,d,e,f
  • arg1=e,f

Major Filters

Single Site Queries

Want to only query one site? Use site (or sites) as your major filter, and put only one site number in the list! Example:

https://waterservices.usgs.gov/nwis/site/?site=01646500

Multiple Site Queries

  • Every multiple site query requires a major filter. Pick the major filter (sites, stateCd, huc, bBox or counties) that best retrieves the data for the sites that you are interested in.
  • You can have more than one major filter per query. However, you cannot replicate a particular major filter in the query. The effect is an AND, reducing the results returned. Ex: &stateCd=nh&huc=01060003 returns sites in New Hampshire for Piscataqua-Salmon Falls.
  • Further refine the query with minor filters, if needed.

Major Filter

(select one of the following)

MeaningMinimum Number of Argument ValuesMaximum Number of Argument ValuesExamples
sites(aliases: site, location)A list of site numbers. You can specify unlimited sites, up to any limit imposed by the application server or your client. Sites are comma separated. Sites may be prefixed with an optional agency code followed by a colon. If you don't know the site numbers you need, you can find relevant sites with the NWIS Mapper or on the USGS Water Data for the Nation site.1Unlimited (see caveat)&site=01646500
&sites=USGS:01646500
&sites=01646500,06306300
stateCd
(alias: stateCds)
U.S. postal service (2-digit) state code. USPS List of State Codes.11&stateCd=NY
huc
(alias: hucs)
A list of hydrologic unit codes (HUC) or aggregated watersheds. Only 1 major HUC can be specified per request. A major HUC has two digits. Minor HUCs must be eight digits in length. Not all sites are associated with a HUC. List of HUCs.11 Major, 10 Minor&huc=01,02070010
bBoxA contiguous range of decimal latitude and longitude, starting with the west longitude, then the south latitude, then the east longitude, and then the north latitude with each value separated by a comma. The product of the range of latitude and longitude cannot exceed 25 degrees. Whole or decimal degrees must be specified, up to six digits of precision. Minutes and seconds are not allowed. Remember: western longitude (which includes almost all of the United States) is specified in negative degrees. Caution: many sites outside the continental US do not have latitude and longitude referenced to NAD83 and therefore can not be found using these arguments. Certain sites are not associated with latitude and longitude due to homeland security concerns and cannot be found using this filter.11&bBox=-83,36.5,-81,38.5
countyCd
(alias: countyCds)
A list of county numbers, in a 5 digit numeric format. The first two digits of a county's code are the FIPS State Code. List of county codes. Some updates were made to the FIPS code standards in 2021. NIST has provided replacement standards.120&countyCd=51059,51061

Outputs

Format (format)

URL Argument Nameformat
Description

Used to specify the output format of the data returned.

  • rdb is a self-describing tab-delimited format used widely by the USGS, documented in a PDF file here (Adobe Acrobat Reader)
  • gm means Google Maps formatted, which is actually encoded in an XML schema called Keyhole Markup Language and optimized for Google Maps. Since the underlying schema is KML, it may work on other map services, like Yahoo Maps. Notes
    • In Google Maps, if you enter the generated URL into the search field and submit the form, the sites should appear.
    • The version of KML is currently 2.2, but 1.0 is accepted as the version number because it is version 1.0 of the USGS's implementation of KML.
  • ge means Google Earth formatted, which is actually encoded as an XML schema called Keyhole Markup Language and optimized for Google Earth. Notes:
    • In Google Earth, add the generated URL to Add > Network Link to see the displayed sites. Since the underlying schema is KML, it may work on other map services, like Yahoo Maps.
    • The version of KML is currently 2.2, but 1.0 is accepted as the version number because it is version 1.0 of the USGS's implementation of KML.
  • mapper is a simple USGS XML format used by the USGS NWIS Mapper.
  • Version numbers are optional. If not specified, the most recent implemented version is used by default.
Syntax

format=[rdb{,1.0} | gm{,1.0) | ge{,1.0} | mapper{,1.0}]

Defaultrdb (This will change to gml when GML output is ready)
Minimum argument values required1
Maximum argument values allowed1
Examples
  • &format=ge // Latest implemented version of KML for Google Earth
  • &format=ge,1.0 // Version 1.0 of the USGS version of KML optimized for Google Earth
  • &format=rdb
  • &format=rdb,1.0

Show expanded Site Output (siteOutput)

URL Argument NamesiteOutput (alias: site_output)
Description

Indicates the richness of metadata you want for site attributes. Note that for visually oriented formats like Google Map format, this argument has no meaning. Note: for performance reasons, siteOutput=expanded cannot be used if seriesCatalogOutput=true or with any values for outputDataTypeCd.

  • basic - provides simple site attributes such as site name, agency, altitude, latitude and longitude.
  • expanded - provides a rich set of extended site attributes such as hydrologic unit code, drainage area and site time zone.
Syntax

siteOutput=[basic | expanded]

Defaultbasic
Minimum argument values required1
Maximum argument values allowed1
Examples
  • &siteOutput=basic
  • &siteOutput=expanded

Show Period of Record (seriesCatalogOutput)

URL Argument NameseriesCatalogOutput (alias: seriesCatalog)
Description

A switch that provides detailed period of record information for certain output formats. The period of record indicates date ranges for a certain kind of information about a site, for example the start and end dates for a site's daily mean streamflow. Note that for visually oriented formats like the Google Maps format, this argument has no meaning. When true, this is behaves the same as outputDataTypeCd=all. Note: for performance reasons, siteOutput=expanded cannot be used if seriesCatalogOutput=true.

Syntax

seriesCatalogOutput=true|false

Defaultfalse
Minimum argument values required0
Maximum argument values allowed1
Examples
  • &seriesCatalogOutput=true

Show one or more data types (outputDataTypeCd)

URL Argument NameoutputDataTypeCd (alias: outputDataType)
Description

This allows you to specify that you want to output specific kinds of period of record data. The default is all. Note that for visually oriented formats like Google Map format, this argument has no meaning. For example, if you set this argument to just "iv" you will see only period of record information for instantaneous values (time-series data) like stage and discharge time-series measurements. Note: for performance reasons, siteOutput=expanded cannot be used with any values for outputDataTypeCd.

  • all - default (see above for qualifications). This is equivalent to &seriesCatalogOutput=true.
  • iv - Instantaneous values (time-series measurements typically recorded by automated equipment at frequent intervals (e.g., hourly)
  • uv - Unit values (alias for iv)
  • rt - Real-time data (alias for iv). Note: use of rv does not restrict time-series data to only those with real-time data.
  • dv - Daily values (once daily measurements or summarized information for a particular day, such as daily maximum, minimum and mean)
  • pk - Peak measurements of water levels and streamflow for surface water sites (such as during floods, may be either an automated or a manual measurement)
  • sv - Site visits (irregular manual surface water measurements, excluding peak measurements)
  • gw - Groundwater levels measured at irregular, discrete intervals. For recorded, time series groundwater levels, use iv or id.
  • qw - Water-quality data from discrete sampling events and analyzed in the field or in a laboratory. For recorded time series water-quality data, use iv or id.
    Note Starting late February 2024, the Site Service will stop retrieving new water quality samples/results data or updates to existing data for queries using hasDataTypeCd=qw.
  • id - Historical instantaneous values (sites in the USGS Instantaneous Data Archive)
  • aw - Sites monitored by the USGS Active Groundwater Level Network
  • ad - Sites included in USGS Annual Water Data Reports
Syntax

outputDataTypeCd=[ all | { [iv | uv | rt], dv, pk, sv, gw, qw, id, aw, ad} ]

DefaultNo period of record output shows, unless seriesCatalogOutput=true
Minimum argument values required0
Maximum argument values allowed9
Examples
  • &outputDataTypeCd=all
  • &outputDataTypeCd=iv
  • &outputDataTypeCd=iv,dv,pk

Minor Filters

Minor filters further reduce the set of expected results and are applied after data is first filtered by the major filter you specified. You are encouraged to use minor filters to minimize the amount of data sent.

Date Filters

Start Date (startDt)

URL Argument NamestartDt
Description
  • Selects sites based on whether data was collected at a point in time beginning with the start date (startDt) through the end date (endDt)
  • Dates must be whole dates and in an ISO-8601 Calendar Date format
  • Should not be used with period
  • If endDt is not supplied, now is used.
Syntax

startDt=[ISO-8601-Calendar-Date]

DefaultstartDt is ignored. If endDt is present but startDt is not, sites through endDt are included
Minimum argument values required1
Maximum argument values allowed1
Examples
  • &startDt=1990-01-01
  • &startDt=1990-01-01 &endDt=1999-12-31

End Date (endDt)

URL Argument NameendDt
Description
  • Selects sites based on whether data was collected at a point in time beginning with the start date (startDt) through the end date (endDt)
  • Dates must be whole dates and in an ISO-8601 Calendar Date format
  • Should not be used with period
  • If startDt is not supplied, all data collection dates are used through and including endDt
Syntax

endDt=[ISO-8601-Calendar-Date]

DefaultendDt is ignored. If startDt is present but endDt is not, sites from the startDt to the present are included
Minimum argument values required1
Maximum argument values allowed1
Examples
  • &endDt=1999-12-31
  • &startDt=1990-01-01 &endDt=1999-12-31

Period (period)

URL Argument Nameperiod
Description
  • Selects sites based on whether or not they were active between now and a time in the past
  • Should not be used with startDt or endDt
  • Please note that you cannot specify months (M) or years (Y), even though it is allowed by ISO-8601, because the resulting time period is ambiguous.
Syntax

period=[ISO-8601-Duration]

Defaultperiod is ignored.
Minimum argument values required1
Maximum argument values allowed1
Examples
  • period=P10W // Active in the last ten weeks
  • period=PT4H // Active in the last four hours

Site was modified since (modifiedSince)

URL Argument NamemodifiedSince
Description
  • Returns only sites and thier metadata where site attributes or period of record data have changed during the requested period. Note this is different than period, which is used to indicate if a site was active for a period in the past.
  • The modifiedSince time period always begins with today and moves toward the past. It must be expressed in an ISO-8601 duration format. Please note that you cannot specify months (M) or years (Y), even though it is allowed by ISO-8601, because the resulting time period is ambiguous.
  • If the modifiedSince argument is not specified in the generated URL, it has no effect on the query.
  • If you request period of record data (&seriesCatalogOutput=true) or specific data types to be output (outputDataTypeCd), the period of record dates will be examined and, if newer, the newest date will be used to indicate if the site was modified. Otherwise, the date a site's attributes were last changed will be used.
Syntax

modifiedSince=[ISO-8601-Duration]

DefaultNone
Minimum argument values required1
Maximum argument values allowed1
Examples
  • ?stateCd=NY&modifiedSince=P1W - NY sites are retrieved only if any of their site level attributes were changed in the last week.
  • ?stateCd=NY&seriesCatalogOutput=true&modifiedSince=P1W NY sites are retrieved only if any of their site level attributes or period of record information were changed in the last week.
  • ?stateCd=NY&outputDataTypeCd=all&modifiedSince=P1W NY sites are retrieved only if any of their site level attributes or period of record information were changed in the last week.
  • ?stateCd=NY&outputDataTypeCd=iv,dv&modifiedSince=P1W NY sites are retrieved only if any of their site level attributes or period of record information for instantaneous values or daily values were changed in the last week.
  • ?stateCd=NY&outputDataTypeCd=iv,dv&hasDataTypeCd=pk&modifiedSince=P1W NY sites are retrieved only if any of their site level attributes or period of record information for instantaneous values or daily values were changed in the last week. However, since this query only shows sites where peaks were measured, the sites have to show peaks and also record instantaneous values and/or daily values. The period of record's last changed date for instantaneous and daily values for these sites are then factored into whether a site's information has changed.

Site Name (siteName)

URL Argument NamesiteName (aliases: siteNm, stationName, stationNm)
Description

This filter allows you to find a site by its name, using either the exact site name or a partial site name. Note that a major filter is still required. String matches are case insensitive, so if you specify "Boulder" you will retrieve site names with "Boulder", "boulder", "BOULDER" as well as many other variants. To embed a space, you can substitute %20.

Syntax

siteName=string

DefaultNone. If used, a string must be supplied or an error will occur.
Minimum argument values required1
Maximum argument values allowed1
Examples
  • &siteName=Boulder%20Creek

Site Name Match Operator (siteNameMatchOperator)

URL Argument NamesiteNameMatchOperator (aliases: siteNameMatch, siteNmMatch, stationNameMatch, stationNmMatch)
Description

If used, this must be used with siteName. It determines how the pattern matching for site name behaves. Matches are case insensitive. The options are:

  • start = The string must be at the start of the site name
  • any = The string must be contained somewhere in the site name
  • exact = The site name must exactly match the string supplied, with the exception that the match is not case sensitive
Syntax

siteNameMatchOperator=[ start | any | exact ]

Defaultstart
Minimum argument values required1
Maximum argument values allowed1
Examples
  • &siteNameMatchOperator=any

Site Status (siteStatus)

URL Argument NamesiteStatus
Description
  • Selects sites based on whether or not they are active. If a site is active, it implies that it is being actively maintained. A site is considered active if:

    The default is all (show both active and inactive sites).

SyntaxsiteStatus=[ all | active | inactive ]
Defaultall - sites of any activity status are returned
Minimum argument values required1
Maximum argument values allowed1
Examples
  • &siteStatus=active

Site Type (siteType)

URL Argument NamesiteType (aliases: siteTypes, siteTypeCd, siteTypeCds)
Description
  • Restricts sites to those having one or more major and/or minor site types.
  • List of valid site types
  • If you request a major site type (ex: &siteType=ST) you will get all sub-site types of the same major type as well (in this case, ST-CA, ST-DCH and ST-TS)
SyntaxsiteType={siteType1,siteType2,...}
DefaultAll site types are returned
Minimum argument values required1
Maximum argument values allowedNo limit
Examples
  • &siteType=ST // Streams only
  • &siteType=ST,LA-OU // Streams and Land Outcrops only

Has one or more data types (hasDataTypeCd)

URL Argument NamehasDataTypeCd (aliases: hasDataType, dataTypeCd, dataType)
Description

Restricts results to those sites that collect certain kinds of data.

Allowed values are:

  • all - default (see above for qualifications). This is equivalent to &seriesCatalogOutput=true.
  • iv - Instantaneous values (time-series measurements typically recorded by automated equipment at frequent intervals (e.g., hourly)
  • uv - Unit values (alias for iv)
  • rt - Real-time data (alias for iv). Unfortunately, using "rt" may retrieve sites that are not "real-time" because it is simply an alias, e.g. it may show discontinued sites. The closest approximation of a list of real-time sites is to use &siteStatus=active
  • dv - Daily values (once daily measurements or summarized information for a particular day, such as daily maximum, minimum and mean)
  • pk - Peaks measurements of water levels and streamflow for surface water sites (such as during floods, may be either an automated or a manual measurement)
  • sv - Site visits (irregular manual surface water measurements, excluding peak measurements)
  • gw - Groundwater levels measured at irregular, discrete intervals. For recorded, time series groundwater levels, use iv or id.
  • qw - Water-quality data from discrete sampling events and analyzed in the field or in a laboratory. For recorded time series water-quality data, use iv or id.
    Note Starting late February 2024, the Site Service will stop retrieving new water quality samples/results data or updates to existing data for queries using hasDataTypeCd=qw.
  • id - Historical instantaneous values (sites in the USGS Instantaneous Data Archive)
  • aw - Sites monitored by the USGS Active Groundwater Level Network
  • ad - Sites included in USGS Annual Water Data Reports

The service distinguishes between selecting sites with one or more data types and actually showing those data types in the output. hasDataTypeCd is used for selection. Since the default is to output all data types, this is normally not an issue, but it is possible to use hasDataTypeCd with outputDataTypeCd for unusual types of filters. See the examples below.

Syntax

hasDataTypeCd=[ all | { [iv | uv | rt], dv, pk, sv, gw, qw, id, aw, ad } ]

Defaultall
Minimum argument values required1
Maximum argument values allowed9
Examples
  • &hasDataTypeCd=all
  • &hasDataTypeCd=dv,iv
  • &hasDataTypeCd=iv&outputDataTypeCd=pk // Show peak period of record information for instantaneous values sites

Parameter Code (parameterCd)

URL Argument NameparameterCd (aliases: variable, parameterCds, variables, var, vars, parmCd)
Description
  • USGS time-series parameter code
  • All parameter codes are numeric and 5 characters in length. Parameter codes are used to identify the constituent measured and the units of measure.
  • Popular codes include stage (00065), discharge in cubic feet per second (00060) and water temperature in degrees Celsius (00010)
  • Complete list of USGS parameter codes (not all parameters are served by time-series sites)
SyntaxparameterCd|variable={parameterCd1,parameterCd2,...}
Defaultreturns all regular time-series parameters for the requested sites
Minimum argument values required1
Maximum argument values allowed100
Examples
  • &parameterCd=00060 // discharge, cubic feet per second
  • &parameterCd=00060,00065 // discharge, cubic feet per second and gage height in feet
  • &variable=00060 // discharge, cubic feet per second
  • &variable=00060,00065 // discharge, cubic feet per second and gage height in feet

Agency Code (agencyCd)

URL Argument NameagencyCd
Description
  • The list of sites returned are filtered to return only those with the provided agency code. The agency code describes the organization that maintains the site. Only one agency code is allowed and is optional.
  • An authoritative list of agency codes can be found here.
SyntaxagencyCd=agencyCd1
DefaultAll sites regardless of agency code are retrieved
Minimum argument values required1
Maximum argument values allowed1
Examples
  • &stateCd=il&agencyCd=USCE // Only US Army Corps of Engineers sites in Illinois

Altitude (altMin and altMax)

URL Argument Name
  • altMin (alias: altMinVa)
  • altMax (alias: altMaxVa)
Description
  • These arguments allows you to select sites where the associated sites' altitude are within a desired altitude, expressed in feet. Altitude is based on the datum used at the site.
  • Providing a value to altMin (minimum altitude) means you want sites that have or exceed the altMin value
  • Providing a value to altMax (maximum altitude) means you want sites that have or are less than the altMax value
  • You may specify decimal feet if precision is critical
  • If both the altMin and altMax are specified, sites at or between the minimum and maximum altitude are returned
Syntax
  • altMin=minValue
  • altMax=maxValue
DefaultAll sites are retrieved, regardless of their altitude
Minimum argument values required1
Maximum argument values allowed1
Examples
  • &altMin=1000&altMax=5000 // Return sites where the altitude is 1000 feet or greater and 5000 feet or less.
  • &altMin=12.5&altMax=13 // Return sites where the altitude is 12.5 feet or greater and 13 feet or less.

Surface water filters

Drainage Area (drainAreaMin and drainAreaMax)

URL Argument Names
  • drainAreaMin (alias: drainAreaMinVa)
  • drainAreaMax (alias: drainAreaMaxVa)
Description
  • These arguments allows you to select principally surface water sites where the associated sites' drainage areas (watersheds) are within a desired size, expressed in square miles or decimal fractions thereof.
  • Providing a value to drainAreaMin (minimum drainage area) means you want sites that have or exceed the drainAreaMin value
  • Providing a value to drainAreaMax (maximum drainage area) means you want sites that have or are less than the drainAreaMax value
  • The values may be expressed in decimals
  • If both the drainAreaMin and drainAreaMax are specified, sites at or between the minimum and maximum drainage areas values specified are returned
  • Caution: not all sites are associated with a drainage area.
  • Caution: drainage area generally only applies to surface water sites. Use with other site types, such as groundwater sites, will likely retrieve no results.
Syntax
  • drainAreaMin=minValue
  • drainAreaMax=maxValue
DefaultAll sites are retrieved, regardless of their drainage area
Minimum argument values required1
Maximum argument values allowed1
Examples
  • &drainAreaMin=1000&drainAreaMax=5000 // Return sites where the drainage area is 1000 square miles or greater and is 5000 square miles or less.
  • &drainAreaMin=10.5&drainAreaMax=10.7 // Return sites where the drainage area is 10.5 square miles or greater and is 10.7 square miles or less.

Groundwater Filters

Aquifer Code (aquiferCd)

URL Argument Names
  • aquiferCd
Description
  • Used to filter sites to those that exist in specified national aquifers. Note: not all sites have been associated with national aquifers.
  • Enter one or more national aquifer codes, separated by commas.
  • A national aquifer code is exactly 10 characters.
  • A complete list of national aquifer codes can be found here.
Syntax
  • aquiferCd={aquiferCd1,aquiferCd2,...}|all
Defaultall
Minimum argument values required0
Maximum argument values allowed1000
Examples
  • &aquiferCd=S500EDRTRN,N100HGHPLN // returns groundwater sites for the Edwards-Trinity aquifer system and the High Plains national aquifers.

Local Aquifer Code (localAquiferCd)

URL Argument Names
  • localAquiferCd
Description
  • Used to filter sites to those that exist in specified local aquifers. Note: not all sites have been associated with local aquifers.
  • Enter one or more local aquifer codes, separated by commas.
  • A local aquifer code begins with a 2 character state abbreviation (such as TX for Texas) followed by a colon followed by the 7 character aquifer code.
  • A complete list of local aquifer codes can be found here.
Syntax
  • all|localAquiferCd={localAquiferCd1,localAquiferCd2,...}
Defaultall
Minimum argument values required0
Maximum argument values allowed1000
Examples
  • &localAquiferCd=AL:111RGLT,AL:111RSDM // returns sites for the Regolith and Saprolite local aquifers in Alabama

Well Depth (wellDepthMin and wellDepthMax)

URL Argument Names
  • wellDepthMin (alias: wellDepthMinVa)
  • wellDepthMax (alias: wellDepthMaxVa)
Description
  • These arguments allows you to select groundwater sites serving data recorded automatically where the associated sites' well depth are within a desired depth, expressed in feet from the land surface datum.
  • Express well depth as a positive number.
  • Providing a value to wellDepthMin (minimum well depth) means you want sites that have or exceed the wellDepthMin value
  • Providing a value to wellDepthMax (maximum well depth) means you want sites that have or are less than the wellDepthMax value
  • The values may be expressed in decimals
  • If both the wellDepthMin and wellDepthMax are specified, sites at or between the minimum and maximum well depth values specified are returned
  • wellDepthMax should be greater than or equal to wellDepthMin.
  • Caution: well depth applies to groundwater sites only
Syntax
  • wellDepthMin=minValue
  • wellDepthMax=maxValue
DefaultAll sites are retrieved, regardless of their well depth
Minimum argument values required1
Maximum argument values allowed1
Examples
  • &wellDepthMin=100&wellDepthMax=500 // Return daily value sites where the well depth is 100 feet or greater and 500 feet or less.

Hole Depth (holeDepthMin and holeDepthMax)

URL Argument Names
  • holeDepthMin (alias: holeDepthMinVa)
  • holeDepthMax (alias: holeDepthMaxVa)
Description
  • These arguments allows you to select groundwater sites serving data recorded automatically where the associated sites' hole depth are within a desired depth, expressed in feet from the land surface datum.
  • Express hole depth as a positive number.
  • Providing a value to holeDepthMin (minimum hole depth) means you want sites that have or exceed the holeDepthMin value
  • Providing a value to holeDepthMax (maximum hole depth) means you want sites that have or are less than the holeDepthMax value
  • The values may be expressed in decimals
  • If both the holeDepthMin and holeDepthMax are specified, sites at or between the minimum and maximum hole depth values specified are returned
  • holeDepthMax should be greater than or equal to holeDepthMin.
  • Caution: hole depth applies to groundwater sites only
Syntax
  • holeDepthMin=minValue
  • holeDepthMax=maxValue
DefaultAll sites are retrieved, regardless of their hole depth
Minimum argument values required1
Maximum argument values allowed1
Examples
  • &holeDepthMin=100&holeDepthMax=500 // Return daily values sites where the hole depth is 100 feet or greater and 500 feet or less.

Feedback

Please provide any feedback you have on this service using this form .