FAQ

Frequently Asked Questions

General 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

How can I get notified of changes to this system?

There are two ways:

Subscribe to the site's news feed to learn when new features are released.
For general news, site outage information etc. news on USGS water services is also sent to email subscribers via the USGS Water Data Notification Service . This is a better method if you want to know what will be coming up. New services may be open to public testing prior to deployment, in which case your testing may prove important to the quality and usability of new services.

How do I find out if I am being blocked?

You should see a HTTP 403 Access Forbidden error.

Why am I being blocked?

Blocking access to a service should only occur if the USGS believes that your use of the service is so excessive that it is seriously impacting others using the service.

How do I get unblocked?

To get unblocked, send us the URL you are using along with the 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.

Do you have guidelines for acceptable usage?

For small requests (e.g., up to 7 or 14 days for a single site) limit requests to a maximum of 5-10 per second at a steady rate. A maximum burst rate of to 40 or 50 request per second is OK, but not for extended periods of time.

My scripts time out. Is your service running slowly?

Possibly. It could also be that the client you are using is not configured to handle redirects. In this case, there are two approaches to handle redirect:

Fully qualify the URL by adding a / before the ? in the URL, ex: http://waterservices.usgs.gov/nwis/iv/?format=waterml,1.1&sites=01646500 rather than http://waterservices.usgs.gov/nwis/iv?format=waterml,1.1&sites=01646500.
Configure your client, if it has the feature, to automatically follow HTTP 301 redirects. For example, if you use curl add the --location or -L option.

How does this site relate to the USGS Water Data for the Nation site (waterdata.usgs.gov)?

This site complements the USGS Water Data for the Nation site. The data are identical between the two sites. The USGS Water Data for the Nation site is designed for browsing and human ad-hoc inquiries of USGS water data. This site is designed to accommodate those interested in acquiring data to frequent machine processing. All services are designed for high availability, fast response and to support modern output formats.

How much traffic does this site receive?

Site web traffic varies from month to month but growth has been strong. In a typical month, fifteen to 20 million requests are made to USGS water services. The site typically ranks second in the rankings of most trafficked USGS web sites tracked within the USGS National Web infrastructure.

Which services are most popular?

Using October 2012-September 2013 as a baseline, 86% of traffic was for the instantaneous values web service, 8% for the daily values web service, 5% for the site service and 1% for the groundwater levels service. It is not surprising that real-time data would be of the most interest.

What are the motivations for this site?

The site serves these major purposes:

It eases the acquisition of approved and provisional data from the USGS National Water Information System for the millions of users of USGS water data. The USGS hopes that this will spur both internal and external communities to use the data for any intended usage by allowing it to be easily acquired from a reliable, trusted and highly available source.
It allows the USGS Water Data for the Nation site to evolve. Over time, the USGS Water Data for the Nation site will be overhauled. It will use the same web services available to anyone to acquire its data. In the long run it will make that system easier to maintain and retrofit for new uses.

Instantaneous Values Service

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

Site Service

