Skip to content

IoT Time Series Service – Read and Write Time Series Data with MindSphere

Introduction

As soon as your device has been connected to MindSphere and sends data, you are able to gain insights by doing analysis and visualization. The Time series data is always stored against an asset and an aspect.

This how to guide shows you how to write and read time series data with MindSphere.

Before you Begin

Prerequisites

  • You have access to MindSphere API collections.
  • You have created an aspect defining the types of data you want to collect.
  • You have assigned the aspect to an asset in order to be able to store time series values.

Get a Token to call IoT API from your App

In order to contact the IoT Time Series Service or IoT TS Aggregates Service you need to retrieve a valid token. Follow the steps in the Authentication & Authorization section to learn how to do this. You will need the following scopes for accessing the service endpoint:

  • iot.tim.r (read time series)
  • iot.tim.w (write time series)

Check out the Roles & Scopes section on how to get those scopes for your application.

Write Time Series Data

To write time series data to a pre-configured aspect, use the following API endpoint:

1
https://gateway.{region}-{environment}.mindsphere.io/api/iottimeseries/v3/timeseries/{assetId}/{aspectName}

The endpoint is called using a PUT request and expects values for the variables defined within the aspect. Assume an aspect with three variables: temperature, pressure and notes. temperature and pressure are numeric values whereas the notes variable can be used to store string values.

Sample Payload:

1
2
3
4
5
6
7
8
[
  {
    "_time": "2017-11-02T00:00:00.001Z",
    "temperature": 10,
    "pressure": 2,
    "notes": "normal operation"
  }
]

The _time field is pre-defined and expects a valid time stamp according to ISO 8601.

You may send multiple values with different time stamps to an aspect using a single request:

Sample Payload:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
[
  {
    "_time": "2017-11-02T00:00:00.001Z",
    "temperature": 10,
    "pressure": 2,
    "notes": "normal operation"
  },
  {
    "_time": "2017-11-02T00:01:00.001Z",
    "temperature": 17,
    "pressure": 2,
    "notes": "normal operation"
  },
  ...
]

Attention

If you write data for a time stamp that already exists, existing values are overwritten. This is also true, if only some values are provided within a request. Existing values are overwritten with NULL, if they are not provided in the request.

Info

The maximum size of the payload for a single request is limited to 1 MB.

Any data sent to the endpoint is asynchronously written into the underlying data store. So there might be a slight delay before you can read back the data from the service. Validation of the payload is done synchronously, so that the client receives immediate feedback.

Read Time Series Data

To read time series data from a pre-configured aspect, use the following API endpoint:

1
https://gateway.{region}-{environment}.mindsphere.io/api/iottimeseries/v3/timeseries/{assetId}/{aspectName}

The endpoint is called using a GET request. It allows the user to get the latest value, values from a defined time range, a defined number of values from a given start time and to select specific variables.

Get the latest Value

If you issue a GET request to the endpoint mentioned above without any parameters, you receive the entry with the latest time stamp. If the latest value is older than 12 months, it is not returned.

Sample Response:

1
2
3
4
5
6
7
8
[
    {
        "temperature": 12,
        "pressure": 4,
        "notes": "normal operation",
        "_time": "2017-11-02T00:00:00.001Z"
    }
]

Get Data from a Time Range

A time range can be specified by using additional URL parameters, e.g.:

1
GET https://gateway.{region}-{environment}.mindsphere.io/api/iottimeseries/v3/timeseries/{assetId}/{aspectName}?from=2017-11-01T00:00:00Z&to=2018-01-01T00:00:00Z

Sample Response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
[
    {
        "temperature": 10,
        "pressure": 2,
        "notes": "normal operation",
        "_time": "2017-11-01T00:00:00.001Z"
    },
    {
        "temperature": 17,
        "pressure": 2,
        "notes": "normal operation",
        "_time": "2017-11-01T01:00:00.001Z"
    }
]

The timestamps in the response are given in ISO8601 format, using the UTC time zone. The service returns the time series records with timestamps greater than the from time and less than or equal to the to time. The respective values in the response are sorted in ascending order.

If you use the + character in the from and to parameters for the time zone, it must be encoded to %2B, because it is used in the URL. For example, instead of sending 2017-09-21T14:08:00+02:00, send 2017-09-21T14:08:00%2B02:00.

Get a Defined Number of Entries after a Given Start Time

To retrieve a certain number of time series entries from a given start time, an additional URL parameter (limit) can be used, e.g.:

1
GET https://gateway.{region}-{environment}.mindsphere.io/api/iottimeseries/v3/timeseries/{assetId}/{aspectName}?from=2017-11-01T00:00:00Z&limit=4

The response is the same as for the previous example. It contains a result array with as many entries as defined by the limit parameter. If there are fewer results available than the defined limit, the response only has this many entries.

The result array is limited to 2,000 entries, regardless of the limit parameter setting.

Select Variables to Retrieve

If not all variables from an aspect are needed, an additional select parameter can be added to the request, e.g.:

1
GET https://gateway.{region}-{environment}.mindsphere.io/api/iottimeseries/v3/timeseries/{assetId}/{aspectName}?select=temperature

The parameter accepts a comma separated list with variable names. It can include the quality code variable names, which are the respective variable names extended with a _qc suffix. If no select clause is specified, all the variables, including quality code variables, are returned. Variable names are case-insensitive.

Info

The select query also returns time series entries for which the selected variable is not available. So it might happen, that the response to the select query in this example contains time series entries that don't have the _temperature field.

Sample Response:

1
2
3
4
5
6
[
    {
        "temperature": 17,
        "_time": "2017-11-01T01:00:00.001Z"
    }
]

The select parameter can be combined with a time range and the limit parameter. If used without any additional parameters, the request returns the latest entry.

Any questions left?

Ask the community


Except where otherwise noted, content on this site is licensed under the MindSphere Development License Agreement.