Overview

API overview and usage

This document explain the usage of the Building Energy Modeling API. This API automatically identifies the best thermal model for a building, a plant in order to assess energy savings, to detect abnormal energy consumption. The typical use cases of the API are :

  1. build a baseline model of a building using the “thermal signature” models recommended by ASHRAE and IPMVP,
  2. build a target model using the same mechanism (assuming the user has created simulated target data)
  3. follow-up the baseline and target models of a building – in particular to detect faults and to compute savings 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.

There are five basic types of change point models according to ASHRAE guideline 14, appendix D4 (2 parameters, 3 parameters (heating), 3 parameters (cooling), 4 parameters, 5 parameters).

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

Features

The Building Energy Modeling API includes 4 features:

  1. Create a building energy model (thermal signature of the building) from a dataset containing several drivers (e.g. external temperature) and an energy consumption measure (createModel endpoint).
  2. Apply a previously generated model over a new dataset to forecast the energy consumption out of the provided drivers (applyModel endpoint).
  3. Get metrics telling if a model is good enough to compute savings (assessModelQualityForSavings endpoint).
  4. Get information on an existing model (getModelInformation endpoint).\n\n## How it works\n\n

Hands-on application

Take the tour and experiment on your own data prior to any development through our hands-on application! https://try-analytics-se.azurewebsites.net/bem

Documentation

How to sign up for the API

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.

  1. Select one of the endpoints and click on
  2. Select the Production as the target environment\n\n
  3. Your API key is shown in the Try Out console\n\n

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

createModel endpoint

The createModel endpoint identifies the best daily, weekly or monthly energy model of a building among reference model types (ASHRAE), with automatic time binning and outlier detection.

applyModel endpoint

The applyModel endpoint applies an existing model to new data to estimate the energy that should have been consumed in these conditions. This can be used to detect anomalous consumptions or track progress of energy conservation measures during a retrofit operation.

assessModelQualityForSavings endpoint

This service returns metrics to ensure a model is good enough to compute savings

getModelInformation endpoint

This service returns information on an existing prediction model that is securely stored on the Schneider-Electric platform.

Getting Started

Step 1: Setup environment

Step 2: Prepare Data

Step 3: Create a new energy model

Step 4: Train model

Step 5: Apply an existing forecasting model to new data

Step 6: Get model information on an existing prediction model

Limitations

Amount of calls to the API in the SANDBOX are limited. To get a full experience and extend the thresholds, please subscribe to the API and use the production environment.

Authentification guide

This API uses API keys to authenticate and allow access to the API. Your API keys carry many privileges, so be sure to keep them secure! The API key should be included in all API requests in the Authorization header that looks like the following: | Authorization | your_subscription_key | Please refer the 'How to sign up for the API' section under Developer Guide above to know how to get your subscription key.

Response Codes

We follow the error response format proposed in RFC 7807also 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.

HTTP Status Code Error Reason
400
Bad Request
This is the generic error type for not being able to process the request, and will generally contain an explanation in the message.
Other reasons could be:
Invalid Resource: The submitted POST body failed our input validation. This error may include an additional “errors” property, with a list of the validation issues.
Invalid Action: Returned when you try to access an action on a resource that doesn’t support that action.
JSON Parse Exception: The JSON sent in the request body is not valid JSON.
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.
405
MethodNotAllowed
The requested method and resource are not compatible. See the Allow header for this resource's available methods. This error means that the requested resource does not support the HTTP method you used. Find out which methods are allowed for each resource in the API Reference.
414
ResourceNestingTooDeep
The sub-resource requested is nested too deeply. This uncommon error appears if you've tried to generate a URL with too many resources.
422
InvalidMethodOverride
This error lets you know you've tried to override an incompatible method. You can only use the X-HTTP-Method-Override header with the POST method.
Other reasons could be:
RequestedFieldsInvalid: The fields requested from this resource are invalid.This error suggests there is a typo in your field request or some other type of syntax error or problem that invalidates your request.
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.
500
InternalServerError
An unexpected internal error has occurred. This error lets you know RP-C has experienced a problem.
503
ComplianceRelated
This method has been disabled.

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.

Authentication

Authentication is the act of proving an assertion, such as the identify of a computer system user.

Security scheme type API Key
Header parameter name Authorization
In contrast with identification, the act of indicating a person or thing's identity, authentication is the process of verifying that identify.