Read Snapshot Data Within a Time Range for a Thing

Retrieves snapshot data of a thing within the specified time range

With this service, you can retrieve the latest value of properties for the specified thing ID. The service uses fromTime and toTime, to define the time range to retrieve the latest non-null value. The difference between the fromTime and toTime must be less than or equal to 30 days. In addition, the service retrieves the reference properties data of the specified thing ID. Based on the value you specify for the fromTime and toTime, the service responds as described below:

  • The difference between the fromTime and toTime is beyond 30 days, for example, fromTime='2018-01-01T06:00:00Z',toTime='2020-01-01T06:00:00Z'.

    • The service does not retrieve any value and displays an error message.

  • You do not specify both fromTime and toTime, for example, fromTime='',toTime=''.

    • In case of time series data, the service scans through the data available from the current time until 30 days in the past and returns the data in the response payload. If the data is not available, the service returns null.

    • In case of master data, the service scans through the data available from the current time until it finds a non-null value. If the data is not available, the service returns null.

  • You do not specify the toTime, for example, fromTime='2018-01-01T06:00:00Z',toTime=''.

    • In case of time series data, the service does not retrieve any value and displays an error message.

    • In case of master data, the service scans through the data available from the time you specified in the fromTime until the current time and retrieves the data, if available.

  • You do not specify the fromTime, for example, fromTime='',toTime='2020-01-01T06:00:00Z'.

    • In case of time series data, the service scans through the data available from the toTime time until 30 days (2019-12-01T06:00:00Z) in the past. If data is available, the service returns the data in the response payload. If the data is not available, the service returns null.

    • In case of master data, the service scans through the data available until the time you specified in the toTime and retrieves the data, if available.

Request

URI: /v2/Snapshot(thingId='<ID>',fromTime='<timestamp>',toTime='<timestamp>',dataCategory='<dataCategory>')

HTTP Method: GET

Permissions: <thing>.r

Request Headers

Parameter Required Description
Accept-Encoding No Retrieve compressed response

Only if you specify the value gzip or gzip,deflate for this parameter, the system returns the compressed response with an additional response header CONTENT-ENCODING with value gzip. If you specify an invalid value or do not use this header parameter, the system returns the uncompressed response.

Request Parameters

Parameter Required Data Type Description
ID Yes string

You can specify one of the following values:

  • Unique thing identifier generated by the system while creating a thing.

  • Alternate thing identifier which is unique only within a specific tenant.
fromTime Yes timestamp Time from which the snapshot details are retrieved for a non-null value of a property. The value for fromTime must correspond to UTC timestamp.
toTime Yes timestamp Time up to which the snapshot details are retrieved for a non-null value of a property. The value for toTime must correspond to UTC timestamp.
dataCategory Yes enum Filters the snapshot details based on data category enumeration values such as MasterData, DerivedData, TimeSeriesData, Parameters, and ReferencePropertyData.
propertySetTypeName No string Property set type name
propertySetID No string Property identifier

Request Example

Read snapshot data of a thing within a specific time range

/v2/Snapshot(thingId='503B8711B5D0445688E7FF7ACFC2177A',fromTime='2015-01-01T06:00:00Z',toTime='2015-01-05T06:00:00Z',dataCategory='TimeSeriesData')

Retrieves snapshot data for the specified thing ID within the time range: January 1, 2015 to January 5, 2015. The service retrieves data only for those properties that belong to the data category TimeSeriesData.

Response

Format: JSON

Response Properties

Property Type Description
_id string Internal identifier for a thing
_thingType Array of thing type objects Array of thing types
value Array of property set objects

Array of property sets along with its properties for the corresponding thing type

The properties block contains the value of the property and its timestamp. In addition, the attribute details such as _qualityCode, description, and _unitOfMeasure are included in the properties block. A _qualityCode with value 0, indicates that property has a quality code value attached and a _qualityCode with value null, indicates that the property does not have a quality code value attached.

Response Status and Error Codes

Code Description
200 Data retrieved successfully

Payload

Format: JSON

Only media type JSON is supported. The JSON for this method has the following structure:

{
	"_id": "503B8711B5D0445688E7FF7ACFC2177A",
	"_thingType": [
		"core.automobiles:ABCXSeries"
	],
	"_referenceProperty": [{
		"path": "/wheel_rr",
		"property": "Pressure",
		"_time": "2015-08-02T07:00:03Z",
		"com.sap.iot.core.UoM": "P",
		"com.sap.iot.core.LowerThreshold": 10,
		"com.sap.iot.core.UpperThreshold": 15,
		"com.sap.iot.core.LowLowerThreshold": 5,
		"com.sap.iot.core.UpperUpperThreshold": 20
	}, {
		"path": "/wheel_rr",
		"property": "Temperature",
		"_time": "2015-08-02T09:00:03Z",
		"com.sap.iot.core.UoM": "PA",
		"com.sap.iot.core.LowerThreshold": 10,
		"com.sap.iot.core.UpperThreshold": 20,
		"com.sap.iot.core.LowLowerThreshold": null,
		"com.sap.iot.core.UpperUpperThreshold": null
	}],

	"value": [{
		"core.automobiles:ABCXSeries": [{
			"/car": [{
				"BodyStyle": {
					"_value": "SUV",
					"_qualityCode": null,
					"_time": "2015-08-02T06:00:03Z",
					"_unitOfMeasure": ""
				}
			}, {
				"Class": {
					"_value": "1st",
					"_qualityCode": null,
					"_time": "2015-08-02T06:00:03Z",
					"_unitOfMeasure": ""
				}
			}, {
				"WheelBase": {
					"_value": "15",
					"_qualityCode": 9,
					"_time": "2015-08-02T06:00:03Z",
					"_unitOfMeasure": ""
				}
			}, {
				"RegistrationNumber": {
					"_value": "001",
					"_qualityCode": null,
					"_time": "2015-08-02T06:00:03Z",
					"_unitOfMeasure": ""
				}
			}, {
				"Colour": {
					"_value": "Black",
					"_qualityCode": null,
					"_time": "2015-08-02T06:00:03Z",
					"_unitOfMeasure": ""
				}
			}],
			"_propertySetType": {
				"name": "core.automobiles:Car",
				"description": "Sensory parameters for car"
			}
		}, {
			"/wheel_rr": [{
				"Pressure": {
					"_value": null,
					"_qualityCode": null,
					"_time": null,
					"_unitOfMeasure": "PA"
				}
			}, {
				"Temperature": {
					"_value": null,
					"_qualityCode": null,
					"_time": null,
					"_unitOfMeasure": ""
				}
			}],
			"_propertySetType": {
				"name": "core.automobiles:Wheel",
				"description": "Sensory parameters for wheel"
			}
		}]
	}]
}