HPE Sustainability Insight Center developer guide

The details and examples in this guide will help you get started using the HPE Sustainability Insight Center API for HPE GreenLake cloud.

Prerequisites

Hostname

When forming an HPE Sustainability Insight Center REST API call, choose the hostname that is closest to your region:

• https://us-west.api.greenlake.hpe.com
• https://ap-northeast.api.greenlake.hpe.com
• https://eu-central.api.greenlake.hpe.com

Endpoints

The URIs for the HPE Sustainability Insight Center API endpoints are as follows:

• GET /sustainability-insight-ctr/v1beta1/usage-by-entity
• GET /sustainability-insight-ctr/v1beta1/usage-totals
• GET /sustainability-insight-ctr/v1beta1/usage-series
• GET /sustainability-insight-ctr/v1beta1/cloud-usage-by-entity
• GET /sustainability-insight-ctr/v1beta1/cloud-usage-totals
• GET /sustainability-insight-ctr/v1beta1/cloud-usage-series
• GET /sustainability-insight-ctr/v1beta1/coefficients
• POST /sustainability-insight-ctr/v1beta1/coefficients
• GET /sustainability-insight-ctr/v1beta1/coefficients/{id}
• GET /sustainability-insight-ctr/v1beta1/ingests
• POST /sustainability-insight-ctr/v1beta1/ingests
• GET /sustainability-insight-ctr/v1beta1/ingests/{id}
• GET /sustainability-insight-ctr/v1beta1/datasources
• GET /sustainability-insight-ctr/v1beta1/datasources/{id}

Permissions

Any user with access to the HPE Sustainability Insight Center application has access to both the UI and the API.

Generating a token

You must configure API credentials and generate an access token to make API calls. HPE GreenLake APIs use OAuth-based access tokens used as an authorization bearer token.

To access this HPE GreenLake Sustainability Insight Center API, proceed as follows:

1. Connect to the HPE GreenLake cloud UI workspace.
2. Go to Manage Workspace > Personal API clients > Create personal API client.
3. Select  HPE Sustainability Insight Center in the Service drop-down to create the credentials and then generate access tokens for the HPE Sustainability Insight Center API. If you do not see HPE Sustainability Insight Center as an option when configuring API client credentials, see the Getting Started Guide for more information.

Getting an access token

Run the cURL command below to get the token from the response["access_token"]:

curl -X POST https://sso.common.cloud.hpe.com/as/token.oauth2 -H
"Content-Type: application/x-www-form-urlencoded"
-d "grant_type=client_credentials&client_id=$YOUR_CLIENT_ID&client_secret=$YOUR_CLIENT_SECRET"

This access token is used as the bearer token for the authentication of the HPE Sustainability Insight Center API. The token is valid for two hours.

Making it all work

Getting energy usage grouped by entity

Run the below API call with the bearer token from the previous step to get energy usage data related to your workspace. The start-time and end-time query parameters are required. The start-time and end-time query parameters must be in ISO 8601 format, for example 2019-10-12T07:20:50.529Z.

GET '{{HOSTNAME}}/sustainability-insight-ctr/v1beta1/usage-by-entity?start-time={{START_TIME}}&end-time={{END_TIME}}&offset=0'

Sample API response:

{
  "items": [
    {
      "id": "COMPUTE1234567",
      "type": "sustainability-insight-ctr/entities",
      "entityId": "COMPUTE1234567",
      "entityMake": "HPE",
      "entityModel": "PROLIANT DL380 GEN10",
      "entityType": "COMPUTE",
      "entitySerialNum": "1234567",
      "entityProductId": "7654321",
      "entityManufactureTimestamp": "2023-11-01T00:00:00.000Z",
      "locationName": "Somewhere",
      "locationId": "00000000-0000-0000-0000-000000000000",
      "locationCity": "Boston",
      "locationState": "MA",
      "locationCountry": "USA",
      "tags": [
        {
          "name": "OS",
          "value": "Linux"
        }
      ],
      "name": "",
      "cost": 100.1234,
      "costUsd": null,
      "currency": "USD",
      "co2eMetricTon": 0.6,
      "kwh": 700.1234
    }
  ],
  "count": 1,
  "offset": 0,
  "total": 1
}

