Aggregated Report Interface

Aggregated Report Interface allows user to query aggregated metrics data in a single account. The reports will enable view of summary data as well as raw level data for managerial and operational purposes.

HTTP Method: POST

URI: accounts/{accountId}/data/report

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

Important notes:

• Non-numeric metrics are not supported
• For dimensions combinations that have no data, no rows will be returned
• If a dimensions exist only in some of the returned component, all other components will be grouped under the value "N/A" for that dimension.
• Numbers are rounded up to 4 decimal places
• Standard deviation is calculated based on sample (n-1)
• Filters do not support "slowly changing dimensions": e.g. if we aggregate devices by deviceName and a device name changed from "My Device X" to "My Device Y" on April, his past data (January-March) will now also be aggregated as "My Device Y", although it was measured when the device name was different.

---

aggregatedReportRequest Message

{
   	"from": <start_date>,
   	"to": <end_date>,
   	"aggregationMethods": ["<value_type1>", "<value_type2>"],
	"dimensions": ["dim1", "dim2"],
	"offset": <results_index>, 
	"limit": <number>, 
	"countOnly": <true/false>,
	"outputType": "json", 	
	"deviceIds":["<device1>", "<device2>"],
	"gatewayIds":["<gateway1>", "<gateway2>"],
	"componentIds":["<component1>", "<component2>"],
	"sort": [
		{"sortField1": "<sortOrder>"},
		{"sortField2": "<sortOrder>"}
	],
	"filters": {
 		"filterName": ["filter_value1", "filter_value2"]	         	
    }
 }

Key	Example Value	Comments
from	1391971083468	Earliest measurement to include in response represented by a Unix time integer.
to	1391972538404	Latest measurement to include in response represented by a Unix time integer.
aggregationMethods	"average", "min"	A list of aggregation methods that will be returned. Acceptable values: average, min, max, std, count and sum. Default: average
dimensions	"timeHour", "componentName", "deviceAttribute_any"	Optional. A list of dimensions for measurements aggregation. The list of Acceptable dimensions values can be found below. Default: componentType
limit	800	Optional. The maximum number of rows to include in the response.
offset	100	Optional. The first row of data to return in the response, starting from 0. If an offset is sent, a limit must be sent as well. Offset and limit together can be used for pagination: for example limit=5 and offset=0 will return rows 1-5; limit=5 and offset=5 will return rows 6-10. Note that if the paged data changes between requests, the pagination might become misaligned. This can be avoided by using an endTimestamp early enough so that new data won't be received between requests.
countOnly	true	Optional. Setting to "true" will return only the number of rows that would have returned from this query, without the data itself.
outputType	"json"	Optional. The desired output type for the data returned in the response. Acceptable values are json and csv. Currently, only json is supported. Default: json
deviceIds	"device-15564144", "device-45555333"	Optional. A list of device ids to be used for filtering returned data.
gatewayIds	"gateway-1", "gateway-2"	Optional. A list of gateway ids to be used for filtering returned data.
componentIds	"4e964fa6-31d9-4caa-bb25-776764eeb7bd", "c8b02124-a74f-45e0-968a-6fcf74114829"	Optional. A list of component ids to be used for filtering returned data.
sort: sortField	"timeHour", "componentName"	Optional. A single dimensions or aggregationMethods value indicating the dimension to sort by the returned data.
sort: sortOrder	"Asc"	Required if sortField is sent. Acceptable values: Asc, Desc
filters	"componentType" : ["accelerometer"],"Status" : [ "OK" ], "Manufacturer" : ["LG", "Intel"],"Tags" : ["Intel", "IOT"]	Optional. A list dimension and values filters that restrict the data returned for the request. The list of Acceptable filters values can be found below.

Acceptable dimensions values:

Dimension name	Acceptable Values	Comments
Time	timeHour, timeDate, timeMonth, timeWWSun (WW starts on Sunday), timeWWMon (WW starts on Monday), timeWeekDay	Workweeks are calculates according to ISO standard and numbered 1 to 52 or 53. Future release will include: timeQuarter.
Device metadata	deviceId, gatewayId, groupPath, deviceName
Component metadata	componentId, componentName	Component type is mandatory dimension for the response, it should not be sent at the request and will always be returned as the first response dimension
Component & Device attributes	All attributes names as sent at device registration, vary from one device to another. Can include, but not limited to - Data Type, Unit of Measure etc.	Each attribute is a separate dimension

Acceptable filters values:

Filter name	Acceptable Values	Comments
Device metadata	groupPath, deviceName, Tags	To filter by deviceId and gatewayId use the designated fields in the request body. Tags will match if any of the tags supplied exist in the device tag list.
Component metadata	componentName, componentType	To filter by componentId use the designated field in the request body
Component & Device attributes	All attributes names as sent at device registration, vary from one device to another. Can include, but not limited to - Data Type, Unit of Measure etc.

Filters Operators:

• Different filters and different attributes within filters are evaluated with AND relation.
• Values in the value list of an attribute are evaluated with OR relation.
• It is possible to filter on a field without returning it as dimension and vice-versa.

For example:

{
"componentIds" : ["123", "456"], "filters" : {"Tags" : ["Intel", "IOT"], 
"componentType" : ["temperature"], "deviceName ": ["device A","device B", "device C"]}
}

Means:

(componentId = "123" OR "456") AND (Tags contains "Intel" OR "IOT") 
AND (Region = "Israel" OR "US") AND (componentType = "temperature")
AND (deviceName = "device A" OR "device B" OR "device C") 

Expected Response

200 OK - response body will include an aggregatedReportResponse message.

aggregatedReportResponse Message

(with countOnly = false):

{
	"msgType" : "aggregatedReportResponse",
	"columnHeaders": ["<col1>","<col2>"] , 
	"data": [
		["dim1_val1"," dim2_val1", agg_value1, agg_value2],
		["dim1_val2"," dim2_val2", agg_value1, agg_value2]                
	],
	"aggregatedDataStartTimestamp": <real_start_time>,
	"aggregatedDataEndTimestamp": <real_end_time>
}

(with countOnly = true):

{
   "msgType": "aggregatedReportResponse",
   "columnHeaders": ["resultCount"] , 
   "data": [
		[<count>]
	],
   "aggregatedDataStartTimestamp": <real_start_time>,
   "aggregatedDataEndTimestamp": <real_end_time>
}

Key	Example Value	Comments
msgType	aggregatedReportResponse	Always "aggregatedReportResponse". Used to validate message type
columnHeaders	"componentType", "deviceName", "timeHour", "min", "max", "average"	Column headers that list dimension names followed by the aggregation method names. The number of headers is the number of dimensions + the number of aggregation methods.
data	["Temperature", "device-12345", "1407330000000", "-25", "-10", "-20"], ["Temperature", "device-67890", "1407330000000", "0", "5.5", "4.33"],["Temperature", "device-12345", "1407340000000", "-20", "-9", "-17.5"],["Temperature", "device-67890", "1407340000000", "0", "5.5", "4.33"]	Report data rows, where each row contains a list of dimension values followed by the aggregation values. The order of dimensions and aggregation values is same as specified in the columnHeaders. Each row has a list of N fields, where N = the number of dimensions + the number of aggregations
aggregatedDataStartTimestamp	1406804400000	Rounds down the request startTimestamp to the hour (e.g. if requested start time is 1/1/2014 09:30:00, data will be returned starting 1/1/2014 09:00:00). This is in order to align with the report pre-aggregation where data is aggregate hourly, meaning 9am data in aggregation of 9am to 10am mesearement.
aggregatedDataEndTimestamp	1406808000000	rounds up the request endTimestamp to the hour (e.g. if requested end time is 1/1/2014 10:30:00, data will be returned ending at one millisecond before 1/1/2014 11:00:00)