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

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.

Provisioning

Auto provisioning endpoints for updating customer, facility and meter info. Used only for partner customers.

Authorization is tenant wide.

Provisioning content is a snapshot of data

  • Import customers and customer information to EnerKey SEMS

  • Data must be complete and missing customers will be deleted

UpsertProvisioningCustomer

  • Customer profiles are created in EnerKey for each json object. 

  • Suggested to import either regularly e.g. nightly or only when changes happen.

  • Mandatory information is externalCustomerId, externalCustomerName and productCode. There are also other customer info that can be imported if needed.

externalCustomerId

  • ID that identifies customer.

  • This ID will also be used to authorize users if SSO is enabled. Without SSO, users are licensed manually.Visible in admin only

externalCustomerName

  • Customer name = profile name

  • Visible in top bar drop down.

productCode

  • Service package code. Code set will be provided by EnerKey. E.g. XS 1000, XL 1001

  • Sets right services for the customer profile

companyOvt, streetAddress, postalCode, city, country, email, phoneNumber

  • Additional customer information

UpsertProvisioningData

Import your facility and meter data to our system.

  • Returns 202 - Accepted if data can be processed.

  • Returns 208 if data set is the same than previous i.e. already processed.

  • Returns also id that must be used when checking status of provisioning via /api/v2/Provisioning/ProvisioningStatus

Following actions are carried out in EnerKey when importing data json

  • Create facilities

  • Create facility properties

  • Create meters and submeters

  • Create reading configurations for meters to get consumptions.

  • Create default alarms for meters 

Picture Picture Picture Picture