REST APIs

IBM® ESG Suite provides a REST API interface for extracting report data.

The base URL for the web service API endpoints is
https://<region>api.envizi/com/api,
where region is one of the supported regions codes, such as au, us, uk, eu, or me.

Typically, the base URL to use for each region is as follows:
  • Australia, New Zealand, and ASEAN: https://auapi.envizi.com/api
  • US and Canada: https://usapi.envizi.com/api
  • UK, Europe, and South Africa: https://ukapi.envizi.com/api or https://euapi.envizi.com/api, depending on your production server location
  • Middle East: https://meapi.envizi.com/api
Note: When you extract data from the APIs, consider the following:
  • Use a valid API token.
  • The base URL must not contain any spaces or any other nonstandard URL characters.
  • If your organization uses single sign-on, you must use the API access token to access the APIs.
  • The APIs use the HTTPs protocol over TLS1.2.
  • To access API endpoints, use a software tool that supports the use of the API token authentication method.
  • The naming convention for each report name is _Envizi- followed by the report name without spaces, for example, _Envizi-MonthyDataSummary.
In Envizi ESG Suite, the following API endpoints are available:
GET /meta
Check your connection and review the list of organizations or associates and reports that you have access to.
GET /meta/reports
Find a list of available reports.
GET /meta/reports/<report_name>
Find the report selection parameters for a specific report and the default value for each parameter.
GET /data/<report_name>
Retrieve data for the specified report based on either the default parameter or the specified input parameters.
When you provide input parameters, you filter the data that the API retrieves. For example, a GET /data/Envizi-MonthlyDataSummary?Period=1&Utility_Type_Id=1 request filters the Monthly Data Summary report so that is includes electricity data for one month.
Use the endpoints to retrieve report data in the following order:
  1. Make a GET request to the /meta endpoint to verify that you can connect to the platform.
  2. Make a GET request to the /meta/reports endpoint to find the list of available reports.
  3. Make a GET request to the /meta/reports/<report_name> endpoint to list the report selection parameters.
  4. Make a GET request to the /data/<report_name> endpoint to request report data based on a report name and report selection parameters.

Reporting date range

Use the Period and End_Period parameters in the API call to specify the time range of the data output. If these parameters are not specified in the API URL, the system uses the default value that is specified in your personal setting, which is typically 12 months ending with the previous month. For example, if an API report is run in May 2019, then Period defaults to 12 and End_Period defaults to 2019/04/30.

The End_Period parameter can also take the following values to suit different scenarios especially if the API is used recurrently, for example, for the current month.

  • CURRENT_MONTH
  • PREVIOUS_MONTH
  • PREVIOUS_QUARTER
  • PREVIOUS_YEAR

For example, the parameters ...?End_Period=Current_Month&Period=1 always return data for current month only.

Endpoint /meta

Use the /meta endpoint to request the list of organization or associates that are available to you based on your login credentials. In the following sample API response, the user has access to two organizations.

https://usapi.envizi.com/api/meta
The API call returned the following JSON output:
{
    "associates": [
        {
            "associate_Id": 35469,
            "name": "Demo Corporation AU"
        },
        {
            "associate_Id": 35477,
            "name": "Demo Corporation EU"
        }
    ]
}

Endpoint /meta/reports

Use the /meta/reports endpoint to request the list of reports that are available to you based on your login credentials. In the following sample API response, two reports are available for the user on Demo Corporation AU; the Monthly Data Summary report and the Raw Data Extract report.

https://usapi.envizi.com/api/meta/reports
The API call returned the following JSON output:
{
    "associates": [
        {
            "associate_Id": 35469,
            "name": "Demo Corporation AU"
        },
    ],
    "reports": [
        {
            "report_Id": 1444,
            "name": "_Envizi-MonthlyDataSummary"
        },
        {
            "report_Id": 1447,
            "name": "_Envizi-RawDataExtract"
        },
    ]
}

In this example, the user has access to two reports and one associate.

Endpoint /meta/reports/<report_name>

Use the /meta/reports/<report_name> endpoint to see the parameters that you can specify when you request a report. The response includes the default values for each parameter. The following parameters are returned, if relevant:
  • Locations, location IDs, and default values.
  • Groups, Group IDs, and default values.
  • Utility types, utility IDs, and default values. Utility type is the same as Data type.
  • Available reporting periods. For example, 1 month, 3 months.
  • Default value for the reporting period.
