Loading...

Web Service URL Generation Tool

This tool provides a simple way to generate syntactically correct URLs to use with the USGS REST 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: ?stateCd=ny, ?STATECD=ny, ?statecd=NY can all be used and are equivalent.

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.

Select Service to Test

Select a Major Filter

A major filter selected with a value is required in order for the generated URL to function properly.

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.

Site or Sites

You can use either site or sites for the URL argument name. sites corresponds to one or more site numbers. Separate sites with commas. The number of site you can specify is unconstrained, but are subject to limits on URL lengths supported by your browser and the application server. 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.

State or Territory

URL argument name is stateCd. You may select no more than one state or territory. Example: ?stateCd=ny.

Hydrologic Unit Codes

URL argument name is huc. You can specify one major hydrologic unit code (2 digit code) and up to 10 minor hydrologic unit codes (8 digit codes). Separate HUCs with commas. For performance reasons, no more than one major HUC is allowed. Complete list of HUCs . External Link Note: not all sites have been associated with a hydrologic unit. As such those sites cannot be retrieved with this method. Example: ?huc=01,02070010.

Latitude/Longitude Box

Northern-most Latitude

Western-most Longitude

Eastern-most Longitude

Southern-most Latitude

URL argument name is bBox for bounding box. The argument is a pair of four numbers separated by commas, beginning with the western longitude, then the southern latitude, then the eastern longitude, then the northern latitude. Note: to ensure fair access, the product of the range of latitude and longitude cannot exceed 25 degrees. Use decimal degrees rather than degrees, minutes and seconds. Decimals are not required. Up to seven digits of precision are allowed. Longitude is in the range of -180 to 180, latitude from -90 to 90. Remember, in the Western hemisphere, longitude is expressed in negative numbers. Example: ?bBox=-83,36.5,-81,38.5

Note: 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.

Counties

URL argument name is countyCd. Enter a list of county codes, separated by commas. There is no default. The county code is actually the state code (digits 1-2) plus the associated county number (digits 3-5). For performance reasons, you may enter no more than 20 county codes. Example: ?countyCd=51059,51061 retrieves sites in Fairfax and Prince William counties in the state of Virginia.

Optional Filters

These filters can help to filter down the data that the service will produce.

Output Format

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. Note: GML will become the default output format once it is available. Formats available:

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.

Indent

Show expanded site information

URL argument name is siteOutput. If you would like to see expanded site information, check this box. This argument is ignored for visually oriented output formats like Mapper, Google Earth and Google Maps. The default is basic. Use expanded to get expanded site information. Example: ?siteOutput=expanded. Note: for performance reasons, ?siteOutput=expanded cannot be used if seriesCatalogOutput=true or with any values for outputDataTypeCd

Show period of record information

URL argument name is seriesCatalogOutput. This argument is ignored for visually oriented output formats like Mapper, Google Earth and Google Maps. If you would like to see all the period of record information for the sites selected, check this box. You will see detailed information, such as a continuous range of dates served by a site for one or more data types, for example, the begin and end dates that streamflow (parameter 00060) was recorded at a site. Note: if you select any data types for output (see below) the period of record data will also appear. In that case specifying this argument is unnecessary. The default is false. The only legal values for this argument are true and false. Example: ?seriesCatalogOutput=true. ?seriesCatalogOutput=true is equivalent to ?outputDataTypeCd=all. Note: for performance reasons, ?siteOutput=expanded cannot be used if seriesCatalogOutput=true.

Show period of record information about these data types

URL argument name is outputDataTypeCd. This will add period of record information to certain output formats (GML, RDB and JSON) that summarize information about the data types requested. The default is all data types. Some output formats are designed for visual use (Google Earth, Google Maps and Mapper). Consequently with these formats you will not see data type code information.

Default information: If seriesCatalogOutput is true, all period of record information is shown by default. If seriesCatalogOutput is false, unless you override it using one of the values below, no period of record information is shown.

Note: for performance reasons, ?siteOutput=expanded cannot be used if with any values for outputDataTypeCd.

Here are the various output data type codes available. These can be selected individually or can be added as comma separated values if desired. Example: ?outputDataTypeCd=iv,dv 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)
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.
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

Statistics codes

URL argument name is statCd. Statistics codes are values that are calculated for the day and vary by USGS parameter. They typically include mean, minimum and maximum, such as mean (average) streamflow for the day. If you specify a statistics code, it will be used for all USGS parameters, if the statistic exists. Complete list of statistics codes . Up to 20 statistics codes allowed per request. The default is all, which can be specified if desired, ex: &statCd=all.

Range Values

URL argument names used include period, startDt and endDt depending on the type of date retrieval desired. If no date range is specified, the most current values at each site are retrieved. Optionally, you can request a range of values from now (a relative range), or from some start and end date that you specify (an absolute range).

