Download PDF
Download page USGS Streamflow Importer.
USGS Streamflow Importer
The USGS Time Series Importer queries the USGS Water Data API for monitoring locations within a user-defined spatial and temporal extent, then imports the selected time series data into HEC-DSS files for use in HEC-HMS.
he USGS Streamflow Importer is launched from the Tools | Data | Gage | USGS Import menu in HEC-HMS.
A project must be open to access the USGS Streamflow Importer.
Query Dialog
The query dialog is the main interface for searching USGS monitoring locations.
Parameter (1)
Select the hydrologic parameter to query:
- Flow — streamflow discharge
- Stage — water surface elevation
Spatial Bounds (2)
Define the geographic area to search for monitoring locations. Two options are available:
- Basin Model — select a spatial basin model from the dropdown. Only basin models with 2D subbasin geometry are listed. The query returns monitoring locations that fall within the basin boundary.
- Shapefile — browse to a shapefile (.shp) on disk. The query returns monitoring locations that fall within the shapefile geometry.
The selected geometry is used for precise spatial filtering. The USGS API receives the bounding envelope of the geometry, and results are then filtered client-side to include only locations that fall within the actual geometry boundary.
If no spatial basin models exist in the project, the Basin Model option is disabled and the Shapefile option is selected automatically.
Time Bounds (3)
Specify the date and time range for the query:
- Start Date — format: dMMMYYYY (e.g., 1Jan2000)
- Start Time — format: HH:mm (e.g., 00:00)
- End Date — format: dMMMYYYY (e.g., 31Dec2020)
- End Time — format: HH:mm (e.g., 23:59)
The time bounds can also be set from a Control Specification by clicking the calendar button to the right of the time bounds panel.
The query finds monitoring locations with data that overlaps the specified time range. A location is included if any portion of its data record falls within the query window.
Frequency (4)
Select the data collection frequency:
- Daily — daily mean values
- Continuous — instantaneous values at sub-daily intervals
API Key (5)
An optional USGS API key for authenticated access. Authenticated requests may have higher rate limits. The API key is cached between sessions. Leave blank for anonymous access.
See: https://api.waterdata.usgs.gov/signup/
Query Button (6)
Click Query to execute the search. A progress dialog appears while the query runs. The query performs the following steps:
- Loads the selected geometry (basin model or shapefile)
- Queries the USGS API for time series metadata within the geometry's bounding envelope
- Fetches monitoring location details (coordinates, names)
- Filters locations to only those within the precise geometry boundary
Results Table (7)
The results table displays monitoring locations returned by the query:
| Column | Description |
|---|---|
| Import | Checkbox to select sites for import. The header checkbox selects or deselects all sites. |
| Site ID | USGS monitoring location identifier (e.g., USGS-10310000) |
| Site Name | Name of the monitoring location |
| Start Time | Effective start time of data available for import, clamped to the query start time if the data begins earlier |
| End Time | Effective end time of data available for import, clamped to the query end time if the data ends later |
Column headers are greyed out until a valid query returns results. Columns are sortable by clicking the header (except the Import checkbox column).
Import Button (8)
Click Import... to proceed with importing the selected sites. At least one site must be selected. This opens the Import Options dialog.
Import Options Dialog
The import options dialog configures how each selected site's data is written to HEC-DSS and registered as a time series gage.
Import Table (9)
Each row represents one monitoring location selected for import:
| Column | Description | Editable |
|---|---|---|
| Site ID | USGS monitoring location identifier | No |
| Part A | DSS A-part (project or area identifier) | Yes |
| Part B | DSS B-part (location identifier). Defaults to the site name. | Yes |
| Part C | DSS C-part (parameter type). Set automatically based on the query parameter. | No |
| Part F | DSS F-part (version descriptor). Defaults to "USGS". | Yes |
| Time Zone | Time zone for the imported data. Defaults to UTC. A dropdown lists UTC and the gage's local time zones. | Yes |
| Time Series Gage | Name of the time series gage to create or update in the project. | Yes |
| HEC-DSS File | Path to the HEC-DSS file for storing the imported data. Editable only if the gage does not already exist. | Conditional |
Import Button (10)
Click Import to begin downloading and writing data. A progress dialog shows the status of each site as it is imported. The import performs the following steps for each site:
- Requests time series values from the USGS API
- Converts the data to a time series container
- Writes the data to the specified HEC-DSS file
- Creates or updates the time series gage in the project
- Sets gage metadata (description, latitude, longitude, station ID) if not already defined
Overwrite
For HEC-DSS files and records that already exist, data will be overwritten without warning!
Error Handling
If the USGS API returns an error (e.g., the requested time range exceeds the API limit), the error message is displayed in the progress dialog and the progress bar stops. Sites that return no data are reported as warnings. Sites that fail to write are collected and redisplayed in the table for retry.