Skip to main content

Time series data

Yggio saves numerical and string data into a time series database.

Using the REST API you can get time-series-data of a specific attribute from an iotnode.

The following is the format of time series data for an attribute of an iotnode:

[
  {
    "time": String,
    "value": Number || String
  },
  ...
]

time is a ISO 8601 timestamp. E.g.: 2019-08-07T12:30:00.00Z.
value is the saved value.

Set time interval​

One can choose to get the data with a set time between each data point. This might be desirable if a high data resolution is not needed. It can improve loading times and performance. The database then uses interpolation to set the values for the data points.

If a set time interval is used the data will have the following format:

[
  {
    "time": String,
    "value": Number,
    "min": Number,
    "max": Number,
    "stddev": Number
  },
  ...
]

time is a ISO 8601 timestamp. E.g.: 2019-08-07T12:30:00.00Z.
value is the interpolated value.
min is the value of the smallest point in the interpolated area.
max is the value of the largest point in the interpolated area.
stddev is the standard deviation of the points in the interpolation area.

Downsample data with valueFunction​

The valueFunction feature allows you to perform operations on data grouped within specific time windows. This can be useful for analyzing data trends over time by summarizing the data points within each window.

Supported Operations​

The following operations can be performed using valueFunction:

  • mean: Calculates the average of all values within the window.
  • timeWeightedMean: Calculates the time weighted average within the window.
  • max: Finds the maximum value within the window.
  • min: Finds the minimum value within the window.
  • first: Uses the first value within the window.
  • last: Uses the last value within the window.
  • sum: Calculates the sum of all values within the window.
  • count: Counts the number of values within the window.
  • difference: Calculates the difference between the fist value of subsequent windows

Defining the Time Window​

The time window for the valueFunction is determined by the distance option. This specifies the length of each window, given in seconds.

Time-Weighted Mean Value Function​

The time-weighted mean is calculated by determining how long a measurement has remained in a certain state within a given interval.

Example: A sensor measures the occupancy of a desk:

[
    {time: "2025-03-18T13:00:00.000Z", value: 0},
    {time: "2025-03-18T13:30:00.000Z", value: 1},
    {time: "2025-03-18T13:45:00.000Z", value: 0},
    {time: "2025-03-18T14.15:00.000Z", value: 1},
    {time: "2025-03-18T14.30:00.000Z", value: 1},
    {time: "2025-03-18T14.45:00.000Z", value: 0},
    {time: "2025-03-18T15.00:00.000Z", value: 1},
    {time: "2025-03-18T15.45:00.000Z", value: 0},
]

The following request calculates the time-weighted mean occupancy for each hour:

$ curl -X 'GET' \
  'https://staging.yggio.net/api/iotnodes/<iotnode._id>/stats?measurement=occupancy&distance=3600&valueFunction=timeWeightedMean' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>'

The response:

 [
     {"time": "13.00", "value": 0.25}
     {"time": "14.00", "value": 0.5}
     {"time": "15.00", "value": 0.75}
 ]

Explanation:

  • Hour 1 (13:00–14:00): Three observations were recorded. The desk was unoccupied (value 0) for 45 minutes and occupied (value 1) for 15 minutes. The time-weighted mean is 0.25.
  • Hour 2 (14:00–15:00): Three observations were recorded. The first 15 minutes used the previous hour's state (0), followed by two measurements at value 1. This results in 30 minutes with value 0 and 30 minutes with value 1, giving a mean of 0.5.
  • Hour 3 (15:00–16:00): Two observations were recorded. The desk was occupied (value 1) for 45 minutes and unoccupied (value 0) for 15 minutes, resulting in a mean of 0.75.

Note:

If the first observation occurs after the start of the first interval, the result for that interval will be null. This is because we do not know the value before the first observation and therefore cannot determine the state for the entire interval.

Example:

If the first interval starts at 13:00, but the first observation is at 13:15, we lack information about the state between 13:00 and 13:15. Since the state before 13:00 is unknown, the system cannot assume or extrapolate a value, resulting in null for that first interval. All following intervals are not affected by this, as they rely on previously known values.

Response format​

When using the valueFunction feature, the response will be in the following JSON format:

[
  {
    "time": String,
    "value": Number
  },
  ...
]

time: An ISO 8601 timestamp (e.g., 2019-08-07T12:30:00.00Z) indicating the start of the time window.
value: The result of the specified valueFunction operation for the time window.

Handling Empty Windows​

If there are no data points within a specified time window, that window will be skipped in the response.

Example​

Here's an example response for an API request with valueFunction=mean and distance=3600 (1 hour):

[
  {
    "time": "2019-08-07T12:00:00.00Z",
    "value": 23.5
  },
  {
    "time": "2019-08-07T13:00:00.00Z",
    "value": 19.8
  },
  ...
]

In this example, the value at each timestamp is the mean of all values within the corresponding one-hour window.

Retention Policy​

An optional retention policy can be set on a iotnode, retention policy allows for automatic removal of time series data after a sertain time period. The retention policy of a node is determined by the retentionPolicy field on the node and will default to no retention policy if not set. Note changing retention policy on an existing iotnode is not recomended as it will make the existing time series data unaccessable

retention policy options

  • retentionForever
  • retention2days
  • retention30days
  • retention183days
  • retention365days
  • retention730days
  • retention1826days