Archived content

Archive date: 2026-01-01

This content is no longer being updated or maintained. The content is provided “as is.” Given the rapid evolution of technology, some content, steps, or illustrations may have changed.

THE IBM Envizi ESG Suite is a Software-as-a-Service (SaaS) offering that consolidates enterprise environmental, social, and governance (ESG) data for analysis and reporting. It helps you simplify the capture, consolidation, management, analysis, and reporting of your ESG data.

This article provides an overview of the different Envizi APIs, and explains how to use them to get data from Envizi to feed into external systems. Envizi provides APIs that let you:

Retrieve report names
Retrieve report parameters
Retrieve report data

To follow the information in this article, you must have access to the IBM Envizi ESG Suite. If you do not have access, you can get a 14-day IBM Envizi ESG Suite trial.

API URLS

The Envizi APIs are web service APIs, and the URLs always start with the following:

For Australia, New Zealand and ASEAN users: https://auapi.envizi.com/api
For US and Canada users: https://usapi.envizi.com/api
For UK and South African users: https://ukapi.envizi.com/api

The Envizi APIs use a basic access authentication method, and you can use the existing Envizi login and password for the API authentication.

Steps

Retrieve report names

The meta API option lets you see the list of reports that are available for you to download based on your login. The report names that are retrieved are the reports that can be used with all other report meta and data API calls. Typically, this is one of the initial queries to be run when setting up your application to work with the Envizi APIs.

Sample URL

The sample URL looks like: https://ukapi.envizi.com/api/meta.

Sample code

The following code example uses the meta API to pull the report names.

export API_USER=<<USER>>
export API_PASSWORD=<<PASSWORD>>
export API_REGION=<<REGION>>

export API_SUFFIX=api.envizi.com/api
export API_USER_PASSWORD="$API_USER:$API_PASSWORD"
export API_URL="https://$API_REGION$API_SUFFIX/meta"

curl -u $API_USER_PASSWORD "$API_URL"

In this code:

<<USER>> is the Envizi login ID.
<<PASSWORD>> is the Envizi password.
<<REGION>> is the value based on your region, for example, uk, au, or us.

Sample output

The sample output from the previous API call is provided in the meta.json file.

The following image highlights the important reports.

Important reports

Retrieve report parameters

Envizi provides a reports meta API to retrieve the list of available parameter names and the IDs for the specified report. This helps you understand what parameters you can use to filter the report data while using the API.

For example, the parameters can be:

Group_Id
Location_Id
Utility_Type_Id
Currency_Id
Period : { 1, 3, 6, 9, 12, 24, 36, 48, 60} - How many months of data from the given end period
End_Period End period of the data, for example, 2023/04/30

Sample URL

The sample URLs look like:

https://ukapi.envizi.com/api/meta/reports/<<REPORT_NAME>
https://ukapi.envizi.com/api/meta/reports/_Envizi-SetupLocations

Sample code

The following code example shows how to use the report meta API to pull the report parameters.

export API_USER=<<USER>>
export API_PASSWORD=<<PASSWORD>>
export API_REGION=<<REGION>>

export REPORT_NAME=_Envizi-SetupLocations

export API_SUFFIX=api.envizi.com/api
export API_USER_PASSWORD="$API_USER:$API_PASSWORD"
export API_URL="https://$API_REGION$API_SUFFIX/meta/reports/$REPORT_NAME"

curl -u $API_USER_PASSWORD "$API_URL"

In this code, the <report_name> is any report name that is taken from the previously retrieved meta.json file. This article uses the _Envizi-SetupLocations to get location parameters.

Sample output

The sample output of the previous API call is provided in the report-parameters.json file. There are three parameters (Group_Id, Location_Id, and Filter_By), and their available values are found in the report. The following image shows the report parameters.

Report parameters

Retrieve report data

Envizi provides a reports data API to retrieve data from a given report. You can pass report filter parameters along with the API to get filtered data.

Sample URLs