This call can be filtered using the filter query parameter. Refer to filtering for more details.

This call can also be filtered by tags using the filter-tags query parameter. Refer to Filtering tags for more details.

This call can be provided a currency currency code query parameter to change the returned currency type. Refer to Currency for more details.

Other supported API parameters are sort, offset and limit.

Returned field costUsd is deprecated in favor of cost.

Getting energy usage totals

This endpoint is for getting the total aggregated energy usages across all entities for the defined time frame. The start-time and end-time query parameters are required. The start-time and end-time query parameters must be in ISO 8601 time format, for example 2019-10-12T07:20:50.52934852Z.

GET '{{HOSTNAME}}/sustainability-insight-ctr/v1beta1/usage-totals?start-time={{START_TIME}}&end-time={{END_TIME}}'

Sample API response:

{
  "items": [
    {
      "type": "sustainability-insight-ctr/totals",
      "cost": 100.1234,
      "costUsd": null,
      "currency": "USD",
      "co2eMetricTon": 0.5,
      "kwh": 700.1234
    }
  ],
  "count": 1
}

This example response returns one result ("count": 1) and returns the following data:

• cost—The estimated energy cost.
• co2eMetricTon—Carbon dioxide equivalent estimated in metric tons.
• kwh—Energy consumption in kilowatts per hour.
• currency—The returned cost currency type.

This call can be filtered using the filter query parameter. Refer to filtering for more details.

This call can also be filtered by tags using the filter-tags query parameter. Refer to Filtering tags for more details.

This call can be provided a currency currency code query parameter to change the returned currency type. Refer to Currency for more details.

Returned field costUsd is deprecated in favor of cost.

Getting energy usage series data

This endpoint is for getting energy usages across all entities grouped by time bucket for the defined time frame. The start-time, end-time, and interval query parameters are required. Behavior is non-deterministic if the time range does not divide evenly by your selected interval.

GET '{{HOSTNAME}}/sustainability-insight-ctr/v1beta1/usage-series?start-time={{START_TIME}}&end-time={{END_TIME}}&interval={{INTERVAL}}'

Sample API response:

{
  "items": [
    {
      "id": "2024-01-18T00:00:00.000Z",
      "type": "sustainability-insight-ctr/timeseries",
      "timeBucket": "2024-01-18T00:00:00.000Z",
      "cost": 0,
      "currency": "USD",
      "costUsd": null,
      "co2eMetricTon": 0,
      "kwh": 0
    },
    {
      "id": "2024-01-19T00:00:00.000Z",
      "type": "sustainability-insight-ctr/timeseries",
      "timeBucket": "2024-01-19T00:00:00.000Z",
      "cost": 50.01234,
      "currency": "USD",
      "costUsd": null,
      "co2eMetricTon": 0.25,
      "kwh": 345.321
    }
  ],
  "count": 2
}

This example response returns two results ("count": 2).

The interval query parameter must be of the format "integer unit". Valid units are day(s), hour(s), week(s), month(s), and year(s), for example, 1 day, 2 hours, 6 week, 18 month, and 3 year. The example response shows an interval of 1 day as the "id:" and "timeBucket" increase by one day (2024-01-18T00:00:00.000Z and 2024-01-19T00:00:00.000Z).

• timeBucket—A time bucket is a feature of time series analysis and forecasting. It is the time interval between successive measurements or values. In the example response, the timeBucket interval is 1 day and the measures for costUsd. co2eMetricTon, and kwh are daily totals.
• cost—The estimated energy cost.
• co2eMetricTon—Carbon dioxide equivalent estimated in metric tons.
• kwh—Energy consumption in kilowatts per hour.
• currency—The returned cost currency type.

