USGS Statistics Web Service - URL Generation Tool

This tool provides a simple way to generate syntactically correct URLs to use with the Beta USGS Statistic web service. Use it to get comfortable with the service before creating your own applications. Press the question mark icon for help with a particular field.

URL argument names and values are not case sensitive, ex: ?agencyCd=usgs, ?AGENCYCD=usgs, ?agencycd=USGS can all be used and are equivalent. See the full service description for details.

Simply enter the values you want in the fields below. Press Generate the URL button at the bottom to get the resulting URL. To see the results in your browser, next press the Run the Generated URL button.

You must have Javascript enabled for your browser to use this tool.

REQUIRED ARGUMENTS:

Major Filter:

You must select one of the following major filters. A major filter is required to limit the list of sites and associated data that can be retrieved, ensuring fair access to the service. For performance reasons, only a list of site numbers is allowed at this time.

List of sites (or just a single site)

Site or Site Numbers:

You can use either site or sites for the URL argument name. sites corresponds to one or more site numbers. These sites need to have approved daily values in order to show statistics. Separate sites with commas. For performance reasons, you can specify no more than ten site numbers. The site number may be optionally prefixed by the agency code followed by a colon, which ensures the site is unique. Examples: ?site=06306300 or ?sites=USGS:06306300. There is no default if this argument is used. Site numbers range from 8 to 15 characters. To find sites of interest, we suggest using the NWIS Mapper .

OPTIONAL ARGUMENTS:

Output Format: USGS RDB (tab-delimited) format USGS RDB (tab-delimited) format, Version 1.0

URL argument name is format. Select the output format desired. If there is no format argument in the generated URL, the most currently supported version of USGS RDB format is returned. Example: &format=rdb. Formats available:

• rdb - a self-describing tab-delimited format used widely by the USGS, documented in a PDF file here (Adobe Acrobat Reader ). Version is 1.0.

The version of the format wanted, if available, can be appended using the syntax: &format=<format_type>,<version_number>. The version number is optional but its use is encouraged because it means your application is less likely to break. If you do not specify the version number in your syntax, the most recently implemented version in that format will be returned instead. In some cases, if there is no known version of a format, 1.0 is used to distinguish it.

Indent:

URL argument name is indent. Used to specify whether block structured data formats (&format=xml and json only) should include indentation for easy viewing. Four space characters are inserted for every level of indentation. Otherwise the parameter is ignored. The default is off.

STATISTICAL PERIODS OF INTEREST:

Calculate statistics against entire period of approved record

Calculate statistics based on start and end dates that I supply

Start Date:

URL argument name is startDT. Use the ISO-8601 date format . Examples: &startDT=1990-01-01, &startDT=1990-01 and &startDT=1990. Specify a date only. Remember if water years are wanted, they begin October 1 of the previous year. So a startDt for WY13 is &startDt=2012-10. Hours, minutes, seconds and timezone values are not allowed, but granularity at the month or year level is allowed. If startDt is specified but endDt is not, endDt is assumed to be the last day of approved data for the site and parameter of interest. If specified, startDt must not be greater than endDt.

End Date:

URL argument name is endDT. Use the ISO-8601 date format . Examples: &endDT=1999-12-31,&endDT=1990-12 and &endDT=1990. If specifying a month, the end date is assumed to be the last day of the month. If specifying a year, the end data is assumed to be the last day of the calendar year. Specify a date only. Remember if water years are wanted, they begin October 1 of the previous year. So an endDt for WY13 is &startDt=2013-09-30. Hours. minutes, seconds and timezone values are not allowed, but granularity at the month or year level is allowed. If endDt is specified but startDt is not, startDt is assumed to be the first day of approved data for the site and parameter of interest. If specified, endDt must not be less than startDt.

STATISTICAL CONTROLS:

Statistics Report Type:

URL argument name is statReportType. There are three kinds of reports that provide different kinds of aggregation of statistics: daily, monthly and annual. They are mutually exclusive so you can only select one. The default is daily, which can be specified if desired, ex: &statReportType=daily. See the service description for details on how daily, monthly and annual statistics are computed.

Daily statistics(default)
Monthly statistics
Annual statistics

Statistics Types:

URL argument name is statType. Calculates the statistics type(s) desired, such as minimum, maximum or mean. Only mean is available for monthly or annual statistics. For daily statistics, you can also specify 5th, 10th, 20th, 25th, 50th (median), 75th, 80th, 90th and 95th percentile statistics. Leave out this argument or use statType=all to get all available statistics. A given statistic may be blank if there are not enough daily values to compute the statistic. In many cases this can be overridden with the missingData argument. You can select more than one statistic. Hold down the CTRL key (CMD on Macs) while selecting to select more than one.

All Mean (average) Minimum Maximum Median (same as P50) 5th Percentile 10th Percentile 20th Percentile 25th Percentile 50th Percentile (median) 75th Percentile 80th Percentile 90th Percentile 95th Percentile

Statistics Year Type: Calendar Year Water Year

URL argument name is statYearType. This switch only applies if annual statistics are desired (statReportType=annual), otherwise it is ignored. The value of an annual statistic is dependent on the kind of year desired. Calendar year (statYearType=calendar) is the default. This means that each annual statistic is based on first computing a yearly statistic that begins January 1 and ends December 31. If you select statYearType=water, a water year, then a year begins October 1 of the year preceding the calendar year and ends September 30 of the calendar year. If you do not specify a startDt when selecting a user year, then January 1 (calendar year) will be assumed.

Missing Data:

