Overview

API overview and usage

This document explains the usage of the Building Energy Modeling API.

This API has three main purposes:

Build a baseline model of a building using the “thermal signature” models recommended by the American Society of Heating, Refrigerating and Air‑Conditioning (ASHRAE) and the International Performance Measurement and Verification Protocol (IPMVP), typically from one year of historical data. Optionally assess its statistical quality to compute savings.
Optionally build a target model using the same mechanism, typically from one year of simulated target data (assuming the user has created simulated target data).
Follow-up the baseline and target models of a building in particular to detect faults and to compute savings.

This document provides a general tutorial for users who want to consume the Building Energy Modeling API.

Sandbox

Sandbox is available to try sample calls for this API! Why not give it a go and see the API working in action. Please refer the API Try it section for details. (Note: only 5 calls per minute are allowed in sandbox)

How it works

The Building Energy Modeling API usage flow is described below.

First you need to create a model through the create service. This service will return a modelId and other model information.

Once the model is created it is possible to either make a consumption prediction using the apply service or determine if your model is good enough for savings computation through the assess quality for savings service.

Create model

This service receives as input a multivariate time-series. Each column of this table represents a variable (feature or the target) and each row represents an observation. At least one of these columns must describe the target you want to model.

Create service also receives only one configuration object composed of one or several section(s) depending on request customization.

Columns configuration

This configuration object is the only mandatory one. It marks which columns to use in the input table:

target (Mandatory): What you want to model (most of the time, it is energy consumption related).
meanTemperature, minTemperature, maxTemperature (Mandatory): outside air temperature needed to model building signature.

Note:

You need either meanTemperature or (minTemperature + maxTemperature) or both. With all temperature data, BEM will automatically choose the best degree days formula available.

otherFeatures (Optional): Input table features that have an influence on your target. For example : production counts, occupancy, exterior heating input to the building.
positiveFeatures (Optional): Features among otherFeatures that are known as positive influence on your target, meaning its increase is correlated to target increase. For example : production numbers, occupancy.

Note:

To sum up, for a daily energy model you will typically need:

An “energy consumption” column (the target)
An outside air temperature columns(mean and / or minmax)
Maybe an optional other columns that are known to influence energy consumption.

DayGroups configuration

An optional configuration object dedicated to your building working calendar:

dayGroupCol : may be present to activate explicit time binning. Indeed it is very frequent that a building has several models, one for each working mode, the most common one being : opened and closed days. This column is the only one not requiring numerical data. If this column is provided, a sub-model will be created for each unique element.
improveCalendar : chooses whether you want BEM to find a better calendar repartition of the week. This extends computation time.

Note:

improveCalendar is usable with or without a dayGroupCol parameter :

If dayGroupCol is provided, improveCalendar will run on combination of already existing groups.

If no dayGroupCol is provided, improveCalendar will run on all possible day of week combinations.

maxMergedDayGroups : linked to improveCalendar parameter, BEM will explore days of week configurations up to a maximum number of groups. For example: 3 means every slicing of 3 groups or lower. It is not recommended to go higher than 3 since the building rarely has more than 3 different working modes per week.

Temporal configuration

An optional configuration object dedicated to customize the temporal resolution of your train data:

resolution : selects whether you want your building signatures and results to be in daily or monthly resolution. It also indicates to BEM your target format.
- daily means that your input table contains data on a daily basis (target and others columns).
- monthly means that your input table contains target data once a month, on each first day, representing the monthly consumption.

Note

On Monthly mode : Any other column (Temperature, Feature) still have to be daily input.
There are some parameters incompatable with the Monthly mode, do not use them: improveCalendar, robustRegression, degreeDaysMode.
Default mode is daily.

Warning!

For daily mode, the train table has to contain at least 80 exploitable days of observations (80 non-NaN rows)
For monthly mode, the train table has to contain at least 8 monthly target observations (8 x ~30 rows for other columns)

Computation configuration

An optional configuration object dedicated to customize computation options. This is an advanced user configuration object:

degreeDaysMode : Select the degree days computing methods that will be parsed by BEM : Basic or Advanced. See degree days formulas

Warning!

Only use on TemporalConfig['resolution'] == “daily”

buildingSignatures : Select the types of building signature that will be parsed by BEM. See thermal signatures

Note:

Reducing the scope of building signature to explore is recommended when you have information on your building heatingcooling technologies : + No cooling devices -> use [twoParameters”,”threeParametersHeating”] + No heating devices -> use [twoParameters”,”threeParametersCooling”]

RobustRegression

Select whether the regression is sensible to outliers or not. This is useful if you have already cleaned your data from outliers : * False value will use a LinearRegression. * True value will use a RANSACRegressor.

Note:

robustRegression means a model robust to outliers but at the price of longer computation time. No robustRegression means faster response time, but user has to be sure to input representative data.

Warning!

Only use on TemporalConfig['resolution'] == “daily”

AutoApply

Selects whether BEM executes an apply of the computed model directly on its training table. This is useful when you just want a full ID card of this year : Model, Model information and metrics :

BEMModel
RegressionMetrics
Prediction table on training set. See apply output table for details.

Apply model

The test table provided to the apply service has to fit the exact same criteria as those required for the create service input table

Note:

This table can be the exact same table than the one provided in the create service.

Apply parameters

faultDetection: decide which type of fault detection you want BEM to apply to your test dataset:
- “both” or True (default):
  - Considered both over and under consumptions as fault.
  - “overconsumption” : Considered only over consumption as fault.
  - “underconsumption” : Considered only under consumption as fault.
- False : Do not consider any fault detection.

Note:

In the no fault detection case, the target becomes optional in the test dataset - faultDetectionThresholdNbStd and removeFaultsFromSavings parameters become useless.

faultDetectionThresholdNbStd: determines the standard deviation coefficient up to which a TARGET value is considered normal. The default values is 2 sigma. see fault_detection_limits.
removeFaultsFromSavings: determines whether savings are kept in accumulation computation or not for anomaly points in test dataset.

The output of the apply service is a prediction table which is basically the same as the one provided as input with some added columns and exact same rows.

Here is a list of added columns:

discarded_for_model_creation
prediction
prediction_residual
cumulative_prediction_residual, cumulative_savings and cumulative_savings_
fault_detection_upper_limit and fault_detection_lower_limit
consumption_anomaly
midrange_temperature
reference_temperature
heating_degree_days and cooling_degree_days
predicted_DRIVER_contribution
estimated_actual_DRIVER_contribution
NTS_DRIVER_predicted_energy and NTS_DRIVER_actual_energy

Note:

For following descriptions other columns than those added are referred:

TARGET: Target provided by the user
DRIVER: Driver provided by the user
DAYGROUP: Day group either provided by the user or computed by the component

discarded_for_model_creation

This column is an autoApply context only. It represents which points were ultimately used for thermal signatures models creation.

Warning!

Points marked True in this columns are not outliers, in the “aberrant value” sense, See consumption_anomaly columns.
Results in this column will vary a lot depending of the robustRegression parameter value.

prediction

Prediction of the provided TARGET made by the BuildingEnergyModeling component.

For each day group we have:

where

prediction_residual

The prediction residual is the prediction error.

cumulative_prediction_residual, cumulative_savings and cumulative_savings_

This represents the sum of differences between ground truth and prediction on the TARGET, expressed in the same physical unit. It is called cumulative_savings in an apply context, cumulative_savings_DAYGROUP represent the cumulative savings made for a specific day group. The cumulative_prediction_residual is used in an autoApply context, as the word “savings” does not make much sense here.

The computation formula stays the same in either case:

where:

k is the number of rows in the provided table.

Note:

cumulative_prediction_residual can be useful if it displays a cyclic pattern in values, this most probably means that there is at least another hidden feature influencing the target value !

fault_detection_upper_limit and fault_detection_lower_limit

Respectively values upper and bellow which a TARGET observation is considered as an anomaly. These values directly depends on the faultDetectionThresholdNbStd value on apply context, and is fixed at default value 2.0 in an autoApply context.

consumption_anomaly

Boolean flag informing if a TARGET observation is or not considered as an anomaly.

Warning!

This column is present in autoApply model creation context.
In apply context, this column is piloted by the faultDetection parameter.

midrange_temperature

The day midrange temperature represent an approximation of the day average temperature with following formula:

Warning!

This metric is only computed when both minTemperature and maxTemperature are provided.

reference_temperature

Since every day group model may use a different temperature value (average or midrange temperature), this column gathered in a single one the reference temperature value used by each day groups.

heating_degree_days and cooling_degree_days

Respectively values of computed heating and cooling degree days. For more information see Degree days.

predicted_DRIVER_contribution

The special predicted_other_uses_of_energy_contribution is equal to the intercept. If the model is 2-parameters, predicted_heating_degree_days_contribution or predicted_cooling_degree_days_contribution will be filled depending on the slope. Note that we choose to NOT provide a predicted_reference_temperature_contrib because the result would be harder to understand.

Note:

On every row, the sum of all such predicted contributions should be equal to the prediction column

estimated_actual_DRIVER_contribution

That is, we prorate the actual energy with the proportions of contribution of this driver in the model.

Note:

On every row, the sum of all such estimated actual contributions should be equal to the provided TARGET column

NTS_DRIVER_predicted_energy and NTS_DRIVER_actual_energy

Normalized Thermal Signature (NTS) columns. By default the building thermal signature is just obtained by plotting the scatter plot of prediction (line) and TARGET (dots) (y axis) against the reference_temperature (x axis). However in case of additional drivers the resulting scatter plot is flawed by the influence of these extra drivers. To circumvent this one can plot a so-called “normalized” version of the thermal signature, obtained for each driver by plotting NTS_DRIVER_predicted_energy (line) and NTS_DRIVER_actual_energy (dots) (y axis) against the DRIVER (x axis). Equations are:

Last but not the least (as they will be the most used), a special NTS_reference_temperature_predicted_energy is computed by merging the predicted energies of cdd and hdd drivers:

Assess model quality for savings

This service answers the question “is my model good enough to compute statistically significant savings?”. Its main parameters are the target savings ratio (20%, 30%), and the assessment period (30 days, 60 days, 365 days). The larger the target savings, and the longer the assessment period, the less precise a model needs to be. On the other hand if the savings ratio to achieve is small (e.g. 1%, 5%) and/or if the assessment period is short (e.g. 10 days, 30 days) the uncertainty will be bigger and certifying the savings will require a much more precise model.

