API Root URL

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

A valid Envizi user name and password 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 Basic Authentication method, which is the same as accessing Envizi's main user interface - using a user name and password. It is recommended to create a new login exclusively for the API access especially if your reporting tool resides in a shared environment, but you can always use your existing Envizi login if that is preferred.

If a new login is created to access the API, you will need to use it to log into Envizi's main interface first to activate it, e.g., by accepting terms & conditions. Once this is done, please allow additional 5 minutes before the new login becomes activated for the API.


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 a new physical Envizi login with user name and password for the authentication.


API Security

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

API Meta option

Format

/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

/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

/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

/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://<au><us><uk>api.envizi.com/api/meta/Reports

Common Problems with API authentication

If for some reason your existing API login does not seem to be working any more, please check whether you can log in through the main Envizi user interface with the same credential. If you also experience problem logging in from the main user interface, chances are that your API login may have been disabled after the number of failed login attempts exceeded your organization's password security threshold (default is 10 times). This feature is in place to prevent any unauthorised access to the system in the way of brute-force attack, e.g., by submitting many passwords with the hope of eventually guessing it correctly.

In such cases you can either request your system admin to reset the password for the API login, or to delete and create a new Envizi login with the same credential details to avoid disruption to your established data automation processes.