The following URLs show examples of the URLs with or without parameters.

Without parameters

    https://ukapi.envizi.com/api/data/<<REPORT_NAME>
    https://ukapi.envizi.com/api/data/_Envizi-SetupLocations

With the Group_Id parameter

    https://ukapi.envizi.com/api/data/<<REPORT_NAME>>?<<PARAM_NAME1>>=<<PARAM_VALUE1>>
    https://ukapi.envizi.com/api/data/_Envizi-SetupLocations?Group_Id=12345

With the Period, End_Period, and Location_Id parameters

    https://ukapi.envizi.com/api/data/_Envizi-MonthlyDataSummary?Period=1&End_Period=2023/03/31&Location_Id=5003114

Sample code

The following code example shows how to use theg report data API to pull the report data.

export API_USER=<<USER>>
export API_PASSWORD=<<PASSWORD>>
export API_REGION=<<REGION>>

export REPORT_NAME=_Envizi-SetupLocations
export GROUP_ID=5037106

export API_SUFFIX=api.envizi.com/api
export API_USER_PASSWORD="$API_USER:$API_PASSWORD"
export API_URL="https://$API_REGION$API_SUFFIX/data/$REPORT_NAME?Group_Id=$GROUP_ID"

curl -u $API_USER_PASSWORD "$API_URL"

In this code example:

REPORT_NAME is the name of the report for which you need to retrieve data. See the meta.json file to view the list of report names. This article uses the _Envizi-SetupLocations report.
GROUP_ID is used to filter the report data based on the Group_Id. See the report-parameters.json file to view the list of available group IDs. This article uses the TurbonomicD1 > ONPREM-DataCenter subgroup.

Sample output

The sample output of the previous API call is provided in the report-data.json file. There are three locations (HawthorneSales, UCS-DC-10.10.150.38, and vc03dc01) found under the given group ID.

Location Name: This column shows the retrieved location.
Group Link: This column shows the GROUP_ID=5037106 parameter that was passed in.
Group Name: The Group Name column shows the Group Name equivalent of the GROUP_ID that was passed in.

The following image shows the output with the important columns.

Important columns

Get scripts

Shell scripts are provided to retrieve report names, all of the report parameters, and all of the report data by using APIs. To run the shell scripts:

Download the files config.sh, 01-meta.sh, 02-report-param.sh, and 03-report-data.sh.
Update the information in the config.sh file.
```
### Envizi User Id
export API_USER=

### Envizi Password
export API_PASSWORD=

### Region (uk, au or us) based on the user region
export API_REGION=
```
In this code:
- API_USER is the Envizi login ID.
- API_PASSWORD is the Envizi password.
- API_REGION is the value uk, au, or us based on your region.

Retrieve report names

Run the following script to retrieve the report names.

sh 01-meta.sh

This script creates a new folder with a timestamp under the output folder. In the new folder, the meta.json file might be created.

Retrieve report parameters

Use the following script to retrieve all of the report parameters one by one.

sh 02-report-param.sh

This script creates a new folder with a timestamp under the output folder. In the new folder, numerous JSON files get created.

Note: This script takes time to execute based on the data available in the organization. So, a few lines are commented in the script. You can uncomment and try again.

Retrieve report data

Use the following script to retrieve all the report data one by one.

sh 03-report-data.sh

This script creates a new folder with a timestamp under the output folder. In the new folder, numerous JSON files get created.

Note: This script takes time to execute based on the data available in the organization. So, a few lines are commented in the script. You can uncomment and try again.

Summary

As an Envizi user, you might understand how to use APIs and the different report data available in Envizi. This article provided an overview of the Envizi APIs and how to use them to get data from Envizi to feed into external systems.

To get more information about Envizi or to try it out yourself, start your 14-day IBM Envizi ESG Suite trial. You can also request a personalized IBM Envizi demo.

Use APIs to expose Envizi data to external systems

Use APIs to expose Envizi data to external systems