Statistics Service Details

Retrieve daily, monthly or annual statistics for sites. Statistics are provided on approved data only for time-series sites. Statistics are available for any parameter on these sites with approved data.

Statistics Web Service

You can use this service to retrieve daily, monthly or annual statistics for a USGS site and parameter.

To provide statistics, the site must serve time-series data, i.e. data is collected via an automated means and at regular intervals (typically every 15 minutes). You can use the daily values test tool or the site service test tool to find these sites. When using the site service test tool, make sure your query is qualifed with the argument &hasDataTypeCd=dv.

The service serves statistics based on approved data only. Recent data is considered provisional and is thus not approved. In general, you may find periods of unapproved statistics when requesting statistics within a year or less from today. Unapproved statistics will not show. The value may be left blank depending on the service called.

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 statistics for one or more sites in one request
Data for historical, as well as currently active sites are available, providing the site collected time-series data.

With hundreds of thousands of qualifying 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 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.

Daily, monthly and annual statistics

Daily statistics are statistics based on the day of the year. For example, if you request a daily mean statistic for streamflow for January 1st for a site, the mean streamflow for January 1st for each year of interest is acquired and the mean of all these values is then calculated. In this case the daily statistics is the mean of all the means for that date. If you asked for minimum, you would get the minimum of all the minimums for the date, etc.

Monthly statistics are calculations based on a month and year. It answers questions like “For February 1999 what was the mean streamflow?” Using mean as an example, you will get a mean (average) of all the daily means for the site for February 1999.

Annual statistics are based on a calendar year or water year. For a given year you will get back a single statistic for a site and a parameter, such as the mean streamflow for a site for calendar year 2010.

Sometimes gages may be down or inaccessible due to equipment malfunctions or other issues. You have the option to calculate monthly or annual statistics if there is missing data using the missingData argument. Otherwise there must be a complete set of approved statistics for the type of statistic wanted to serve that statistic. If it cannot be served, the value is generally left blank or null.

Interpreting the output

Currently only tab-delimited data can be downloaded using this service. XML and JSON outputs will be added in a subsequent release. Regardless of the format downloaded, only the way it is encoded and marked up differs.

Daily statistics

Caution: with daily statistics, the years in the output are in water years, not calendar years. Water years begin October 1 of the year before the calendar year and end September 30 of the calendar year. As a consequence, if concerned about the actual calendar year for the statistic, you must subtract 1 from the year shown if the date is between October 1 and December 31.

This query returns default statistics for site 01646500, at the Little Falls Pumping Station on the Potomac River, specifically streamflow or discharge. The site number is identified in Column B and the parameter being measured (streamflow) is identified in column C (00060). Row 1 contains column names and Row 2 contains some information about the type of data in the column. For example, 5s means expect a string (set of characters) not to exceed 5 characters. Data begin with Row 3.

Column F indicates the month of the statistic and column G indicates the day in the month of the statistic. So Row 3 contains statistics for January 1st across the entire period of record, which in this case was from the beginning of water year 1931 (October 1, 1930) to end of water year 2013 (September 30, 2013), as indicated by Columns H and I. The last row, Row 21, contains statistics for December 31. Many rows were removed for readability.

Mean is the same as average. So Cell O3 indicates that the average streamflow for this site on January 1st is 13,400 cubic feet per second across more than eighty years of record.

What was the maximum flow on January 1st? Cell L3 tells us: 118,000 cubic feet per second and this record occurred in 1943 (Cell K3). Similarly, minimum flow for January 1st occurred in 1966 (Cell M3) when streamflow was 940 cubic feet per second (Cell N3).

Columns P through X indicate percentiles, indicating the value below which a given percentage of observations in a group of observations fall. For example, the 20th percentile is the value below which 20 percent of the observations may be found, which for January 1st is 3,490 cubic feet per second (Cell R3). The median value is the same as the 50th percentile. The median value for January 1st is 9,050 cubic feet per second (Cell T3). The percentiles shown are provided by default. There is no year associated with percentile, just as there is no year associated with the mean, as it makes sense only for minimum or maximum values.

The “loc_web_ds” column (Column D) is normally blank. Some sites may measure from different locations, such as the right bank and the left bank of a river. If this site has multiple measurement locations, you will see text here describing the site location. The “dd_nu” column (Column E) indicates the Data Descriptor associated with streamflow at this site. Generally, this is of interest only to USGS scientists and can be ignored.

