Get Thermal Control Forecast

curl --request GET \
  --url https://api.nox.energy/v1/device/thermal-control/forecast \
  --header 'x-api-key: <api-key>'

{
  "data": {
    "device_id": "HP123456",
    "forecasts": [
      {
        "timestamp": "2025-01-15 12:00:00",
        "tank": {
          "upperbound_Z": 32.07,
          "lowerbound_X": 22.45,
          "Y_avg": 27.26,
          "Q_loss": 0.61,
          "Q_gain": [
            16.35,
            16.35,
            16.35,
            16.35
          ],
          "P_if_activated": [
            2.37,
            2.89,
            3.27,
            3.48
          ],
          "tank_activation_limit": 24.4,
          "tank_activation_limit_temp": 45
        },
        "house": {
          "upperbound_Z": 528.88,
          "lowerbound_X": 486.19,
          "Y_avg": 507.53,
          "Y_ideal": 521.76,
          "Q_natural": -1.86,
          "Q_heating": [
            5.94,
            5.94,
            5.94,
            5.94,
            5.94,
            5.94,
            5.94,
            5.94
          ],
          "Q_cooling": [
            0,
            0,
            0,
            0,
            0,
            0,
            0,
            0
          ],
          "P_heating": [
            1.8,
            1.8,
            1.8,
            1.8,
            1.8,
            1.8,
            1.8,
            1.8
          ],
          "P_cooling": [
            0,
            0,
            0,
            0,
            0,
            0,
            0,
            0
          ]
        }
      },
      {
        "timestamp": "2025-01-15 12:15:00",
        "tank": {
          "upperbound_Z": 32.07,
          "lowerbound_X": 22.45,
          "Y_avg": 27.26,
          "Q_loss": 0.61,
          "Q_gain": [
            16.35,
            16.35,
            16.35,
            16.35
          ],
          "P_if_activated": [
            2.36,
            2.88,
            3.27,
            3.48
          ],
          "tank_activation_limit": 24.4,
          "tank_activation_limit_temp": 45
        },
        "house": {
          "upperbound_Z": 528.88,
          "lowerbound_X": 486.19,
          "Y_avg": 507.53,
          "Y_ideal": 521.76,
          "Q_natural": -1.74,
          "Q_heating": [
            5.99,
            5.99,
            5.99,
            5.99,
            5.99,
            5.99,
            5.99,
            5.99
          ],
          "Q_cooling": [
            0,
            0,
            0,
            0,
            0,
            0,
            0,
            0
          ],
          "P_heating": [
            1.8,
            1.8,
            1.8,
            1.8,
            1.8,
            1.8,
            1.8,
            1.8
          ],
          "P_cooling": [
            0,
            0,
            0,
            0,
            0,
            0,
            0,
            0
          ]
        }
      }
    ]
  },
  "meta": {
    "forecast_generation_date": "2025-01-14",
    "forecast_generation_date_time_zone": "UTC",
    "timestamp_time_zone": "UTC",
    "tank_upperbound_Z_unit": "kWh",
    "tank_lowerbound_X_unit": "kWh",
    "tank_Y_avg_unit": "kWh",
    "tank_Q_loss_unit": "kW",
    "tank_Q_gain_unit": "kW",
    "tank_P_if_activated_unit": "kW",
    "house_upperbound_Z_unit": "kWh",
    "house_lowerbound_X_unit": "kWh",
    "house_Y_avg_unit": "kWh",
    "house_Q_natural_unit": "kW",
    "house_Q_heating_unit": "kW",
    "house_Q_cooling_unit": "kW",
    "house_P_heating_unit": "kW",
    "house_P_cooling_unit": "kW",
    "tank_activation_limits_unit": "kWh",
    "tank_activation_limit_temp_unit": "°C",
    "energy_supplier": "Energy Supplier A"
  }
}

Thermal Control

Get Thermal Control Forecast

Get the thermal model forecast data for a specific device.

The forecast contains predicted thermal energy flows for both the domestic hot water (DHW) tank and the house (space heating/cooling), broken down into 15-minute intervals.

Tank fields:

upperbound_Z / lowerbound_X / Y_avg — Upper/lower comfort bounds and average state of the tank.
Q_loss / Q_gain (kW) or T_loss / T_gain (°C) — Thermal loss to the environment and gain per activation level.
P_if_activated — Electrical power consumption (kW) per activation level if the heat pump is activated for DHW.
tank_activation_limit (kWh) / tank_activation_limit_temp (°C) — Tank state threshold below which DHW heating can be triggered.

House fields:

upperbound_Z / lowerbound_X / Y_avg / Y_ideal — Comfort bounds, average and ideal state.
Q_natural / Q_heating / Q_cooling (kW) or T_natural / T_heating / T_cooling (°C) — Natural thermal drift, and heating/cooling effect per activation level.
P_heating / P_cooling — Electrical power consumption (kW) per activation level for space heating and cooling.

