REST Web Services

USGS Groundwater Levels Web Service

You can use this service to retrieve historical manually-recorded groundwater levels from hydrologic sites served by the USGS. If you are looking to retrieve data for real-time or recent groundwater levels recorded with automated equipment on a regular basis, please use the instantaneous values web service.

This service provides USGS groundwater data in WaterML, the legacy RDB (tab-delimited) format, and in a Web 2.0 friendly JSON format (which renders WaterML as JSON). The data in the service is identical to data available from the USGS Water Data for the Nation site .

Please join the USGS Water Data for the Nation Notification List . This way you will receive an announcement when changes are made to this web service, or if it there are significant problems with the service.

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 information about one or more sites in one request

With millions of groundwater levels collected at sites across the nation, 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 at the same time. 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. When you have perfected your query you can copy and paste the URL into your application to get the precise data you need.

Test the service now

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.

Interpreting the Output

WaterML

When using format=waterml (the default format), data are returned in XML using the WaterML 1.1 schema . WaterML is a schema that has recently been adopted by the Open Geospatial Consortium . The crucial data are the groundwater level values, which can be found inside the <value> tag. Example:

<ns1:values>
  <ns1:value dateTime="1968-08-28T00:00:00.000" sourceCode="D">145</ns1:value>
  <ns1:value dateTime="1980-09-16T00:00:00.000" sourceCode="D">311.5</ns1:value>
  <ns1:method methodID="1"/>
</ns1:values>

Please also note that the values found for this site are associated with the variable node that precedes it. The variable node indicates the parameter that is being measured or calculated. In this case, both the <ns1:values> and <ns1:variable> nodes are nested within the <ns1:timeSeries> node.

<ns1:variable ns1:oid="52331280">
  <ns1:variableCode network="NWIS" vocabulary="NWIS:UnitValues" default="true" variableID="52331280">72019</ns1:variableCode>
  <ns1:variableName>Depth to water level, ft below land surface</ns1:variableName>
  <ns1:variableDescription>Depth to water level, feet below land surface</ns1:variableDescription>
  <ns1:valueType>Derived Value</ns1:valueType>
  <ns1:unit>
    <ns1:unitCode>ft</ns1:unitCode>
  </ns1:unit>
  <ns1:options>
    <ns1:option name="Statistic" optionCode="00011"/>
  </ns1:options>
  <ns1:noDataValue>-999999.0</ns1:noDataValue>
</ns1:variable>

Putting it altogether, this means that for this site, two manual groundwater level measurements were recorded: 145 feet below the surface of the land on August 28, 1968 and 311.5 feet below the surface of the land on September 16, 1980.

The option code of 00011 indicates the type of statistics code that was measured. For groundwater levels, the statistics code of 00011 will typically be used, as it represents discrete manual measurements. A list of statistics codes can be found here .

With other output formats, the location of the data will depend on the syntax of the format. You will need to inspect the format to locate the relevant data.

Note: the current version of WaterML is 1.1. WaterML 1.2 is an unofficial variant created by the USGS needed to accommodate the discrete data provided by this service, and is referenced in a USGS name space.

Tab-delimited (RDB)

Returning tab delimited data provides the same data is a more succinct format. A partial excerpt is shown:

# ---------------------------------- WARNING ----------------------------------------
# The data you have obtained from this automated U.S. Geological Survey database
# have not received Director's approval and as such are provisional and subject to
# revision. The data are released on the condition that neither the USGS nor the
# United States Government may be held liable for any damages resulting from its use.
# Additional info: http://waterdata.usgs.gov/nwis/help/?provisional
#
# File-format description: http://waterdata.usgs.gov/nwis/?tab_delimited_format_info
# Automated-retrieval info: http://waterdata.usgs.gov/nwis/?automated_retrieval_info
#
# Contact:   gs-w_waterdata_support@usgs.gov
# retrieved: 2012-02-27 14:05:09 EST (nwisvatestws01)
#
# US Geological Survey groundwater levels
#
# Data for the following 1 site(s) are contained in this file
#    USGS 375907091432201 Rolla Industrial Park
# -----------------------------------------------------------------------------------
#
# The fields in this file include:
# ---------------------------------
# agency_cd     Agency Code
# site_no       USGS site number
# site_tp_cd    Site Type Code
# lev_dt        Date level measured
# lev_tm        Time level measured
# lev_tz_cd     Time datum
# lev_va        Water level value in feet below land surface
# sl_lev_va     Water level value in feet above specific vertical datum
# sl_datum_cd   Referenced vertical datum
# lev_status_cd The status of the site at the time the water level was measured
# lev_agency_cd The agency code of the person measuring the water level
#
# Discrete groundwater status codes (lev_status_cd) included in this output:
#
#     ""         The reported water-level measurement represents a static level
#
# Agency codes (lev_agency_cd) included in this output:
#
#     MO005      MO DIV OF GEOL & LAND SURVEY, DEPT-NAT RESO, MO
#     USGS       US GEOLOGICAL SURVEY
#
# Referenced vertical datum codes (sl_datum_cd) included in this output:
#
#
#
# Site Type Codes (site_tp_cd) included in this output:
#
#     GW         Well
#
agency_cd site_no site_tp_cd lev_dt lev_tm lev_tz_cd lev_va sl_lev_va sl_datum_cd lev_status_cd lev_agency_cd
5s 15s 6s 10d 4d 5s 12s 12s 10s 1s 5s
USGS 375907091432201 GW 1968-08-28 145 MO005
USGS 375907091432201 GW 1980-09-16 311.5 USGS

Tab-delimited output does not indicate which USGS parameter code is associated with the measurements. This is true on the USGS Water Data for the Nation site as well. WaterML requires an associated <variable> tag with a measurement. To accommodate this request, the USGS assigns these data an appropriate USGS parameter code to the output, which is typically 72019.

Error codes

Since this system uses Hypertext Transfer Protocol (HTTP), any application errors are reported in the HTTP headers, which are normally not seen. This means that when writing applications, when you get a response 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: Using startDT and endDT with the period argument. Mixing startDt and endDt arguments where startDt includes a time zone and endDt does not
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: 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.
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.

Service Documentation

URL Format
Specifying the URL Arguments
URL argument conventions
Major Filters
- Single Site Queries
- Multiple Site Queries
  - by Site Number or Site Numbers (site or sites)
  - by State or Territory (stateCd)
  - by Hydrologic Unit Code or Watershed (huc)
  - by Latitude/Longitude Box (bBox)
  - by County (countyCd)
Outputs
- Format (format)
Minor Filters
- Specifying Date Ranges
  - Latest Groundwater Levels
  - From now (period)
  - From a start date (startDt)
  - From an end date (endDt)
  - Any groundwater levels were changed from now (modifiedSince)
- Site Status (siteStatus)
- Parameter Code (parameterCd)
- Groundwater Site Type (siteType)
- Agency Code (agencyCd)
- Altitude (altMin and altMax)
- Well Depth (wellDepthMin and wellDepthMax)
- Hole Depth (holdDepthMin and holeDepthMax)
- Aquifer Code (aquiferCd)
- Local Aquifer Code (localAquiferCd)

URL Format

The URL must always be in this format:

http://waterservices.usgs.gov/nwis/gwlevels?<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 arguments that go 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.
URL arguments are separated by ampersands (&)
The order of the URL arguments does not matter
If a URL argument name does not match one of the names below, a HTTP 400 error is triggered.

Here is an example of a valid URL that should return data:

http://waterservices.usgs.gov/nwis/gwlevels?sites=375907091432201

URL argument names and URL 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:

http://waterservices.usgs.gov/nwis/gwlevels?stateCd=ny
http://waterservices.usgs.gov/nwis/gwlevels?statecd=ny
http://waterservices.usgs.gov/nwis/gwlevels?STATECD=ny
http://waterservices.usgs.gov/nwis/gwlevels?stateCd=NY
http://waterservices.usgs.gov/nwis/gwlevels?STATECD=NY
http://waterservices.usgs.gov/nwis/gwlevels?stateCd=Ny