What is “count_nu”? In this case it represents the 83 years of statistics, or its period of record in years. This will stay the same except in the peculiar case of February 29. Since this is recorded only every four years, the number is smaller, 21 in this case.

Daily statistics are rounded using these rounding rules .

Monthly statistics

Annual statistics

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 Code	HTTP Error Code Description	Explanation
200	OK	The request was successfully executed and some data should have been returned.
304	Not_Modified	This 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.
400	Bad_Request	This 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
403	Access_Forbidden	This 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.
404	Not_Found	Returned 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) exists but they do not serve time-series data 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.
500	Internal_Server_Error	If 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.
503	Service_Unavailable	The 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/stats/?<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 code is returned

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

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

URL argument names and 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/iv/?site=01646500

Multiple Site Queries

Unlike the other services on this site, at this time the statistics service is limited to accepting a list of up to ten site numbers only. At least one site number must be supplied.

Major Filter (select one of the following)	Meaning	Minimum Number of Argument Values	Maximum Number of Argument Values	Examples
sites (aliases: site)	A list of site numbers. You can specify up to ten site numbers per query. 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. Note that only sites containing time series data (serve daily values) can return data.	1	10	&site=01646500 &sites=USGS:01646500 &sites=01646500,06306300

Major Filter

(select one of the following)

Meaning

Minimum Number of Argument Values

Maximum Number of Argument Values

Examples

sites (aliases: site)

A list of site numbers. You can specify up to ten site numbers per query. 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. Note that only sites containing time series data (serve daily values) can return data.

&site=01646500
&sites=USGS:01646500
&sites=01646500,06306300

Specifying Date Ranges for calculating statistics

Specifying dates is optional

Choosing to specify date ranges is optional. If you don’t specify a date range then statistics will be calculated against the entire period of record for a site and the parameter(s) of interest. So one site may have fifty years of record and its statistics will be calculated based on that period, while another site may have ten years of record and its statistics will be calculated over its 10 years. If you want to constrain statistics to be calculated over a narrower period of interest than the period of record, specify dates using startDt and endDt arguments.

Annual statistics: calendar year and water year, what’s the difference?

Annual statistic can be calculated against a calendar year or water year. You can select the type of year you want with the statYearType parameter.

Calendar years begin January 1 and end December 31. Calendar years are assumed by default.
Water years are the same as federal fiscal years. Federal fiscal years begin October 1 of the previous year and end on September 30 of the current year. For example, Water Year 2013 began October 1, 2012 and ended September 30, 2013. Water years are selected by including the URL argument statYearType=water. Thus when you specify statReportType=annual&startDt=2005&endDt=2005&statYearType=water the annual statistics will be based on a year beginning October 1, 2004 and ending September 30, 2005.

Start Date (startDt)

URL Argument Name	startDt
Description	Used to specify a start date for a period of interest. Statistics will be calculated based on the start date that you specify.
Syntax	startDt=[ YYYY-MM-DD \| YYYY-MM \| YYYY ] // for daily stats startDt=[ YYYY-MM \| YYYY ] // for monthly stats startDt=YYYY // for annual stats
Default	The start of the period of record. Specifying YYYY returns the start of the year YYYY-01-01, unless you request a water year. Specifying YYYY-MM returns the start of the month YYYY-MM-01 The effective start date may be "rounded" to the level of accuracy needed based on whether daily, monthly or annual statistics are wanted. The period of record includes only approved values.
Minimum argument values required	1
Maximum argument values allowed	1
Examples	&startDt=1931-03-01 &startDt=1931-03 &startDt=1931

End Date (endDt)

URL Argument Name	endDt
Description	Used to specify an end date for a period of interest. Statistics will be calculated based on the end date that you specify.
Syntax	endDt=[ YYYY-MM-DD \| YYYY-MM \| YYYY ] // for daily stats endDt=[ YYYY-MM \| YYYY ] // for monthly stats endDt=YYYY // for annual stats
Default	The end of the period of interest. Specifying YYYY returns the end of the year YYYY-12-31, unless you request a water year. Specifying YYYY-MM returns the last day of the year and month. So 2004-02 would return 2004-02-29 because it was a leap year. In addition, the effective end date may be "rounded" to the level of accuracy needed based on whether daily, monthly or annual statistics are wanted. The period of record includes only approved values.
Minimum argument values required	1
Maximum argument values allowed	1
Examples	&endDt=2010-12-31 &endDt=2010-12 &endDt=2010