URL argument name is missingData. Used to indicate the rules to follow to generate statistics if there are gaps in the period of record during the requested statistics period. This applies to monthly and annual statistics only. The argument is ignored for daily statistics. By default if there is any missing data for the report type, the information is left blank. This can happen for various reasons including there was a technical problem with the gage or the gage was ice affected for part of the time period. Enabling this switch will attempt to provide a statistic if there is enough data to create one. Note that some statistics require a minimum number of values. For example, to generate a median statistic at least three values are needed. At least ten values in the month are required to compute a percentile statistics. The default is missingData=off. If you want to calculate statistics even though there may be gaps in the period of record, set missingData=on.

Generate statistics only if there is no missing data (default)
Generate statistics if possible if there is missing data

PARAMETERS OF INTEREST:

Sites serving parameter codes:

URL argument names are variable or parameterCd. In this case, parameterCd means a USGS parameter, and indicates some aspect of the site being measured or calculated, such as streamflow. If parameterCd or variable is specified in the generated URL, only sites serving those parameters are returned. To specify more than one parameter code, separate with commas, ex: &variable=00060,00065. Complete list of parameter codes . Up to 100 parameter codes allowed per request. The default is all, which can be specified if desired, ex: &variable=all. For this service, only parameter codes used to measure time-series data will return statistics.

OPTIONAL FILTERS:

Optional filters, if used, further reduce the list of sites returned.

Sites with agency code of:

URL argument name is agencyCd, which indicates the organization maintaining or funding the sites. You can filter to show only sites with one specific agency code. For example, ?stateCd=tx&agencyCd=USCE would return sites in Texas for the U.S. Army Corps of Engineers only. By default if agencyCd does not appear in the URL then sites with any agency code are returned. Agency codes are 3-5 characters long with most being 5 characters in length. List of agency codes .

Minimum site altitude in feet:

Maximum site altitude in feet:

URL argument names are altMin and altMax. Enter the minimum and/or maximum altitude in feet for the sites you want retrieved. Decimal values are allowed. If both are specified, altitudes between the minimum and maximum altitudes are included. Maximum altitude must be greater than or equal to minimum altitude. Values are inclusive, so if you specify altMin at 1000 feet, you will get sites at exactly 1000 feet or more. Selecting sites based on a desired altitude datum is presently not possible. If you leave these arguments blank, site altitude is ignored. Example: ?altMin=1000&altMax=1500.

Sites contained within these national aquifer codes:

Parameter name is aquiferCd. Use this to filter sites 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 . Example: &aquiferCd=S500EDRTRN,N100HGHPLN returns groundwater sites for the Edwards-Trinity aquifer system and the High Plains national aquifers. The default is all, which means the results are not filtered to exclude any aquifer codes. It can be specified if desired, however, if a list is provided you cannot exceed 1000 aquifer codes. ex: &aquiferCd=all.

Sites contained within these local aquifer codes:

Parameter name is localAquiferCd. Use this to filter sites that exist in specified local aquifers. Note: not all sites have been associated with local aquifers. Enter one or more local aquifer codes in the field, separated by commas. A local aquifer code is 10 characters, beginning with the state's abbreviation followed by a colon followed by the local aquifer code. A complete list of local aquifer codes can be found here. To translate the state code associated with the local aquifer, you may need this reference. Example: &localAquiferCd=AL:111RGLT,AL:111RSDM returns groundwater sites for the Regolith and Saprolite local aquifers in Alabama. The default is all, which means the results are not filtered to exclude any local aquifer codes. It can be specified if desired, however, if a list is provided you cannot exceed 1000 local aquifer codes. ex: &localAquiferCd=all.

Surface Water Attributes:

Sites located in watershed with a minimum drainage area in square miles:

Sites located in watershed with a maximum drainage area in square miles:

URL argument names are drainAreaMin and drainAreaMax. These arguments allows you to select surface water sites where the associated sites' drainage areas (watersheds) are within a desired size, expressed in square miles. Decimal values are allowed. If neither are specified, drainage area is ignored. If both the minimum and maximum drainage area are specified, sites between the minimum and maximum drainage areas specified are returned. If only one is provided, then only sites at or above the minimum drainage area or at or below the maximum drainage area are returned. Caution: not all sites are associated with a drainage area. Since drainage area only applies to surface water sites, this should not be used with groundwater sites other than springs. Example: &drainAreaMin=1000&drainAreaMax=5000

Groundwater Attributes:

Well has a minimum depth in feet of:

Well has a maximum depth in feet of:

URL argument names are wellDepthMin and wellDepthMax. These arguments allows you to select finished wells with the desired depth from the land surface datum, expressed in feet. Decimal values are allowed. If neither are specified, well depth is ignored. If both the minimum and maximum well depths are specified, then sites between the minimum and maximum well depth are returned. If only one is provided, then only sites at or above the well depth or at or below the well depth are returned. Example: &wellDepthMin=500&wellDepthMax=1000

Hole has a minimum depth in feet of:

Hole has a maximum depth in feet of:

URL argument names are holeDepthMin and holeDepthMax. These arguments allows you to select sites where the hole was initially drilled within a given range, with the depth from the land surface expressed in feet. Decimal values are allowed. If neither are specified, hole depth is ignored. If both the minimum and maximum hole depths are specified, sites between the minimum and maximum hole depth are returned. If only one is provided, then only sites at or above the hole depth or at or below the hole depth are returned. Example: &holeDepthMin=500&holeDepthMax=1000

Generated URL:

Caution: queries that return large sets of data may cause your browser to slow down or lock as it attempts to download and format large sets of data for display. When testing services in a browser, it is suggested that you create queries that should return relatively small sets of data. When creating an application you will typically use a program like curl , wget or the Windows task scheduler to retrieve data, which should acquire data more quickly than a browser.

Generate the URL Run the Generated URL Reset

(Note: if you do not see the XML in the output, please View Source.)