• 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) exists but they do not serve time-series data
• 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.

• waterml,1.1 is WaterML 1.1, an XML schema approved by the OpenGeospatial Consortium.
• waterml,2.0 is WaterML 2, an XML schema published by the OpenGeospatial Consortium.
• rdb is a self-describing tab-delimited format used widely by the USGS, documented in a PDF file here (Adobe Acrobat Reader)
• json is Javascript Object Notation. WaterML 1.1 will be rendered in a JSON structure as a set of name/value pairs. JSON is excellent for Web 2.0 applications. Note: json is returned with an application/json MIME type which generally has the effect in a browser of being prompted to download and save a file. In actual Web 2.0 usage this should be handled by your Javascript logic.
• Version numbers are optional. The version is actually tied to WaterML, so if you want WaterML 1.1 rendered as JSON, this can be done explicitly using format=json,1.1

• &format=waterml // Latest implemented version of WaterML wanted
• &format=waterml,1.2 // USGS version WaterML version 1.1 (1.2) wanted
• &format=rdb
• &format=rdb,1.0
• &format=json // Latest implemented version of WaterML translated to JSON
• &format=json,1.2

• None, no argument needed

• period must be in ISO-8601 Duration format.
• Negative periods (ex: P-2W) are not allowed
  
• Data are always returned up to the most recent groundwater level if it falls within the requested period range.
• Since groundwater levels tend to be recorded irregularly, it makes little sense to specify a period less than a day.
• Data is returned for a period from now. For example, if it is 8:43 AM and you go back one day, it will look for groundwater levels starting at 8:43:01 AM yesterday.
• Avoid using months (M) and years (Y) for the interval, since these values are non-deterministic. Instead, use days (D) and weeks (W).

&period=P7D (Retrieve groundwater levels that occurred in the last seven days)
&period=P104W (Retrieve groundwater levels that occurred in roughly the last two years.)

• Both startDt and endDt must be in ISO-8601 Date/Time format
• Do not to be more precise than a day, since groundwater levels typically do not include the time of day measured.
• If startDT is supplied and endDT is not, endDT ends with the most recent groundwater level later than the startDt
  
• startDT must be chronologically before endDT
• If endDT is present, startDt must also be present.
  

Use the modifiedSince argument

• The modifiedSince time period always begins with today and moves toward the past. It must be expressed in an ISO-8601 duration format.
• 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.

&stateCd=NY&modifiedSince=P1W - All NY sites with groundwater levels are retrieved only if some groundwater levels were changed in the last week.
&modifiedSince=P10W&startDt=2005-01-01&endDt=2005-12-31 // Retrieve groundwater levels for all sites that had groundwater levels recorded in 2005 if any only if any of the associated sites had any groundwater level measurement changes in the last ten weeks

• Selects sites based on whether or not they are active. 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 (show both active and inactive sites).

• &siteStatus=active

• USGS groundwater level 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.
• Twelve groundwater level parameter codes are currently available using the service:
  1. 00000 (No measurement was taken)
  2. 62610 (Groundwater level above NGVD 1929, feet)
  3. 62611 (Groundwater level above NAVD 1988, feet)
  4. 72019 (Depth to water level, feet below land surface)
  5. 72020 (Elevation above NGVD 1929, feet)
  6. 72150 (Groundwater level relative to Mean Sea Level (MSL), feet)
  7. 72226 (Groundwater level above American Samoa Datum of 1962 (retired in 2001), feet)
  8. 72227 (Groundwater level above American Samoa Vertical Datum of 2002, feet)
  9. 72228 (Groundwater level above Guam Vertical Datum of 1963 (retired in 2003), feet)
  10. 72229 (Groundwater level above Guam Vertical Datum of 2004, feet)
  11. 72230 (Groundwater level above Local Hawaiian Datum, feet)
  12. 72231 (Groundwater level above Northern Marianas Vertical Datum of 2003, feet)

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

• &parameterCd=72019 // depth to water level below land surface
• &parameterCd=72019,72150 // depth to water level below land surface, including local datums
• &variable=72019 // depth to water level below land surface
• &variable=72019,72150 // depth to water level below land surface, including local datums

• Restricts sites to those having one or more major and/or minor groundwater site types. Specifying site types that are not for groundwater, such as stream (ST), while allowed, will simply return no associated sites.
• List of valid site types
• If you request a major site type (ex: &siteType=GW) you will get all sub-site types of the same major type as well (in this case, GW-CR, GW-EX, GW-HZ, GW-IW, GW-MW and GW-TH).

siteType={siteType1,siteType2,...}

• &siteType=GW // Wells only
• &siteType=GW-MW,GW-TH// Multiple wells and test wells only

• The list of sites returned are filtered to return only those with the provided agency code. The agency code describes the organization that maintains the site. Only one agency code is allowed and is optional.
• An authoritative list of agency codes can be found here.

• &stateCd=il&agencyCd=USCE // Only US Army Corps of Engineers sites in Illinois

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

• These arguments allows you to select instantaneous values 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 groundwater levels for sites where the altitude is 12.5 feet or greater and 13 feet or less.

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

• These arguments allows you to select groundwater sites serving data recorded automatically 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 groundwater level sites where the well depth is 100 feet or greater and 500 feet or less.
• &wellDepthMin=10.5&wellDepthMax=10.7 // Return groundwater level 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 serving data recorded automatically 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 groundwater level sites where the hole depth is 100 feet or greater and 500 feet or less.
• &holeDepthMin=10.5&holeDepthMax=10.7 // Return groundwater level sites where the hole depth is 10.5 feet or greater and 10.7 feet 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