URL argument conventions

The following conventions are used below to document URL argument values:

arg1=[ a {,x | ,y} | b | c,d,...]

square brackets [] are used to show a set of possible choices, with the pipe symbol | 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
arg1=e,f

Major Filters

A major filter is required to ensure fair access to the service. It prevents any one user from downloading all data in a single call, thus allowing others to share the service at the same time with minimal processing delays.

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:

http://waterservices.usgs.gov/nwis/gwlevels?site=375907091432201

Multiple Site Queries

Every multiple site query requires a major filter. Pick the major filter (sites, stateCd, huc, bBox, or countyCd) that best retrieves the data for the sites that you are interested in.
You can have more than one major filter per query. However, you cannot replicate a particular major filter in the query. The effect is an AND, reducing the results returned. Ex: &stateCd=nh&huc=01060003 returns sites in New Hampshire for Piscataqua-Salmon Falls.
Further refine the query with minor filters, if needed.

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. For this service, the site number needs to be a groundwater site number, which is typically 15 characters. You can specify unlimited number of sites, up to the limit supported by the client, the application server and the HTTP GET protocol. Site numbers 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	Unlimited (see caveats)	&site=375907091432201 &sites=USGS:375907091432201 &sites=375907091432201,360425089485001
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 aggregated watersheds. Only 1 major HUC (2-digits) can be specified per request. Up to 10 minor HUCs may be specified. A major HUC has two digits. Minor HUCs must be eight digits in length. Caution: not all sites have been associated with a HUC. List of HUCs.	1	1 Major, 10 Minor	&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.	1	20	&countyCd=51059,51061

Outputs

Format (format)

URL Argument Name	format
Description	Used to specify the output format of the data returned. waterml (default) is WaterML 1.2 , an XML schema published by the CUAHSI. Note: the current version of WaterML is 1.1. 1.2 contains a slight modification by the USGS needed to accommodate the discrete data provided by this service, and is referenced in a USGS name space. 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 . The current version of WaterML will be rendered in a JSON structure as a set of name/value pairs. JSON is excellent for Web 2.0 applications. However, use JSON with caution as name/value pairs will change automatically when the default version of WaterML is upgraded. 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.
Syntax	format=[waterml{,1.2} \| waterml,2.0 \| rdb{,1.0} \| json{,1.2}]
Default	waterml
Minimum argument values required	1
Maximum argument values allowed	1
Examples	&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

Minor Filters

Minor filters further reduce the set of expected results and are applied after data is first filtered by the major filter you specified. You are encouraged to use minor filters to minimize the amount of data sent.

Specifying Date Ranges

I want to...	Do this...	Syntax Rules	Examples
Get the latest manually recorded groundwater level only for a site	Nothing. Only the latest manually recorded groundwater level is returned by default for each requested site and parameter.	None, no argument needed	&stateCd=ny // Get the latest groundwater levels (excluding those recorded by automated means) for all sites in New York state
Get a range of groundwater levels from now	Specify the period argument	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.)
Get a range of groundwater levels from an explicit begin or end date/time	Use the startDT and endDT arguments	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.	&startDT=2000-01-01&endDT=2009-12-31 // All groundwater levels for a decade &startDt=2010-11-22&endDT=2010-11-22 // Full day, from 00:00 to 23:59 site local time
Get groundwater levels for all applicable sites where any groundwater levels were changed or added during a given period from now	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

Site Status (siteStatus)

URL Argument Name	siteStatus
Description	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).
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	&siteStatus=active

Parameter Code (parameterCd)

