---
updatedAt: 2026-03-16T16:23:14.000Z
agentTools:
  projectIndex: https://developers.opentrack.co/llms.txt
---

# 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

```json
{
  "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:

| Field                   | Description                                                                        |
| ----------------------- | ---------------------------------------------------------------------------------- |
| `currentLocation`       | Structured location with `name`, `unlocode`, `type`, `timezone`, and `coordinates` |
| `lastKnownPosition`     | GPS coordinates (`latitude`, `longitude`) from AIS vessel tracking                 |
| `lastKnownPositionDate` | Timestamp of the last AIS position report                                          |

### `changes` object

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

## Common Use Cases

| Use Case                          | How to Implement                                                                                                                 |
| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| **Map visualization**             | Update a map display with the container's latest coordinates from `lastKnownPosition` or `currentLocation.coordinates`           |
| **Geofence alerts**               | Compare `lastKnownPosition.coordinates` against geofence boundaries to trigger alerts when a container enters or leaves a region |
| **Location-based ETA refinement** | Use real-time position data to refine arrival estimates in conjunction with `etaAtTerminal`                                      |
| **Facility transition tracking**  | Monitor `currentLocation.type` changes to track container movement between ports, rail yards, and off-dock facilities            |
| **Customer visibility portal**    | Push location updates to a customer-facing tracking page for real-time container visibility                                      |