Rules for specifying dates

Dates are specified in an ISO-8601 date format. You can use the format YYYY for years, YYYY-MM for months and YYYY-MM-DD for days. Use the startDt and endDt URL arguments when you need to specify period of interest dates that are less than the period of record. startDt is the start date, month or year. endDt is the end date, month or year. endDt must always be equal to or greater than startDt.

Daily statistics:

Use startDt and endDt to a day, month or year granularity. For example, startDt=2010-03-01. If you use less granularity, the start of the month or year will be assumed. startDt=2010-03 yields startDt=2010-03-01 and startDt=2010 yields startDt=2010-01-01.
For endDt, if you use less granularity then the end of the month or year will be assumed. endDt=2010-11 yields endDt=2010-11-30 and endDt=2010 yields endDt=2010-12-31.

Monthly statistics:

Do not specify a startDt or endDt to a day’s granularity. For example, do not do this: startDt=2010-03-01. You will get an error.
Use startDt and endDt to a month granularity. For example, use startDt=2010-03.
For startDt, if you use less granularity than month, then the start of the calendar year will be assumed. startDt=2010 yields endDt=2010-01.
For endDt, if you use less granularity than month then the end of the calendar year will be assumed. endDt=2010 yields endDt=2010-12.

Annual statistics:

Annual statistics can be calculated against a calendar year or a water year. The statYearType argument is used to set the type of annual statistics desired.

Specify only to the granularity of a year, ex: startDt=2010 or endDt=2012. Specifying these dates in a YYYY-MM or YYYY-MM-DD format will result in an error.
For calendar year statistics (statYearType=calendar), which is the default, statistics are calculated based on years starting January 1 and ending December 31.
For water year statistics (statYearType=water), statistics are calculated based on years starting October 1 of the previous year and ending September 30 of the current year. Thus, the meaning of the year specified in startDt and endDt will change, even though you will use the YYYY format to indicate the year. For example, startDt=2010&endDt=2013&statYearType=water means that annual statistics are calculated based on a calendar period from October 1, 2009 through September 30, 2013.

Defaults for start and end dates

Daily, monthly and annual statistics all depend on daily values, so daily values must exist and they must be approved. Moreover, they will only exist if a site has been recording statistics for the entire day. This helps explain the logic on defaults for dates with this service.

For start date (startDt):

For daily statistics, the default is the first full day of the period of record. For example, if a site started recording data on April 13, 1995 at 12:00 local time then the default startDt will be startDt=1995-04-14
For monthly statistics, the default start month is the first month after a site started recording data. For example, if a site started recording data on April 13, 1995 then the default startDt will be startDt=1995-05
For annual statistics, the default start year is the first year after a site started recording data. For example, if a site started recording data on April 13, 1995 then the default startDt will be startDt=1996. Note that annual statistics can be calculated over calendar years or water years.

For end date (endDt):

For daily statistics, the default is the last day of the full period of record. For example, if a site stopped recording data on September 12, 2007 at 12 PM local time, then the default endDt will be endDt=2007-09-11
For monthly statistics, the default end month is the first month before a site stopped recording data. For example, if a site stopped recording data on September 12, 2007 then the default endDt will be endtDt=2007-08
For annual statistics, the default end year is the first year before a site stopped recording data, unless it stopped at the end of the year exactly. For example, if a site stopped recording data on September 12, 2007 then the default endDt will be endDt=2006. Note that annual statistics can be calculated over calendar years or water years using the statYearType and startDt URL arguments.

Note that you can ask for annual and monthly statistics despite missing data within the month or year with the missingData argument. In some cases this will change default behavior if there are enough partial values to create a statistic for a start or end month.

Statistics and date ranges

Regardless of the statistics type wanted (daily, monthly or annual), statistics are computed against the period of interest by using startDt and endDt arguments. If not specified, the start and end dates for the period of record are used.

You can specify a range shorter or longer than a site’s period of record using the startDt and endDt arguments.

If the period of interest is less than the period of record, it will calculate statistics across that date range, for example startDt=1960&endDt=1979 will calculate over those twenty years, even if the full period of record is from 1950 to 2009.
If the period of interest is greater than a site’s actual period of record, the actual period of record will be used. For example, if the period of record is from 1995-2004 and you specify &startDt=1990&endDt=2009, values will be computed against the ten years of record from 1995 to 2004. After all, you can only generate statistics based on data actually available.

