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())