property.history

For more information about properties see Defining Properties.

The property history request can specify the following:

a specific time period using a start and end date
a time period defined by the last period-of-time-style query (for example, "last":"24h")
number of records to return

TR50 Request

// Specific 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"
    }
  }
}

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

Request Parameters


Name	Type	Required	Description
	Thing Identifier Parameters		Identifies the thing to which the property data is to be associated. If omitted, the request uses the thingKey associated with the session. For a list of supported parameters, refer to Thing Identifier Parameters.
key	String	Yes	The key for the property to retrieve.
split	Bool		Specify true to retrieve the timestamp and value fields in separate arrays
start	String		In a specific time period request, this is the timestamp of the start of the specified time window.
end	String		In a specific time period request, this is the timestamp for the end of the specified time window.
last	String		In 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		In a last number of records request, this specifies the number of records to return. If the number is not specified, a maximum value of 5000 records per call is used by default.
returnIds	Bool		Returns the id of the property
showMillis	Bool		Returns the ts in milliseconds

Thing Identifier Parameters


Name	Type	Description
thingKey	String	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

TR50 Response

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

Device Cloud limits the number of records returned. If your selection results exceed the limit, shorten the time period or reduce the number of records in your request.

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

Response Parameters

The property.history response can contain either of the following:

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

Separate values and timestamps 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 included in the response, the value is true and indicates that the number of possible records is equal to or greater than the maximum configured.