Documentation

Getting started

These are the minimal steps to use this component through its APIs.

Authentication

Authentication is mandatory to use this API product. API_KEY must be included in the Authorization header of each request. To see how you can obtain your API KEY please refer How to signup section. Sample requests included as examples below.

Create model

First step is to create a trained model with:

configuration parameters, e.g.:

{

  "configuration": {

"columns":{

"target": "energy_consumption",

"meanTemperature": ["mean_temperature"] }

  }

}

Note

These are the minimal configuration parameters that can be used to train a model.
For advanced usage, see the complete /create API description.

training data, e.g.:

{

  "trainTbl": {

  "format": "row_objects_indexed", 

  "indexName": "timestamp", 

  "rows": { 

  "2016-05-20": {

  "energy_consumption": 479.157,

  "mean_temperature": 19.1 },

  "2016-05-21": {

  "energy_consumption": 478.475,

  "mean_temperature": 16.8 } } }

}

Apply model

Second step is to apply the created model to other data to make a prediction, with:

the previously returned modelId

some data to apply the model on, e.g.:

{

  "testTbl": {

  "format": "row_objects_indexed", 

  "indexName": "timestamp", 

  "rows": {

"2016-05-20": {

  "energy_consumption": 400.0,

  "mean_temperature": 42.0 },

"2016-05-21": {

  "energy_consumption": 500.0,

  "mean_temperature": 69.0 } } }

}

For advanced usage, see the complete /apply API description.

How to sign up

Before you can sign up for the Building Energy Modeling API, you must register or login with an Exchange account.

Then you can subscribe to the API product in our Shop and where you can read about terms & conditions.

After subscription, you will find your API key prepopulated in the Try Out console.

Note: If you're an existing V1 consumer then you do not need to subscribe again. Your existing API key will work for calling both V1 and V2 APIs.

Select one of the endpoints and click on .

Select Production as the target environment

Your API key is shown in the Try Out console

Status of your API consumption will soon be available from the Exchange cockpit

Table formats

Below described are all possible input table formats.
By default table returned after an apply will have the same format as the one provided in the input.

TableRowFormat

{

    "format": "rows",

    "indexName": "Date",

    "columnNames": ["Date", "Energy_EMS_DELTAS_kWh", "T_mean", "T_min", "T_max", "Shipment_RMB", "DVC_hours", "week_day", "daytype_basic"],

    "rows": [

["2011-01-01", 2226.5569999999834, 0.4, -3.0, 3.0, 0.0, 77433.66666666667, 5, "SaturdaysMondays"],

["2011-01-02", 3593.3263999999967, 2.8, 0.0, 6.0, 0.0, 77433.66666666667, 6, "Sundays"],

["2011-01-03", 4172.260399999936, 1.3, -2.0, 4.0, 0.0, 77433.66666666667, 0, "SaturdaysMondays"],

["2011-01-04", 4364.47360000005, 2.3, -1.0, 5.0, 8226221.91, 77433.66666666667, 1, "NormalDays"],

["2011-01-05", 4347.980599999986, 2.6, 0.0, 4.0, 3105077.285, 77433.66666666667, 2, "NormalDays"],

["2011-01-06", 4313.757400000002, 0.8, -1.0, 3.0, 3550134.215, 77433.66666666667, 3, "NormalDays"],

["2011-01-07", 4244.50959999999, 1.1, -3.0, 4.0, 6014563.55, 77433.66666666667, 4, "NormalDays"],

["2011-01-08", 3864.668000000063, 3.6, 0.0, 8.0, 0.0, 77433.66666666667, 5, "SaturdaysMondays"],

["2011-01-09", 2344.0981999999844, 0.9, -3.0, 6.0, 0.0, 77433.66666666667, 6, "Sundays"],

["2011-01-10", 3728.927799999993, 0.2, -2.0, 3.0, 2506211.045, 77433.66666666667, 0, "SaturdaysMondays"] ]

}

TableRowIndexObjectFormat

