HydroForecast Time Series API (v2)

HydroForecast Time Series API (v2) is available and adds a significant amount of functionality over v1. It now allows:

• Retrieving any forecast (HydroForecast Short-term, Seasonal, and the underlying weather forecasts) and observation series (satellite, snow, cleaned flow observations and more)
• Retrieving any available forecast issue time, and multiple in a single request
• Performing time aggregations
• Converting rates to volumes
• Accessing data from multiple sites within the same request

The easiest way to construct queries is to use HydroForecast Dashboard. To do so, change any options on a given plot and then select "View API v2 queries" from the plot title dropdown:

This will then show the exact underlying forecast and observation queries made to construct the plot.

If you have questions about how to construct a specific query, send a message to team@hydroforecast.com and we'd be happy to help.

Retrieve Forecasts: api/v2/timeseries/forecasts

This API route returns a list of one or more forecasts matching each query. Both weather and flow forecasts are available.

There are a few methods of selecting the forecast issue times to retrieve:

• Providing a time range with issueTimeStartDate (inclusive) and issueTimeEndDate (exclusive). This is ideal for paging through an archive of forecasts.
• Providing issueTimeAfterDate to retrieve only forecasts issued since a certain time. This is supports regularly syncing the latest forecasts into your database.
• Providing a list timestamps with issueTimes to select specific forecast issues times.

Retrieve Observations: api/v2/timeseries/observations

This API route provides a time series of observations matching each query.

When this route is used with a weather forecast source it returns a time series created by joining the first N hours of each weather forecast in the requested date range. For example, if the forecast is issued every 6 hours it will join the first 6 hours of each forecast. 

Example Usage

Python

import json
import requests  # Requests library to make HTTP calls. `pip install requests`

url = "https://api.upstream.tech/api/v2/timeseries/forecasts"
api_key = "API-Key"
data = {
    "queries": [{
        "columns": ["discharge_q0.05", "discharge_q0.95", "discharge_q0.25", "discharge_q0.75", "discharge_mean"],
        "siteId": "example-site-id",
        "source": "hydroforecast-seasonal",
        "unitSystem": "US",
        "timeAggregation": "10D",
        "ratesToVolumes": "false",
        "issueTimes": ["2022-12-29T00:00:00.000Z"]
    }]
}

response = requests.post(url, data=json.dumps(data), headers={"Authorization": api_key})

if response.status_code != 200:
  raise RuntimeError(f'{response.text} Status code: {response.status_code}')
else:
  print(response.json())