How to use external location events

Customers may have secondary sources of information that indicate when a tracker enters or exits a location, even if there are no geofence events in place. In these situations, customers can send external location events to a project's input stream. These events can then activate the automatic state transitions for shipments.

The tracking service makes automatic shipment state transitions based on geofence events and by external location events. State transitions for a shipment can be driven with geofence events, external location events, or both, depending on which are available in shipment's locations.

An external location event identifies the shipment, location, whether the shipment has entered or exited that location, and the time when the enter/exit happened. Additionally, the event can contain an optional segment identifier and optional metadata object. Segment identifier can be used to identify the location when the same location is used in multiple segments in the shipment. The metadata object can be used to store customer specific event data.

For more precise event definition, refer to the input stream ingestion schema. The definition is under inputStreamLocationEvent property.

Geofence events versus external location events

There are some differences on how the geofence events and external location events affect shipment states.

With geofence events the shipment locations have to be traversed in the order they are defined for the shipment. Only geofence events for locations which affect shipment's ongoing segment, or if no segment is ongoing, then the first pending segment are taken into account.

External location events are taken as the ground truth for the shipment location and if they tell that shipment is already at certain location, then segment states are changed accordingly until that location even if there are pending segments before that location. However states of already completed segments can not be changed afterwards.

If the same location is used multiple times in the shipment, the optional segment identifier in the event can be used to identify the location which the event targets. When the segment is not identified in the location event and the same location is used more than once, the next possible state change is made. When the segment is identified in the location event, it has to specify either:

• the segment whose origin location is exited for the exit event or
• the segment whose destination location is entered for the enter event.

Example event

Below is an example of an external location event sent to input stream:

{
  requestId: '5d4d0797-5946-48a7-b1af-9e4913284364',
  type: 'event',
  version: '1.0',
  data: [
    {
      timestamp: '2025-08-08T06:00:26.445Z',
      eventSource: 'location',
      eventType: 'exit',
      shipment: { extId: 'example-shipment' },
      segment: { extId: 'example-segment-1' },
      location: { extId: 'example-location-1' }
    }
  ]
}

And how it comes out from the events output stream:

{
  type: 'events',
  version: '1.0',
  events: [
    {
      trackingId: 'SHP-828770a4-0701-41b7-b86e-ccc76b453d81',
      timestamp: 1754632826445,
      ruleId: '00000000-0000-4000-8000-000000000002',
      eventSource: 'location',
      eventType: 'exit',
      initialState: false,
      trigger: 'external',
      extOrderId: 'example-shipment',
      extSegmentId: 'example-segment-1',
      segmentId: 'SEG-4b2a5d73-bf26-441f-824a-f81fb357bc10',
      segmentIndex: 1,
      extLocationId: 'example-location-1',
      locationId: 'LOC-245dfbda-ae1e-4baa-8f20-fea94584ab86'
    }
  ],
  correlationId: '5d4d0797-5946-48a7-b1af-9e4913284364'
}