{

    "format": "row_objects_indexed",

    "indexType": null,

    "indexName": "Date",

    "rows": {

"2011-01-01": {"Energy_EMS_DELTAS_kWh": 2226.55, "T_mean": 0.4, "T_min": -3.0, "T_max": 3.0, "Shipment_RMB": 0.0, "daytype_basic": "SaturdaysMondays"},

"2011-01-02": {"Energy_EMS_DELTAS_kWh": 3593.32, "T_mean": 2.8, "T_min": 0.0, "T_max": 6.0, "Shipment_RMB": 0.0, "daytype_basic": "Sundays"},

"2011-01-03": {"Energy_EMS_DELTAS_kWh": 4172.26, "T_mean": 1.3, "T_min": -2.0, "T_max": 4.0, "Shipment_RMB": 0.0, "daytype_basic": "SaturdaysMondays"},

"2011-01-04": {"Energy_EMS_DELTAS_kWh": 4364.47, "T_mean": 2.3, "T_min": -1.0, "T_max": 5.0, "Shipment_RMB": 8226221.91, "daytype_basic": "NormalDays"},

"2011-01-05": {"Energy_EMS_DELTAS_kWh": 4347.98, "T_mean": 2.6, "T_min": 0.0, "T_max": 4.0, "Shipment_RMB": 3105077.285, "daytype_basic": "NormalDays"},

"2011-01-06": {"Energy_EMS_DELTAS_kWh": 4313.75, "T_mean": 0.8, "T_min": -1.0, "T_max": 3.0, "Shipment_RMB": 3550134.215, "daytype_basic": "NormalDays"},

"2011-01-07": {"Energy_EMS_DELTAS_kWh": 4244.50, "T_mean": 1.1, "T_min": -3.0, "T_max": 4.0, "Shipment_RMB": 6014563.55, "daytype_basic": "NormalDays"},

"2011-01-08": {"Energy_EMS_DELTAS_kWh": 3864.66, "T_mean": 3.6, "T_min": 0.0, "T_max": 8.0, "Shipment_RMB": 0.0, "daytype_basic": "SaturdaysMondays"},

"2011-01-09": {"Energy_EMS_DELTAS_kWh": 2344.09, "T_mean": 0.9, "T_min": -3.0, "T_max": 6.0, "Shipment_RMB": 0.0, "daytype_basic": "Sundays"},

"2011-01-10": {"Energy_EMS_DELTAS_kWh": 3728.92, "T_mean": 0.2, "T_min": -2.0, "T_max": 3.0, "Shipment_RMB": 2506211.045, "daytype_basic": "SaturdaysMondays"} }

}

TableColumnFormat

{

    "format": "columns",

    "index": ["2011-01-01","2011-01-02","2011-01-03","2011-01-04","2011-01-05","2011-01-06","2011-01-07","2011-01-08","2011-01-09","2011-01-10"],

    "indexName": "Date",

    "columns": {

    "Energy_EMS_DELTAS_kWh": [2226.55,3593.32,4172.26,4364.47,4347.98,4313.75,4244.50,3864.66,2344.09,3728.92],

    "T_mean": [0.4,2.8,1.3,2.3,2.6,0.8,1.1,3.6,0.9,0.2],

    "T_min": [-3.0,0.0,-2.0,-1.0,0.0,-1.0,-3.0,0.0,-3.0,-2.0],

    "T_max": [3.0,6.0,4.0,5.0,4.0,3.0,4.0,8.0,6.0,3.0],

    "Shipment_RMB": [0.0,0.0,0.0,8226221.91,3105077.285,3550134.215,6014563.55,0.0,0.0,2506211.045],

    "daytype_basic": ["SaturdaysMondays","Sundays","SaturdaysMondays","NormalDays","NormalDays","NormalDays","NormalDays","SaturdaysMondays","Sundays","SaturdaysMondays"] }

}

TableColumnObjectFormat

{

    "format": "column_objects",

    "indexType": null,

    "indexName": "Date",

    "columns": {

"Energy_EMS_DELTAS_kWh": {

    "2011-01-01": 2226.5569999999834,

    "2011-01-02": 3593.3263999999967,

    "2011-01-03": 4172.260399999936,

    "2011-01-04": 4364.47360000005,

    "2011-01-05": 4347.980599999986,

    "2011-01-06": 4313.757400000002,

    "2011-01-07": 4244.50959999999,

    "2011-01-08": 3864.668000000063,

    "2011-01-09": 2344.0981999999844,

    "2011-01-10": 3728.927799999993},

"T_mean": {

    "2011-01-01": 0.4,

    "2011-01-02": 2.8,

    "2011-01-03": 1.3,

    "2011-01-04": 2.3,

    "2011-01-05": 2.6,

    "2011-01-06": 0.8,

    "2011-01-07": 1.1,

    "2011-01-08": 3.6,

    "2011-01-09": 0.9,

    "2011-01-10": 0.2 },

"T_min": {

    "2011-01-01": -3.0,

    "2011-01-02": 0.0,

    "2011-01-03": -2.0,

    "2011-01-04": -1.0,

    "2011-01-05": 0.0,

    "2011-01-06": -1.0,

    "2011-01-07": -3.0,

    "2011-01-08": 0.0,

    "2011-01-09": -3.0,

    "2011-01-10": -2.0 },

"T_max": {

    "2011-01-01": 3.0,

    "2011-01-02": 6.0,

    "2011-01-03": 4.0,

    "2011-01-04": 5.0,

    "2011-01-05": 4.0,

    "2011-01-06": 3.0,

    "2011-01-07": 4.0,

    "2011-01-08": 8.0,

    "2011-01-09": 6.0,

    "2011-01-10": 3.0 },

"Shipment_RMB": {

    "2011-01-01": 0.0,

    "2011-01-02": 0.0,

    "2011-01-03": 0.0,

    "2011-01-04": 8226221.91,

    "2011-01-05": 3105077.285,

    "2011-01-06": 3550134.215,

    "2011-01-07": 6014563.55,

    "2011-01-08": 0.0,

    "2011-01-09": 0.0,

    "2011-01-10": 2506211.045 },

"daytype_basic": {

    "2011-01-01": "SaturdaysMondays",

    "2011-01-02": "Sundays",

    "2011-01-03": "SaturdaysMondays",

    "2011-01-04": "NormalDays",

    "2011-01-05": "NormalDays",

    "2011-01-06": "NormalDays",

    "2011-01-07": "NormalDays",

    "2011-01-08": "SaturdaysMondays",

    "2011-01-09": "Sundays",

    "2011-01-10": "SaturdaysMondays"} }

}

