TSTool / Command / ReadNrcsAwdb

Overview
Command Editor
Command Syntax
Examples
Troubleshooting
See Also

Overview

The ReadNrcsAwdb command reads one or more time series from the Natural Resources Conservation Service (NRCS) Air and Water Database (AWDB) web service (see the NRCS AWDB Datastore Appendix), including SNOTEL and Snow Course data and other data. Data from other sources is available within the NRCS naming convention.

As of TSTool 15.3.0, the NrcsAwdb datastore configuration included with TSTool uses the REST API and the NrcsAwdbSoap datastore uses the older SOAP API. Prior to version 15.3.0, the NrcsAwdb datastore used the SOAP API. The SOAP API will be decommissioned by the NRCS in the future and features will be removed from TSTool.

The NRCS AWDB web service allows station lists to be filtered, both as a convenience and to ensure reasonable web service performance. Many of the choices that are available for limiting queries allow 0+ values to be provided. For example, specifying no requested element (data type) will return all available elements for a location. Specifying a list of elements (separated by commas) will return only stations and time series that have data for the requested elements.

Command Editor

The command is available in the following TSTool menu:

Commands / Read Time Series

The following dialog is used to edit the command and illustrates the syntax for general parameters.

Some choices are provided as a convenience. However, full listing of choices (such as all the thousands of HUCs) are not provided due to performance issues. Additional query features such as cascading choices may be enabled as web service integration is enhanced.
Querying many time series can be slow. It is recommended that filters be used to constrain the query, and then modify to converge on an appropriate set of filters for optimal performance.

ReadNrcsAwdb Command Editor for General Parameters (see full-size image)

The following figure illustrates the Reservoirs tab of the dialog. No additional parameters are provided; however, the notes explain that reservoir data are available only from the BOR network and appropriate network element codes must be selected.

ReadNrcsAwdb Command Editor for Reservoir Query Parameters (see full-size image)

The following figure illustrates the Forecasts tab of the dialog. Forecasts are available for several element codes but mainly SRVO (stream volume, adjusted). Because it is possible to read normal time series and forecasts, the ReadForecast parameter is provided to specifically indicate that a forecast is being requested. The forecast is uniquely identified by the forecast period and publication date (typically the first day of a month).

ReadNrcsAwdb Command Editor for Forecast Query Parameters (see full-size image)

The resulting forecast table, as shown in the following figure, includes all the relevant information about the forecast. Use table processing commands to filter the table for a specific station and publication date.

ReadNrcsAwdb Command Output Forecast Table (REST API) (see full-size image)

The table for the SOAP API uses CalculationDate instead of IssueDate.

ReadNrcsAwdb Command Output Forecast Table (SOAP API) (see full-size image)

The following illustrates new command parameters that are available for the REST API, which are being evaluated.

ReadNrcsAwdb Command Editor for REST API Query Parameters (see full-size image)

Command Syntax

The command syntax is as follows:

ReadNrcsAwdb(Parameter="Value",...)

Command Parameters

Tab	Parameter	Description	Default
*All (top)*	`DataStore` required	The NRCS AWDB datastore to use for queries.	None – must be specified.
	`Interval` required	The data interval (“duration” in NRCS AWDB terms) to query. The Irregular interval is used for instantaneous data.	None – must be specified.
*Stations*	`Stations`	A list of station identifiers to read, separated by commas.	Do not limit the query to a station list.
	`States`	A list of state codes (e.g., `AL`), separated by commas.	Do not limit the query to a state list.
	`Networks`	A list of data network codes (e.g., `SNTL`), separated by commas.	Do not limit the query to a network list.
	`StationTriplets`	A list of station triplets of the form `StationId:StateAbbrev:Network`, separated by commas, where each part can use `*` wild card.	Do not limit the query to a station triplet list.
	`StationNames`	A list of station names of the form `StationId:StateAbbrev:Network`, separated by commas, where each part can use `*` wild card.	Do not limit the query using a station name list.
	`HUCs`	A list of 8-digit hydrologic unit codes, separated by commas.	Do not limit the query to a HUC list.
	`BoundingBox`	A bounding box consisting of west longitude, south latitude, east longitude, and north latitude, separated by spaces. Longitudes in the western hemisphere are negative. This feature is not finalized, pending resolution of a web service issue.	Do not limit the query to a bounding box.
	`Counties`	A list of county names, separated by commas. The state must be specified because county names are not unique.	Do not limit the query to a county list.
