This guide describes how to retrieve time-series data from the CWMS-Data-API (CDA). CDA provides public access to low-risk data that is maintained by USACE. Only time series data are available through this service.

The example script included with this guide is configured for use within an HEC-RTS forecast. When run in that context, it automatically extracts the forecast start and end times from the active forecast. However, the script can be easily modified for use outside of an active HEC-RTS forecast.

This guide is intended to serve as a template demonstrating the general process for retrieving time-series data from USACE. The example script is provided as-is and is not guaranteed to be maintained or updated.

Prerequisites

  • Using HEC-RTS: You must have an HEC-RTS model configured with an active forecast.
  • Outside of HEC-RTS: Ensure the required HEC Python packages are available for import. A convenient way to do this is by installing the HEC-Jython extension from the VS Code Marketplace and running the script through that extension.

Step 1: Review the Script

This is an example script and may not remain up to date. Supported and actively maintained scripts from HEC’s Water Management Systems team are available on HEC's GitHub repository.

  1. Download the example script: getCDA.py
  2. Review the script to understand the overall process used to retrieve time series data from CDA.

Step 2: Identify Time Series IDs (optional)

This step explains how to identify the time series IDs (TS IDs) required to retrieve data from CDA.

The Water Management Data website, also known as Access to Water (A2W), displays all publicly available data accessible through CDA.

  1. Open the A2W website.
  2. Choose either the Locations view or the Map view from the header (this guide uses the Map view).

  3. In Map View, ensure the Other Locations layer is enabled using the layer toggle in the upper-right corner.

    1. If this option is not enabled, only Projects (primarily locks and dams) will be shown.

  4. Zoom in to an appropriate level. Additional locations will not appear at the initial zoom level.
  5. Select a location of interest. A panel will open on the right side of the screen.
  6. Expand the Data Sources and select the parameter of interest under the JSON listing.
  7. In the resulting window, locate the key value. This is used as the TS_ID in the script.

Step 3: Modify the Script for Your Workflow

Several portions of the script can be modified to suit your specific needs.

  1. Update the Office ID.
    1. Change the Office ID (line 496) to match the office of interest.
  2. Modify the Time Series IDs.
    1. Update the TS IDs of interest on lines 499-502 to reference the specific gage(s) and the associated attributes.
  3. Adjust the Basin Name (optional).
    1. Update the basin_name to control the A-Part of the DSS pathname.
  4. Specify a Manual Time Range (optional).
    1. Define a manual start and end time on lines 507 and 508. Be sure to maintain the formatting provided in the script.
  5. Change the Output DSS File (optional).
    1. Modify the DSS file path on line 510 to control where the data is saved. 
  6. Save Automatically to the HEC-RTS forecast.dss File (optional). 
    1. To automatically save data to the forecast.dss file within HEC-RTS, remove the comment on line 475.

Step 4: Test the Script

You should now test the script outside of an active HEC-RTS forecast. This is useful for validating that the script can successfully retried data from CDA and write it to a DSS file.

The instructions below assume you are using VS Code with the HEC-Jython Extension, as described in the prerequisites. 

  1. Add a comment indicator (#) to the following line: 

    1. Line 492: # begin_date,end_date, dss_file_path = RtsParameters()

  2. Remove the comment indicator (#) from the following lines:

    1. Line 507: begin_date = "2025-01-01T00:00:00"

    2. Line 508: end_date = "2026-01-15T00:00:00"
    3. Line 510: dss_file_path = "C:/temp/cwms_data.dss"
  3. The updated script should now look something like this:
  4. Run the script in VS Code. 
  5. Once the script completes, open the DSS file to verify that it ran successfully.  
    1. By default, the output file will be C:/temp/cwms_data.dss.
  6. If the DSS file contains populated time series data for the expected pathnames, the script is functioning as intended.

Step 5: Prepare the Script for HEC-RTS Execution

Now that the script has been successfully tested outside of HEC-RTS, a few updates are required to enable it to run within an active HEC-RTS forecast.

  1. Remove the comment indicator (#) from the following line: 

    1. Line 492: begin_date,end_date, dss_file_path = RtsParameters()

  2. Add a comment indicator (#) to the following lines:

    1. Line 507: # begin_date = "2025-01-01T00:00:00"

    2. Line 508: # end_date = "2026-01-15T00:00:00"
    3. Line 510: # dss_file_path = "C:/temp/cwms_data.dss"

You are now ready to run the script from HEC-RTS.