IoT Time Series Service – Samples¶

As soon as your device is connected to Insights Hub and sends time series data, you will be 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.

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;

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.

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}

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;

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.

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