USGS Site Web Service

• Using startDT and endDT with the period argument.
• Mixing startDt and endDt arguments where startDt includes a time zone and endDt does not

• The site number(s) are invalid
• The site number(s) are valid but the requested parameter(s) are not served for these sites
• No values exist for the requested date range. For example, a gage might be down for a period of time due to storm damage when it would normally have data.

Used to specify the output format of the data returned.

• rdb is a self-describing tab-delimited format used widely by the USGS, documented in a PDF file here (Adobe Acrobat Reader )
• gm means Google Maps formatted, which is actually encoded in an XML schema called Keyhole Markup Language and optimized for Google Maps. Since the underlying schema is KML, it may work on other map services, like Yahoo Maps. Notes
  • In Google Maps, if you enter the generated URL into the search field and submit the form, the sites should appear.
  • The version of KML is currently 2.2, but 1.0 is accepted as the version number because it is version 1.0 of the USGS's implementation of KML.
• ge means Google Earth formatted, which is actually encoded as an XML schema called Keyhole Markup Language and optimized for Google Earth. Notes:
  • In Google Earth, add the generated URL to Add > Network Link to see the displayed sites. Since the underlying schema is KML, it may work on other map services, like Yahoo Maps.
  • The version of KML is currently 2.2, but 1.0 is accepted as the version number because it is version 1.0 of the USGS's implementation of KML.
• mapper is a simple USGS XML format used by the USGS National Water Information System Mapper.
• Version numbers are optional. If not specified, the most recent implemented version is used by default.

format=[rdb{,1.0} | gm{,1.0) | ge{,1.0} | mapper{,1.0}]

• &format=ge // Latest implemented version of KML for Google Earth
• &format=ge,1.0 // Version 1.0 of the USGS version of KML optimized for Google Earth
• &format=rdb
• &format=rdb,1.0

Indicates the richness of metadata you want for site attributes. Note that for visually oriented formats like Google Map format, this argument has no meaning. Note: for performance reasons, siteOutput=expanded cannot be used if seriesCatalogOutput=true or with any values for outputDataTypeCd.

• basic - provides simple site attributes such as site name, agency, altitude, latitude and longitude.
• expanded - provides a rich set of extended site attributes such as hydrologic unit code, drainage area and site time zone.

siteOutput=[basic | expanded]

• &siteOutput=basic
• &siteOutput=expanded

A switch that provides detailed period of record information for certain output formats. The period of record indicates date ranges for a certain kind of information about a site, for example the start and end dates for a site's daily mean streamflow. Note that for visually oriented formats like the Google Maps format, this argument has no meaning. When true, this is behaves the same as outputDataTypeCd=all. Note: for performance reasons, siteOutput=expanded cannot be used if seriesCatalogOutput=true.

seriesCatalogOutput=true|false

• &seriesCatalogOutput=true

This allows you to specify that you want to output specific kinds of period of record data. The default is all. Note that for visually oriented formats like Google Map format, this argument has no meaning. For example, if you set this argument to just "iv" you will see only period of record information for instantaneous values (time-series data) like stage and discharge time-series measurements. Note: for performance reasons, siteOutput=expanded cannot be used with any values for outputDataTypeCd.

• 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). Note: use of rv does not restrict time-series data to only those with real-time data.
• dv - Daily values (once daily measurements or summarized information for a particular day, such as daily maximum, minimum and mean)
• pk - Peak 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

outputDataTypeCd=[ all | { [iv | uv | rt], dv, pk, sv, gw, qw, id, aw, ad} ]

• &outputDataTypeCd=all
• &outputDataTypeCd=iv
• &outputDataTypeCd=iv,dv,pk

• Selects sites based on whether data was collected at a point in time beginning with the start date (startDt) through the end date (endDt)
• Dates must be whole dates and in an ISO-8601 Calendar Date format
• Should not be used with period
• If endDt is not supplied, now is used.

startDt=[ISO-8601-Calendar-Date ]

• &startDt=1990-01-01
• &startDt=1990-01-01&endDt=1999-12-31

• Selects sites based on whether data was collected at a point in time beginning with the start date (startDt) through the end date (endDt)
• Dates must be whole dates and in an ISO-8601 Calendar Date format
• Should not be used with period
• If startDt is not supplied, all data collection dates are used through and including endDt

endDt=[ISO-8601-Calendar-Date ]

• &endDt=1999-12-31
• &startDt=1990-01-01&endDt=1999-12-31

• Selects sites based on whether or not they were active between now and a time in the past
• Should not be used with startDt or endDt
• Please note that you cannot specify months (M) or years (Y), even though it is allowed by ISO-8601, because the resulting time period is ambiguous.

period=[ISO-8601-Duration ]