TableRowObjectFormat

{

    "format": "row_objects",

    "indexName": "Date",

    "rows": [

{"Date": "2011-01-01", "Energy_EMS_DELTAS_kWh": 2226.5569999999834, "T_mean": 0.4, "T_min": -3.0, "T_max": 3.0, "Shipment_RMB": 0.0, "daytype_basic": "SaturdaysMondays"},

{"Date": "2011-01-02", "Energy_EMS_DELTAS_kWh": 3593.3263999999967, "T_mean": 2.8, "T_min": 0.0, "T_max": 6.0, "Shipment_RMB": 0.0, "daytype_basic": "Sundays"},

{"Date": "2011-01-03", "Energy_EMS_DELTAS_kWh": 4172.260399999936, "T_mean": 1.3, "T_min": -2.0, "T_max": 4.0, "Shipment_RMB": 0.0, "daytype_basic": "SaturdaysMondays"},

{"Date": "2011-01-04", "Energy_EMS_DELTAS_kWh": 4364.47360000005, "T_mean": 2.3, "T_min": -1.0, "T_max": 5.0, "Shipment_RMB": 8226221.91, "daytype_basic": "NormalDays"},

{"Date": "2011-01-05", "Energy_EMS_DELTAS_kWh": 4347.980599999986, "T_mean": 2.6, "T_min": 0.0, "T_max": 4.0, "Shipment_RMB": 3105077.285, "daytype_basic": "NormalDays"},

{"Date": "2011-01-06", "Energy_EMS_DELTAS_kWh": 4313.757400000002, "T_mean": 0.8, "T_min": -1.0, "T_max": 3.0, "Shipment_RMB": 3550134.215, "daytype_basic": "NormalDays"},

{"Date": "2011-01-07", "Energy_EMS_DELTAS_kWh": 4244.50959999999, "T_mean": 1.1, "T_min": -3.0, "T_max": 4.0, "Shipment_RMB": 6014563.55, "daytype_basic": "NormalDays"},

{"Date": "2011-01-08", "Energy_EMS_DELTAS_kWh": 3864.668000000063, "T_mean": 3.6, "T_min": 0.0, "T_max": 8.0, "Shipment_RMB": 0.0, "daytype_basic": "SaturdaysMondays"},

{"Date": "2011-01-09", "Energy_EMS_DELTAS_kWh": 2344.0981999999844, "T_mean": 0.9, "T_min": -3.0, "T_max": 6.0, "Shipment_RMB": 0.0, "daytype_basic": "Sundays"},

{"Date": "2011-01-10", "Energy_EMS_DELTAS_kWh": 3728.927799999993, "T_mean": 0.2, "T_min": -2.0, "T_max": 3.0, "Shipment_RMB": 2506211.045, "daytype_basic": "SaturdaysMondays"} ]

}

Thermal signature

What is a Thermal signature?

The thermal signature of a building describes the energy consumption of a building considering external temperature. Basically it models how much energy a building will require for heating when external temperature is cold (heating degree days, HDD) and how much energy it will require for cooling when external temperature is hot (cooling degree days, CDD).

The heating change-point is the outside air temperature below which the heating system is on.

The cooling change-point is the outside air temperature above which cooling system is on.

See Degree days section for more information.

There are 5 types of change-point models according to ASHRAE guideline 14, appendix D4:

2-parameters
3-parameters-heating
3-parameters-cooling
4-parameters
5-parameters

Note:

All these model types are able to take into account additional drivers (production, occupancy…). These drivers will be considered to have a linear impact on energy, independently on the weather’s impact.

2-parameters

The 2-parameters model is a straight line with no change-points. It can model either a heating season only, a cooling season only or a building without heating or cooling.

3-parameters-heating

The slope heating 3-parameters model includes a linear dependency with HDD: when outside air temperature is below a change-point value, energy linearly depends on it ; above it is a constant. See the example below. 3-parameters heating models are used to model energy consumption in buildings without cooling system, or to model the energy consumption of heating equipments alone (using a sub-meter).

3-parameters-cooling

The slope cooling 3-parameters model includes a linear dependency with CDD: when outside air temperature is above a change-point value, energy linearly depends on it ; below it is a constant. See the example below. 3-parameters cooling models are used to model energy consumption in buildings without heating system, or to model the energy consumption of cooling equipments alone (using a sub-meter).

4-parameters

The 4-parameters model includes one linear dependency for heating (HDD) and another for cooling (CDD), with a single shared change-point between the two. 4-parameter models are appropriate to model heating and cooling energy consumption in buildings where there is no inter-seasonal behavior: there are almost no days in the year where the heating and cooling systems are both off. Note that these models can correctly take into account days where both heating and cooling are on, if an appropriate degree days calculation methods is used (by default this component searches for the best method).

5-parameters

The 5-parameters model includes one linear dependency for heating (HDD) and another for cooling (CDD), with one dedicated change-point for each mode. Unlike the 4-parameter model, the 5-parameter model is able to model heating and cooling energy consumption in buildings where there is an inter-seasonal behavior with both systems turned off. Note that these models can correctly take into account days where both heating and cooling are on, if an appropriate degree days calculation methods is used (by default this component searches for the best method).