This call can be filtered using the filter query parameter. Refer to filtering for more details.

This call can also be filtered by tags using the filter-tags query parameter. Refer to Filtering tags for more details.

This call can be provided a currency currency code query parameter to change the returned currency type. Refer to Currency for more details.

Returned field costUsd is deprecated in favor of cost.

Getting public cloud sustainability data grouped by entity

Run the below API call to get public cloud sustainability data related to your workspace. The start-time and end-time query parameters are required. The start-time and end-time query parameters must be in ISO 8601 format, for example 2019-10-12T07:20:50.529Z.

GET '{{HOSTNAME}}/sustainability-insight-ctr/v1beta1/usage-by-entity?start-time={{START_TIME}}&end-time={{END_TIME}}&offset=0'

Sample API response:

{
  "items": [
    {
      "id": "COMPUTE1234567",
      "type": "sustainability-insight-ctr/cloud-entities",
      "serviceProvider": "aws",
      "serviceName": "s3",
      "serviceRegion": "us-east",
      "serviceAccount": "123456789012",
      "name": "",
      "co2eMetricTon": 0.6
    }
  ],
  "count": 1,
  "offset": 0,
  "total": 1
}

This call can be filtered using the filter query parameter. Refer to filtering for more details.

Other supported API parameters are sort, offset, and limit.

Getting public cloud sustainability data totals

This endpoint is for getting the total aggregated public cloud sustainability data across all entities for the defined time frame. The start-time and end-time query parameters are required. The start-time and end-time query parameters must be in ISO 8601 time format, for example 2019-10-12T07:20:50.52934852Z.

GET '{{HOSTNAME}}/sustainability-insight-ctr/v1beta1/usage-totals?start-time={{START_TIME}}&end-time={{END_TIME}}'

Sample API response:

{
  "items": [
    {
      "type": "sustainability-insight-ctr/cloud-totals",
      "co2eMetricTon": 0.5
    }
  ],
  "count": 1
}

This example response returns one result ("count": 1) and returns the following data:

• co2eMetricTon—Carbon dioxide equivalent estimated in metric tons.

This call can be filtered using the filter query parameter. Refer to filtering for more details.

Getting public cloud sustainability series data

This endpoint is for getting public cloud sustainability data across all entities grouped by time bucket for the defined time frame. The start-time, end-time, and interval query parameters are required. Behavior is non-deterministic if the time range does not divide evenly by your selected interval.

GET '{{HOSTNAME}}/sustainability-insight-ctr/v1beta1/cloud-usage-series?start-time={{START_TIME}}&end-time={{END_TIME}}&interval={{INTERVAL}}'

Sample API response:

{
  "items": [
    {
      "id": "2024-01-01T00:00:00.000Z",
      "type": "sustainability-insight-ctr/cloud-timeseries",
      "timeBucket": "2024-01-01T00:00:00.000Z",
      "co2eMetricTon": 0
    },
    {
      "id": "2024-02-01T00:00:00.000Z",
      "type": "sustainability-insight-ctr/cloud-timeseries",
      "timeBucket": "2024-02-01T00:00:00.000Z",
      "co2eMetricTon": 6.25
    }
  ],
  "count": 2
}

This example response returns two results ("count": 2).

The interval query parameter must be of the format "integer unit". Valid units are hour, hours, day, days, week, weeks, month, months, year, and years, for example, 1 day, 2 hours, 6 week, 18 month, and 3 year. The example response shows an interval of 1 month as the "id:" and "timeBucket" increase by one day (2024-01-01T00:00:00.000Z and 2024-02-01T00:00:00.000Z).

• timeBucket—A time bucket is a feature of time series analysis and forecasting. It is the time interval between successive measurements or values. In the example response, the timeBucket interval is 1 day and the measures for costUsd. co2eMetricTon, and kwh are daily totals.
• co2eMetricTon—Carbon dioxide equivalent estimated in metric tons.

