container.location.updated

Overview

Fired when the physical location or last known position of a container changes. This event tracks where the container currently is, using both structured location data (port, terminal, facility) and AIS-based vessel position data.

When This Event Fires

The system detects a difference in the location (current structured location) or lastKnownPosition (GPS coordinates from AIS) between the previous and current container snapshot. Common triggers:

• Container's current location changes (e.g. moves from port to rail facility)
• AIS vessel tracking reports a new position for the vessel carrying the container
• Container's location type changes (e.g. from PORT to RAIL)

Payload Structure

{
  "event": "container.location.updated",
  "data": { /* IContainerVoyageResponse — full container snapshot */ },
  "changes": {
    "currentLocation": {
      "previous": {
        "name": "Port of Los Angeles",
        "unlocode": "USLAX",
        "type": "PORT",
        "coordinates": { "latitude": 33.7361, "longitude": -118.2642 }
      },
      "current": {
        "name": "BNSF Logistics Park Chicago",
        "type": "RAIL",
        "coordinates": { "latitude": 41.6123, "longitude": -88.0731 }
      }
    }
  },
  "deliveryAttempt": 1,
  "pendingRetries": 4,
  "sentAt": "2025-07-19T17:00:00.654Z"
}

data object

The full current state of the container. Key location-related fields include:

changes object

Contains { previous, current } pairs for either currentLocation, lastKnownPosition, or both.

Common Use Cases