1 Data Exchange Format
- 1.1 Guidelines
2 Sending data
- 2.1 Example of sending your reservoir level actuals
- 2.2 Example of turbine telemetry power actuals
3 Receiving data
- 3.1 Example of receiving the optimized plan for gate opening

In order to compute an optimized production plan, HYDROGRID needs to receive your latest sensor data for your turbines, gates and reservoirs. You can send them in bulk and you can manually overwrite specific points in time.

Data Exchange Format

The data you send must be in JSON format. For more details, refer to the original JSON documentation here.

The telemetry data for reservoirs and control units (gates and turbines) is sent to the HYDROGRID API as time series. Each time series consists of UNIX timestamps in milliseconds.

Guidelines

Submitting Data:

Provide time series of actual sensor readings for reservoirs, turbines, and gates.
Do not include planned data.

Fetching Data:

Retrieve time series of optimized dispatch plans for turbines and gates.
Start time has to be smaller than end time (ts_start < ts_end, ts_start != ts_end).

Submit sensor data as a time series in 48h rolling window (more details):

Sending data

Example of sending your reservoir level actuals

See how to obtain an auth token here.

import requests

# Configurations
access_token = "your_access_token_here"
reservoir_id = "YOUR_RESERVOIR_ID_HERE"
plant_id = "YOUR_PLANT_ID_HERE"

endpoint = f"https://api.hydrogrid.ai/v1/plant/{plant_id}/reservoir/level"
reservoir_data = [
  {
    "reservoirId": reservoir_id,
    "timeseries": [
      {
        "timestamp": 1688389171000,
        "value": 8000
      }
      # Only one datapoint provided here as an example. In real applications
      # the sensor data for the last 48h should be provided
    ]
  }
]

# Send the POST request
response = requests.post(
  endpoint,
  headers={
    "Authorization": f"Bearer {access_token}",
    "Content-Type": "application/json"
  },
  json=reservoir_data,
)

# Handle the response
if response.ok:
  print("Data sent successfully!", response.json())
else:
  print(f"Error: {response.status_code}, {response.text}")

Example of turbine telemetry power actuals

# Like above

turbine_data = [
  {
    "turbineId": "Turbino_Uno",
    "timeseries": [
      {
        "timestamp": 1600041600000,    # 14. September 2020 00:00 (UTC)
        "value": 1.3
      }
      {
        "timestamp": 1600041900000,    # 00:05
        "value": 0.4
      }
      {
        "timestamp": 1600042500000,    # 00:15
        "value": 2.7
      }
      {
        "timestamp": 1600043400000,    # 00:30
        "value": 0.0
      }
      {
        "timestamp": 1600045200000,    # 01:00
        "value": 0.0
      }
      {
        "timestamp": 1600046100000,    # 01:15
        "value": 0.691
      }
      {
        "timestamp": 1600047000000,    # 01:30
        "value": null
      }
      # Only a few datapoints provided here as an example. In real applications
      # the sensor data for the last 48h should be provided
    ]
  }
]

# Like above

Here is how the HYDROGRID API will interpret this data (all times in UTC, 15th of September 2020):

During the time between 00:00 and 00:05, the gate Turbino_Uno was producing 1.3 MW in average.
Starting from 00:05 production was reduced to 0.4 MW and kept at this power until 00:15.
In the time between 00:15 and 00:30, the turbine was running at 2.7 MW production power.
Starting from 00:30 it was switched off (0 MW), and kept off until 01:15.
Between 01:15 and 01:30 it produced again, in average 0.691 MW.

No information was provided what happened after 01:30 or before 00:00.

Note: This example data was probably sent to us shortly after 01:30, because after 01:30 the average production of the interval between 01:15 and 01:30 is know an can be provided.

Recommendation

We suggest to send the telemetry data in the plant granularity (e.g. 15 min interval data), or finer. This way, you avoid data loss because of averaging on the interface between your system and HYDROGRID API.

Receiving data

Example of receiving the optimized plan for gate opening

See how to obtain an auth token here.

import requests

# Configurations
access_token = "your_access_token_here"
plant_id = "YOUR_PLANT_ID_HERE"

endpoint = f"https://api.hydrogrid.ai/v1/plant/{plant_id}/gate/opening-plan"
params = {
    "unit": "percent",
    "start-ts": 1700006400000,      # 2023.11.15 00:00 (UTC)
    "end-ts":   1700013600000,      # 2023.11.15 02:00 (UTC)
}

# Fetch data with the GET request
response = requests.get(
    endpoint,
    headers={"Authorization": f"Bearer {access_token}"}
    params=params
)

# Handle the response
if response.ok:
    print("Data fetched successfully:", response.json())
else:
    print(f"Error: {response.status_code}, {response.text}")

Example response for the above request (assuming the plant is set up in 15min market granularity):

To summarize the meaning of this response (all times in UTC, on the 15th of November 2023):

During the time between 00:00 and 00:30, the gate YourGate_42 should be completely close (0%).
Starting from 00:30 the gate should open to 25% and keep this opening until 01:00.
At 01:00, the gate should open fully (100%), and keep the opening until 01:30.
At 01:30 it should reduce the opening to 42%, and keep the opening until 01:45.
At 01:45 it should close again (0%).

There if no information about the opening before 00:00 and after 02:00 in this example response.
No end marker is provided, because each plan datapoint is exactly valid for the granularity of the plant – which is 15 minutes in this example.

Turbine power plans have to be interpreted in the same way.

← Previous section

Next section →

API DOCUMENTATION

Sending and Receiving Data

Analytics