This is the multi-page printable view of this section. Click here to print.
Instantaneous Values
1 - Intantaneous Values Frequently Asked Questions
Are new services planned? If so what will they be?
A number of new web services are being considered. In 2014, the USGS hopes to deploy an OGC-compliant Sensor Observation Service. A water quality web service is also on the planning radar for 2015 or later. Reference list web services (returning metadata information, such as a list of counties for a state) will be introduced piecemeal as needed to support projects. All such changes will be announced via the USGS Water Data Notification Service External Link.
What new features are likely to be developed for this service?
The development of a new Sensor Observation Service (SOS) in 2014 will serve equivalent data in a more “geo-friendly” format. The same data will be available via the SOS as is served by this service, with data served in the WaterML 2 format. Support for Excel output are planned for FY13 or FY14 for this service.
Will WaterML 2.0 be supported?
Yes, it will be supported by a Sensor Observation Service to be deployed in 2014 or 2015 and also by this service in 2014.
Where can I find older historical instantaneous values?
Currently values are supported from October 1, 2007 forward. Most historical streamflow data is available through the Instantaneous Data Archive External Link. Other data may be available through an inquiry with the local USGS water science center by writing gs-w-xx_nwisweb_data_inquiries@usgs.gov where xx is the state postal code (such as “ny”) of interest.
2 - Instantaneous Values Service Details
Instantaneous Values Service
You can use this service to retrieve recent and historical values for streamflow as well as data for other regular time-series parameters served by the USGS. This service provides these USGS water data in Extensible Markup Language (XML), Javascript Object Notation (JSON) and the legacy RDB (tab-delimited) format currently available from the USGS Water Data for the Nation site . More media types will follow.
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 recent water readings for one or more sites in one request
- Data from October 1, 2007 to the present can be returned with one request. However, certain operational data that is not quality assured (this typically includes temperature and precipitation) is limited to 120 days or less by the local USGS water science center responsible for the data.
With thousands of sites monitored across the nation, and with the majority of these sites having measurements for more than one type of data, the amount of data available is very large. No one user is allowed to download all of the data with a single call. The service has consequently been designed and engineered to facilitate common mass queries, defaulting to returning a narrower set of data. You are encouraged to make your queries efficient too, mindful that many others need access to the data. 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.
Enabling gzip compression
Typically data is downloaded as plain text via Hypertext Transfer Protocol (HTTP). However, gzip compression
is supported by this service. Use of gzip compression may markedly speed up acquisition of data, particularly on large queries. It also is a more efficient use of USGS servers, so we appreciate when you are thoughtful enough to use it. Whether you can receive the data in gzip compressed formats depends on the capabilities of your client. Web browsers support gzip compression natively, but most regular users will use specialized utility programs like wget
and curl
to acquire data. If you can handle gzip compression, please place the following string into your HTTP request headers: Accept-Encoding: gzip, compress
curl and wget are typically used to download data. They may be configured to use gzip compression if the server will accept it. You may also explicitly have to tell it to use gzip compression. If so these tips should work:
- curl: try adding the argument:
-H 'Accept-Encoding: gzip,deflate'
- wget: try adding the argument:
--header="Accept-Encoding: gzip"
gzip files are typically returned as a file with a .gz file suffix unless you instruct your program to uncompress it. See the gzip man page for instructions on uncompressing .gz files.
Output
Please note that most recent data are marked provisional, so these data should be interpreted with caution as it is possible (although unlikely) to be incorrect. See the USGS Provisional Data Disclaimer page for more information.
Error codes
Since this system uses Hypertext Transfer Protocol (HTTP), any application errors are reported in the HTTP headers. This means that when writing applications, it is important to first examine the HTTP status code that is returned in the HTTP response. The application server will return the error code along with a message describing the error in the event there is a problem. Programmers should always check the HTTP response code and if not a 200 handle the response as an exception. Among the status codes you may see:
HTTP Error 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:
|
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:
|
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/iv/?<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 content that goes 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.
- Arguments are separated by ampersands (&)
- The order of the arguments in the URL does not matter.
- If a URL argument name does not match one of the names below, it is ignored.
Here is an example of a valid URL that should return data:
https://waterservices.usgs.gov/nwis/iv/?sites=01646500¶meterCd=00060,00065
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:
- https://waterservices.usgs.gov/nwis/iv/?stateCd=ny
- https://waterservices.usgs.gov/nwis/iv/?statecd=ny
- https://waterservices.usgs.gov/nwis/iv/?STATECD=ny
- https://waterservices.usgs.gov/nwis/iv/?stateCd=NY
- https://waterservices.usgs.gov/nwis/iv/?STATECD=NY
- https://waterservices.usgs.gov/nwis/iv/?stateCd=Ny
Argument conventions
The following conventions are used below to document argument values:
arg1=[ a {,x | ,y} | b | c,d,...]
- square brackets
[]
are used to show a set of possible choices, with|
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
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:
Multiple Site Queries
- Every query requires a major filter. Pick the major filter (
sites
,stateCd
,huc
,bBox
,counties
) that best retrieves the data for the sites that you are interested in. - You can have only one major filter per query. If you specify more than one major filter, you will get an error.
Major Filter (select one of the following) | Meaning | Minimum Number of Argument Values | Maximum Number of Argument Values | Examples |
---|---|---|---|---|
sites (aliases: site, location) | A list of site numbers. You can specify up to 100 sites. 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. | 1 | 100 | &site=01646500 &sites=USGS:01646500 &sites=01646500,06306300 |
stateCd (alias: stateCds) | U.S. postal service (2-digit) state code. USPS List of State Codes. | 1 | 1 | &stateCd=NY |
huc (alias: hucs) | A list of hydrologic unit codes (HUC) or watersheds. Only 1 major HUC can be specified per request. A major HUC has two digits. Minor HUCs must be eight digits in length. List of HUCs. | 1 | 10 | &huc=01,02070010 |
bBox | A contiguous range of decimal latitude and longitude, starting with the west longitude, then the south latitude, then the east longitude, and then the north latitude with each value separated by a comma. The product of the range of latitude and longitude cannot exceed 25 degrees. Whole or decimal degrees must be specified, up to six digits of precision. Minutes and seconds are not allowed. Remember: western longitude (which includes almost all of the United States) is specified in negative degrees. Caution: many sites outside the continental US do not have latitude and longitude referenced to NAD83 and therefore can not be found using these arguments. Certain sites are not associated with latitude and longitude due to homeland security concerns and cannot be found using this filter. | 1 | 1 | &bBox=-83,36.5,-81,38.5 |
countyCd (alias: countyCds) | A list of county numbers, in a 5 digit numeric format. The first two digits of a county's code are the FIPS State Code. List of county codes. Some updates were made to the FIPS code standards in 2021. NIST has provided replacement standards. | 1 | 20 | &countyCd=51059,51061 |
Outputs
Format
URL Argument Name | format |
---|---|
Description | Used to specify the output format of the data returned.
|
Syntax | format=[rdb{,1.0} | json{,1.1}] |
Minimum argument values required | 1 |
Maximum argument values allowed | 1 |
Examples |
|
Indent (indent)
URL Argument Name | deta |
---|---|
Description | Used to specify whether block structured data formats (&format=waterml|json only) should include indentation for easy viewing. Four space characters are inserted for every level of indentation. Otherwise the parameter is ignored. |
Syntax | indent=[on|off] |
Default | off |
Minimum argument values required | 1 |
Maximum argument values allowed | 1 |
Examples |
|
Specifying Date Ranges
Data going back as far as October 1, 2007 are available for each site. You typically do not need all this data, so you generally express a range of dates needed. Here is how to limit the amount of values you receive:
I want to... | Do this... | Syntax Rules | Examples |
---|---|---|---|
Get the latest values only | Nothing. Only the latest value is returned by default for each requested site and parameter. |
| &stateCd=ny¶meterCd=00060 // Get the latest discharge values for all time-series sites in New York state |
Get a range of values from now | Specify the period argument |
| &period=PT2H (Retrieve last two hours from now up to most recent instantaneous value) &period=P7D (Retrieve last seven days up from now to most recent instantaneous value) |
Get a range of values from an explicit begin or end date/time | Use the startDT and endDT arguments |
| &startDT=2010-11-22&endDT=2010-11-22 // Full day, from 00:00 to 23:59 &startDT=2010-11-22T12:00&endDT=2010-11-22T18:00 &startDT=2010-11-22&endDT=2010-11-22 &startDT=2010-11-22T12:00 // Ends with most recent instantaneous value |
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.
Parameter Code (parameterCd)
URL Argument Name | parameterCd (aliases: variable, parameterCds, variables, var, vars, parmCd) |
---|---|
Description |
|
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 |
|
Site Type (siteType)
URL Argument Name | siteType (aliases: siteTypes, siteTypeCd, siteTypeCds) |
---|---|
Description |
|
Syntax | siteType={siteType1,siteType2,...} |
Default | All site types are returned |
Minimum argument values required | 1 |
Maximum argument values allowed | No limit |
Examples |
|
Site was modified since (modifiedSince)
URL Argument Name | modifiedSince |
---|---|
Description |
|
Syntax | modifiedSince=ISO-8601-duration |
Default | None |
Minimum argument values required | 1 |
Maximum argument values allowed | 1 |
Examples |
|
Agency Code (agencyCd)
URL Argument Name | agencyCd |
---|---|
Description |
|
Syntax | agencyCd=agencyCd1 |
Default | All sites regardless of agency code are retrieved |
Minimum argument values required | 1 |
Maximum argument values allowed | 1 |
Examples |
|
Site Status (siteStatus)
URL Argument Name | siteStatus |
---|---|
Description |
|
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 |
|
Altitude (altMin and altMax)
URL Argument Name |
|
---|---|
Description |
|
Syntax |
|
Default | All sites are retrieved, regardless of their altitude |
Minimum argument values required | 1 |
Maximum argument values allowed | 1 |
Examples |
|
Surface water filters
Drainage Area (drainAreaMin and drainAreaMax)
URL Argument Names |
|
---|---|
Description |
|
Syntax |
|
Default | All sites are retrieved, regardless of their drainage area |
Minimum argument values required | 1 |
Maximum argument values allowed | 1 |
Examples |
|
Groundwater Filters
Aquifer Code (aquiferCd)
URL Argument Names |
|
---|---|
Description |
|
Syntax |
|
Default | all |
Minimum argument values required | 0 |
Maximum argument values allowed | 1000 |
Examples |
|
Local Aquifer Code (localAquiferCd)
URL Argument Names |
|
---|---|
Description |
|
Syntax |
|
Default | all |
Minimum argument values required | 0 |
Maximum argument values allowed | 1000 |
Examples |
|
Well Depth (wellDepthMin and wellDepthMax)
URL Argument Names |
|
---|---|
Description |
|
Syntax |
|
Default | All sites are retrieved, regardless of their well depth |
Minimum argument values required | 1 |
Maximum argument values allowed | 1 |
Examples |
|
Hole Depth (holeDepthMin and holeDepthMax)
URL Argument Names |
|
---|---|
Description |
|
Syntax |
|
Default | All sites are retrieved, regardless of their hole depth |
Minimum argument values required | 1 |
Maximum argument values allowed | 1 |
Examples |
|
Feedback
Please provide any feedback you have on this service using this form .