This call can be filtered using the filter query parameter. Refer to filtering for more details.

Getting cost and CO₂ coefficients

This endpoint is for getting previously defined cost and CO₂ coefficients.

GET '{{HOSTNAME}}/sustainability-insight-ctr/v1beta1/coefficients'

Sample API response:

{
  "items": [
    {
      "id": "00000000-0000-0000-0000-0000000000000",
      "type": "sustainability-insight-ctr/coefficient",
      "associatedLocation": {

        "locationId": "00000000-0000-0000-0000-000000000000",
        "locationName": "Denver, CO",
        "resourceUri": "/locations/v1beta1/locations/00000000-0000-0000-0000-0000000000000"
      },
      "startTime": "2024-01-01T00:00:00.000Z",
      "co2eGramsPerKwh": 0.5,
      "costUsdPerKwh": null,
      "costPerKwh": 0.5,
      "currency": "USD",
      "generation": 0,
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-02-01T00:00:00.000Z"
    }
  ],
  "count": 1,
  "offset": 0,
  "total": 1
}

This call can be filtered using the filter query parameter. The only field available to filter on is locationId. Refer to filtering for more details.

This call can also be filtered by tags using the filter-tags query parameter. Refer to Filtering tags for more details.

This call can be provided a currency currency code query parameter to change the returned currency type. Refer to Currency for more details.

Other supported API parameters are offset and limit.

Returned field costUsdPerKwh is deprecated in favor of costPerKwh.

Setting cost and CO₂ coefficients

This endpoint is for setting cost and CO₂ coefficients for your workspace. This endpoint requires the HPE Sustainability Insight Center Administrator Role. You must provide a location URI as locationId. If you exclude co2eGramsPerKwh or costPerKwh, its behavior is the same as including it with useCurrent set to true.

• useDefault - Set to true if you want to use the default value determined by HPE. This cannot be true if useCurrent is true.
• useCurrent - Set to true if you want to keep whatever was previously set for this coefficient. This cannot be true if useDefault is true.
• value - A floating point number to be used as the coefficient starting the next day, as long as useDefault and useCurrent are both false.
• currency - In the case of the costPerKwh, you can provide a currency code to specify the type of cost. Refer to Currency for more details.

Input field costUsdPerKwh is deprecated in favor of costPerKwh.

POST '{{HOSTNAME}}/sustainability-insight-ctr/v1beta1/coefficients'

Sample payload:

{
  "locationId": "/locations/v1beta1/locations/00000000-0000-0000-0000-0000000000000",
  "co2eGramsPerKwh": {
    "useDefault": false,
    "useCurrent": false,
    "value": 0.1
  },
  "costUsdPerKwh": null,
  "costPerKwh": {
    "useDefault": false,
    "useCurrent": false,
    "value": 0.1,
    "currencyCode": "USD"
  }
}

If this POST call succeeds, the API returns a 201 Created response with the created coefficient. This response contains the exact startTime that the coefficient will begin taking effect. Here is an example:

{
  "id": "00000000-0000-0000-0000-0000000000000",
  "type": "sustainability-insight-ctr/coefficient",
  "associatedLocation": {
    "locationId": "00000000-0000-0000-0000-000000000000",
    "locationName": "Denver, CO",
    "resourceUri": "/locations/v1beta1/locations/00000000-0000-0000-0000-0000000000000"
  },
  "startTime": "2024-01-02T00:00:00.000Z",
  "co2eGramsPerKwh": 0.5,
  "costUsdPerKwh": null,
  "costPerKwh": 0.5,
  "currency": {
    "currencyCode": "USD",
    "currencyName": "United States Dollar"
  },
  "generation": 0,
  "createdAt": "2024-01-01T12:00:00.000Z",
  "updatedAt": "2024-01-01T12:00:00.000Z"
}

Returned field costUsdPerKwh is deprecated in favor of costPerKwh.

Getting a specific cost and CO₂ coefficient by ID

