Gets reports

A token from the previously returned response to retrieve the specified page.

The number of items to return per page

Defines the report metric to be calculated. The metrics are always calculated over a time period, either over each interval specified by the interval parameter (for example, over a week) or over the whole time period of the report.

• duration: duration of the event
  • "The asset dwelled for 45 hours during week 2. It was in detention for 4 hours."
• occurrence: total number of the event occurrences
  • "During week 3, the asset was in detention 2 times. During the past month it had 7 individual dwelling periods."
• day: the number of days the event lasted
  • "The asset was utilized for 3 days during week 4."
• asset: the number of assets that generated the event
  • "On Monday 5 assets were in detention. On Tuesday 16 assets were in detention."

Defines an interval, which can be a day, a week or a month, that will be used to group the report results.

When the interval parameter is provided, the response will be an array of timestamp-value pairs where the timestamp defines the beginning of the interval and the value is the specified report metric's value calculated over the interval time.

Tracking ID. Provide a tracking ID to get a report on a specific asset.

Note that in the report context an asset is a device.

For example, to get a report on how many times the specified asset was in detention during each week, create a request specifying the following:

• reportId: ID of a report created for a detention rule
• trackingId: tracking ID
• measure: 'occurrence'
• interval: 'week'

ID of the geofence.

One can provide a geofence ID in case one wants to get reports on a specific geofence. This parameter can only be used with reports created for a dwelling rule type.

For example, to get a report on assets' average dwelling time in the specified geofence during each week, create a request specifying the following:

• reportId: ID of a report created for a dwelling rule
• measure: 'duration'
• groupBy: 'asset'
• interval: 'week'
• method: 'average'
• geofenceId: geofence ID

Defines whether the report metrics, such as cumulative or average, are calculated per asset or per geofence.

The parameter can have a value 'geofence' only with reports created for a dwelling rule.

To get a report on how many times on average assets were in detention during each time interval, create a request specifying the following:

• reportId: ID of a report created for a detention rule
• groupBy: 'asset'
• method: 'average'
• measure: 'occurrence'

To get a report on how long all assets dwelled inside each geofence during the report period, create a request specifying the following:

• reportId: ID of a report created for a dwelling rule
• groupBy: 'geofence'
• measure: 'duration'

To get a report on how long each asset dwelled (inside any geofence) during the report period, create a request specifying the following:

• reportId: ID of a report created for a dwelling rule
• groupBy: 'asset'
• measure: 'duration'

Defines the calculation method. The parameter method can only be provided along with interval.

The parameter value can be percentage only when measure is 'asset'.

For example, to get a report on percentage of all assets that were in use during each week, create a request specifying the following:

• reportId: ID of a report created for a utilization rule
• interval: 'week'
• method: 'percentage'
• measure: 'asset'

When method is set to 'cumulative' or 'average' and measure is set to 'duration' or 'occurrence', the groupBy parameter needs to be provided also. For example, to get a report on how long all assets dwelled in total in the specified geofence during each week, create a request specifying the following:

• reportId: ID of a report created for a dwelling rule
• geofenceId: ID of a geofence
• interval: 'week'
• method: 'cumulative'
• measure: 'duration'
• groupBy: 'asset'

When method is set to 'cumulative' or 'average' and measure is set to 'day', the groupBy parameter is automatically set to 'asset'. For example, to get a report on how many days on average assets were in use during each month, create a request specifying the following:

• reportId: ID of a report created for a utilization rule
• interval: 'month'
• method: 'average'
• measure: 'day'
• groupBy: 'asset'

Defines how the items are sorted.

• If interval is provided, the default is sort=timestamp:asc
• If interval is not provided, the default is sort=value:desc