In the following sample API call, the selection parameters for the Monthly Data Summary report are requested:
https://usapi.envizi.com/api/meta/reports/_Envizi-MonthlyDataSummary
The API call returned the following JSON output:
[
    {
        "associateId": 35469,
        "params": [
            {
                "name": "Group_Id",
                "defaultValue": null,
                "availableValues": [
                    {
                        "name": "All Groups",
                        "value": ""
                    },
                    {
                        "name": "Aberfoyle Tenants",
                        "value": "5003643"
                    },
                …
                ]
            },
            {
                "name": "Location_Id",
                "defaultValue": null,
                "availableValues": [
                    {
                        "name": "All Locations",
                        "value": ""
                    },
                    {
                        "name": "Aberfoyle Head Office",
                        "value": "5003114"
                    },
                …
                ]
            },
            {
                "name": "Utility_Type_Id",
                "defaultValue": null,
                "availableValues": [
                    {
                        "name": "All Data Types",
                        "value": ""
                    },
                    …
                    {
                        "name": "Electricity [kWh]",
                        "value": "1"
                    },
               …
            {
                "name": "Period",
                "defaultValue": "12",
                "availableValues": [
                    {
                        "name": " 1  Month",
                        "value": "1"
                    },
                    {
                        "name": " 3  Months",
                        "value": "3"
                    },
                   ...
                ]
            },
            {
                "name": "End_Period",
                "defaultValue": "2018/12/31",
                "availableValues": null
            }
        ]
   }
]

Endpoint /data/<report_name>

Use the /data/<report_name> endpoint to retrieve a report. If you don't specify reporting parameters in the API call, the default parameters are used. When you don't specify a report period explicitly, most API reports return 12 month of data ending in the last month.
Note: The default report period that is used depends on the reporting period in your personal setting. For more information, see Configuring personal settings.

The following sample API call requests data for the Monthly Data Summary report by using the default parameters.

https://usapi.envizi.com/api/data/_Envizi-MonthlyDataSummaryThe API call returns the following JSON output:[
    {
        "Start_Period": "01 Jan 2018",
        "End_Period": "31 Dec 2018",
        "Associate_Id": 35469,
        "Associate": "Demo Corporation AU",
        "Level 1 Group": "Business Groups",
        "Level 2 Group": "Non-retail",
        "Level 3 Group": "Administration",
        "Country": "Australia",
        "Region": "New South Wales",
        "Location": "11 Talavera Road Macquarie Park",
        "Location Reference": "",
        "Category": "Offsets and GHG Reductions",
        "Data Type": "Electricity - Green Offsets [kWh]",
        "Item Type": "Account",
        "Account Style/Component": "Electricity - Small Market",
        "Sub type": "",
        "Item Number": "Electricity Small Market",
        "Account Ref/Meter Name": "",
        "Supplier": "",
        "Reader / Notes": "",
        "Opened_On": null,
        "Replaced_On": null,
        "Occurred_On": "Jan-2018",
        "Units": "kWh",
        "Actual Data": 0,
        "Estimated Data": 0,
        "Accrued Data": 0,
        "Total Data": null,
         ...
    },
...
]

In the following example, the Monthly Data Summary report is run and an end period and a location ID are specified:

https://usapi.envizi.com/api/data/_Envizi-MonthlyDataSummary?Period=1&End_Period=2018/10/31&Location_Id=5003114
The API call returns the following JSON output:
[
    {
        "Start_Period": "01 Oct 2018",
        "End_Period": "31 Oct 2018",
        "Associate_Id": 35469,
        "Associate": "Demo Corporation AU",
        "Level 1 Group": null,
        "Level 2 Group": null,
        "Level 3 Group": null,
        "Country": "Australia",
        "Region": "Adelaide",
        "Location": "Aberfoyle Head Office",
        "Location Reference": "AB:AD",
        "Category": "Electricity",
        "Data Type": "Electricity [kWh]",
        "Item Type": "Meter",
        "Account Style/Component": "NEMMCO 12...",
        "Sub type": null,
        "Item Number": "6000000001",
        "Account Ref/Meter Name": "Tenant",
        "Supplier": "Demo Utility Company",
        "Reader / Notes": "",
        "Opened_On": "01 May 2014",
        "Replaced_On": null,
        "Occurred_On": "Oct-2018",
        "Units": "kWh",
        "Actual Data": 595002.2,
        "Estimated Data": 0,
        "Accrued Data": 0,
        "Total Data": 595002.2,
        ...
    },
...
]
When you specify input parameters, after the report name, start the parameter list with a question mark (?). Each parameter is separated by an ampersand (&). The data parameter uses the format yyyy/mm/dd without any surrounding quotes. For example:
https://usapi.envizi.com/api/data/_Envizi-MonthlyDataSummary?End_Period=2024/06/30&Location_Id=5003114