Overview

EcoStruxure™ Facility Expert Data API has been designed to give you access to the key data of your buildings and equipment:

  • Energy and comfort data to improve energy performance and sustainability of your entire buildings portfolio and to ensure comfort of occupants

  • Key processes and equipment instant data to prevent downtime and to enhance its reliability

Ensure business continuity of your key equipment

In the event of an equipment fault, you can easily be notified and access to the instant data from your connected equipment for remote analysis


Improve energy efficiency and sustainability of your building portfolio

Gain visibility on relevant energy data to reduce your consumption and improve your building's performance.


API overview and usage

This document explains the usage of the Facility Expert API. This allows you to get instant data from your equipment / buildings connected to the Facility Expert cloud:

Sites information and assets topology:

  • Site information, including devices topology and measurements
  • The assets dataset contains the topology of assets within each site

Time series:

  • Room comfort data: zone temperature, humidity, CO2
  • Energy consumption: active energy (kWh), reactive energy (kVar)
  • Electrical parameters: voltage, power demand and frequency
  • LV switchboard / MV switchgear condition data: thermal and hygrometry monitoring

Alarms/alerts:

  • Room comfort alarms/alerts
  • Load status and alerts: power loss, overload, load stop, trip
  • Phase loss and/or voltage loss alert
  • Cable overheating
  • And many other pre-configured alarms for low voltage/ medium voltage Schneider Electric equipment

Please note that you need to be pre-authorized by Schneider-Electric to use this API. This document provides a general tutorial for users who want to consume the Facility Expert API.

How it works

Thanks to this API, a Schneider Electric customer/partner can remotely access to the near real time energy, equipment and room comfort data collected in the Facility Expert cloud.

Prior to accessing the data, connected architecture compatible with Facility Expert need to be installed and commissioned on site.

In a site there could be one or several gateways / controllers and connected architectures, depending of the complexity of the installation.

Before configuring the Facility Expert API you need to:

  1. Order a Facility Expert subscription allowing to access the API

  2. Activate the service on top of the connected architectures using Facility Expert app

  3. Then let’s use the following documentation to configure the API.

Documentation

How to sign up

Before you can sign up for the Facility Expert API, you must register or login with an Exchange account. Then you can subscribe to the API product in our Shop and you can read about Terms & Conditions. After subscription, you will receive further information on how to access the API including the API Key.

Authentication guide

This API requires 2 keys to authenticate and allow access to the API.

  1. SE Exchange API Subscription Key:

    This key is delivered once the subscription to the API has been approved. This key should be included in all API requests in the Authorization header that looks like the following:

    | Authorization: your_subscription_key

  2. Facility Expert Technical Token:

    This token will be delivered by the Facility Expert technical team once subscription request to the API is accepted.
    This token grants the partner access to the data of the program requested from the API.

    There is no link between this technical token and the subscription key.

    This key should be included in all API requests in the apiKey header that looks like the following:

    apikey: <**api_key**>

    Your API keys carry many privileges, so be sure to keep them secure!

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.

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.

Get help from the community here.

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.