EnerKey API

Overview

EnerKey API is a interface that enables you to access your EnerKey SaaS data using 3rd party application. This service can be enabled by EnerKey service desk.

  • REST API: Widely used and easy integration

  • JSON format: standard file format and data interchange format

A technical description of the EnerKey API can be via links above.

Authentication

The REST API identifies 3rd party application using API key authorization. An application must pass EnerKey API key in all requests as request header Authorization field.

API key is unique and it's granted per EnerKey profile or EnerKey tenant. There are two API keys per profile and the keys have validity dates. Two key mechanism makes a key renewing possible while the application uses the other key.

Rate limit

The rate limit boundary for EnerKey API key is 40000 requests in 24 hours. If the request doesn't get rate limited then the X-Rate-Limit header shows number of calls available in 24h period.

Date format

Supported timestamp formats:

  • UTC format, e.g 2017-01-01T00:00:00Z,

  • Time zone format, e.g 2017-01-01T00:00:00+02:00.

API response is in the requested format. In request timestamps should be URL encoded.

API root and documentation

API root address is https://api.enerkey.com

API description (this text) and endpoint descriptions can be found in https://developer.enerkey.com

Getting started

Steps to start using

  • As an existing EnerKey SaaS customer contact service desk to enable API service for your profile

  • EnerKey services will create a key and make needed configurations

  • You get an API key that you will need to access EnerKey API

  • Implement a service/function/etc. in your system to access EnerKey via API

  • Start using

Support

In case you have any questions regarding API please contact our support. We are also happy to provide you a trusted partner if you need technical help to implement integration to EnerKey API.

Picture

How to Get Emissions Data from EnerKey External API

  1. Get All Facilities

    • Send a request with an empty body to:

      POST https://api.enerkey.com/data/api/v2/Facilities/Search

    • Use the response to create a list of energiaIds for the facilities you are interested in.

    • Save the co2Factors for each or specific quantities.

  2. Get All Meters for the Listed Facilities

    • Send a request with an empty body to:

      POST https://api.enerkey.com/data/api/v2/Meters

    • Use the response to create a list of meterIds you are interested in.

  3. Get Consumption Data for the Meters

    • Send a request with the meterId list to:

      POST https://api.enerkey.com/consumption/api/v1/consumption/

    • Use the response to multiply the consumption data with the co2Factor for each meter and quantity type.

  4. Check Available Quantities

    • You can check the available EnerKey quantities by sending a request to:

      GET https://api.enerkey.com/data/api/v2/Quantities

API content

Actions

Get and update energy management actions in EnerKey. Updating EnerKey action requires an identifier that need to be get before update.

Before calling update user is required to fetch the current value of 'action' object from EnerKey by calling Get API function. Modifications are done to received 'action' object that is sent back to EnerKey via Update method. Values of 'action' object are saved as they are, hence replacing any previous value in EnerKey system.

Authorization is profile wide.

Facilities

Get information and properties of facilities in EnerKey. It is possible to get one, many or all data of facilities using these endpoints.

Authorization is profile wide.

Images

Get consumption and facility information per facility in picture format. Supported file formats "png" and "pdf". Custom colors can be defined.

There are two types of images that are available. One includes facility information, graphs and data in table. See example link below. The other is more limited by its features and is intended to be used as a part of something else.

Authorization is profile wide.

Example of consumption image.

Logs

Get alarm details and images by id.

Authorization is currently for EnerKey partners only.

Meters

Get meter information and properties saved in EnerKey.

Authorization is profile wide.

Quantities

Get quantities ie type of consumption available in EnerKey. Id, name and unit is returned.

Authorization is profile wide.

Values

EnerKey values endpoints enables you to retrieve and push measurement data into EnerKey SaaS. This service can be enabled by EnerKey service desk.

Values can be get for one or multiple meters. If you wan't to get values for all meters of certain profile, it is recommended to first get all facilities using one of facilities endpoints, then get all meters for all facilities using meters endpoint. Then get values using freshly get meters id list. This way possible recently added meters are included and removed meters ignored.

Get endpoints provide hourly or monthly consumption for given meters. Also normalized consumption can be retrieved.

  • Get hourly values

  • Get monthly values

  • Get monthly normalized values

If specific values are needed, you should first get needed properties from facilities endpoint, get values and then do the calculation at your end. Same applies for costs and CO2 values.

Pushing/posting values

  • Straightforward content: timestamp and value

  • Support for both consumption and cumulative readings

There are two alternative endpoints for push:

  1. PushConsumptionsForMeter: for meters that measure consumption 

  2. PushCumulativeReadingsForMeter: for meters that measure cumulative readings

Data resolution for push is hourly. Multiple values for same hour are summed. 

  • API accepts data for 365 days at a time.

  • Data for one meter can be sent at in one message.

  • Unit of data is meter default in EnerKey. Please check units in EnerKey help.

Authorization is profile wide.