Date examples

?site=01646500 // Returns daily statistics for all parameters for the entire period of record of the site. Daily statistics are the default statistics type.
?site=01646500&statReportType=annual // Returns calendar year annual statistics for all parameters for the entire period of record
?site=01646500&statReportType=annual&startDt=2010 // Returns annual statistics for all parameters starting with calendar year 2010 through the last full calendar year of approved statistics
?site=01646500&statReportType=annual&statYearType=water // Returns annual statistics for all parameters by water year, where each water year actually begins October 1 of the previous calendar year and ends September 30 of the calendar year
?site=01646500&statReportType=annual&startDt=2010&endDt=2010 // Returns annual statistics for all parameters for calendar year 2010 only
?site=01646500&statReportType=monthly&startDt=2010-01 // Returns monthly statistics for all parameters based on the calendar year 2010 through the last full month of approved statistics
?site=01646500&statReportType=monthly&startDt=2010&endDt=2010 // Returns monthly statistics for all parameters based on calendar year 2010 only
?site=01646500&statReportType=monthly&startDt=2010-01&endDt=2010-12 // Returns monthly statistics for all parameters based on calendar year 2010 only
?site=01646500&statReportType=monthly&startDt=2010-05&endDt=2010-06 // Returns monthly statistics for all parameters for May and June 2010
?site=01646500&startDt=2010-01-01 // Returns daily statistics for all parameters for calendar year 2010 through to the present year
?site=01646500&startDt=2010-01-01&endDt=2010-12-31 // Returns daily statistics for all parameters for calendar year 2010 only. Note: since this is within a calendar year, the data returned should be the same as a daily values, so it would be better to use the daily values service.
?site=01646500&startDt=2010-01&endDt=2010-12 // Same as above
?site=01646500&startDt=2010&endDt=2010 // Same as above
?site=01646500&startDt=2010-05-15&endDt=2010-05-17 // Returns daily statistics for all parameters from May 15, 2010 through May 17, 2010. Note: since this is within a calendar year, the data returned should be the same as a daily value, so it would be better to use the daily values service.

Format (format)

URL Argument Name	format
Description	Used to specify the output format of the data returned. Only tab-delimited (RDB) is available at this time. XML, JSON and Excel will be available in the future. rdb is a self-describing tab-delimited format used widely by the USGS, documented in a PDF file here (Adobe Acrobat Reader)
Syntax	format=rdb{,1.0}
Default	rdb
Minimum argument values required	1
Maximum argument values allowed	1
Examples	&format=rdb &format=rdb,1.0

Indenting (indent)

URL Argument Name	indent
Description	Used to specify whether block structured data formats (&format=xml\|json only) should include indentation for easy viewing. Four space characters are inserted for every level of indentation. Otherwise the parameter is ignored. Since only tab-delimited (RDB) output is available at this time, this argument is effectively ignored at this time.
Syntax	indent=[on\|off]
Default	off
Minimum argument values required	1
Maximum argument values allowed	1
Examples	&format=rdb&indent=on // Format parameter ignored, does not apply to RDB

Statistical Controls

These controls influence which statistics are served and how statistics are calculated.

Statistics Report Type (statReportType)

URL Argument Name	statReportType (aliases reportType, statReportTypeCd)
Description	The type of statistics desired. Valid statistic report types include: daily - daily statistics (default) monthly - monthly statistics annual - annual statistics, based on either calendar year or water year, as defined by statYearType. If statYearType is not provided, calendar year statistics are assumed.
Syntax	statReportType= [ daily \| monthly \| annual ]
Default	daily - daily statistics
Minimum argument values required	1
Maximum argument values allowed	1
Examples	&parameterCd=00060,00065&statReportType=monthly // monthly discharge and gage height statistics

Statistics Type (statType)

URL Argument Name	statType (aliases statTypeCd, statTypesCd, statTypes)
Description	Selects sites based on the statistics type(s) desired, such as minimum, maximum or mean Valid statistic types include: mean - arithmetic mean or average For daily statistics you can also specify: min - minimum, or smallest value found for the daily, monthly or annual statistics max - maximum, or largest value found for the daily, monthly or annual statistics median - the numerical value separating the higher half of a the data from the lower half, same as specifying P50. If used median will be represented by the column name p50_va. P05, P10, P20, P25, P50, P75, P80, P90, P95 with the number indicating percentile. Note: the service can calculate only these percentiles. all - selects all of the above
Syntax	statType= {all \| { mean,min,max,median,P05...P95 } }
Default	all
Minimum argument values required	1
Maximum argument values allowed	12
Examples	&parameterCd=00060,00065&statType=mean // mean discharge and gage high statistics

