Live USGS Water Services Agent

<< Click to Display Table of Contents >>

Navigation:  Live > Agents > Web API Agents > Web API Open Data >

Live USGS Water Services Agent

The USGS (United States Geological Survey) Water Services Agent is a data loading agent available in EQuIS Live for obtaining water data from the following USGS Water Services web APIs:

Instantaneous Values

Daily Values

Groundwater Levels


Adding Station


Before using the USGS Water Services Agent, add one or more sites to the DT_LOGGER table:

1.Execute the equis.get_ids stored procedure to get a new LOGGER_ID, or add the site (DT_LOGGER row) in EQuIS Professional.

2.Set LIVE_DATA_SOURCE to USGS-WS-IV to get Instantaneous Values, USGS-WS-DV to get Daily Values, or USGS-WS-GW to get Groundwater Levels.

3.Set LOGGER_CODE to a site number (e.g., 01646502 for the Potomac River, near Washington, D.C. site). You can search for a site here or here.


Note: You can view a site's info, including its available data, by clicking on its site link. For example, go to, where 01646502 is a USGS site number, zero-padded to 8 digits.


4.Set STATUS_FLAG to 'A' to activate the logger.


Loading Data


The USGS Water Services Instantaneous Values Agent, Daily Values Agent, Groundwater Levels Agent or Historical Data Loader can be run as a scheduled EQuIS Information Agent (EIA), at the desired frequency, to automatically load data as often as needed.


The USGS Water Services Agents or Historical Data Loader can also be run in EQuIS Professional or Enterprise (using the EZView widget) to load the data manually, without having to schedule an EIA.


The USGS Water Services Instantaneous Values, Daily Values, and Groundwater Levels Agents will load values for all loggers with LIVE_DATA_SOURCE set to USGS-WS-IV, USGS-WS-DV and USGS-WS-GW, respectively.


When the report is run initially, the agent will retrieve values from a logger's site (DT_LOGGER.LOGGER_CODE) for the past one month. If data has been previously loaded for that logger, the agent will request data from the logger's most recent date (in DT_LOGGER_DATUM.DATUM_UTC_DT) until today's date.


The USGS Water Services Historical Data Loader allows you to select the (IV, DV, and/or GW) loggers and date range. It has the following input parameters:

Logger(s) Select the sites for which to load data. If no sites are selected, the agent will load data for all USGS Water Services sites.

Date Range – Select a date range; choose from recent, period, or start and end dates. The recent option works the same way as the USGS Water Services Instantaneous Values, Daily Values, and Groundwater Levels Agents. If the period option is selected, a period must be specified in ISO-8601 duration format. If the start and end dates option is selected, start and end dates must be specified.

Parameter Codes – Data for a subset of parameter codes can be loaded by adding them here (as a comma-separated string, e.g. 60,65). Leave this field empty to get all available parameter codes.

Update existing values? – Check this box to update existing EQuIS Live data values.

Max Period Per Request – When requesting a large date range from the web API, it may take a long time to return the data, causing the request to timeout, and, if it encounters an error, it may not return any data at all.  Use this parameter to break up one request into multiple requests, each of this period, in ISO-8601 duration format (e.g.. P12M requests up to 12 months of data at a time).


A series can be activated or deactivated, by setting its STATUS_FLAG = "A" or "R", to start or stop (respectively) obtaining data for it. A series' SERIES_DESC may be changed, but not the SERIES_NAME and SERIES_UNIT; they uniquely identify the series using the parameter names and units from the USGS Water Services API.