Use the unit query parameter to choose between energy values (kWh, default) or temperature equivalents (celsius / °C). In celsius mode, bounds are returned in °C and thermal flows as temperature change rates (°C per 15min) instead of energy (kWh/kW). Power fields (P_*) are always returned in kW regardless of the unit choice.

The timestamp refers to the data that will happen in the next 15 minutes after the timestamp. All timestamps are in UTC.

GET

device

thermal-control

forecast

Get Thermal Control Forecast

curl --request GET \
  --url https://api.nox.energy/v1/device/thermal-control/forecast \
  --header 'x-api-key: <api-key>'

{
  "data": {
    "device_id": "HP123456",
    "forecasts": [
      {
        "timestamp": "2025-01-15 12:00:00",
        "tank": {
          "upperbound_Z": 32.07,
          "lowerbound_X": 22.45,
          "Y_avg": 27.26,
          "Q_loss": 0.61,
          "Q_gain": [
            16.35,
            16.35,
            16.35,
            16.35
          ],
          "P_if_activated": [
            2.37,
            2.89,
            3.27,
            3.48
          ],
          "tank_activation_limit": 24.4,
          "tank_activation_limit_temp": 45
        },
        "house": {
          "upperbound_Z": 528.88,
          "lowerbound_X": 486.19,
          "Y_avg": 507.53,
          "Y_ideal": 521.76,
          "Q_natural": -1.86,
          "Q_heating": [
            5.94,
            5.94,
            5.94,
            5.94,
            5.94,
            5.94,
            5.94,
            5.94
          ],
          "Q_cooling": [
            0,
            0,
            0,
            0,
            0,
            0,
            0,
            0
          ],
          "P_heating": [
            1.8,
            1.8,
            1.8,
            1.8,
            1.8,
            1.8,
            1.8,
            1.8
          ],
          "P_cooling": [
            0,
            0,
            0,
            0,
            0,
            0,
            0,
            0
          ]
        }
      },
      {
        "timestamp": "2025-01-15 12:15:00",
        "tank": {
          "upperbound_Z": 32.07,
          "lowerbound_X": 22.45,
          "Y_avg": 27.26,
          "Q_loss": 0.61,
          "Q_gain": [
            16.35,
            16.35,
            16.35,
            16.35
          ],
          "P_if_activated": [
            2.36,
            2.88,
            3.27,
            3.48
          ],
          "tank_activation_limit": 24.4,
          "tank_activation_limit_temp": 45
        },
        "house": {
          "upperbound_Z": 528.88,
          "lowerbound_X": 486.19,
          "Y_avg": 507.53,
          "Y_ideal": 521.76,
          "Q_natural": -1.74,
          "Q_heating": [
            5.99,
            5.99,
            5.99,
            5.99,
            5.99,
            5.99,
            5.99,
            5.99
          ],
          "Q_cooling": [
            0,
            0,
            0,
            0,
            0,
            0,
            0,
            0
          ],
          "P_heating": [
            1.8,
            1.8,
            1.8,
            1.8,
            1.8,
            1.8,
            1.8,
            1.8
          ],
          "P_cooling": [
            0,
            0,
            0,
            0,
            0,
            0,
            0,
            0
          ]
        }
      }
    ]
  },
  "meta": {
    "forecast_generation_date": "2025-01-14",
    "forecast_generation_date_time_zone": "UTC",
    "timestamp_time_zone": "UTC",
    "tank_upperbound_Z_unit": "kWh",
    "tank_lowerbound_X_unit": "kWh",
    "tank_Y_avg_unit": "kWh",
    "tank_Q_loss_unit": "kW",
    "tank_Q_gain_unit": "kW",
    "tank_P_if_activated_unit": "kW",
    "house_upperbound_Z_unit": "kWh",
    "house_lowerbound_X_unit": "kWh",
    "house_Y_avg_unit": "kWh",
    "house_Q_natural_unit": "kW",
    "house_Q_heating_unit": "kW",
    "house_Q_cooling_unit": "kW",
    "house_P_heating_unit": "kW",
    "house_P_cooling_unit": "kW",
    "tank_activation_limits_unit": "kWh",
    "tank_activation_limit_temp_unit": "°C",
    "energy_supplier": "Energy Supplier A"
  }
}

Authorizations

x-api-key

string

header

required

API Key authentication. Enter your API key in the format: YOUR_API_KEY

Query Parameters

device_id

string

required

The ID of the device.

unit

enum<string>

default:kWh

Unit for thermal values returned in the response.

'kWh' (default) returns energy in kWh and power in kW.

'celsius' returns temperature equivalents in °C.

Available options:

kWh,

celsius

start_time

string | null

Start time when the forecasts were generated. The time is in UTC in ISO 8601 format.

Time format examples:

2023-10-01T00:00:00Z
2023-10-01T00:00:00

end_time

string | null

End time when the forecasts were generated. The time is in UTC in ISO 8601 format.

Time format examples:

2023-10-01T00:00:00Z
2023-10-01T00:00:00

Response

Successful response

Get Device Consumption Historical Get Thermal Control Current State