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.
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.
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:
PushConsumptionsForMeter: for meters that measure consumption
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