• period=P10W // Active in the last ten weeks
• period=PT4H // Active in the last four hours

• Returns only sites and thier metadata where site attributes or period of record data have changed during the requested period. Note this is different than period, which is used to indicate if a site was active for a period in the past.
• The modifiedSince time period always begins with today and moves toward the past. It must be expressed in an ISO-8601 duration format . Please note that you cannot specify months (M) or years (Y), even though it is allowed by ISO-8601, because the resulting time period is ambiguous.
• If the modifiedSince argument is not specified in the generated URL, it has no effect on the query.
• If you request period of record data (&seriesCatalogOutput=true) or specific data types to be output (outputDataTypeCd), the period of record dates will be examined and, if newer, the newest date will be used to indicate if the site was modified. Otherwise, the date a site's attributes were last changed will be used.

modifiedSince=[ISO-8601-Duration ]

• ?stateCd=NY&modifiedSince=P1W - NY sites are retrieved only if any of their site level attributes were changed in the last week.
• ?stateCd=NY&seriesCatalogOutput=true&modifiedSince=P1W NY sites are retrieved only if any of their site level attributes or period of record information were changed in the last week.
• ?stateCd=NY&outputDataTypeCd=all&modifiedSince=P1W NY sites are retrieved only if any of their site level attributes or period of record information were changed in the last week.
• ?stateCd=NY&outputDataTypeCd=iv,dv&modifiedSince=P1W NY sites are retrieved only if any of their site level attributes or period of record information for instantaneous values or daily values were changed in the last week.
• ?stateCd=NY&outputDataTypeCd=iv,dv&hasDataTypeCd=pk&modifiedSince=P1W NY sites are retrieved only if any of their site level attributes or period of record information for instantaneous values or daily values were changed in the last week. However, since this query only shows sites where peaks were measured, the sites have to show peaks and also record instantaneous values and/or daily values. The period of record's last changed date for instantaneous and daily values for these sites are then factored into whether a site's information has changed.

Selects sites based on whether or not they are currently active. Each USGS Water Science Center determines whether a site is active or inactive. The default is all (show both active and inactive sites).

siteStatus=[ all | active | inactive ]

• &siteStatus=active

• Restricts sites to those having one or more major and/or minor site types, such as stream, spring or well.
• List of valid site types
• If you request a major site type (ex: &siteType=ST) you will get all sub-site types of the same major type as well (in this case, ST-CA, ST-DCH and ST-TS)

siteType={siteType1,siteType2,...}

• &siteType=ST // Streams only
• &siteType=ST,LA-OU // Streams and Land Outcrops only

Restricts results to those sites that collect certain kinds of data.

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). Unfortunately, using "rt" may retrieve sites that are not "real-time" because it is simply an alias, e.g. it may show discontinued sites. The closest approximation of a list of real-time sites is to use &siteStatus=active
• 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

The service distinguishes between selecting sites with one or more data types and actually showing those data types in the output. hasDataTypeCd is used for selection. Since the default is to output all data types, this is normally not an issue, but it is possible to use hasDataTypeCd with outputDataTypeCd for unusual types of filters. See the examples below.

hasDataTypeCd=[ all | { [iv | uv | rt], dv, pk, sv, gw, qw, id, aw, ad } ]

• &hasDataTypeCd=all
• &hasDataTypeCd=dv,iv
• &hasDataTypeCd=iv&outputDataTypeCd=pk // Show peak period of record information for instantaneous values sites

• USGS parameter code.
• Returns site data only for those sites containing the requested USGS parameter codes.
• All parameter codes are numeric and 5 characters in length. Parameter codes are used to identify the constituent measured and the units of measure.
• Popular codes include stage (00065), discharge in cubic feet per second (00060) and water temperature in degrees Celsius (00010)
• Complete list of USGS parameter codes

parameterCd|variable={parameterCd1,parameterCd2,...}

• &parameterCd=00060 // discharge, cubic feet per second
• &parameterCd=00060,00065 // discharge, cubic feet per second and gage height in feet
• &variable=00060 // discharge, cubic feet per second
• &variable=00060,00065 // discharge, cubic feet per second and gage height in feet

• The list of sites returned are filtered to return only those for the provided agency code. An agency is the organization operating or funding the collection of data at the site. The agency code describes the organization that maintains the site.
• An authoritative list of agency codes can be found here.
• Note: most sites are USGS maintained, and have an agencyCd of USGS

agencyCd=agencyCd1

• &stateCd=tx&agencyCd=USCE // Only US Army Corps of Engineers sites in Texas

• altMin (alias: altMinVa)
• altMax (alias: altMaxVa)

