Gets the number of devices and shipments in each event state

This API call counts the number of devices and shipments that are currently in the different event states per rule or per event source (that is per rule type).

An event state of a device is the event type of the most recent device event. It indicates a state the device is currently in, in relation to a rule the device is associated with.

For example, the event state can be either INSIDE_GEOFENCE or OUTSIDE_GEOFENCE in case the event source is geofence; or BELOW_RANGE, IN_RANGE or ABOVE_RANGE in case the event source is battery rule.

A device can be in several different event states at the same time when it has more than one rule associated with it. For example, a device can be at the same time in INSIDE_GEOFENCE and ABOVE_RANGE event states.

The same applies for shipments.

The groupBy query parameter defines how the results are grouped.

The default value for the groupBy parameter is ruleId. The response contains a list of objects, one per each rule, that are associated to at least one device or shipment of the project. Each object has the following properties:

• ruleId: a rule ID
• eventSource: the rule type
• every distinct event state (applicable for the rule type) and the number of devices in this state
• total: the total number of devices associated to the rule

When the groupBy parameter value is eventSource, the response contains a list of objects, one per event source (that is per each rule type), that are associated to at least one device or shipment of the project. Each object has the following properties:

• eventSource: a rule type
• every distinct event state (applicable for the rule type) and the number of devices in this state. One device is counted only once per eventType state, but in case a single device is associated to multiple rules of the same type, it will be counted separately for each event state.
• total: the total number of devices associated to the rule type. A single device is counted only once.

For example, a device A is associated to 2 geofences and is inside one and outside the other. A device B is associated to 3 geofences and is outside all of them. With the request query parameter set as groupBy=eventSource, the response body will contain the following result item:

{
  "eventSource": "geofence",
  "INSIDE_GEOFENCE": 1,
  "OUTSIDE_GEOFENCE": 2,
  "total": 2
}.

If the request is supplied with eventSource query parameter, the response results will be limited to the specified rule types only.

If the request is supplied with ruleId query parameter, the response results will be limited to the specified rule IDs only.

If the request is supplied with trackingId query parameter, the response results will be limited to the specified devices only. Also shipmentId can be used as a trackingId.

If the request is supplied with geofenceId query parameter, it will only affect dwelling event statuses filtering, limiting the results to the specified geofence only. Other event types are not affected by this setting. Note that for the event statuses of geofence type, the ruleId is the geofenceId.

If the request is supplied with shipments query parameter, the response results will be limited either to shipments (shipments=true) or devices (shipments=false) only. Otherwise, if shipments query parameter is not specified, response results will include both devices and shipments.

All the aforementioned query parameters can be combined together.