Advanced Data Inquiry

Advanced Data Inquiry allows querying measurement data (values, location and attributes) for a single account using advanced filtering and sorting.

HTTP Method: POST

URI: accounts/{accountId}/data/search/advanced

Parameter	Type	Description	Value
Authorization	HTTP Header	Access Token	Authorization: Bearer eyJ0eX...
Content-Type	HTTP Header		application/json
accountId	URL Slug	The ID of the required account	534da46c820cb9f74a0d3de6

advancedDataInquiryRequest Message

{
	"gatewayIds" : ["<gid1>", "<gid2>"],
	"deviceIds" : ["<did1>", "<did2>"],
	"componentIds" : ["<cid1>", "<cid2>"],
	"from" :  <start_datetime>,
	"to" :  <end_datetime>,
	"returnedMeasureAttributes" : ["att_1", "att_2"],
	"showMeasureLocation" :  <true/false>,
        "aggregations":<include/exclude/only>,
	"devCompAttributeFilter" : {
		"filterName1" : ["filter_value1", "filter_value2"],
		"filterName2" : ["filter_value1", "filter_value2"]
	},
	"measurementAttributeFilter" : {
		"filterName1" : ["filter_value1", "filter_value2"],
		"filterName2" : ["filter_value1", "filter_value2"]
	},
	"valueFilter" : {
		"value" : ["filter_value1", "filter_value2"]
	},
	"componentRowLimit" :  <limit_value>,
	"countOnly" :  <true/false>,
	"sort" : [{
			"sortField1" : "<sort_order>"
		}, {
			"sortField2" : "<sort_order>"
		}		
	]
}

Message Fields:

Key	Example Value	Comments
gatewayIds	["436-e7e", "269-32f"]	Optional. An array of gateway IDs that devices connected to them will be returned in the response.
deviceIds	["436-e7e", "269-32f"]	Optional. An array of devices IDs to return in the response. If field isn't sent - will return all devices in account.
componentIds	["234-f7a", "249-42c"]	Optional. An array of component IDs to return in the response. If field isn't sent - will return all components in account.
from	1391971083468	Earliest measurement to include in response.
to	1391972538404	Latest measurement to include in response.
returnedMeasureAttributes	["interval", "intensity"]	Optional. An array of attributes that will be returned for each measurement. If the requested attribute was not sent in the measurement, an empty string will be returned for that attribute.
showMeasureLocation	true	Optional. If set to true, the lat, lon and alt fields will be returned for each measurement. If one of the location fields does not exist in the measurement, a null value will be returned for that field. Possibel Values: true, false. Default: false.
aggregations	include	Optional. include would add aggregations to the response(Max, Min, Count, Sum, sumSquares) for each component; only would not have the samples array; Non-numeric metrics will be ignored during for aggregation calculations. Possible Values: include, exclude, only. Default: exclude
componentRowLimit	10	Optional. Limits the number of records returned for each component in the response. Can be used in conjuction with the sorting options to get "top" records.
sort	[{"Timestamp": "Asc"},{"Value": "Desc"}]	Optional. An array of sort objects, each has the sort field as a key and the sort order as value. The objects order in the list sets the sorting order within each component. Possible values for the sortField key: Timestamp, Value. Possible values for sortOrder: Asc, Desc.
countOnly	true	Optional. Setting to true will return the number of rows that would have returned from this query. Default: false
devCompAttributeFilter	{"componentType" : ["temperature.v1.0", "humidity.v1.0"], "deviceName" : ["My Watch" ], "Tags" : ["Intel","IOT"]}	Optional. Filters by device and/or component attributes. See below.
measurementAttributeFilter	{"fromPhoneNumber" :["123","456"]}	Optional. Filters by measurement attributes. See below.
valueFilter	"value":["1","0"]	Optional. Filters by measurement values. See below.

Attribute and Value filters

All filter keys and values are sent as strings (including numeric values).

gatewayIds, deviceIds and componentIds filter on the unique ID and can be used to pin-point a specific gateway/device/component.

valueFilter work on the "value" field of each measurement.

