Skip to content

IoT Time Series Service – Samples

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.

Prerequisites

  • 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 entries.

Writing 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. For example, 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 timestamp according to ISO 8601.

You may send multiple entries with different timestamps 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 timestamp that already exists, existing values are overwritten. If only some values are provided within a request, the remaining values are overwritten with NULL.

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. Hence, there might be a 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.

Reading 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 entry, entries from a defined time range, a defined number of entries from a given start time and to select specific variables.

Get the Latest Entry

If the endpoint mentioned above receives a request without any parameters, it returns the entry with the latest timestamp. If the latest entry 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 is specified by 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 entries in the response are sorted in ascending order.

For setting the time zone of the from and to times, the + character must be encoded to %2B 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 specific number of time series entries from a given start time, use the URL parameter (limit), 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 only specific variables of an aspect are of interest, use the select parameter in 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 of variable names and quality code variable names. These 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. In this example, the response to the select query may 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. Otherwise, the request returns the latest entry, which satisfies the filter.

Any questions left?

Ask the community


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