URL Argument Name	parameterCd (aliases: variable, parameterCds, variables, var, vars, parmCd)
Description	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: 00000 (No measurement was taken) 62610 (Groundwater level above NGVD 1929, feet) 62611 (Groundwater level above NAVD 1988, feet) 72019 (Depth to water level, feet below land surface) 72020 (Elevation above NGVD 1929, feet) 72150 (Groundwater level relative to Mean Sea Level (MSL), feet) 72226 (Groundwater level above American Samoa Datum of 1962 (retired in 2001), feet) 72227 (Groundwater level above American Samoa Vertical Datum of 2002, feet) 72228 (Groundwater level above Guam Vertical Datum of 1963 (retired in 2003), feet) 72229 (Groundwater level above Guam Vertical Datum of 2004, feet) 72230 (Groundwater level above Local Hawaiian Datum, feet) 72231 (Groundwater level above Northern Marianas Vertical Datum of 2003, feet)
Syntax	parameterCd\|variable={parameterCd1,parameterCd2,...}
Default	returns all groundwater parameters for the requested sites
Minimum argument values required	1
Maximum argument values allowed	100
Examples	&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

Groundwater Site Type (siteType)

URL Argument Name	siteType (aliases: siteTypes, siteTypeCd, siteTypeCds)
Description	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).
Syntax	siteType={siteType1,siteType2,...}
Default	All site types are returned
Minimum argument values required	1
Maximum argument values allowed	No limit
Examples	&siteType=GW // Wells only &siteType=GW-MW,GW-TH// Multiple wells and test wells only

Agency Code (agencyCd)

URL Argument Name	agencyCd (alias:agencyCds)
Description	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 agency code of USGS
Syntax	agencyCd=agencyCd1
Default	All sites regardless of agency code are retrieved
Minimum argument values required	1
Maximum argument values allowed	1
Examples	&stateCd=tx&agencyCd=USCE // Only US Army Corps of Engineers sites in Texas

Altitude (altMin and altMax)

URL Argument Name	altMin (alias: altMinVa) altMax (alias: altMaxVa)
Description	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
Syntax	altMin=minValue altMax=maxValue
Default	All sites are retrieved, regardless of their altitude
Minimum argument values required	1
Maximum argument values allowed	1
Examples	&altMin=1000&altMax=5000 // Return groundwater levels for 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.

Well Depth (wellDepthMin and wellDepthMax)

URL Argument Names	wellDepthMin (alias: wellDepthMinVa) wellDepthMax (alias: wellDepthMaxVa)
Description	These arguments allows you to select groundwater level sites where the associated sites' well depths 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
Syntax	wellDepthMin=minValue wellDepthMax=maxValue
Default	All sites are retrieved, regardless of their well depth
Minimum argument values required	1
Maximum argument values allowed	1
Examples	&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.

Hole Depth (holeDepthMin and holeDepthMax)

URL Argument Names	holeDepthMin (alias: holeDepthMinVa) holeDepthMax (alias: holeDepthMaxVa)
Description	These arguments allows you to select groundwater level sites where the associated sites' hole depths 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
Syntax	holeDepthMin=minValue holeDepthMax=maxValue
Default	All sites are retrieved, regardless of their hole depth
Minimum argument values required	1
Maximum argument values allowed	1
Examples	&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.

Aquifer Code (aquiferCd)

URL Argument Names	aquiferCd
Description	Used to filter groundwater sites to those that exist in specified national aquifers. Note: not all groundwater 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 .
Syntax	aquiferCd={aquiferCd1,aquiferCd2,...}\|all
Default	all
Minimum argument values required	0
Maximum argument values allowed	1000
Examples	&aquiferCd=S500EDRTRN,N100HGHPLN // returns groundwater sites for the Edwards-Trinity aquifer system and the High Plains national aquifers.

Local Aquifer Code (localAquiferCd)

URL Argument Names	localAquiferCd
Description	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 .
Syntax	all\|localAquiferCd={localAquiferCd1,localAquiferCd2,...}
Default	all
Minimum argument values required	0
Maximum argument values allowed	1000
Examples	&localAquiferCd=AL:111RGLT,AL:111RSDM // returns sites for the Regolith and Saprolite local aquifers in Alabama

Examples

PHP Example

Here is a simple example using the popular PHP scripting language that retrieves all manually recorded groundwater levels recorded in Broome County, New York during 2011. PHP is popular on web servers for serving dynamic content. It may be useful in understanding how to access the service and traverse XML trees but should not be used as a "best practice" way of retrieving data.