Attribute filters work on the device/component/measurement attributes. Each entry is an attribute name with a list of values to be matched.

For device and component, in addition to user-defined attributes, special metadata attributes can be used for filtering: groupPath, deviceName, Tags, componentName, componentType.

Different filters and different attributes within filters are evaluated with AND relation. Values in the value list are evaluated with OR relation:

{
"deviceIds" : ["ABC"],
"componentIds" : ["123", "456"],
"devCompAttributeFilter" : {"Tags" : ["Intel", "IOT"], "componentType" : ["temperature"]}
}

Means:

(deviceId = "ABC") AND (componentId = "123" OR "456") 
AND (Tags contains "Intel" OR "IOT") AND (componentType = "temperature")

The combination of gatewayIds, deviceIds, componentIds and devCompAttributeFilter determine the objects returned in the response. The other filters determine which records are returned for each object. Therefore, if a device satisfies the device filters but has no records that satisfy the value filter, it will return with an empty samples array. Conversely, if the filter combination is empty (e.g. componentID value that doesn't exist in the supplied deviceID), no objects will be returned. It is the client responsibility to ensure the filters sent are valid.

The device/component/gateway filters do not support "slowly changing dimensions": e.g. if the device list is filtered by deviceName and a device name changed from "My Device X" to "My Device Y" on April, his past measurements (January-March) will also be returned when requesting "My Device Y", although they were measured when the device name was different.

Expected Response

200 OK - response body will include an advancedDataInquiryResponse message.

advancedDataInquiryResponse Message

with countOnly = false:

{
	"msgType" : "advancedDataInquiryResponse",
	"accountId" : "<account_id>",
	"startTimestamp" :  <start_datetime>,
	"endTimestamp" :  <end_datetime>,
	"componentRowLimit" :  <limit>,
	"data" : [
		{
		"deviceId" : "<did1>",
		"deviceName" : "<name>",
		"components" : [{
			"componentId" : "<cid>",
			"componentType" : "<component_type>",
			"componentName" : "<component_label>",
            "max":"<max_value>",
			"min":"<min_value>",
			"sum":"<sum_value>",
			"count":"<count_value>",
			"sumSquares":"<sum_squares>",
			"samplesHeader" : ["Timestamp", "Value", "lat", "lon", "alt", "att1", "att2"]
			"samples" : [
					["ts", "val", "", "", "", "", "<att2_value>"],
					["ts", "val", "<lat>", "<lon>", "<alt>", "<att1_value>", ""],
					["ts", "val", "", "", "", "", ""]
					]
				}, 	
				{
				 < component2 > 
				}
			]
		}, 
		{
		 < device2 > 
		}
	]
}

with countOnly = true:

{
   "msgType": "advancedDataInquiryResponse",
   "rowCount" : <count>
}

Message Fields:

Key	Example Value	Comments
msgType	advancedDataInquiryResponse	Always “advancedDataInquiryResponse”
accountId	WaterWorks Inc.
startTimestamp	1391971083468	Repeats the field sent in the request
endTimestamp	1391972538404	Repeats the field sent in the request
componentRowLimit	10	Optional. repeats the componentRowLimit sent in the request (if sent).
data	array	An array of deviceData objects. If no data exists for the required filters, an empty array will be returned.

deviceData Object:

Key	Example Value	Comments
deviceId	436e7e74-6771-4898
deviceName	My Device 1
componentId	436e4-4898-7e101
componentName	Humidity Sensor 1
componentType	humidity_v10
samplesHeader	"ts", "val", "lat", "lon", "alt", "measure_accuracy"	Header row for the component's data. Always includes timetsamp (ts) and value (val). Followed by lat, lon, alt (if showMeasureLocation was true) and then the attributes ordered as set in returnedMeasureAttributes.
samples	["1345786321","0.8", "32.1", "34.2", "4.5", "+-2%"]	A list of records, each ordered according to the fields in samplesHeader. All values sent as strings, null values as empty strings.

If request would result in 500 000 samples or more, error 413 - Entity too large will be returned.