Payload formats based on JSON

There are two JSON payload formats for time series:

  • Format TsChannelsFloatSeriesJSON
  • Format TsChannelsFloatAtTimeJSON

Per request / message, the formats let you include data for one device for one or more of its channels. The device is always denoted outside of the payload (as part of the URL path / MQTT topic). Therefore, a device identifier does not appear within any of the formats.

Using the format TsChannelsFloatSeriesJSON

- format_name: TsChannelsFloatSeriesJSON
- format_id: 17
- format_byte_id: the byte value 0x11 (Binary 00010001)
- Technology: JSON encoded with UTF-8

Example

{
  "data": {
    "1": [
      {
        "time": 1605813332501,
        "value": 1.11
      },
      {
        "time": 1605813333501,
        "value": 1.12
      }
    ],
    "2": [
      {
        "time": 1605813332501,
        "value": 1.21
      },
      {
        "time": 1605813333501,
        "value": 1.22
      }
    ],
    "3": [],
    "4": [
      {
        "time": 1605813332501,
        "value": 1.4
      }
    ]
  }
}

This JSON data format can be used to send time series to the Cloud.

  • The integer keys are the channel indices, each pointing to an array of one or more values.
  • The field time represents the point in time of a value on a time series. It requires a non-decimal JSON Number simply representing EpochMillis (not to be confused with EpochSeconds or other variants).
  • The field value represents the amplitude of a value on a time series. It requires a JSON Number, which must however at the same time adhere to the further restrictions of the Java float, since this number is interpreted by the Cloud as a Java float. The JSON Number may be positive, zero or negative. It must not be lesser or greater than the minimum or maximum float value supported by Java, respectively.
  • You may freely omit channels if there are currently no values to be sent for these. Alternatively, the arrays of values for these channels may be empty, as shown in the example for channel 3.

Note

This format is basically the JSON equivalent of the format TsChannelsFloatSeriesProto3.

Using the format TsChannelsFloatAtTimeJSON

- format_name: TsChannelsFloatAtTimeJSON
- format_id: 19
- format_byte_id: the byte value 0x13 (Binary 00010011)
- Technology: JSON encoded with UTF-8

Example

{
  "time": "1588103045342",
  "data": {
    "1": 10000.001,
    "2": 20000.002,
    "3": 30000.004,
    "4": 40000.004
  }
}

This JSON data format can be used to send values from one particular point in time to the Cloud.

  • The integer keys are the channel indices, each pointing to one value.
  • The field time represents the point in time of the values. It requires a JSON String representing EpochMillis (not to be confused with EpochSeconds or other variants).
  • The value represents the amplitude at the point in time. It requires to be a JSON Number, which must however at the same time adhere to the further restrictions of the Java float, since this number is interpreted by the Cloud as a Java float. The JSON Number may be positive, zero or negative. It must not be lesser or greater than the minimum or maximum float value supported by Java, respectively.

An example scenario for using this format is when you wish to publish measurements to the Cloud, in regular intervals, also usually in near time or near real time, in such a way that in each request / message you want to only include values from one particular point in time. In such a scenario, this format reduces overall bandwidth consumption when compared to the format TsChannelsFloatSeriesJSON. Note that by using the formats based on Google Protocol Buffers 3 instead of JSON, you can save much more on bandwidth consumption.

You may freely omit channels if there are currently no values to be sent for these.

Note

This format is basically the JSON equivalent of the format TsChannelsFloatAtTimeProto3.

Did you find it helpful? Yes No

Send feedback
Sorry we couldn't be helpful. Help us improve this article with your feedback.