Envizi API Technical

Documentation
API Root URL

The Envizi API is a Web Service API and the URL always starts 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

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 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- [ This API requests data for 1
MonthlyDataSummary?Period=1&End_Period=2018/10/31&Location_Id=5003114 { month ending 2018-Oct-31
"Start_Period": "01 Oct 2018",
and for one particular location
"End_Period": "31 Oct 2018",
"Associate_Id": 35469, only.
"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,
...
},
...
]
 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 IRL, the platform will default them to user’s personal setting, wihich 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 suit 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

Comon 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.