Overview

Schneider Electric provides EcoStruxure™ Energy Contextualized Data API for getting time series of energy and their contextualization in the site to understand your energy consumption.

API overview and usage

This API enables the following features:

Sites information

  • Discover Available Sites: Easily find out which sites are available for your customer portfolio.

  • Access In-depth Site Information: Get comprehensive insights into individual sites, including their unique characteristics and features.

Metering Information

  • Overview of Site Meters: Review all the metering devices connected to any given site in your portfolio.

  • Detailed Meter Insights: Fetch granular data for each meter, enabling precise utility tracking and reporting.

Measurement Data

  • Aggregate Site Metrics: Collect a range of measurements for entire sites, providing a comprehensive view of site performance.

  • Meter-Specific Measurements: Access finely-tuned data for individual meters, aiding in more specialized analysis and decision-making.

Energy Consumption and Utilities

  • Active Energy Monitoring: Keep track of active energy metrics for all your sites, supporting informed decisions on energy usage and efficiency.

  • Other Utilities Data: Gain insights into additional utility consumption metrics beyond just electricity, like gas or water, for a holistic view of site operations.

How it works

Listing Sites

The API provides an endpoint for listing all the sites that you have access to. This is useful for initially discovering what site IDs are available for further data extraction.

curl -X GET "https://api.exchange.se.com/ecostruxure/energy-contextualized/v1/sites" \

     -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Fetching Measurements Data for a Specific Site

Once you have a list of site IDs, you can use another API endpoint to fetch the measurements data for a specific site

curl -X GET "https://api.exchange.se.com/ecostruxure/energy-contextualized/v1/sites/YOUR_SITE_ID/measurements" \

     -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

By following these steps, you can programmatically list all the sites available to you and then, using a specific site ID, fetch the corresponding next level of data like meters, measurements, active-energy etc.

Documentation

How to sign up

Step 1: Register or login with an Exchange account.

Step 2: Subscribe to the API product in our Shop.

Step 3: After subscription, API credentials and usage details for the API are available in developer portal.

Authentication guide

This API supports the following authentication mechanism:

OAuth2 Authorization Code Flow

This authorization schema is intended for ISV applications that have obtained authorization from a Schneider Electric customer. Follow the steps below to initiate the authorization process, obtain an access token, and refresh the token as needed.

Step 1: Initiate Authorization and Consent Flow

Firstly, your application should initiate the Authorization and Consent flow by calling the Authorize Endpoint.

curl -X GET "https://api.exchange.se.com/ecostruxure/v1/oauth/authorize" \

     -d "client_id=YOUR_CLIENT_ID" \

     -d "response_type=code" \

     -d "redirect_uri=YOUR_REDIRECT_URI" \

     -d "scope=required_scope1 required_scope2" \

     -d "state=YOUR_STATE_STRING"

Upon successful authorization and user consent, you'll be redirected to the redirect_uri you provided, and an authorization code will be appended as a query parameter.

Step 2: Exchange Authorization Code for Token

Once you have received the authorization code, you need to exchange it for an access token by calling the Token Endpoint.

curl -X POST "https://api.exchange.se.com/ecostruxure/v1/oauth/token" \

     -d "grant_type=authorization_code" \

     -d "code=RECEIVED_AUTHORIZATION_CODE" \

     -d "redirect_uri=YOUR_REDIRECT_URI" \

     -d "client_id=YOUR_CLIENT_ID" \

     -d "client_secret=YOUR_CLIENT_SECRET"

This will return an access_token and a refresh_token.

Step 3: Refresh the Token

Your access_token will be valid for 1 hour. To get a new one without requiring the user to log in again, use the refresh_token.

curl -X POST "https://api.exchange.se.com/ecostruxure/v1/oauth/token" \

     -d "grant_type=refresh_token" \

     -d "refresh_token=YOUR_REFRESH_TOKEN" \

     -d "client_id=YOUR_CLIENT_ID" \

     -d "client_secret=YOUR_CLIENT_SECRET"

By following these steps, your ISV application can securely interact with Schneider Electric's API services, with the proper authorizations in place.

Personal Access Token Flow

This authorization mechanism is intended for end users who are using the API to access their own data in Schneider Electric's ecosystem. Upon purchasing the API, end users can generate a Personal Access Token directly from the Exchange DevPortal.

How to Generate a Personal Access Token

  1. Log in to the Exchange DevPortal.
  2. Navigate to the API product you have subscribed to.
  3. Locate the "Generate Personal Access Token" section and follow the on-screen instructions to create your token.

How to Use the Personal Access Token

Once you have generated your Personal Access Token, you can use it as a Bearer Token to authorize your API calls.

curl -X GET "https://api.exchange.se.com/ecostruxure/energy-contextualized/v1/sites" \

     -H "Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN"

Your Personal Access Token serves as a credential that grants you access to your own data. Ensure that you keep it secure and never share it publicly.

Support

Contact our Exchange support team at exchange.support@se.com and include,

- Endpoint URL

- Request/Response of the URL

- Any additional information like Screenshots, Postman collections

Get help from the community here.