*Reservoirs*		No parameters are currently provided.
*Forecasts*	`ReadForecast`	Indicate whether a forecast table should be read.	`False` (read observed time series)
	`ForecastTableID`	The identifier for the output table.	`NRCS_Forecasts`
	`ForecastPeriod`	The forecast period for a forecast, which is a string like `JAN-MAR`. A list of choices is provided; however, only certain forecast periods will be valid for specific element codes.	Must be specified when `ReadForecast=True`.
	`ForecastPublicationDateStart`	The earliest publication date for a forecast, needed to uniquely identify the time series.	All publication dates are queried.
	`ForecastPublicationDateEnd`	The latest publication date for a forecast.	All publication dates are queried.
*REST API*	`InsertOrUpdateBeginDate`	The date from which to return inserted or updated data, used to query modified data.
	`PeriodRef`	Indicate whether the data for data values should be at the `START` of the output interval or the `END`. For example, for monthly data, `Janary 1` is the start and `January 31` is the end of data for January. For water year data, using `END` ensures that the end is the last day of the water year and will therefore be the correct year.	`END`
	`ActiveOnly`	Indicate that only active stations are returned. Specify as `True` or `False`.	`True`
	`ReturnOriginalValues`	Indicate whether calculated and derived values are allowed to be returned. Specify as `True` or `False`.	`False` (allow calculated values to be returned)
	`ReturnSuspectData`	Indicate whether suspect data values are returned. Specify as `True` or `False`.	`False` (return approved values)
*All (bottom)*	`Elements`	Data element codes for the stations (e.g., `WTEQ` for snow water equivalent), separated by commas.	All available elements are returned.
	`ElevationMin`	Minimum station elevation, feet.	Do not limit the query based on elevation minimum.
	`ElevationMax`	Maximum station elevation, feet.	Do not limit the query based on elevation maximum.
	`InputStart`	The start of the period to read data – specify if the period should be different from the global query period. Specify to the precision of the data using the format `YYYY-MM-DD hh:mm`. The time corresponds to station local time and is passed to the API as the begin time.	Use the global query period.
	`InputEnd`	The end of the period to read data – specify if the period should be different from the global query period. Specify to the precision of the data using the format `YYYY-MM-DD hh:mm`. The time corresponds to station local time and is passed to the API as the end time.	Use the global query period. If the end from NRCS AWDB is `2100-01-01`, the current time for the computer will be used (specify directly if necessary if the station is in a different time zone than the computer).
	`OutputYearType`	The year type for year interval time series, either `CalenderYear` or `WaterYear` (October 1 to September 30).	`CalendarYear`
	`TimeZoneMap`	Indicate how to map the NRCS AWDB time zone to the output time series. This is a simple time zone assignment, with no adjustment of date/time numerical values. The `stationDataTimeZone` data value from station metadata indicates the time zone for time series data. For SOAP API and SNOTEL, this is typically `8.0` and for REST API and SNOTEL, this is typically -8 (equivalent to Pacific Standard Time), regardless of station location, although other stations may use different time zone.	Specify the time zone map as: `NrcsZone1:ZoneToUse1, NrcsZone2:ZoneToUse2` for example: `-8:GMT-08:00`.
	`Alias` required	The alias to assign to the time series, as a literal string or using the special formatting characters listed by the command editor. The alias is a short identifier used by other commands to locate time series for processing, as an alternative to the time series identifier (`TSID`).	None – must be specified.

Examples

See the automated tests.

Troubleshooting

See the main TSTool Troubleshooting documentation.