HydroForecast Put Observations API (v1)

Explanation of PUT /observations/<siteId>

PUT /api/v1/observations/<siteId>

URL Parameter
* siteId - The site identifier for your site of interest provided to you by the HydroForecast team.

Request Body
A JSON encoded object containing observations and their associated timestamps in the following structure.

Datetimes must be *start of period* timestamps. For example, if data is aggregated at a daily step, the datetime 2020-01-01T00:00:00+0000 represents data from 2020-01-01T00:00:00+0000 to 2020-01-02T00:00:00+0000. A timezone offset must be included.

Up to 1,000 timestamps and their associated values may be submitted in a single request.

At least one of the keys "inflow", "outflow", and "flow" must be included, as appropriate for the site.

If values are sent for a previously submitted timestamp those values will overwrite the existing data.

{
  "datetime": [
    "2020-01-01T00:00:00-0500",
    "2020-01-02T00:00:00-0500",
    ...
  ],
  "inflow": [  # Use for reservoir inflows
    42.1,
    39.5,
    ...
  ],
  "outflow": [ ... ],  # Use for reservoir outflows (generation and spill)
  "flow": [ ... ],  # Use for stream gauge observations
  "units": {
    "inflow": "cms", # Or "cfs"
    "outflow": "cms",
    "flow": "cms"
  }
}

Testing Mode

When testing to send data to our API you can add test to the endpoint url in order to see if the code is formatted correctly.

Instead of this endpoint:

https://api.hydroforecast.com/api/v1/observations/{site_id}

Test with this endpoint:

https://api.hydroforecast.com/api/v1/test/observations/{site_id}

Example Usage

Python

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

site_id = 'example-site-id'
api_token = 'API-Token'

dates = [...]
inflow_cfs = [...]

data = {
  "units": {"inflow": "cfs"},
  "datetime": [date.isoformat() for date in dates],
  "inflow": inflow_cfs
}

response = requests.put(
    f'https://api.hydroforecast.com/api/v1/observations/{site_id}',
    data=json.dumps(data),
    headers={
        'Authorization': api_token,
        'Content-Type': 'application/json'
    })

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