HERE Shipments API

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`. Each segment is started upon exiting the origin location of the segment and completed upon entering the destination location of the segment. If the origin and the destination of a segment share the same location (that is, dwelling in a single location), the segment will automatically be started after the previous segment was completed. To automatically start a segment which follows a dwelling segment, both the dwelling and following segment has to have the same `trackingId` assigned to them. 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.