Services overview
Ingestion
The ingestion service provides an interface for devices to do data ingestion to HERE Tracking. The ingested data is a device telemetry, which may include, for example, a GPS position, sensor readings, WLAN or Bluetooth scans. Only a provisioned and a claimed device data is accepted. Devices should use uniquely this interface to send data to HERE Tracking.
Largedata
The Largedata service is used for storing large data blobs from devices to HERE Tracking and retrieving the resulting assembled data from HERE Tracking by the users.
The data upload from a device follows the multipart data upload pattern:
- Create a new data upload. Check that the upload status is no longer preparing.
For each part:
- Upload the part.
Complete the upload after all parts have been uploaded. A data upload state can be one of the following: - preparing: The storage for the data is being prepared.
- pending: Data upload has been succesfully created but no parts have been uploaded yet.
- ongoing: Data upload is ongoing.
- completed: Data upload has been successfully completed.
- failed: Data upload has failed.
Data parts can be uploaded only if the upload state is one of the following: pending, ongoing, failed.
Note that the state will be changed to failed if uploading a part fails but if the part is uploaded again successfully, the upload state is changed back to ongoing.
The data can be downloaded only if the upload state is completed.
Registry
The Registry service is used for provisioning and claiming devices.
Aliases
Within the Alias service, an alias is an arbitrary type - externalId pair, which can be associated with a trackingId.
The externalId can be, for example, an external management system asset ID or a human-readable name.An alias is uniquely identified by an externalId and a type pair within a tracking project. Note also that Aliases v2 API is deprecated.
Associations
Within the Association service, an association is a link between a device and a geofence, a sensor rule or a rule.
Device events get generated for existing associations only.
Events
The Events service manages device and shipment events.
An event is created every time an associated rule or geofence is triggered by a device ingestion.
A geofence event is created every time a device enters or exits an associated geofence.
A sensor event is created when sensor data reported by a device triggers a sensor rule.
A rule event (such as dwelling, detention, utilization, stock and online rule) is created when a device behaviour triggers a rule.
Geofences
The Geofences service creates and manages geofences.
A geofence is an area boundary that users can define and associate with their devices.
The area that the geofence encloses can be defined using geographic coordinates or radio measurements.
Geographic geofences can be circular or polygonal.
A circular geofence is defined by geographic coordinates of its center and a radius, while polygonal geofences are defined as a set of geographic coordinates.
POI geofence (Point Of Interest) is a geofence, which is defined using radio measurements.
POI geofences need to be trained separately using a telemetry that a device has recorded while being at the desired point of interest.
Once created, a geofence can be associated to a device. Every time a position or a radio measurement update is received from a device, HERE Tracking would evaluate whether the device has transitioned across the boundary of
an associated geofence.
If such a transition has happened, a transition event will be recorded.
For the geographic geofences, the evaluation is based on the coordinates of the trace.
For POI geofences, the device is considered to be inside a trained POI geofence when the radio
measurements of the device-ingested telemetry and the training data match.
Indoor geofences can be created by adding the floor properties to the geofence definition.
Circular and polygonal geofences can be both outdoors and indoors.
POI geofences should only be used indoors.
For indoor geofences, a device transition is recorded only if the position of the device is indoors and the floor details of the position match the geofence floor definition.
NOTE: A geofence can also be referred to as a geozone, and these two terms are interchangeable.
Labels
The Labels service creates and manages labels.
A label is a key-value pair that can be associated to the following resources:
- device
- geofence
- sensor
- rule
- location
- shipment
One can list labels for a specific resource or resource type, and filter labels by keys or key-value pairs. Note also that Labels v4 API is deprecated.
Locations
The Locations service creates and manages locations.
Locations are geographical points of interest users may store in HERE Tracking. Locations are used as building blocks for shipments.
Metadata
The Metadata service creates and manages metadata.
Metadata is a descriptive information added to a device, a shipment, a geofence or a sensor rule. Note also that Metadata v2 API is deprecated.
Rules
The Rules service creates and manages rules.
Rules generate events and notifications when get triggered by a device behaviour.
The following rule types are supported:
- dwelling
- detention
- utilization
- stock
- online
- shipmentEtaChange
- shipmentSchedule
After a rule has been created, it needs to be associated to a device to get activated.
This association means that every time a telemetry is received from the device, it will be evaluated against the rule condition. As soon as the evaluation changes (for example, from true to false), an event will be recorded.
Sensors
The Sensors service creates and manages sensor rules.
The sensor rules generate events and notifications when get triggered by a reported device sensor reading.
The following sensor rule types are supported:
- battery
- humidity
- pressure
- temperature
- acceleration
- attach
- tamper
After a sensor rule has been created, it needs to be associated to a device to get activated.
This association means that every time a sensor update is received from the device as a part of its ingestion telemetry, it will be evaluated against the sensor rule condition. As soon as the evaluation changes (for example, from true to false), an event will be recorded.
Shadows
The Shadows service provides an effective way to manage configurations for devices that are only intermittently online.
The device shadow contains reported and desired state objects of a device, referred to as reported and desired shadows.
The desired shadow contains configuration settings that the device should use and possibly also some optional custom settings.
The device receives the desired shadow from HERE Tracking as a response to the ingestion request.
The reported shadow contains the most recent position, sensor readings and settings that thedevice has sent. The reported shadow may also contain additional properties generated by HERE Tracking based on the device-ingested telemetry. Such properties are stored in the system.computed property.
In case the most recent telemetry did not contain all the possible fields, the last known information will remain in the shadow. This means that one can see, for example, the last reported temperature or tracker firmware information in the reported shadow, even if the device did not send that information in the latest telemetry.
Devices should not communicate directly with this service, but should instead send the telemetry to the ingestion endpoint, which updates the
reportedshadow and returns thedesiredshadow. Applications should only write to thedesiredshadow and only read from thereportedshadow.
Shipments
The Shipments service manages shipments.
A shipment describes a structure of a multimodal logistics journey. Shipments are useful when the lifetime of an asset one is tracking spans across multiple devices.
A shipment consists of segments that span from a location to another. The segments and their origins and destinations must form a continuous chain of locations, that is the origin of a segment must match the destination of a previous segment.
Each segment of the shipment may be assigned a trackingId that can vary between segments. Devices assigned to a shipment generate traces and events for the entire shipment.
The shipmentId of a shipment can be used in similar fashion as a trackingId in selected APIs. For example, one can query for shipment traces and events and associate aliases and metadata to a shipment.
Each shipment has one of the following statuses:
- pending: The shipment has not yet started.
- ongoing: The shipment has started and it has one segment ongoing.
- completed: The shipment has ended and all of its segments are completed.
- cancelled: The shipment has ended and it has one or more cancelled segments.
HERE Tracking progresses the shipment automatically if each segment has been assigned a trackingId and the origin and destination locations contain a geofenceId. A moving segment is started upon exiting the origin location of the segment and completed upon entering the destination location of the segment.
A segment is a dwelling segment when its transportMode is set to dwelling (which is only allowed when the segment's origin and destination are the same location).
A dwelling segment is started upon entering its location and completed upon exiting it.
To automatically start a segment which follows a dwelling segment, both the dwelling and following segment have to have the same trackingId assigned to them.
A segment whose origin and destination are the same location but whose transportMode is not dwelling is a moving segment: it is started upon exiting the location and completed upon returning to (re-entering) the location.
If a segment does not have a device assigned, the user must start and complete the segment manually.
A new shipment should be instantiated for each separate logistical journey.
Shipments that are still ongoing after two weeks are automatically cancelled. This time limit can be altered via registry/v2/features endpoint by changing data.shipments.ongoingRetentionPeriod configuration option.
Shipments older than six months are automatically removed.
Automatic shipment startup can be constrained to trigger only at time of shipment's providedEtd by defining an auto-start limit window via configuration options of data.shipments.autoStartLimitBefore and data.shipments.autoStartLimitAfter through registry/v2/features endpoint.
With the auto-start limit window configured, pending shipments that have providedEtd set that are not started within the limit window are automatically cancelled.
Traces
The Traces service allows users querying device traces based on time ranges.
A device trace is a device-ingested telemetry along with the ingestion timestamp and the device current position.
Devices should not communicate directly with this service, but should instead send telemetry to the ingestion endpoint. Each data ingestion results in an update to the
reporteddevice shadow and a new device trace creation.
Users
The Users service provides HERE Tracking user authentication and authorization.
Updated 1 hour ago