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
  ]
]

GET /feeds/{feed_id}/related_streams

Lists groups of related streams. Returns an array with the groups, where each group is an array with stream IDs identifying streams that belong to the group.

Streams are related when they derive from the same measurement. For example, in case of electricity measurement, streams reporting current power (W), consumption (kWh), and cost will be reported as related. Similarly for gas or water.

Example response

[
  [
    "embmog",
    "embmoh",
    "embmoi"
  ],
  [
    "emiwm",
    "emiwu",
    "emixk"
  ]
]