Select all code

<?php

// Example script that returns the groundwater level measurements in Broome County, New York during 2011.
// Uses the services documented at http://waterdata.usgs.gov
// Written by Mark D. Hamill, mdhamill@usgs.gov, 15 February 2012
//
// Note: this is a simple example only. The USGS recommends tools such as curl and wget to retrieve data.

$url = 'http://waterservices.usgs.gov/nwis/gwlevels?countyCd=36005&startDT=2011-01-01&endDT=2011-12-31';

// Fetch the data.
$data = file_get_contents($url);
if (!$data)
{
 	echo 'Error retrieving: ' . $url;
 	exit;
}

// Remove the namespace prefix for easier parsing
$data = str_replace('ns1:','', $data);

// Load the XML returned into an object for easy parsing
$xml_tree = simplexml_load_string($data);
if ($xml_tree === FALSE)
{
 	echo 'Unable to parse USGS\'s XML';
 	exit;
}

// The page should not refetch the data more than every day, since groundwater levels change infrequently
$offset = 3600 * 24;
// Calculate the string in GMT not localtime and add the offset
$expire = "Expires: " . gmdate("D, d M Y H:i:s", time() + $offset) . " GMT";
Header($expire);

?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
<title>Groundwater levels recorded in Broome County, New York in 2011</title>
<style type="text/css">
	th {background-color:#CCCCCC;}
</style>
</head>
<body>
<h1>Groundwater levels recorded in Broome County, New York in 2011</h1>
<p>Retrieved at <?php echo date('H:i:s \o\n M j, Y', time());?></p>
<table border="1">
<tr>
	<th id="c1">Site Number</th>
	<th id="c2">Site Name</th>
	<th id="c3">Site Latitude</th>
	<th id="c4">Site Longitude</th>
	<th id="c5">Measurement<br />Date & Time</th>
	<th id="c6">Groundwater Level<br />ft. below land surface</th>
</tr>
<?php
foreach ($xml_tree->timeSeries as $gw_data)
{

	$first_row = true;

	foreach($gw_data->values->value as $gw_level)
	{
		if ($gw_level['dateTime'] == '')
		{
			$date = '-';
		}
		else
		{
			$date = substr($gw_level['dateTime'],0,10) . ' ' . substr($gw_level['dateTime'],11,5);
		}

		if ($gw_level == '')
		{
			$value = '-';
		}
		else if ($gw_level == -999999)
		{
			$value = 'UNKNOWN';
		}
		else
		{
			$value = number_format((float) $gw_level, 2);
		}

		echo "<tr>\n";
		if ($first_row)
		{
			printf("<td headers=\"c1\" rowspan=\"%s\" style=\"text-align:center; vertical-align:top;\">%s</td>\n", $gw_data->values->value->count(), $gw_data->sourceInfo->siteCode);
			printf("<td headers=\"c2\" rowspan=\"%s\" style=\"text-align:center; vertical-align:top;\">%s</td>\n", $gw_data->values->value->count(), $gw_data->sourceInfo->siteName);
			printf("<td headers=\"c3\" rowspan=\"%s\" style=\"text-align:center; vertical-align:top;\">%s</td>\n", $gw_data->values->value->count(), $gw_data->sourceInfo->geoLocation->geogLocation->latitude);
			printf("<td headers=\"c4\" rowspan=\"%s\" style=\"text-align:center; vertical-align:top;\">%s</td>\n", $gw_data->values->value->count(), $gw_data->sourceInfo->geoLocation->geogLocation->longitude);
			$first_row = false;
		}
		printf("<td headers=\"c5\" style=\"text-align:center;\">%s</td>\n", $date);
		printf("<td headers=\"c6\" style=\"text-align:right;\">%s</td>\n", $value);
		echo "</tr>\n";
	}

}
?>
</table>
</body>
</html>

Feedback

Please provide any feedback you have on this service using this form.