This endpoint is for getting a single cost and CO₂ coefficient.

GET '{{HOSTNAME}}/sustainability-insight-ctr/v1beta1/coefficients/00000000-0000-0000-0000-0000000000000'

Sample API response:

{
  "id": "00000000-0000-0000-0000-0000000000000",
  "type": "sustainability-insight-ctr/coefficient",
  "associatedLocation": {
    "locationId": "00000000-0000-0000-0000-000000000000",
    "locationName": "Denver, CO",
    "resourceUri": "/locations/v1beta1/locations/00000000-0000-0000-0000-0000000000000"
  },
  "startTime": "2024-01-01T00:00:00.000Z",
  "co2eGramsPerKwh": 0.5,
  "costPerKwh": 0.5,
  "currency": {
    "currencyCode": "USD",
    "currencyName": "United States Dollar"
  },
  "costUsdPerKwh": null,
  "generation": 0,
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-02-01T00:00:00.000Z"
}

Returned field costUsdPerKwh is deprecated in favor of costPerKwh.

Getting metadata on uploaded device measurements

This endpoint is for getting the metadata related to any user uploaded device measurements.

GET '{{HOSTNAME}}/sustainability-insight-ctr/v1beta1/ingests'

Sample API response:

{
  "items": [
    {
      "id": "00000000-0000-0000-0000-0000000000000",
      "type": "sustainability-insight-ctr/ingest",
      "name": "Example Data",
      "description": "This data is blah blah blah",
      "generation": 0,
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-02-01T00:00:00.000Z"
    }
  ],
  "count": 1,
  "offset": 0,
  "total": 1
}

This call supports the API parameters offset and limit.

Uploading device measurements

This endpoint is for users to upload their own device measurements to HPE Sustainability Insight Center. The upload must be .csv file and match the HPE Sustainability Insight Center third party data template. You can find the template on the HPE Sustainability Insight Center UI on the Data Configuration > Data Import page. The maximum size allowed for a single upload is 300MB. This endpoint requires the HPE Sustainability Insight Center Administrator Role.

POST '/sustainability-insight-ctr/v1beta1/ingests' -F name="Example Name" -F description="Blah blah blah" -F file=@measurements.csv

Form data payload:

name="Example Name"
description="Blah blah blah"
file=@measurements.csv

Getting metadata on uploaded device measurements by ID

This endpoint is for getting a metadata on a single device measurement upload.

GET '{{HOSTNAME}}/sustainability-insight-ctr/v1beta1/ingests/00000000-0000-0000-0000-0000000000000'

Sample API response:

{
  "id": "00000000-0000-0000-0000-0000000000000",
  "type": "sustainability-insight-ctr/ingest",
  "name": "Example Data",
  "description": "This data is blah blah blah",
  "generation": 0,
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-02-01T00:00:00.000Z"
}

Getting data sources

This endpoint is for getting the list of all HPE Sustainability Insight Center data sources.

GET '{{HOSTNAME}}/sustainability-insight-ctr/v1beta1/datasources'

Sample API response:

{
  "items": [
    {
      "id": "00000000-0000-0000-0000-0000000000000",
      "type": "sustainability-insight-ctr/datasources",
      "name": "HPE Aruba Central",
      "provider": "HPE",
      "lastCollectionTime": "2024-05-28T00:00:00.000Z",
      "firstCollectionTime": "2024-02-29T00:00:00.000Z",
      "generation": 0,
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-02-01T00:00:00.000Z"
    }
  ],
  "count": 1,
  "offset": 0,
  "total": 1
}

Getting a single data source

This endpoint is for getting the details of a single data source by id.

GET '{{HOSTNAME}}/sustainability-insight-ctr/v1beta1/datasources/{id}'

Sample API response:

