Create and manage shipments

A shipment describes a structure of a multimodal logistics journey. Shipments are useful when the lifetime of an asset you are tracking spans across multiple tracker devices. A shipment consists of 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 Tracking APIs (where applicable). For example, one can query shipment traces and events and associate aliases and metadata to a shipment. A new shipment should be instantiated for each separate logistical journey. However, if the structure of the shipment is recurring, a shipment plan can be defined. A shipment segment can have a subshipment assigned to it in place of the trackingId, that is if the trackingId of a segment contains a shipmentId the segment has a subshipment. Subshipments have the following limitations:

• Subshipments must have the subShipment property set to true.
• Subshipments must be created before they can be used as subshipment in another shipment (parent shipment).
• Subshipments can not be deleted if used in a parent shipment.
• Only one level of subshipments is supported, as a subshipment can not contain other subshipments.
• The parent segment origin must be the same as the origin of the first subshipment segment, and the parent segment destination must be the same as the destination of the last subshipment segment.

When creating shipments, it is highly recommended to set autoStart property to true. If the shipment has the autoStart property enabled, a shipment is started when the HERE Tracking API receives a telemetry ping from within the origin location and then one outside of the origin location. The shipment is marked complete once the ping is received within the destination location.

Shipment states can also be affected by external location events.

Estimated Time of Arrival (ETA) prediction for a shipment is initially calculated when a shipment is created, in case an estimated time of departure is provided. Once the shipment is started, the ETA prediction is updated each time when a device associated with the shipment sends a new telemetry ingestion.

The latest ETA prediction can be obtained from the shipment details.

One can also assign a predefined duration to the shipment segments when creating a shipment plan. This information will be used to calculate the Estimated Time of Departure (ETD) and Estimated Time of Arrival (ETA) when a shipment is instantiated from a shipment plan. Shipments are managed via the shipments endpoint.