USGS - science for a changing world

REST Web Services

USGS Instantaneous Values REST Web Service URL Generation Tool

This tool provides a simple way to generate syntactically correct URLs to use with the USGS Instantaneous Values 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. 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 Filters:Show or hide major filter help

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

(or just a single site)



Show or hide site help
You can use either site or sites for the URL argument name. sites corresponds to one or more site numbers containing time-series data. Separate sites with commas. Any number of sites can be specified, up to the limits of your browser, the HTTP GET protocol and the capabilities of the USGS's appication 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. For time-series streamflow sites, the site number is normally 8 characters. Site numbers range from 8 to 15 character. To find sites of interest, we suggest using the NWIS Mapper External Link. Make sure you search for time-series sites only.
Show or hide state help
URL argument name is stateCd. You may select no more than one state or territory. Example: ?stateCd=ny
Show or hide HUC help
URL argument name is huc. You can specify one major Hydrologic Unit code and up to 10 minor Hydrologic Unit codes. Separate HUCs with commas. For performance reasons, no more than one major HUC (a two digit code) is allowed. A minor HUCs must be 8 digits long. 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: Show or hide Latitude/Longitude help

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, but only six decimals of precision will be used. 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.






Show or hide county help
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 number (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. Reference.

OPTIONAL ARGUMENTS:
Show or hide format help
URL argument name is format. Select the output format desired. Most formats have yet to be developed. Graphical formats are available only with single site retrievals. If there is no format argument in the generated URL, WaterML 2.0 is now defaulted. WaterML 1.1 is deprecated. Example: &format=waterml.

The version of the format wanted, if available, can be appended using the syntax: &format=<format_type>,<version_number>. The version number is optional. 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. See the warning on JSON before using this format.
Show or hide indent help

URL argument name is indent. Used to specify whether block structured data formats (&format=waterml 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.
Date Range:Show or hide date range help
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 value at each site is retrieved. Optionally, you can request a range of values from now (a relative range), or from some start and end date/time that you specify (an absolute range). Currently, data since October 1, 2007 are available. If no date range is specified, only the most current values are returned. Note that only data since October 1, 2007 are available, so queries beyond this date will not work.


Show or hide period help
URL argument name is period. Use only a positive ISO-8601 duration format External Link. period returns data for a site generally from now to a time in the past. Bear in mind that there is latency between when a value is recorded at the site and when it appears on the web, typically 0-4 hours. For format examples, click here External Link, ex: &period=P2D goes back two days from now, &period=PT4H goes back four hours from now, &period=P2DT2H (or &period=PT50H) goes back 50 hours and &period=P1DT22H (or &period=PT46H) goes back 46 hours from now. For performance reasons, with multi-site retrievals you may retrieve data since October 1, 2007 only. Note that when period is used all data up to the most recent value is returned. In the case of a predictive gage, you may get predicted values in the future.
Show or hide Start Date help
URL argument name is startDT. Use the ISO-8601 date format External Link.

Examples: &startDT=2010-07-01T12:00 (site local time), &startDT=2010-07-01T12:00-05:00 (Eastern Standard Time), &startDT=2010-07-01T12:00Z (Universal Time) or startDT=2010-07-01. If you do not specify an hour, T00:00 for the start date is assumed.

A + timezone offset must be coded as %2B in the URL. The TestTool here will do this automatically for you.
Example: To indicate T15:00+01:00 Use &startdt=2015-05-01T15:00%2B01:00.

With Start Date and End Date you can express an absolute site time period for retrieval. Real time data typically lag 0-4 hours behind the current time. Start Date and End Date values are inclusive. For example, if you specify a Start Date of 2009-06-15T22:15 and a reading is available for this time, it will appear in the results. For multi-site retrievals, only data since October 1, 2007 are available.
Show or hide End Date help
URL argument name is endDT. Use the ISO-8601 date format External Link.

Examples: &endDT=2010-07-01T18:00 (site local time), &endDT=2010-07-01T18:00-05:00 (Eastern Standard Time), &endDT=2010-07-01T18:00Z (Universal Time) or endDT=2010-07-01. If you do not specify an hour, &endDT=T23:59 for the end date is assumed. 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.

A + timezone offset must be coded as %2B in the URL. The TestTool here will do this automatically for you.
Example: To indicate T15:00+01:00 Use &startdt=2015-05-01T15:00%2B01:00.
Show or hide Modified Since help

URL argument name is modifiedSince. For any retrieval, you can use this argument to request to return values for those sites only if any the values 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 External Link. If the modifiedSince argument is not specified in the generated URL, it has no effect on the query.

Partial URL examples:

  • ?stateCd=NY&period=P1D&modifiedSince=PT2H returns all values for sites and period of record requested for 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 all values for sites and period of record requested for sites in NY for 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 values for sites and period of record requested for 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, all values for sites and period of record requested for NY time-series sites are retrieved only if some values were updated in the last two hours.

Show or hide parameter code help
URL argument names are variable or parameterCd. In this case, parameterCd means a USGS parameter, not a URL parameter. Either can be used equivalently. If parameterCd or variable is not specified in the generated URL, all time-series parameters are returned for the site(s) of interest. If parameterCd or variable is used, only data for those parameter codes are returned. To specify more than one parameter code, separate with commas, ex: &variable=00060,00065. Most typical time-series parameter codes include 00065 = gage height (ft.), 00060 = streamflow (cu ft/sec) and 00010 = water temperature in degrees Celsius. Complete list of parameter codes External Link. Please note that even common parameters like gage height and discharge are not served by all time-series sites. There is a limit of 100 parameter codes allowed per request.

Show or hide site type help
URL argument name is siteType. You can filter for just 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. 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 or hide agency code help
URL argument name is agencyCd. You can filter to show only sites with a specific agency code. For example, ?stateCd=il&agencyCd=USCE would return sites in Illinois for the U.S. Army Corps of Engineers only. Only one agencyCd is allowed. 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 External Link.
Show or hide aquifer code help
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.
Show or hide local aquifer help
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.
Show or hide parameter code help
URL argument name is siteStatus. The site status indicates whether the site is active or inactive. 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.

Example: &siteStatus=active
Show or hide altitude help
URL argument names are altMin and altMax. Enter the minimum and/or maximum altitude in feet for the sites you want retrieved. 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.

Surface Water Site Attributes:
Show or hide drainage area help

URL argument names are drainAreaMin and drainAreaMax. The values should be in whole numbers only. 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. 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 Site Attributes:
Show or hide well depth help
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. 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
Show or hide well depth help
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. 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

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.

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