Missing Data (missingData)

URL Argument Name	missingData
Description	Used to indicate the rules to follow to generate statistics if there are gaps in the period of record during the requested statistics period. By default if there are any missing data for the report type, the statistic is left blank or null. This option does not apply to daily statistics, but optionally can be used with monthly and yearly statistics. If used with daily statistics, an error will occur. Missing data can happen for various reasons including there was a technical problem with the gage for part of the time period. Enabling this switch will attempt to provide a statistic if there is enough data to create one.
Syntax	missingData={ on \| off }
Default	off
Minimum argument values required	1
Maximum argument values allowed	1
Examples	&missingData=on // follow rules for calculating statistics if there is missing data &missingData=off // follow default rules for calculating statistics if there is missing data

Statistics Year Type (statYearType)

URL Argument Name	statYearType (aliases yearType, statYearTypeCd)
Description	Indicates which kind of year statistics should be created against. This only applies when requesting annual statistics, i.e. statReportType=annual. Valid year types codes include: calendar - calendar year, i.e. January 1 through December 31 water - water year, i.e. a year begins October 1 of the previous year and ends September 30 of the current year. This is the same as a federal fiscal year.
Syntax	statYearType=[ calendar \| water ]
Default	calendar
Minimum argument values required	1
Maximum argument values allowed	1
Examples	&parameterCd=00060,00065&statType=mean&statReportType=annual&statYearType=water // annual mean discharge and gage height statistics, calculated based on a water year

Minor Filters

Additional filters can be applied after specifying a major filter. This further reduces the set of expected results. Users are encouraged to use minor filters because it allows more efficient use of this service. Note: since only site numbers can be supplied as a major filter at this time, minor filters other than parameter code have limited usefulness.

Parameter Code (parameterCd)

URL Argument Name	parameterCd (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)
Syntax	parameterCd\|variable={parameterCd1,parameterCd2,...}
Default	returns all regular time-series parameters for the requested sites
Minimum argument values required	1
Maximum argument values allowed	100
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

Site Status (siteStatus)

URL Argument Name	siteStatus
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: it has collected time-series (automated) data within the last 183 days (6 months) it has collected discrete (manually collected) data within 397 days (13 months) If it does not meet these criteria, it is considered inactive. Some exceptions apply. If a site is flagged by a USGS water science center as discontinued, it will show as inactive. A USGS science center can also flag a new site as active even if it has not collected any data. The default is all (show both active and inactive sites).
Syntax	siteStatus=[ all \| active \| inactive ]
Default	all - sites of any activity status are returned
Minimum argument values required	1
Maximum argument values allowed	1
Examples	&siteStatus=active

Site Type (siteType)

URL Argument Name	siteType (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)
Syntax	siteType={siteType1,siteType2,...}
Default	All site types are returned
Minimum argument values required	1
Maximum argument values allowed	No limit
Examples	&siteType=ST // Streams only &siteType=ST,LA-OU // Streams and Land Outcrops only

Agency Code (agencyCd)

URL Argument Name	agencyCd
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.
Syntax	agencyCd=agencyCd1
Default	All sites regardless of agency code are retrieved
Minimum argument values required	1
Maximum argument values allowed	1
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 instantaneous values 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
Default	All sites are retrieved, regardless of their altitude
Minimum argument values required	1
Maximum argument values allowed	1
Examples	&altMin=1000&altMax=5000 // Return sites where the altitude is 1000 feet or greater and 5000 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
Default	All sites are retrieved, regardless of their drainage area
Minimum argument values required	1
Maximum argument values allowed	1
Examples	&drainAreaMin=1000&drainAreaMax=5000 // Return sites where the drainage area is 1000 square miles or greater and is 5000 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
Default	all
Minimum argument values required	0
Maximum argument values allowed	1000
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,...}
Default	all
Minimum argument values required	0
Maximum argument values allowed	1000
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
Default	All sites are retrieved, regardless of their well depth
Minimum argument values required	1
Maximum argument values allowed	1
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
Default	All sites are retrieved, regardless of their hole depth
Minimum argument values required	1
Maximum argument values allowed	1
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 .