The National Ground-Water Monitoring Network (NGWMN) is a compilation of selected groundwater monitoring wells from Federal, State, and local groundwater monitoring networks across the nation. In addition to providing access to these groundwater data from multiple, dispersed databases through a web-based mapping application, the data is accessible via web services. Web service requests may be submitted to obtain data directly and to bypass the NGWMN map interface. Currently only basic site information and water levels are available through web service requests. For full site information, lithology, construction information or water quality data visit the NGWMN Data Portal. For more information on the NGWMN Data Portal, see the User Guide.

Submitting a Web Service Request

The NGWMN web services follow the OGC Sensor Observation Service (SOS) specification and may be queried using a REST (REpresentational State Transfer) technique. This method may be used to retrieve water levels or basic site data. The basic building blocks for querying the services are outlined in the following series of tables. Most non-alphanumeric characters (such as punctuation) must be "url-encoded", (for example: space is "%20").

The request type and parameters must be appended to the base Uniform Resource Locator (URL) for the REST NGWMN web service (http://cida.usgs.gov/ngwmn_cache/sos?). There are three request options, which each offer a different type of data and have different options for query parameters.

Table 1. URL-encoded request and offering, descriptions for NGWMN web service

Construct a REST web service query by concatenating the base URL with the desired request type (Table 1), parameters and arguments (Tables 2-4). At least one parameter-argument pair must be specified. Separate multiple parameter-argument pairs with an ampersand ("&"). Unneeded web service parameters may be omitted. If no mime type is specified, the retrieval will default to WQX-XML format. Station and Result retrieval data elements are output in a consistent format and nomenclature. See the User Guide for a list of elements included in the station and result retrievals.

Service Request = [Base URL]?request=[Request]&[Parameter]={argument}

Table 2. URL-encoded retrieval parameters and arguments for NGWMN web service GetCapabilities request

Table 3. URL-encoded retrieval parameters and arguments for NGWMN web service GetObservation request

Table 4. URL-encoded retrieval parameters and arguments for NGWMN web service GetFeatureOfInterest request

Web Service Request Examples

SOS GetCapabilities:https://cida.usgs.gov/ngwmn_cache/sos?request=GetCapabilities&service=SOS&acceptVersions=2.0.0&acceptedFormats=text/xml

SOS GetObservation by FID:https://cida.usgs.gov/ngwmn_cache/sos?request=GetObservation&service=SOS&version=2.0.0&observedProperty=urn:ogc:def:property:OGC:GroundWaterLevel&responseFormat=text/xml&featureOfInterest=VW_GWDP_GEOSERVER.USGS.403836085374401

SOS GetFeatureOfInterest by FID:https://cida.usgs.gov/ngwmn_cache/sos?request=GetFeatureOfInterest&service=SOS&version=2.0.0&featureOfInterest=VW_GWDP_GEOSERVER.USGS.403836085374401

SOS GetFeatureOfInterest by BBOX:https://cida.usgs.gov/ngwmn_cache/sos?request=GetFeatureOfInterest&service=SOS&version=2.0.0&bbox=30,-99,31,102&srsName=urn:ogc:def:crs:EPSG::4269

HTTPS-Only on the NGWMN Data Portal

USGS-hosted websites, which included the NGWMN Data Portal, switched to the secure and encrypted HTTPS protocol in December, 2016. For most users, the changes won't be noticeable other than a visual change in web browsers indicating a private connection. But users who write or maintain software that uses USGS web services could be impacted and should read on for details.

After this switch, requests for USGS web resources using the HTTP protocol will receive one of the 3xx Redirection HTTP status codes indicating an equivalent HTTPS URL. Software that receives this response likely falls into one of these categories:

1. No change required. Many underlying software libraries transparently process redirects and switch to the HTTPS protocol with no required programming changes. The additional redirect will reduce performance slightly, however, so an optimization would be changing all USGS URLs to HTTPS.

2. Does not follow redirects automatically, change required. Some software libraries may report redirects as errors instead of following them. For this, change all USGS URLs to HTTPS, or alter the software to follow the redirect response.

3. Supports HTTPS only with additional configuration, change required. Underlying software libraries might require additional configuration, installed modules, or invocation options to support HTTPS.

4. Does not support HTTPS, potentially major change required. Some software libraries, particularly older ones, might not be capable of supporting HTTPS. For this, alternate libraries can be sought or the software can be ported to another language or platform that supports HTTPS.

Software developers may test a software library's redirect and HTTPS support by retrieving an arbitrary web resource, including this URL that generates a 3xx redirect to an HTTPS URL: http://https.cio.gov/. The NGWMN Data Portal's Web Services already support HTTPS, and you can make the change to you scripts today. If you have issues, please contact us at  gwdp_help@usgs.gov.

This conversion is part of a federal-government-wide effort observing that "the American people expect government websites to be secure and their interactions with those websites to be private."