property.history

The property.history command is used to obtain historical property data (typically sensor data) for a Thing. For more information about properties see Understanding properties.

Property history can be requested by specifying:

A definite time period using a start and end date
A time period defined by the "last period of time" style query (last "24h", etc.)
A last number of records

TR50 Request

// Definite time period request
{
  "cmd": {
    "command": "property.history",
    "params": {
      "thingKey": "mything",
      "key": "myprop",
      "start": "2018-01-01T00:00:00Z",
      "end": "2018-01-31T23:59:59Z"
    }
  }
}

// Last period of time request
{
  "cmd": {
    "command": "property.history",
    "params": {
      "thingKey": "mything",
      "key": "myprop",
      "last": "24h"
    }
  }
}

// Last number of records request
{
  "cmd": {
    "command": "property.history",
    "params": {
      "thingKey": "mything",
      "key": "myprop",
      "records": 100
    }
  }
}

Request Parameters

Name	Type	Required	Description
thingKey	String	Yes*	Key of the thing.
thingId	String		Id of the thing.
esn	String		ESN of the thing.
iccid	String		ICCID of the thing.
imei	String		IMEI of the thing.
imsi	String		IMSI of the thing.
meid	String		MEID of the thing.
msisdn	String		MSISDN of the thing.
*One of the above parameters is required to identify the thing. The parameter identifies the Thing to which the alarm data is associated. If omitted, the thingKey associated with your session will be used.
key	String	Yes	The key for the property that you wish to publish.
split	Bool		Set to true if you want the timestamp and value fields to be split into two arrays
start	String		When doing a definite time period request this is the timestamp for the start of the specified time window.
end	String		When doing a definite time period request this is the timestamp for the end of the specified time window.
last	String		When doing a last period of time request this specifies the last X amount of time in seconds (s), minutes (m), hours (h), or days (d).
records	Integer		When doing a last number of records request this specifies the number of records to return. A value of zero returns 5000 records.
returnIds	Bool		Returns the id of the property
showMillis	Bool		Returns the ts with milliseconds

If the command is sent successfully a success message and the property values found are returned. Otherwise, an error and error message will be returned.

The number of records returned is limited to 5000 by the deviceWISE Cloud. If your query returns more results than the limit of the deviceWISE Cloud, you should shorten your time window or lower the number of records you are requesting.

TR50 Response

{
  "cmd": {
    "success": true,
    "params": {
      "values": [
        {
          "value": 42,
          "ts": "2018-01-01T01:01:01Z"
        },
        {
          "value": 43,
          "ts": "2018-01-01T01:11:02Z"
        },
        {
          "value": 41,
          "ts": "2018-01-01T01:22:01Z"
        }
      ]
    }
  }
}
 
// "split" response example
{
  "cmd": {
    "success": true,
    "params": {
      "values": [
        42,
        43,
        41
      ],
      "timestamps": [
        "2018-01-01T01:01:01Z",
        "2018-01-01T01:11:02Z",
        "2018-01-01T01:22:01Z"
      ],
      "corrIds": [
        "",
        "123TestCorrelationId",
        ""
      ]
    }
  }
}

Response Parameters

The property.history response can be either:

Values array with the following parameters

Name	Type	Description
id	String	The id of the property (if returnIds is set to true)
value	Integer	The value for the given timestamp.
ts	String	Timestamp for the given value.
corrId	String	The correlation identifier associated with the property.

Multiple arrays: when the split request parameter is set to true

Name	Type	Description
ids	Array	Array of ids (if returnIds is set to true)
values	Array	Array of values
timestamps	Array	Array of timestamps
corrIds	Array	Array of correlation IDs.

The property.history response can also contain the following key:

Name	Type	Description
truncated	Boolean	If this value is in the response, it will be true. It is defined if the number of possible records is equal to or greater than the maximum configured.