Enectiva REST API - Librarian

Librarian is a simple public API of Enectiva for ingesting readings. It can be used only in conjunction with a valid account in Enectiva application.

JSON API

This API sticks to REST principles as interpreted by JSON API. Due to gradual development, not all endpoints are fully compliant with JSON API, please, refer to documentation of each endpoint for details.

Auth

TL;DR: Each request has to include Authorization header in the form Bearer [token].
Each token has a limited scope and thus can access only certain resources.

All tokens are managed on the API dashboard.

For import actions, use the Import token.

For the rest of the actions, use a Login token to obtain a short lived access token.

Errors

Each endpoint lists possible error states, but most of them are shared:

400: validation error, described in the detail attribute

401: invalid token — token is missing altogether, it is not syntactically correct, it is malformed, claims are malformed or the scope is invalid, described in the detail attribute

403: the token scope is not permitted to perform the requested operation

406: the request doesn't include Accept: application/vnd.api+json header

409: duplicity — identical record is already stored

415: the declared Content-Type is not application/vnd.api+json

429: you have exceeded the rate limit

500: any other error

Filters

The filter query parameter can be used in some endpoints to traverse all the available data.

The request can limit which records should be returned by adding the filter query parameter. Its value has the form [resource object type].[field][condition][value], some examples are:

readings.time>2019-10-02T00:00:00Z

data_series.time>2019-10-02T00:00:00Z

meter_deltas.time>2019-10-02T00:00:00

entity_deltas.time>2019-10-02T00:00:00

Currently

[resource object type].time>[value]

[resource object type].time>=[value]

[resource object type].time<[value]

filters are supported and they can be concatenated using ?filter[]=....&filter[]=.... An example is

?filter[]=readings.time>2019-10-02T00:00:00Z&filter[]=readings.time<2019-10-06T00:00:00Z

The API returns most times in UTC (marked explicitly by Z). The API accepts times without offset specification and treats them as being in UTC. Any other explicitly defined offset is honoured. This means that

readings.time>2019-10-02T12:00:00

readings.time>2019-10-02T12:00:00Z

readings.time>2019-10-02T13:00:00+01:00

are all equivalent.

There are a few endpoints which return and accepts times without offset specification.

NOTE: The filters need to be URL encoded but for readability the documentation is using an un-encoded version.

Sort options

The sort query parameter can be used in some endpoints to reorder all the available data.
The sort query parameter implementation follows the JSON API specification.

The request can specify how the records should be ordered by adding sort query parameter. Its value has the form [direction][resource].[field], some examples are:

-readings.time

data_points.time

-meter_deltas.time

entity_deltas.time

TIP: Use ?sort=-[resource].time&limit=1 to retrieve only the latest record.

Direction

Use - to specify sort direction to be descending, otherwise use [resource].[field] to specify ascending direction.

Temporal records are ordered by time in ascending order by default.

Chaining

Sort options can be chained by using a comma:

?sort=-data_points.value,data_points.time

Sort options are applied in the given order, thus firstly ordered by value DESC and then by time ASC.

Meter identification

Meter endpoints use two forms of meter identification:

Enectiva's numeric meter ID

User entered external ID

External IDs must be prepended by e_ to be distinguishable from Enectiva IDs. If meter with Enectiva ID 42 has external ID the-ultimate-answer, these two endpoints will provide identical data:

https://api.enectiva.cz/meters/42/readings

https://api.enectiva.cz/meters/e_the-ultimate-answer/readings

A request with non-unique external ID results in 409 response status. The response includes error details with links to all matching meters using their Enectiva IDs, allowing the client to choose the appropriate meter and retry the request using the Enectiva ID instead of the external ID.

Limit & pagination

You can control the number of returned records of most endpoints returning a collection. The default limit is 1000 you can go lower. If you want to get fewer than 1000 records you need to pass limit query argument.

To paginate, set page query argument. Implicit value is 1.

Rate limiting

API requests are tracked and can be throttled in order to ensure operational stability. The intention is to protect the API from unterminated loops or attempts to aggressively download all data at once. If you're hitting the limits with legitimate use, please contact us.

A throttled request results in 429 response status. The response also contains RateLimit-* headers describing the current state and of the throttle and most importantly the time when a new request is going to be accepted.

Contact

If you have any questions related to this API, client implementation or its use, please contact us at api@enectiva.cz.

Introduction

Enectiva REST API - Librarian#

JSON API#

Auth#

Errors#

Filters#

Sort options#

Direction#

Chaining#

Meter identification#

Limit & pagination#

Rate limiting#

Contact#