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.
How to Get Emissions Data from EnerKey External API
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.
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.
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.
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.
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.