What container-tracking APIs actually give you
The gap between "track your shipment" on a carrier's website and what their API will really tell you — milestones, schedules, reefer telemetry, and where each one goes quiet.
If you move goods by sea, "where is my container?" turns out to be several different questions wearing one coat. The carrier's website blurs them together into a friendly map. Their API pulls them apart again — which is more honest, and more useful, once you know what each piece is really telling you.
Most ocean carriers now expose tracking through a shared industry standard (the DCSA Track & Trace interface), so the shapes below are broadly the same whoever you ship with.
Events are the backbone
The core of tracking is a stream of events, each one a small factual record: something happened, to this container, at this place, at this time. They come in a few flavours:
- Equipment events — the box was gated in, loaded, discharged, gated out.
- Transport events — a vessel departed or arrived at a port.
- Shipment events — the paperwork reached a milestone.
Each event carries a classifier that's easy to miss but changes everything: is this actual (it happened), estimated (the carrier's current guess), or planned (the original intention)? A single port can appear three times — planned, estimated, actual — and the drift between them is often the most useful thing on the screen. When an arrival's estimate keeps sliding later, that's your early warning, sitting in plain sight.
The position isn't the ship
Here's the trap that catches everyone. Events include coordinates, so it's tempting to plot them and call it the vessel's position. It isn't. Those are the coordinates of the port where the event occurred. Your container shows as sitting in Algeciras because it was discharged there — not because the ship is there now. Plot those points and you get a dotted line that teleports between ports and tells you nothing about the weeks in between.
If you genuinely want the vessel moving across the ocean, that's a different data source — either the ship's live position feed, or per-container telemetry (more on that below). Don't mistake an event's location for a GPS track. They answer different questions.
Schedules answer "where is it going"
Events tell you where a container has been. To know where the ship is headed, you want the carrier's commercial schedules — the full planned rotation of a vessel, port by port, with dates. This is what lets you draw the whole route ahead of time rather than discovering each port only as your box touches it. It's a separate subscription from tracking, and worth it if you care about the forward picture rather than just the rear-view mirror.
Reefer telemetry is a world of its own
For refrigerated cargo, some carriers offer a premium telemetry feed — and this is where the data gets genuinely rich. A reefer container's own data logger reports, typically pushed to you on a webhook rather than polled:
| Reading | What it tells you |
|---|---|
| Setpoint | The target temperature — not a measurement, the instruction |
| Supply air | What the unit is delivering into the box |
| Return air | What the box is giving back |
| Cargo probes | Actual product temperature, if probes were physically fitted |
| Humidity, CO₂, O₂ | For controlled-atmosphere cargo (produce, not frozen goods) |
| GPS | The container's own position — the real track |
The subtlety worth internalising: for frozen cargo, supply air is the number that matters, because that's what the unit is holding. But the gap between supply and return is the early-warning signal. Frozen product has enormous thermal inertia — a short failure barely moves the cargo temperature — so by the time the pulp probe shows a problem, you've had one for a while. Watch the air gap and you see trouble coming; watch only the cargo and you see it arriving.
And a caveat that will save you a confused afternoon: the fields exist, but the sensors might not. Cargo pulp probes are physical hardware someone inserts when the container is stuffed, usually for specific inspection protocols. If your supplier doesn't fit them, those fields arrive empty. The first real payload tells you what's actually wired up far better than any documentation.
The practical lesson
Every one of these feeds is useful, and every one goes quiet somewhere — events between ports, positions in deep ocean, probes that were never fitted. The mistake is treating any single source as "the truth" about your shipment. The better mental model is a set of overlapping partial views: events for what's confirmed, schedules for what's intended, telemetry for what the box itself can feel. Hold them loosely, together, and you get an honest picture — including an honest picture of what you don't know.