Feeds & streams

Using this part of the API you can retrieve data measured by sensors and all data derived from it by Energomonitor’s processing engine, together with all the information needed to process it or display it to users in a meaningful way.

Introduction

The data is organized into feeds and streams. To explain these concepts, we need to look into how data is gathered and processed.

Each sensor produces one or more streams of timestamped values, which it sends to the homebase over radio. For example, the Optosense sensor produces just one stream: the impulse count read form a digital electricity meter. Other sensors may produce more streams. All these streams are called raw streams. In addition, the sensors may produce system streams with system information (such as signal strength).

The homebase combines all streams received from sensors into a feed, and sends the measurements over MQTT to Energomonitor’s servers. There, Energomonitor’s processing engine performs various operations (such as aggregation), and computes additional data (such as overall consumption or costs) from the measurements. These computations create new, derived streams, which are called processed streams.

Both feeds and streams are associated with information which is used to process incoming data. Some of this information varies with time and it is separated into stream or feed configuration. In case of streams, only processed streams are associated with configuration.

The API allows you to access information about feeds and streams, their configuration, and in case of streams, their data.

Objects

Feed

The feed object describes a feed.

Example

{
  "id": "200242",
  "subscription": {
    "from": "2015-12-01T10:13:19.659004+00:00",
    "to": "2016-12-01T10:13:19.659004+00:00"
  },
  "configs": [
    {
      "title": "Energomonitor HQ",
      "timezone": "Europe/Prague",
      "valid_from": "2000-01-01T00:00:00+00:00",
      "valid_to": null
    }
  ]
}

Properties

Name Type Description
id string Feed ID. It uniquely identifies the feed within the system.
subscription object Subscription information, a feed subscription object.
configs array List of configurations associated with the feed. Each configuration is valid for a period of time (specified by its valid_from and valid_to properties) and the list is ordered by these periods. The last configuration is always the the current one (with valid_to set to null).

Feed subscription

The feed subscription object describes feed subscription.

Example

{
  "from": "2015-12-01T10:13:19.659004+00:00",
  "to": "2016-12-01T10:13:19.659004+00:00"
}

Properties

Name Type Description
from string Time from which the subscription is valid (inclusive), in ISO 8601 format.
to string Time to which the subscription is valid (exclusive), in ISO 8601 format.

Feed configuration

The feed configuration object describes feed configuration. This configuration can change over time, which is why the object contains information about its validity period.

Example

{
  "title": "Energomonitor HQ",
  "timezone": "Europe/Prague",
  "valid_from": "2000-01-01T00:00:00+00:00",
  "valid_to": null
}

Properties

Name Type Description
title string Title of the feed.
timezone string Timezone of the homebase paired with this feed, in IANA Time Zone Database format.
valid_from string | null Time from which the configuration is valid (inclusive), in ISO 8601 format. The value null means configuration validity is not bound into the past.
valid_to string | null Time to which the configuration is valid (exclusive), in ISO 8601 format. The value null means configuration validity is not bound into the future.

Stream

The stream object describes a stream. There are 3 types of streams:

Raw streams
These streams contain raw data measured by a sensor. For example, in case of electricity measurement, there will be a raw stream reporting power data (W). The frequency of data points depends on the sensor, but it is 5s in most cases.
Processed streams
These streams contain processed data created by Energomonitor’s processing engine from raw data. For example, in case of electricity measurement, there will be a processed stream reporting consumption (kWh) and another one reporting cost. The frequency of data points is currently 90s with timestamps aligned to the epoch, but this may change in the future.
System streams
These streams contain various system data (such as signal strength). Streams from unconfigured sensors which Energomonitor’s processing engine cannot process are also classified as system streams.

Examples

Raw stream:

{
  "id": "embvko",
  "type": "raw",
  "channel": 16,
  "device": 8,
  "medium": 16
}

Processed stream:

{
  "id": "embnos",
  "type": "processed",
  "channel": 4,
  "combined": false,
  "configs": [
    {
      "title": "Electricity - Fridge",
      "medium": "power",
      "unit": "W",
      "valid_from": "2000-01-01T00:00:00+00:00",
      "valid_to": null
    }
  ]
}

System stream:

{
  "id": "embvkt",
  "type": "system",
  "channel": 16
}

Properties

Streams of all types contain the following properties:

Name Type Description
id string Stream ID. It uniquely identifies the stream within the system.
type string Stream type, one of "raw", "processed", or "system".
channel integer Channel on the homebase to which the sensor producing the stream is paired to.

Raw streams contain the following additional properties:

Name Type Description
device integer Device ID identifying the sensor producing the stream. See the table of device IDs for possible values.
medium integer Medium ID identifying the type of measured data. See the table of medium IDs for possible values.

Processed streams contain the following additional properties:

Name Type Description
combined boolean Indicates whether the stream is combined, that is, whether its data is computed by combining data from several other streams. A typical example is a sum stream in case of 3-phase electricity consumption measurement.
index integer Index of the stream in a set of streams produced by the same sensor that contain the same kind of data. Optional, present only when a sensor produces multiple such streams. A typical example are phase streams in case of 3-phase electricity consumption measurement.
configs array List of configurations associated with the stream. Each configuration is valid for a period of time (specified by its valid_from and valid_to properties) and the list is ordered by these periods. The last configuration is always the the current one (with valid_to set to null).

Stream configuration

The stream configuration object describes stream configuration. This configuration can change over time, which is why the object contains information about its validity period.

Example

{
  "title": "Electricity - Fridge",
  "medium": "power",
  "unit": "W",
  "valid_from": "2000-01-01T00:00:00+00:00",
  "valid_to": null
}

Properties

Name Type Description
title string Title of the stream.
medium string | null Measured medium, one of "power", "gas", "water", or "temperature". The value null means the stream is not being used by the processing engine.
unit string Unit of measured data, in a form suitable to display to users.
valid_from string | null Time from which the configuration is valid (inclusive), in ISO 8601 format. The value null means configuration validity is not bound into the past.
valid_to string | null Time to which the configuration is valid (exclusive), in ISO 8601 format. The value null means configuration validity is not bound into the future.

Resources

GET /users/{user_id}/feeds

Lists user’s feeds. Returns an array of feed objects.

Example response

[
  {
    "id": "200242",
    "subscription": {
      "from": "2015-12-01T10:13:19.659004+00:00",
      "to": "2016-12-01T10:13:19.659004+00:00"
    },
    "configs": [
      {
        "title": "Energomonitor HQ",
        "timezone": "Europe/Prague",
        "valid_from": "2000-01-01T00:00:00+00:00",
        "valid_to": null
      }
    ]
  }
]

GET /feeds/{feed_id}

Retrieves a single feed. Returns a feed object.

Example response

{
  "id": "200242",
  "subscription": {
    "from": "2015-12-01T10:13:19.659004+00:00",
    "to": "2016-12-01T10:13:19.659004+00:00"
  },
  "configs": [
    {
      "title": "Energomonitor HQ",
      "timezone": "Europe/Prague",
      "valid_from": "2000-01-01T00:00:00+00:00",
      "valid_to": null
    }
  ]
}

GET /feeds/{feed_id}/streams

Lists streams belonging to a feed. Returns an array of stream objects.

Parameters

Name Type Description
type string Only list streams of this type. See the description of stream objects for more details about stream types. Can be specified multiple times.
channel integer Only list streams with this channel. See the description of stream objects for more details about channels. Can be specified multiple times.
data_time_from integer Only list streams with data points measured after or at this time.
data_time_to integer Only list streams with data points measured before or at this time.

Example response

[
  {
    "id": "embnos",
    "type": "processed",
    "channel": 4,
    "combined": false,
    "configs": [
      {
        "title": "Electricity - Fridge",
        "medium": "power",
        "unit": "W",
        "valid_from": "2000-01-01T00:00:00+00:00",
        "valid_to": null
      }
    ]
  },
  {
    "id": "embvko",
    "type": "raw",
    "channel": 16,
    "device": 8,
    "medium": 16
  },
  {
    "id": "embvkt",
    "type": "system",
    "channel": 16
  },
]

GET /feeds/{feed_id}/streams/{stream_id}

Retrieves a single stream. Returns a stream object.

Example response

{
  "id": "embnos",
  "type": "processed",
  "channel": 4,
  "combined": false,
  "configs": [
    {
      "title": "Electricity - Fridge",
      "medium": "power",
      "unit": "W",
      "valid_from": "2000-01-01T00:00:00+00:00",
      "valid_to": null
    }
  ]
}

GET /feeds/{feed_id}/streams/{stream_id}/data

Lists stream’s data points. Returns an array with the data points, where each data point is an array with 2 elements: the time of measurement (integer, a Unix timestamp) and a value (integer | float).

For raw streams, the frequency of data points depends on the sensor, but it is 5s in most cases. For processed streams, the frequency of data points is currently 90s with timestamps aligned to the epoch, but this may change in the future. Note there may be gaps in the sequence (e.g. when the sensor lost connectivity).

Parameters

Name Type Description
time_from integer Only list data points measured after or at this time, a Unix timestamp.
time_to integer Only list data points measured before or at this time, a Unix timestamp.
limit integer Maximum number of returned data points. When there are more matching data points than limit, the newest ones are returned. Default: 100.

Example response

[
  [
    1496066670,
    57
  ],
  [
    1496066760,
    56.94
  ],
  [
    1496066850,
    56.53
  ],
  [
    1496066940,
    56.2
  ]
]