Get Thermal Control Forecast
curl --request GET \
--url https://api.nox.energy/v1/device/thermal-control/forecast \
--header 'x-api-key: <api-key>'import requests
url = "https://api.nox.energy/v1/device/thermal-control/forecast"
headers = {"x-api-key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};
fetch('https://api.nox.energy/v1/device/thermal-control/forecast', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.nox.energy/v1/device/thermal-control/forecast",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.nox.energy/v1/device/thermal-control/forecast"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("x-api-key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.nox.energy/v1/device/thermal-control/forecast")
.header("x-api-key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.nox.energy/v1/device/thermal-control/forecast")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"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 Battery 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) orT_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) orT_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
/
v1
/
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>'import requests
url = "https://api.nox.energy/v1/device/thermal-control/forecast"
headers = {"x-api-key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};
fetch('https://api.nox.energy/v1/device/thermal-control/forecast', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.nox.energy/v1/device/thermal-control/forecast",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.nox.energy/v1/device/thermal-control/forecast"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("x-api-key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.nox.energy/v1/device/thermal-control/forecast")
.header("x-api-key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.nox.energy/v1/device/thermal-control/forecast")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"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
Query Parameters
Response
Successful response