Degree days

What are degree days?

Degree days are a specialist kind of weather data providing a simplified representation of outside-air-temperature data. They are calculated from readings of outside air temperature and mainly used in calculations relating to building energy consumption.

It is possible to distinguish two kinds of degree days:

“Heating degree days”, or “HDD”, are a measure of how much (in degrees), and for how long (in days), outside air temperature was lower than a specific “base temperature” (or “heating change-point”). They are used for calculations relating to the energy consumption required to heat buildings.
“Cooling degree days”, or “CDD”, are a measure of how much (in degrees), and for how long (in days), outside air temperature was higher than a specific “base temperature” (or “cooling change-point”). They are used for calculations relating to the energy consumption required to cool buildings.

Note

It is possible for a building to only have HDD or CDD
It is possible for heating change-points and cooling change-points to be equal
The thermal signature of a building will depend on the presence/absence of HDD and CDD as well as the number of different change-points

Example

Considering a building with a base temperature of 17°C and a single day, let’s say July 1st, with an average outside air temperature at 16°C. So, on July 1st, the mean outside air temperature (16°C) was 1 degree below the base temperature of the building (17°C), and we can work out the heating degree days on that day like so:

degree_days = ( 17 - 16 ) * 1 = 1 degree days

Base temperature

As seen above, the calculation of degree days requires to define a base temperature for both HDD and CDD. If you are not sure which temperatures to use for your building, keep reading.

Base temperature (Tbase) can be physically interpreted as the outdoor temperature at which solar and internal gains offset heat losses (Eto, 1988 [5]).

As can be seen, the base temperature is not easy to calculate. It is different for each building and climatic zone. Anyway, the following table gives different standard values for different countries (Spinoni, Vogt, & Barbosa, 2015)

Country	Base Heating Degree Days	Base Cooling Degree Days	Source
Turkey	14-22°C	28°C	Buyukalaca et al. (2001) [1]
Spain	15°C	21°C	Valor et al. (2001) [13]
Greece	10-20°C	27.5°C	Papakostas et al. (2010) [9]
Canada	18°C	18°C	Wibig (2003) [14]
United States	18.3°C	18.3°C	Wibig (2003) [14]
United Kingdom	15.5°C	22°C	UK Met-Office [12]
France	18°C	18°C	COSTIC [3]

Despite these general references, every Energy Manager can use their own base temperatures (per building, per project, etc) according to specific project needs or previous experience.

Implemented degree days formulas

Depending on provided information, the BuildingEnergyModeling component will calculate degree days using different methods:

Basic
UK Met-Office
COSTIC

Note:

For all the following degree days formulas we have:

Basic

For Heating Degree Days (HDD)

For Cooling Degree Days (CDD)

UK Met-Office

This method was developed by the UK Met-Office in 1928 (CIBSE, 2006)[2], daily Heating Degree Days (HDD) and Cooling Degree Days (CDD) are calculated based on a comparison of daily minimum and maximum air temperatures with the selected base temperature, taking account of fluctuations of daily air temperature around the base temperature, as well as the asymmetry between daily average temperature and diurnal temperature variations. The UK Met-Office equations for computing daily HDD and CDD are shown below (Matzarakis & Balafoutis, 2004)[7] (Spinoni et al., 2018)[11]:

For Heating Degree Days (HDD)

For Cooling Degree Days (CDD)

COSTIC

This method is the standard of the Scientific and Technical Committee of the Climatic Industries of France, also called the Method of Energy Professionals. The Unified Day Degree (Degré jour unifié - DJU) is the difference between the outside temperature and a reference temperature which allows estimates of thermal energy consumption to keep a building comfortable in proportion to the harshness of winter or the heat of the summer. The usual reference of 18°C was defined by considering that the interior temperature of the premises is 19°C and that the free internal (occupants, lighting, equipment, etc.) and external (solar radiation, etc.) supplies cover the equivalent of 1°C of heat loss. They are therefore divided into heating degree-days (DJC) and cooling degree-days (DJF).

