Envizi API Technical Documentation

API Root URL

The Envizi API is a Web Service API and the URL always starts with the following:

For most Australia, New Zealand and ASEAN users - https://auapi.envizi.com/api
For most US and Canada users - https://usapi.envizi.com/api
For most UK, Europe and South African users - https://ukapi.envizi.com/api or https://euapi.envizi.com/api depending on your production server location
For most Middle East users - https://meapi.envizi.com/api

A valid API token must be supplied for authentication.

There should be no space or any other non URL standard characters supplied in the API address.

API Authentication

The Envizi API employs API Access Token for authorizing access to Envizi API.

Envizi API Access Tokens - using API Access Tokens is a recommended approach to gain access to Envizi API for the reasons of added security, as opposed to the traditionally basic authentication method, which uses an username and a password. Any eligible active Envizi user is able to generate and use an API token when the user has a ‘API Token Personal Role’ assigned. A system administrator user is also able to view and manage tokens of other users on their behalf, with a ‘API Token Admin Role’. Once corresponding roles are assigned, a new menu ‘My API Access Tokens’ will be available under the Personal menu.
For details about the enablement of the feature, what is and how to use an API token, please refer to the API token knowledge base article. Advanced topics such as token revokation and admin functions can be found in the Admin & advanced API token topics article.

Single Sign-On

SSO logins are not able to access the Envizi API - SSO credentials are being defined and authored by your own organization rather than Envizi. In order to access the API, you would need to create and use an Envizi API Access Token.

API Security

The Envizi API is communicated on HTTPS protocol over TLS1.2.

API Meta option

Format	<root URL>/meta

The /meta option allows you to see the list of API reports that are available to your login. If you manage multiple organizations, it will also display a list of organizations you have access to. This is usually the first API query to be run when you start to set up your application to work with the Envizi API. It can also be used to verify your application's environmental setting such as having valid credentials.

The API report names retrieved here are the reports that you are able to use with all other meta and data API calls.

Sample

API URL	JSON Output (partial)
https://usapi.envizi.com/api/meta	{ "associates": [ { "associate_Id": 35469, "name": "Demo Corporation AU" }, ], "reports": [ { "report_Id": 1444, "name": "_Envizi-MonthlyDataSummary" }, { "report_Id": 1447, "name": "_Envizi-RawDataExtract" }, ] }

Retrieve Report Parameters in API Meta Option

Format	<root URL>/meta/reports/<API report name>

Similar to running report in Envizi's main user interface, with Envizi API you are able to specify report parameters, such as report ending period, location name etc. However there is no user interface in API to allow you to make such selections - the solution to this is to use the meta/reports/<API report name> API call.

Unlike running reports from Envizi's main interface, in the API, for Envizi entities such as Location and Group, their exact Envizi Id must be specified in the API data call. The meta/reports/<API report name> call allows you to retrieve list of available parameter names and their ids in the specified report. These parameter names and ids can then be used in the actual API data calls later.

The /meta/reports/<API report name> allows you to see the following, provided they are applicable to the report:

List of applicable Locations, their Location Ids and its default value
List of applicable Groups, their Group Ids and its default value
List of applicable Utility Types, their Utility Type Ids (a.k.a. Data Types) and its default value
List of available reporting period, e.g. 1 month, 3 months and its default value
Default value for reporting end period, e.g. 31-Dec-2018

Sample

API URL

JSON Output (partial)

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
            }
        ]
   }
]

API Data Option

Format	<root URL>/data/<API report name>

Once you have retrieved API report names through meta option, you can use the data option to retrieve the data. The naming convention for all Envizi supplied API reports is that they all start with '_Envizi', followed by a dash '-' and then the API report name, e.g., _Envizi-MonthlyDataSummary.

Specify the API report name after /data/ to call the API, e.g. , https://usapi.envizi.com/api/data/_Envizi-MonthlyDataSummary

Report data requested in this way does not have any input parameters. This will be accepted by the system and it will result in default parameter values being used. In some cases this will be equivalent to running the same report on Envizi's main user interface without changing any of the default report selections, but for some reports, the API will return more data, with all the possible report selection combinations.

Sample

API URL

JSON Output (partial)

https://usapi.envizi.com/api/data/_Envizi-MonthlyDataSummary

[
    {
        "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,
...
    },
...
]

Currency of API Data

Data retrieved from most API reports are close to live data in the system, with up to a maximum of 15 minutes of delay. Hence in certain circumstances they may be different from the values you see on Dashboards or Power Reports, which typically have a longer refresh cycle of 24 hours.

Specify Parameters in API Data Option

Format	<root URL>/data/<API report name>?Parameter1=Value1&Parameter2=Value2&...

Sometimes it may make sense to restrict and reduce the amount of data returned in the API to optimize the data retrieval process. This can be done by supplying the optional report parameters in the API call, after appending a question mark ? to the API report name. Multiple parameters can also be specified, and each should be separated by an ampersand & sign.

Most parameter values should use the internal id instead of its name, e.g., use Location_Id = 12345 instead of Location_Name = Aberfoyle. The list of names and ids mapping can be found through /meta/reports/<API report name> call.

When specifying the values for parameters, you must not surround values with single or double quotes - only open values are accepted.

The format for date should always follow YYYY/MM/DD, e.g. 2018/12/31

Sample

API URL	JSON Output (partial)	Remarks
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, ... }, ... ]	This API requests data for 1 month ending 2018-Oct-31 and for one particular location only.

Period and End_Period

'Period' and 'End_Period' are important parameters to determine the reporting data output range. If these parameters are not specified in the API URL, the platform will default them to user's personal setting, which is usually 12 months ending with previous month. For example, if the API report is run in May-2019, then 'Period' will be defaulted to 12 and 'End_Period' will be defaulted to 2019/04/30.

In addition to specifying a date, the 'End_Period' parameter can also take the following values to suite the need in different situations, especially if the API is to be used recurrently. e.g., always to run for current month.

CURRENT_MONTH
PREVIOUS_MONTH
PREVIOUS_QUARTER
PREVIOUS_YEAR

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

List of available API Reports

Reports in Envizi are constantly being reviewed and enabled for API access. There are about 40+ API reports currently available in the API module. You can use the following query to find out the list of accessible API reports based on your login credential:

https://<region>api.envizi.com/api/meta/reports

(replace <region> with one of the supported region codes: au, us, uk, eu or me)

All Envizi’s web service API calls need to be made by using a software tool that supports the use of API Token authentication method. In general you cannot run an Envizi API call on web browsers due to limited authentication features available in browser applications. Please refer to the Envizi API Overview page for more details on a list of recommended tools.