Skip to content

IoT Time Series Service – Samples

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

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 data.

Writing Time Series Data

The samples in this section are based on the PUT endpoint for which limitations apply.

Attention

If data for an already existing timestamp is uploaded, the complete record for this timestamp including all variables is replaced. Variables which are not provided are set to NULL.

Create a Single Time Series Record

Call the following endpoint without additional URL parameters to create a time series record for an aspect:

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

The endpoint expects payload containing a timestamp filed _time and fields for the variables of the selected aspect. The timestamp must adhere with ISO 8601.

Sample payload for an aspect with two numeric variables temperature and pressure, and a string variable notes:

[
  {
    "_time": "2017-11-02T00:00:00.001Z",
    "temperature": 10,
    "pressure": 2,
    "notes": "normal operation"
  }
]

Create Multiple Time Series Records

Create multiple records with different timestamps using a single request to the same endpoint as above.

Sample Payload:

[
  {
    "_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"
  }
]

Create Time Series Records for Multiple Aspects

Create time series data for multiple aspects of the same or different assets using the following endpoint:

https://gateway.{region}-{environment}.{mindsphere-domain}/api/iottimeseries/v3/timeseries;

Info

All aspects must belong to the same environment.

Sample Payload:

{
  "timeseries": [
    {
      "entityId": "{assetId_1}",
      "propertysetName": "{aspectName_1}",
      "data": [
        {
          "enginetemperature_1": 100,
          "speed_1": 100,
          "_time": "2019-03-25T01:00:00Z"
        },
        {
          "enginetemperature_2": 200,
          "speed_2": 200,
          "_time": "2019-03-25T02:00:00Z"
        }
      ]
    },
    {
      "entityId": "{assetId_2}",
      "propertysetName": "{aspectName_2}",
      "data": [
        {
          "rpm_1": 10,
          "pressure_1": 200,
          "_time": "2019-03-25T01:00:00Z"
        }
      ]
    }
  ]
}

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

The samples in this section are based on the GET endpoint for which limitations apply.

A response from this endpoint contains up to 2,000 records. If more records are available, the response contains a Link header with a URI to get the remaining records, such as:

https://gateway.{region}-{environment}.{mindsphere-domain}/api/iottimeseries/v3/timeseries/{assetId}/{aspectName}; rel="next"

Get Data of a Specific Variable

Specify a variable of an aspect using the URL parameter select:

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

The select parameter is case-insensitive. It accepts a comma separated list of variable names and quality code variable names, which suffix the respective variable names with _qc.
The select parameter can be combined with the URL parameters described in the following sections.

Info

The select query excludes other variables from the response, but does not check if the specified variable is available. The response may contain time series records which only consist of the timestamp field.

Sample Response:

[
    {
        "temperature": 17,
        "_time": "2017-11-01T01:00:00.001Z"
    }
]

Get the Latest Record

This endpoint is preferred when aspect data is changing frequently. Call the following endpoint without additional URL parameters to read the latest record of an aspect:

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

Latest Record vs. Latest Value

Note that the latest record might only contain a timestamp. For reading the latest received values, use the respective URL parameter.

Sample Response:

[
    {
        "temperature": 12,
        "pressure": 4,
        "notes": "normal operation",
        "_time": "2017-11-02T00:00:00.001Z"
    }
]

Get the Latest Values

This endpoint is preferred when aspect data is changing non-frequently. Request the latest values using the URL parameter latestValue:

https://gateway.{region}-{environment}.{mindsphere-domain}/api/iottimeseries/v3/timeseries/{assetId}/{aspectName}?latestValue=true;

Latest Record vs. Latest Value

Note that this request returns the latest received value and associated timestamp for each variable. For reading the latest received record, use the respective request.

Sample Response:

[
    {
        "enginetemperature": 11234570,
        "speed": 3,
        "_time": "2019-05-15T04:30:00Z"
    },
    {
        "rpm": 13.12,
        "_time": "2019-05-16T04:30:00Z"
    },
    {
        "pressure": 4,
        "_time": "2019-05-16T05:30:00Z"
    }
]

Get Data from a Specific Time Range

Specify the desired time range using the URL parameters from and to:

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

For setting the time zone of the time range, the + character must be encoded to %2B in the URL. For example, 2017-09-21T14:08:00%2B02:00 instead of 2017-09-21T14:08:00+02:00.

Sample Response:

[
    {
        "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"
    }
]

Timestamps in the response are given in ISO8601 format in UTC. The service returns time series records with timestamps greater than the from time and less than or equal to the to time. The respective records in the response are sorted in ascending order by default. The order can be changed using the optional URL parameter sort (currently only available in region Europe 1.) which accepts either desc or asc.

Bad Request

If the endpoint responds with HTTP 400 Bad Request, it might be caused by:
- The specified timespan is greater than 90 days.
- The from field is greater than the to field.

Get a Defined Number of Records after a Given Start Time

Specify the desired number of records and the start time using the URL parameters from and limit:

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

Sample Response:

[
    {
        "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"
    }
]

If there are fewer results available than the defined limit, the response only contains the available records.

Deleting Time Series Data

The samples in this section are based on the DELETE endpoint for which limitations is applicable.

Valid Delete Request Examples

Specify the desired hourly aligned time range using the URL parameters from and to:

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

The specified time range cannot be more than 7 days:

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

Invalid Delete Request Examples

The specified time range must be aligned hourly. The following request would fail if the from and to is not aligned to the UTC hours:

DELETE https://gateway.{region}-{environment}.{mindsphere-domain}/api/iottimeseries/v3/timeseries/{assetId}/{aspectName}?from=2017-11-01T00:15:00Z&to=2017-11-01T02:15:00Z

The specified time range must be at most 7 days. The following request would fail if the duration between from and to is greater than 7 days:

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

Last update: December 13, 2023

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