Quick Start¶

Getting started with using Energy APIs involves the following steps:

1. Create an account and a machine user
2. Create a JSON Web Token (JWT) by using the machine user credentials
3. Make API requests using the JWT

Create an account and a machine user¶

The Getting Started page documents the required steps to get a hold of the clientId, clientSecret and partitionId.

Create a token¶

Use the values described in the Authorization section to construct the Create Token request.

Example request¶

export CLIENT_ID=<YOUR_CLIENT_ID>
export CLIENT_SECRET=<YOUR_CLIENT_SECRET>

curl https://siemens-bt-015.eu.auth0.com/oauth/token \
  -H 'content-type: application/json' \
  -d "{
            \"client_id\":\"$CLIENT_ID\",
            \"client_secret\":\"$CLIENT_SECRET\",
            \"audience\":\"https://horizon.siemens.com\",
            \"grant_type\":\"client_credentials\"
      }"

To run this example yourself, set the CLIENT_ID and CLIENT_SECRET first.

Example response¶

{
  "access_token": "eyJ0eXAiOiUSJ9.eyJpc3MiOiJdGlhbHMifQ.MJpcxLfyOt",
  "token_type": "Bearer",
  "expires_in": 86400
}

The token, or JWT (JSON Web Token), is the value of the access_token-property in the response. You can now use it by passing it in the Authorization-header of any subsequent API requests. The expires_in-property represents the number of seconds your token is valid, usually, the value corresponds to 24 hours. When this time has elapsed you will need to create a new token.

Now you have all you need to start using the API. As a last step of preparation set the token and partitionId as environmental variables.

export PARTITION=<YOUR_PARTITION_ID>
export TOKEN=<YOUR_TOKEN>

Make API requests¶

This guide will take you through the steps you need to perform to extract your energy consumption, emission, or cost data for a location or a meter in the granularity and for the period of interest.

List Medium consumptions¶

The first step to perform is to list the medium consumptions in your partition. This you can do by performing the Get list of medium consumptions operation.

curl -H "Authorization: Bearer $TOKEN" \
    "https://api.bpcloud.siemens.com/energy/partitions/$PARTITION/medium-consumptions"

The response contains all location and equipment related medium consumptions in your partition.

Select the id property of one of the medium consumption in the response and set it in an environmental variable. E.g. if the id is 8db4216d-61c5-4e79-8558-164aa179bfe9 then set it using the following command:

export MEDIUM_CONSUMPTION=8db4216d-61c5-4e79-8558-164aa179bfe9

Read Consumption per location or meter(equipment)¶

Read consumption of location or meter(equipment) is possible by related medium consumption ID(how to get it is described in first step). This is achieved by using the Get consumption values of medium consumption operation.

curl -H "Authorization: Bearer $TOKEN" \
    "https://api.bpcloud.siemens.com/energy/partitions/$PARTITION/medium-consumptions/$MEDIUM_CONSUMPTION/consumption?from=2023-01-01T00:00Z&to=2023-02-01T00:00Z&unit=unit:KiloW&interval=1d"

The response contains a list of consumption items(with granularity by interval) for requested unit and time range.

Read Cost per location or meter(equipment)¶

Read cost of location or meter(equipment) is possible by related medium consumption ID(how to get it is described in first step). This is achieved by using the Get cost values of medium consumption operation.

curl -H "Authorization: Bearer $TOKEN" \
    "https://api.bpcloud.siemens.com/energy/partitions/$PARTITION/medium-consumptions/$MEDIUM_CONSUMPTION/cost?from=2023-01-01T00:00Z&to=2023-02-01T00:00Z&unit=cur:USD&interval=1d"

The response contains a list of cost items(with granularity by interval) for requested unit and time range.

Read Emission per location¶

Read Emission of location is possible by related medium consumption ID(how to get it is described in first step). This is achieved by using the Get emission values of medium consumption operation.

curl -H "Authorization: Bearer $TOKEN" \
    "https://api.bpcloud.siemens.com/energy/partitions/$PARTITION/medium-consumptions/$MEDIUM_CONSUMPTION/emission?from=2023-01-01T00:00Z&to=2023-02-01T00:00Z&unit=unit:KiloGM&interval=1d"

The response contains a list of emission items(with granularity by interval) for requested unit and time range.

Note for usage:
Today's solution cannot yet identify the exact point of a meter reflecting its energy consumption for the case that multiple data points are assigned to one meter. Using the Energy API is limited to the assumption that only one data point is assigned to a meter which then can be identified via Equipment endpoints.

Community

Connect and Collaborate with Industrial Professionals and Join the Community!