{
  "id": "00000000-0000-0000-0000-0000000000000",
  "type": "sustainability-insight-ctr/datasources",
  "name": "HPE Aruba Central",
  "provider": "HPE",
  "lastCollectionTime": "2024-05-28T00:00:00.000Z",
  "firstCollectionTime": "2024-02-29T00:00:00.000Z",
  "generation": 0,
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-02-01T00:00:00.000Z"
}

Filtering

Filters allow you to limit the entities involved in the REST call. They are specified using the query parameter filter. The following fields can be filtered for regular entities:

• entityId
• entityMake
• entityModel
• entityType
• entitySerialNum
• entityProductId
• locationName
• locationId
• locationCity
• locationState
• locationCountry
• name

The following fields can be filtered for cloud entities:

• entityId
• serviceProvider
• serviceName
• serviceRegion
• serviceAccount
• name

Requirements

• Queries will be separated by and.

• Queries will have 'equality', 'contains', and 'in' comparison.

• Each query must follow the format below for different operators.

  • key eq 'value' for an 'equality' operation.
  • contains(key, 'value') for a 'contains' operation.
  • key in ('value1', 'value2') for an 'in' operation.

Filtering on a single property

Here is a simple example of filtering energy usage data based on an entity model:

GET <URI>?filter=entityModel eq 'PROLIANT DL380 GEN10'

In this example, the API call only returns data from the entities with the model of ProLiant DL380 Gen10.

Property is the name of an attribute in the requested resource type, for example, flag. The property name is always to the left of the operation. Specify nested property names with the / separator.

The following example of the possible filter values use the GET Usage by Entity endpoint.

Operations compare properties against literals, for example, eq. All parameters require the property on the left and the literal on the right.

Examples of operations:

A literal is what an operation compares a property to. For a successful matching operation, the data types must match, and the syntax determines the data type of the literals. Since our API only supports string filters at this time, this means the literal must be a string literal. String literals are anything inside 'single quotes'. Due to URL encoding, reserved characters ! # $ & ' ( ) * + , / : ; = ? @ [ ] in string literals must be replaced with percent-encoded equivalents.

Composite filtering on multiple properties

The previous section explained queries for filtering on a single property. However, the logical operations enable more elaborate filtering using multiple queries. Currently, filtering supports combining multiple operations using the 'and' operator.

• Require both (and): entityMake eq 'HPE' and locationCity eq 'Boston'

OData filtering reference

This filtering is a subset of OData 4.0 filtering.

Filtering tags

Similar to filter, the filter-tags query parameter allows you to limit the entities involved in a REST call based on their tags. You can filter based on a tag's key and value, case-insensitive.

Requirements

• Separate multiple tag filter queries with and.

• The only comparison available for tag filters is 'equality'.

• Each query must follow the format below.

  • 'key' eq 'value' for an 'equality' operation.

Filtering on a single tag

Here is a simple example of filtering energy usage data based on an entity model:

GET <URI>?filter-tags='OS' eq 'Linux'

In this example, the API call only returns data from the entities tagged with the Linux operating system.

Operations compare tag keys against tag values using the eq equality operation. All parameters require the tag key on the left and the tag value on the right.

Examples of operations:

The type of all tag keys and values is string literal. String literals are anything inside 'single quotes'. Due to URL encoding, reserved characters ! # $ & ' ( ) * + , / : ; = ? @ [ ] in string literals must be replaced with percent-encoded equivalents.

Composite filtering on multiple properties

The previous section explained queries for tag filtering on a single tag. However, the logical operations enable more elaborate tag filtering using multiple queries. Currently, tag filtering supports combining multiple operations using the 'and' operator.

• Require both (and): 'type' eq 'business' and 'OS' eq 'Linux'

OData filtering reference

This filtering is a subset of OData 4.0 filtering.

Currency

Several endpoints allow you to specify the currency type for your input values or the currency type for the returned values. Valid values for the currency are case-insensitive, 3-letter currency codes, such as USD for the United States Dollar.

The following table shows all supported currency codes and their expanded name.

At the start of each day, a currency conversion rate is calculated for each currency and used to convert any values collected for that day.