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
.
- 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
- 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.
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.
- Make a GET request to the /meta endpoint to verify that you can connect to the platform.
- Make a GET request to the /meta/reports endpoint to find the list of available reports.
- Make a GET request to the /meta/reports/<report_name> endpoint to list the report selection parameters.
- 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
{
"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
{
"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>
- 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.
https://usapi.envizi.com/api/meta/reports/_Envizi-MonthlyDataSummary
[
{
"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>
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
[
{
"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,
...
},
...
]
?
). 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