Last Known Positions

The List Last Known Positions endpoint returns the most recent position for every active container reference in your organization — one snapshot per reference, in a single call. Positions are derived from each reference's latest carrier milestone that includes a transport mode; when a container is currently on a vessel, that snapshot is enriched with live AIS (Automatic Identification System) coordinates.

The data returned includes the reference's identifiers (reference_id, container_id, and whichever of bill_of_lading or booking_number apply), the timestamp of the last known position, the active transport mode (for example Vessel, Truck, or Rail), vessel details when available, and the latitude/longitude of that position.

How this differs from Container Trace

Last Known Positions and Container Trace both return geocoordinates, but they answer different questions and aren't interchangeable:

	Last Known Positions	Container Trace
Question it answers	"Where is everything, right now?"	"Where has this one container been?"
Scope	Every active reference in your organization, in one call	A single reference, specified by `reference_id`
Response shape	One snapshot (one point) per reference	An array of timestamped points forming a route
Transport modes covered	Any mode with a carrier milestone (vessel, truck, rail, etc.)	Vessel movements only
Position source	Latest carrier milestone, enriched with live AIS when on a vessel	AIS vessel tracking over time
Extra fields	None beyond current position	`vessel_heading` and `vessel_speed` at each point
Typical use	Powering a live fleet map or "where is everything" dashboard	Plotting a single container's route, or analyzing a vessel's speed/heading/behavior over a leg

In short: reach for Last Known Positions when you need a wide, current snapshot across many containers; reach for Container Trace when you need the detailed movement history of one.

Filtering and pagination

Because Last Known Positions returns data across your whole organization, it supports the standard pagination parameters (limit, page, include_metadata), plus an active_only filter (defaults to true) to restrict results to active references.

Example response:

[
  {
    "reference_id": "421f1c94-001e-4a0a-8c5e-c3593b8d000b",
    "container_id": "CMAU2118620",
    "bill_of_lading": "CMDUSHZ5537156",
    "booking_number": null,
    "timestamp": "2024-02-01T18:22:11.000Z",
    "mode": "Vessel",
    "mode_details": {
      "vessel": "YM CELEBRITY",
      "vessel_imo": "9864502"
    },
    "geolocation": {
      "latitude": 23.828665,
      "longitude": 122.0337208421651
    }
  }
]

Enabling Last Known Positions

Last Known Positions is a Pro Tier feature. For access, please contact support.