Sign in

v1

latestOpenAPI 3.0.0HERE Documentation License2026-07-142162791.8 MB
Events

Gets the event statuses

Gets all events statuses for all devices and shipments of the project. An event status of a device is the most recent event of any rule or geofence the device is associated with. The same applies for shipments.

The response contains a list of event status objects and each object has the following properties:

  • trackingId or shipmentId: a device ID or a shipment ID
  • ruleId: an associated rule or geofence ID
  • eventSource: the rule type
  • eventType: an event type of the latest event of the rule (same as the "event state")
  • timestamp: a time since when the device has been in this event state

The array is sorted by the following fields in the following order: trackingId, eventSource, timestamp, ruleId, geofenceId.

A time range can be defined with before and after timestamps. The response will contain event statuses that were recorded within the range.

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 eventType query parameter, the response results will be limited to the specified type only.

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.

get/events/v3/statuses

Query parameters

'attach' | 'battery' | 'geofence' | 'humidity' | 'pressure' | 'tamper' | 'temperature' | 'acceleration' | 'dwelling' | 'stock' | 'detention' | 'utilization' | 'online' | 'shipmentSchedule'

The event source rule type.

OR
string[]
'BELOW_RANGE' | 'IN_RANGE' | 'ABOVE_RANGE' | 'FALSE_TO_TRUE' | 'TRUE_TO_FALSE' | 'EVENT' | 'INSIDE_GEOFENCE' | 'OUTSIDE_GEOFENCE' | 'OVERSTOCK' | 'NORMAL_VOLUME' | 'UNDERSTOCK' | 'DWELLING_STARTED' | 'DWELLING_ENDED' | 'DETENTION_STARTED' | 'DETENTION_ENDED' | 'UTILIZED' | 'UNUTILIZED' | 'SHIPMENT_EARLY' | 'SHIPMENT_ON_TIME' | 'SHIPMENT_DELAYED'

Type of the event.

An event is created every time an associated rule or geofence is triggered by a device ingestion. The event type depends on the data the device sends.

Sensors that report numerical data (such as battery, humidity, pressure and temperature sensors), generate an event when the reported sensor reading of the device goes in or out of range, which is configured in the rule. This produces events of BELOW_RANGE, IN_RANGE and ABOVE_RANGE types.

Sensors that report boolean data (such as attach and tamper sensors), generate events when the device transitions from one state to another, either from false to true or vice versa. This produces events of FALSE_TO_TRUE and TRUE_TO_FALSE types. The same event types are also generated by the online rule when the device state changes from offline (when the device has stopped ingesting data) to online (when the device data ingestion has resumed) or vice versa.

The acceleration sensor generates events whenever the reported sensor reading crosses the acceleration threshold (for example, when the device was dropped). This produces events of the type EVENT. Such events are stateless.

Events of INSIDE_GEOFENCE and OUTSIDE_GEOFENCE types are generated when the device enters or exits a geofence associated with the device.

Events of DWELLING_STARTED type are generated when the device has stayed inside an associated geofence for longer than the threshold duration. DWELLING_ENDED type events are generated when dwelling of the device has ended.

Events of DETENTION_STARTED type are generated when the device has been stationary for longer than the threshold duration, regardless whether the device is inside or outside of any geofence. DETENTION_ENDED type events will be generated when the device starts moving again.

Events of UNUTILIZED type are generated when the device has been stationary for longer than the threshold duration. UTILIZED type events are generated when the device starts moving again after having been stationary.

Events of OVERSTOCK, NORMAL_VOLUME and UNDERSTOCK types are generated when the number of assets inside a geofence crosses the minVolume and maxVolume thresholds of an associated stock rule.

Events of SHIPMENT_EARLY, SHIPMENT_ON_TIME and SHIPMENT_DELAYED types are generated when a shipment is too early, on time or delayed.

OR
string[]
string

This is a unique ID associated with the device data in HERE Tracking. For physical devices the trackingId gets assigned to a device when the device is claimed by a user, and for virtual devices it is an external device ID along with the device project appId. Alternatively, a valid shipmentId may be used.

OR
string[]
string uuid

ID of the rule or geofence. Must be a valid UUIDv4.

OR
string[]
string uuid

ID of the geofence. Must be a valid UUIDv4. This filter can be used to filter results related to dwelling event source.

OR
string[]
shipmentsboolean

If true, the results will be limited to shipment event statuses only. If false, the results will be limited to device event statuses only. If not specified, the results will include both device and shipments event statuses.

beforenumber

Milliseconds elapsed since 1 January 1970 00:00:00 UTC. The accepted range is from 1 to the current time.

afternumber

Milliseconds elapsed since 1 January 1970 00:00:00 UTC. The accepted range is from 0 to the current time.

pageTokenstring

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

countinteger

The number of items to return per page.

appIdstring

Application identifier. Used together with an external ID to identify a virtual device.

Response

Successful

countinteger

The number of items in the response.

pageTokenstring

A token that can be used to retrieve the next page of the response.