Skip to content

IoT Time Series Service

Learn how to read and write time series data with MindSphere.

Introduction

As soon as your device has been connected to MindSphere and sending data you are able to gain insights by doing analysis and visualization.

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. Please follow the steps in the Authentication & Authorization section to learn how to do this. You will need the following OAuth 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.

Prerequisites

Time Series data is always associated to an Asset with a respective Aspect. Therefore, in order to be able to store Time Series values, you will first need to create an Aspect defining the types of data you want to collect and assign the Aspect to an Asset.

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, expecting values for the defined variables within the Aspect. Let's 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 for an aspect with different time stamp each 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 part of the values is provided within a request. Existing values are overwritten with null, if they are not present in the current request.

Info

Currently the maximum size of the payload for a single request is limited to 1 MByte. This will probably change in future releases.

Any data sent to the endpoint gets written asynchronously to 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 an 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 to get the latest value, values from a defined time range, a defined number of values from a given start time and selection of specific variables.

Get the latest value

If you issue a GET request to the endpoint mentioned above without any parameters, you will receive the entry with the latest time stamp.

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

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 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 respective values in the response are sorted in ascending order.

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 equals the response from the time range query. It contains a result array with the number of entries equal to the limit parameter value. If there are fewer entries than specified by limit, then only the existing entries are returned.

The maximum number of entries that can be retrieved is 2.000, 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 property names.

Sample Response:

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

The select parameter can be combined with range and limit parameters. 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.