Period (All Values)

URL argument name is period. Use only a positive ISO-8601 duration format . period returns data for a site generally from now to a time in the past. Ex: ?period=P30D goes back thirty days from now to the hour and minute, not to midnight of that day. Note that when period is used all data up to the most recent value is returned if it falls within the requested period range.

Start Date

URL argument name is startDT. It is recommended not to be more precise than a day, since groundwater levels typically do not include the time of day measured. Use the ISO-8601 date format

Example: ?startDT=2010-07-01

With Start Date and End Date you can express an absolute site time period for retrieval. Start Date and End Date values are inclusive. For example, if you specify a Start Date of 2009-06-15 and a reading is available for this date, it will appear in the results.

End Date

URL argument name is endDT. It is recommended not to be more precise than a day, since groundwater levels typically do not include the time of day measured. Use the ISO-8601 date format

Example: ?endDT=2010-07-01

If endDT is not provided with startDT, now is assumed. If a time zone is used, specify it in both the startDT and endDT arguments, otherwise a HTTP 400 error code is returned.

Modified Since

URL argument name is modifiedSince. For any retrieval, you can use this argument to request to return values for all sites only if any any values for any site were changed in the modifiedSince date range. This is useful if you periodically need to poll a site but are only interested in processing data if some of it has changed. Use the ISO-8601 duration format If the modifiedSince argument is not specified in the generated URL, it has no effect on the query.

?stateCd=NY&period=P1D&modifiedSince=PT2H returns values for all sites in NY for the last twenty four hours from now if and only if any values were modified during the last two hours. Otherwise a null set of time-series data are returned.
?stateCd=NY&startDt=2010-09-01&endDt=2010-09-03&modifiedSince=PT2H returns values for all sites in NY with groundwater levels in this date range if and only if any of the values were modified in the last two hours. Otherwise a null set of time-series data are returned.
?stateCd=NY&startDt=2010-09-01&modifiedSince=PT2H returns all the values for all sites in NY from 2010-09-01 up to the most recent value if and only if any of the values in this date range were modified in the last two hours.
?stateCd=NY&modifiedSince=PT2H Since period, startDt or endDt are not used, the latest groundwater levels for all NY real-time sites are retrieved if and only if some values were updated in the last two hours.

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.

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.

Statistics Year Type

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

Site Status

URL argument name is siteStatus. The site status indicates whether the site is active or inactive. 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 (both active and inactive sites). Example: ?siteStatus=active

Site name

URL argument name is siteName. 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. Examaple: &siteName=Boulder%20Creek

Site Name Operator

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

start = The string must be at the start of the site name (default)
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

Example: &siteNameMatchOperator=any

Sites With These Site Types

URL argument name is siteType. You can filter for sites with certain site types. If the siteType argument does not appear in the URL, then by default all site types will be shown. Hold down CTRL/CMD to select more than one site type. The default is all. Note: if you select a major site type (like Stream) you will get its minor site types (canal, ditch and tidal stream) by default even if you do not select them.

Show sites serving these data types

URL argument name is hasDataTypeCd. Default is all. Restricts results to those sites that collect certain kinds of data. Separate values with commas. 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)
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.
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

Example: ?hasDataTypeCd=dv,iv

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 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.

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.

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

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

Current URL Generated

When a major filter and any optional filters have been selected, the generated URL below will give the data based upon the selections above. Be sure to use the best filters possible to reduce the records to only those that you need.

Run generated URL dataRetrieval Code Share

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.

Glacier
Ocean
Coastal
Estuary
Lake
Stream
Canal
Ditch
Tidal stream
Spring
Well
Collector or Ranney type well
Extensometer well
Hyporheic-zone well
Interconnected wells
Multiple wells
Test hole
Other subsurface
Cave
Groundwater drain
Tunnel, shaft, or mine
Unsaturated zone
Wetland
Land
Excavation
Outcrop
Sinkhole
Soil hole
Shore
Facility
Cistern
Combined sewer
Diversion
Field, Orchard, or Nursery
Golf course
Hydroelectric plant
Laboratory or sample-prep area
Landfill
Outfall
Pavement
Septic system
Storm sewer
Thermoelectric plant
Waste-injection well
Wastewater sewer
Wastewater disposal
Wastewater-treatment plant
Water-distribution system
Water-supply treatment plant
Water-use establishment
Aggregate water-use establishment
Aggregate ground-water use
Aggregate surface-water-use

Loading...

Web Service URL Generation Tool

Select Service to Test

Select a Major Filter

Optional Filters

Optional Arguments

Date Ranges

Statistical Controls

Site Filters

Surface Water Attributes

Groundwater Attributes

Current URL Generated

Generated dataRetrieval Code

Share