There are two methods of calculating DJU giving different results: a method called “météo” (Météo-France, 2017) 8 with simple calculation and a method called “Professionnels de l’énergie” or “COSTIC method” with more elaborate calculation (COSTIC, 2020)[#f3]_. The COSTIC calculation method is the recommended one by the French government (GEM/CC), 2007 6 and it’s the following:

For Heating Degree Days (HDD)

For Cooling Degree Days (CDD)

References

[1] Buyukalaca O, Bulut H, Yilmaz T. 2001. Analysis of variable-baseheating and cooling degree-days for Turkey. Appl. Energy 69 (4): 269–283
[2] CIBSE. 2006. Degree-days: theory and application. Technical Manual41. Chartered Institution of Building Services Engineers: London,UK. ISBN-10: 1-903287-76-6. https://www.cibse.org/knowledge/knowledge-items/detail?id=a0q20000008I73TAAS
[3] COSTIC, « https://www.costic.com/ressources-techniques-et-reglementaires/service-degres-jours-unifies », consulted on (19/02/2020).
[4] Degree Days, 2020. https://www.degreedays.net/calculation, consulted on (20/02/2020)
[5] Eto, J. H. (1988). On using degree-days to account for the effects of weather on annual energy use in office buildings. Energy and Buildings, 113-127. Obtained from https://doi.org/10.1016/0378-7788(88)90073-4
[6] Groupe d’étude des marchés de chauffage et de climatisation (GEM/CC), 2007. Guide de rédaction des clauses techniques des marchés publics d’exploitation de chauffage avec ou sans gros entretien des matériels et avec obligation de résultat: Paris, France, Ministère de l’Économie des Finances et de l’Industrie. Obtained from: https://www.economie.gouv.fr/daj/guide-redaction-des-clauses-techniques-des-marches-publics-dexploitation-chauffage-avec-ou-sans
[7] Matzarakis, A., & Balafoutis, C. (2004). Heating degree-days over Greece as an index of energy consumption. International Journal of Climatology, 1817 - 1828. doi:10.1002/joc.1107
[8] Météo-France, « Degres jours unifies - DJU », Relevés et statistiques, 2017 (consulted on 19/02/2020).
[9] Papakostas, K., Mavromatis, T., & Kyriakis, N. (2010). Impact of the ambient temperature rise on the energy consumption for heating and cooling in residential buildings of Greece. Renewable Energy, 35(7), 1376-1379.
[10] Spinoni, J., Vogt, J., & Barbosa, P. (2015). European degree-day climatologies and trends for the period 1951-2011. International Journal of Climatology, 25-36. doi:10.1002/joc.3959. Obtained from https://rmets.onlinelibrary.wiley.com/doi/full/10.1002/joc.3959
[11] Spinoni, J., Vogt, J. V., Barbosa, P., Dosio, A., McCormick, N., Bigano, A., & Füssel, H. (2018). Changes of heating and cooling degree‐days in Europe from 1981 to 2100, 38, e191–e208. doi:10.1002/joc.5362
[12] UK Met-Office, 2020. http://www.metoffice.gov.uk/
[13] Valor, E., Meneu, V., & Caselles, V. (2001). Daily Air Temperature and Electricity Load in Spain. Journal of Applied Meteorology and Climatology, 1413-1421. Obtained from https://doi.org/10.1175/1520-0450(2001)040%3C1413:DATAEL%3E2.0.CO;2
[14](1,2) Wibig J. 2003. Heating degree days and cooling degree days variabilityin Lodz in the period 1931–2000. In Fifth International Conferenceon Urban Climate. Lodz, Poland

Building calendar

What is a “building calendar”?

A building calendar is the representation of the working process of a building. It means that it gathers days with similar energy consumption profiles e.g.: week days / week-end days.

Example

Following picture represents a building with a calendar constitute by 3 day-groups:

NormalDays: Nominal mode of the building with a 5-parameters.
SaturdaysMondays: Slowed down activity with a 4-parameters.
Sundays: No activity (only basal consumption) with a 2-parameters.

How are building calendar computed?

Warning!

Following informations are true only for the “daily” mode. “Monthly” mode only tolerates one single day group.

Following are described methods used by the BuildingEnergyComponent to compute the building calendar:

Don’t try to improve the building calendar
Try to improve the building calendar

Don’t try to improve the building calendar

If the BuildingEnergyComponent is called with the instruction of not trying to improve the building calendar two scenarios are possible:

The user didn’t provide its own building calendar: In this case all observations are gathered within the same single day group. Only one model is computed.
The user provided its own building calendar: In this case a sub-model (also named day group model) is computed for each day groups. In addition to global model performance metrics, all of these sub-models will all have their own performance metrics computed. Computed sub-models may have different thermal signatures.

Try to improve the building calendar

If the BuildingEnergyComponent is called with the instruction of trying to improve the building calendar two scenarios are possible (same as previously):

The user didn’t provide its own building calendar: In this case the component will try to gather observations according to the day of the week (Monday, Tuesday, Wednesday…). Once week days are gathered within day groups, a sub-model (also named day group model) is computed for each day groups. In addition to global model performance metrics, all of these sub-models will all have their own performance metrics computed. Computed sub-models may have different thermal signatures.
The user provided its own building calendar: In this case the component will try to gather observations according to their associated day group. After that a sub-model (also named day group model) is computed for each day groups. In addition to global model performance metrics, all of these sub-models will all have their own performance metrics computed. Computed sub-models may have different thermal signatures.

Response Codes

We follow the error response format proposed in RFC 7807 also known as Problem Details for HTTP APIs. As with our normal API responses, your client must be prepared to gracefully handle additional members of the response.

The below table defines the HTTP Status codes that this API may return

HTTP Status Code	Error Reason
400 UnknownIdError	The model stored cannot be found with the current model ID.
401 APIKeyMissing	Your request did not include an API key.This error suggests that your API key was missing from your request, or that something was formatted or named improperly in your header. Other reason could be: APIKeyInvalid: Your API key may be invalid, or you've attempted to access the wrong data center. Check that your API key was input correctly, and verify which data center to access.
403 Forbidden	You are not permitted to access this resource. This is a generic error. Other reasons could be: UserDisabled: This account has been disabled. WrongDatacenter: The API key provided is linked to a different data center. This error suggests that you tried to contact the wrong data center. It's often associated with misconfigured libraries.
404 ResourceNotFound	The requested resource could not be found. This error tells you a specific resource doesn't exist. It's possible that the resource has been moved or deleted, or that there's a typo in your request.
422 RequestValidationError	An input is invalid
422 OutdatedModelError	The stored model is outdated.
422 TableConversionError	Provided table cannot be processed. It is probably due to a bad datetime column format.
422 InvalidDatetimeError	Unexpected datetime.
422 SamplingDeclarationError	Datetime column doesn’t fit the expected sampling (1-day).
422 MissingMandatoryColumnError	One or several expected columns of the input table are missing.
422 MandatoryColumnWrongExpectedTypeError	One or several columns have an unexpected type.
422 NotEnoughObservationsErrorModel	Provided input table is empty.
422 DuplicatedTimestampsErrorModel	Datetime column contain one or several duplicated items.
422 NotMonotonicIncreasingTimestampsError	Datetime column is not monotonic increasing.
422 NonUniformSamplingError	Datetime column of the input dataset is not uniform: all time steps encountered are not multiple of the minimal one.
422 InvalidTimedeltaError	Unexpected timesteps in the datetime column. Expected timesteps: modulo 1-day.
422 WrongExpectedTimeDeltaCoverageError	The datetime column contains too many gaps between consecutive records. The expected timesteps (1 day) is observed between less than 75% of rows.
422 WrongNbOfMonthlyObservationsError	Found several energy values for the same month. When temporal resolution is monthly, a single energy value per month is allowed.
422 WrongMonthlyInformationErrorModel	Found an energy value at a date that is not a month start. When temporal resolution is monthly, the mean monthly energy value should be provided in the first day of the month.
422 WrongDayGroupNbError	Found several day group values. When temporal resolution is monthly, day groups do not make sense and should not be used.
422 ModelMigrationError	The model stored cannot be used with the current application version, please re-create a new model.
422 TemporalResolutionRestrictionError	Found configuration incompatibility with Temporal_resolution and other parametersWhen temporal resolution is monthly, improve_calendar and robust_regression cannot be true, and degree_days_mode cannot be in advanced mode
429 TooManyRequests	You have exceeded the limit of 10 simultaneous connections. When you reach the connection limit, we'll throttle the server response. If any of your requests time out after you've reached the limit, those requests could still be considered open and continue to slow your connection.

Deprecation of V1

With effect from Dec 2023, the Building Energy Modeling V1 APIs are deprecated. They are replaced by V2 APIs which run with the latest code and on a new platform. They have more structured request-response format and provide better precision in terms of generating energy consumption preditions. They have the same auth mechanism as V1 so the existing API Key used when calling the V1 APIs will also work for calling the V2 APIs.

If you are currently using V1 APIs then we strongly recommend that you to migrate to V2 APIs. Please refer "Migrating to V2" section for more details.

Migrating to V2

The Building Energy Modeling V2 APIs are built on top of the new backend platform and run with the latest code when compared to V1. They provide better precision in terms of predicting the energy model and offer a better way to structure the request and response payloads, yet provide similar functionality as V1 thereby keeping the migration impact minimal.

The BEM V2 has the following operations:

Create
Apply
Assess quality for savings

Note: The "Get model information" operation(available in V1) has been removed in V2, as essentially it returns the same model information as the Create service.

In order to facilitate easy migration from V1 to V2, a mapping recipe has been prepared that provides a detailed view of request-response paramater mappings. If you need any further help in terms of migration then please do not hesitate to contact us (see Support).

Migrating to BEM API V2.pdf

Support

Contact the SE Exchange support team at exchange.support@se.com and include:

Endpoint URL
Request/Response
Any additional information like Screenshots , Postman collections.

Get help from the community here.

➔ Next to API Specification V1

Overview

API overview and usage

Sandbox

How it works

Create model

Columns configuration

Note:

Note:

DayGroups configuration

Note:

Temporal configuration

Note

Warning!

Computation configuration

Warning!

Note:

RobustRegression

Note:

Warning!

AutoApply

Apply model

Note:

Apply parameters

Note:

Note:

discarded_for_model_creation

Warning!

prediction

prediction_residual

cumulative_prediction_residual, cumulative_savings and cumulative_savings_

Note:

fault_detection_upper_limit and fault_detection_lower_limit

consumption_anomaly

Warning!

midrange_temperature

Warning!

reference_temperature

heating_degree_days__ and __cooling_degree_days

predicted_DRIVER_contribution

Note:

estimated_actual_DRIVER_contribution

Note:

NTS_DRIVER_predicted_energy and NTS_DRIVER_actual_energy

Assess model quality for savings

Documentation

Getting started

Authentication

Create model

Note

Apply model

How to sign up

Table formats

Thermal signature

What is a Thermal signature?

Note:

2-parameters

3-parameters-heating

3-parameters-cooling

4-parameters

5-parameters

Degree days

What are degree days?

Note

Example

Base temperature

Implemented degree days formulas

Note:

Basic

For Heating Degree Days (HDD)

For Cooling Degree Days (CDD)

UK Met-Office

COSTIC

Building calendar

What is a “building calendar”?

Example

Warning!

Response Codes

Deprecation of V1

Migrating to V2

Support

heating_degree_days and cooling_degree_days