How do I retrieve just real-time sites?: Real-time sites are USGS hydrologic sites that regularly transmit automated measurements and observations. Currently there is no perfect mechanism for retrieving real-time sites. In particular &hasDataTypeCd=rt will not return only real-time sites, since rt is an alias for instantaneous values (iv). The National Water Information System Mapper uses an approach that shows "active" sites. However, active sites have different meanings depending on whether they serve automated (time-series) data or are regularly visited by humans for collecting data manually (discrete data). For real-time sites, users are usually interested in automated record stations. Thus combining this with a list of "active" sites that have been operational over a recent time period helps flag those sites that recorded traffic recently. This is close to being a list of current real-time sites. For example, to retrieve all active sites for Rhode Island in a Google Maps format that have recorded observations in the last week, use: http://waterservices.usgs.gov/nwis/site/?format=mapper&stateCd=ri&period=P1W&outputDataTypeCd=iv.
Is this service available as a Web Feature service?: Not yet. The USGS will offer a web feature service in 2014 or 2015, funding permitting. Stay tuned for an announcement.
How do I integrate your site service with commercial mapping services, like Google Maps?: For other mapping services, consult their application programming interfaces (APIs). Most mapping applications can map geographic data in a Keyhole Markup Language (KML) format. Using &format=ge for Google Earth and &format=gm for Google Maps will probably work with Yahoo, Microsoft and other public mapping services because they are KML-friendly.
What is a period of record?: This is the time period that the site was actively maintained and used. Ideally, it is a period of contiguous time to the present, but sites may be discontinued for a while due to lack of funding or are seasonally affected by the weather. Note that sites where discrete (manual) measurements were made are not "active" in the traditional sense, unless automated equipment is collocated at the site. However they do represent dates when data was collected at the site. A site's period of record may be further refined to show periods of record for different data types, for example a time range for collecting daily values and discrete water quality measurements.
How do I use the service to determine a list of sites that were removed?: Data collected at a site is always maintained as a matter of record. Sometimes a site is removed from public display. Unfortunately, there is no way to get a list of these sites from the service other than to keep your own copy and compare changes. Note that the modifiedSince argument effectively only shows new sites and sites where site information has changed.
What new features are planned for the site service?: Aside from the web feature service, which is likely to be a separate service, the following improvements are anticipated: Excel 2007 output, search by site name, polygons of enclosed sites, and minimum bounding rectangles. These features are expected in 2014 or 2015.

Daily Values Service

What new features are planned for the daily values service?: Likely new features include: Excel 2007 output, Google Earth and Google Map (KML) output, WaterML 2.0 output and search by site name.
Will WaterML 2.0 be supported?: The USGS hopes to support an OGC-compliant Sensor Observation Service in 2014 or 2015, which will be able to serve daily values.

Groundwater Levels Service

Why does the service support WaterML 1.2 when there is no version 1.2 of WaterML?: WaterML is used to describe time-series water data. The groundwater levels service provides discrete (manual) measurements, which can be considered irregular instead of regular time series measurements. To accommodate the difference, a slight change was made to the WaterML 1.1 schema. This USGS revision is referenced by placing the schema in the USGS namespace only.
Where can I find automated groundwater measurements?: These are available in the instantaneous values web service. Search on common groundwater parameters such as 72019 (depth of water below land surface). Currently these are limited to data served since October 1, 2007. Older groundwater 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.

Statistics Web Service

Why is only tab-delimited (RDB) format available?: The USGS is starting with a commonly used internal format for serving statistical data for this service. Schemas need to be created to represent statistical water data in XML and JSON. When these are completed they will be integrated into the service.
Why are there no statistics served for discrete sites?: Discrete sites are those where human (manual) measurements are made. However, to generate a statistic it must be based on looking at many values over a time period. Automated time-series sites perform this function, making statistics like minimum, maximum and mean easy to calculate. Months or years may go by before a human visits the site to take a manual measurement. Consequently, a site must serve daily values for statistics to be generated.
Why are provisional data not included in statistics?: Provisional data, as the name implies, is subject to change. USGS hydrologists frequently change provisional data, for example to remove aberrant spikes or to estimate flow when a site is ice affected. After these changes, the data are marked as approved and statistics can be calculated from these values. Since some values will be incorrect or missing if marked provisional, statistics based on provisional data will be misleading, so they are not allowed.
Why are there no statistics for a period because only a few daily values are missing?: To be faithful to the intent of a statistic, it should be calculated based on a complete set of values. For example, a monthly statistics for a given month and year should be based on accurate daily values for all days in the month for the year. Consequently, if there is not a complete record of daily values for that month, statistics for that month are not served. However, the service allows this to be overridden by supplying the missingData argument.
How are statistics calculated? Are they rounded? What rules apply?: See this topic in the USGS Water Data for the Nation help system.

Questions?

If you have any questions, contact us.