• These arguments allows you to select sites where the associated sites' altitude are within a desired altitude, expressed in feet. Altitude is based on the datum used at the site.
• Providing a value to altMin (minimum altitude) means you want sites that have or exceed the altMin value
• Providing a value to altMax (maximum altitude) means you want sites that have or are less than the altMax value
• You may specify decimal feet if precision is critical
• If both the altMin and altMax are specified, sites at or between the minimum and maximum altitude are returned

• altMin=minValue
• altMax=maxValue

• &altMin=1000&altMax=5000 // Return sites where the altitude is 1000 feet or greater and 5000 feet or less.
• &altMin=12.5&altMax=13 // Return sites where the altitude is 12.5 feet or greater and 13 feet or less.

• drainAreaMin (alias: drainAreaMinVa)
• drainAreaMax (alias: drainAreaMaxVa)

• 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 or decimal fractions thereof.
• Providing a value to drainAreaMin (minimum drainage area) means you want sites that have or exceed the drainAreaMin value
• Providing a value to drainAreaMax (maximum drainage area) means you want sites that have or are less than the drainAreaMax value
• The values may be expressed in decimals
• If both the drainAreaMin and drainAreaMax are specified, sites at or between the minimum and maximum drainage areas values specified are returned
• Caution: not all sites are associated with a drainage area.
• Caution: drainage area only applies to surface water sites, this should not be used with groundwater sites other than springs.

• drainAreaMin=minValue
• drainAreaMax=maxValue

• &drainAreaMin=1000&drainAreaMax=5000 // Return sites where the drainage area is 1000 square miles or greater and is 5000 square miles or less.
• &drainAreaMin=10.5&drainAreaMax=10.7 // Return sites where the drainage area is 10.5 square miles or greater and is 10.7 square miles or less.

• aquiferCd

• Used to filter sites to those 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 .

• aquiferCd={aquiferCd1,aquiferCd2,...}|all

• &aquiferCd=S500EDRTRN,N100HGHPLN // returns groundwater sites for the Edwards-Trinity aquifer system and the High Plains national aquifers.

• localAquiferCd

• Used to filter sites to those that exist in specified local aquifers. Note: not all sites have been associated with local aquifers.
• Enter one or more local aquifer codes, separated by commas.
• A local aquifer code begins with a 2 character state abbreviation (such as TX for Texas) followed by a colon followed by the 7 character 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 .

• all|localAquiferCd={localAquiferCd1,localAquiferCd2,...}

• &localAquiferCd=AL:111RGLT,AL:111RSDM // returns sites for the Regolith and Saprolite local aquifers in Alabama

• wellDepthMin (alias: wellDepthMinVa)
• wellDepthMax (alias: wellDepthMaxVa)

• These arguments allows you to select groundwater sites where the associated sites' well depth are within a desired depth, expressed in feet from the land surface datum.
• Express well depth as a positive number.
• Providing a value to wellDepthMin (minimum well depth) means you want sites that have or exceed the wellDepthMin value
• Providing a value to wellDepthMax (maximum well depth) means you want sites that have or are less than the wellDepthMax value
• The values may be expressed in decimals
• If both the wellDepthMin and wellDepthMax are specified, sites at or between the minimum and maximum well depth values specified are returned
• wellDepthMax should be greater than or equal to wellDepthMin.
• Caution: well depth applies to groundwater sites only

• wellDepthMin=minValue
• wellDepthMax=maxValue

• &wellDepthMin=100&wellDepthMax=500 // Return daily value sites where the well depth is 100 feet or greater and 500 feet or less.
• &wellDepthMin=10.5&wellDepthMax=10.7 // Return daily value sites where the well depth is 10.5 feet or greater and 10.7 feet or less.

• holeDepthMin (alias: holeDepthMinVa)
• holeDepthMax (alias: holeDepthMaxVa)

• These arguments allows you to select groundwater sites where the associated sites' hole depth are within a desired depth, expressed in feet from the land surface datum.
• Express hole depth as a positive number.
• Providing a value to holeDepthMin (minimum hole depth) means you want sites that have or exceed the holeDepthMin value
• Providing a value to holeDepthMax (maximum hole depth) means you want sites that have or are less than the holeDepthMax value
• The values may be expressed in decimals
• If both the holeDepthMin and holeDepthMax are specified, sites at or between the minimum and maximum hole depth values specified are returned
• holeDepthMax should be greater than or equal to holeDepthMin.
• Caution: hole depth applies to groundwater sites only

• holeDepthMin=minValue
• holeDepthMax=maxValue

• &holeDepthMin=100&holeDepthMax=500 // Return daily values sites where the hole depth is 100 feet or greater and 500 feet or less.
• &holeDepthMin=10.5&holeDepthMax=10.7 // Return daily value sites where the hole depth is 10.5 feet or greater and 10.7 feet or less.