Get Forecasts API Route
GET /forecasts/<siteId>
GET /api/v1/forecasts/<siteId> URL Parameter * siteId - The site identifier for your site of interest provided to you by the HydroForecast team. Query Parameters * type - The forecast type, one of "short-term" or "seasonal". Required. * startDate - Retrieve forecasts where forecastDate >= startDate. Optional. * endDate - Retrieve forecasts where forecastDate < endDate. Optional. * updatedSince - Filter forecasts where updatedAt > updatedSince. Optional. * sort - Order forecasts by forecastDate. Value must be one of "asc" or "desc". Optional, defaults to "asc". * format - The format of the response. Value must be one of "json" or "csv". Optional, defaults to "json". * page - The page of results to retrieve. Optional, defaults to 1. * perPage - The number of forecasts to return in each page. Optional, defaults to 25 and limited to a maximum of 25. Dates should be formatted as ISO 8601 date strings including a timezone offset. For example, 2021-01-01T01:23:45-08:00 or 2021-01-01T00:00:00Z.
Example JSON response:
{ "page": 1, "hasNextPage": true, "data": { "siteId": "example-site", "type": "short-term", # or "seasonal" "units": "cms" # or "cfs" "forecasts": [ { "forecastDate": "2021-01-01T00:00:00+00:00", "updatedAt": "2021-01-01T01:23:45+00:00", "data": { "datetime": [ "2021-01-01T00:00:00+00:00", "2021-01-01T01:00:00+00:00", "2021-01-01T02:00:00+00:00", ... ], # The 0.01 quantile forecast - the value likely to be exceeded 99% of the time "discharge_q0.01": [ 1.0, 2.0, 1.5, ... ], "discharge_q0.025": [ ... ], "discharge_q0.05": [ ... ], "discharge_q0.1": [ ... ], "discharge_q0.25": [ ... ], # This key contains HydroForecast's estimate of the most likely forecast value "discharge_q0.5": [ ... ], "discharge_q0.75": [ ... ], "discharge_q0.9": [ ... ], "discharge_q0.95": [ ... ], "discharge_q0.975": [ ... ], "discharge_q0.99": [ ... ] } }, { "forecastDate": "2021-01-02T00:00:00+00:00", "updatedAt": "2021-01-02T01:23:45+00:00", "data": { ... } } ] } }
Example CSV response
{"siteId": "example-site", "type": "short-term", "units": "cms", "page": 1, "hasNextPage": true} issueTime,validTime,updatedAt,discharge_q0.01,discharge_q0.025,discharge_q0.05,discharge_q0.1,discharge_q0.25,discharge_q0.5,discharge_q0.75,discharge_q0.9,discharge_q0.95,discharge_q0.975,discharge_q0.99 2021-01-01T00:00:00+00:00,2021-01-01T00:00:00+00:00,2021-01-01T00:30:00+00:00,12.92,13.57,14.52,16.00,18.93,22.51,26.70,32.74,35.92,39.44,46.00 2021-01-01T00:00:00+00:00,2021-01-01T01:00:00+00:00,2021-01-01T00:30:00+00:00,12.46,13.43,14.27,15.87,18.56,22.23,26.42,32.28,35.66,39.12,45.15 2021-01-01T00:00:00+00:00,2021-01-01T02:00:00+00:00,2021-01-01T00:30:00+00:00,12.32,13.36,14.14,15.82,18.36,22.06,26.28,31.99,35.50,39.07,44.94
Example Usage
Retrieve the latest forecast
Curl
# Retrieve in JSON format curl 'https://api.hydroforecast.com/api/v1/forecasts/example-site-id?type=short-term&sort=desc&perPage=1' -H 'Authorization: API-Token' # Retrieve in CSV format curl 'https://api.hydroforecast.com/api/v1/forecasts/example-site-id?type=short-term&sort=desc&perPage=1&format=csv' -H 'Authorization: API-Token' --remote-name --remote-header-name
Python
import requests # Requests library to make HTTP calls. Install with `pip install requests` site_id = 'example-site-id' forecast_type = 'short-term' api_token = 'API-Token' response = requests.get(f'https://api.hydroforecast.com/api/v1/forecasts/{site_id}', params={'type': forecast_type, 'sort': 'desc', 'perPage': 1}, headers={'Authorization': api_token}) if response.status_code != 200: raise RuntimeError(f'{response.text} Status code: {response.status_code}') response_json = response.json() # Visualize the forecast import pandas as pd # pip install pandas import matplotlib.pyplot as plt # pip install matplotlib for forecast in response_json['data']['forecasts']: forecast_data = pd.DataFrame(forecast['data']).set_index('datetime') forecast_data.plot() plt.show()
Ongoing forecast retrieval
Python
import requests site_id = 'example-site-id' forecast_type = 'short-term' api_token = 'API-Token' # Retrieve the updatedAt time of the latest forecast already saved # in your system or None if this is the first time accessing forecasts. updated_since = get_latest_forecast_updated_date() page = 1 has_next_page = True while has_next_page: response = requests.get(f'https://api.hydroforecast.com/api/v1/forecasts/{site_id}', params={ 'type': forecast_type, 'updatedSince': updated_since, 'page': page }, headers={'Authorization': api_token}) response.raise_for_status() response_json = response.json() has_next_page = response_json['hasNextPage'] page += 1 if len(response_json['data']['forecasts']) > 0: # Save forecasts to your system save_forecasts(response_json) if not has_next_page: print(f"Done retrieving new forecasts at {site_id}. " f"Latest forecast date retrieved: {response_json['data']['forecasts'][-1]['forecastDate']}") else: print(f'All forecasts at {site_id} updated since {updated_since} have already been retrieved.')