Working with time zones

Every date and time in the OpenTrack API is returned as an ISO 8601 timestamp in UTC — for example "2026-06-11T06:59:59.999Z". The trailing Z means Zulu / UTC.

We deliberately do not localize timestamps for you, because a single shipment moves through multiple time zones (origin port, discharge port, inland rail ramp). Instead, we give you the IANA time zone of each location so you can render every value in the time zone that is meaningful to your users.

Time zones are attached to locations

Each Location object in a container response carries a timezone field using the IANA time zone database name (also called an Olson name), such as America/Los_Angeles or Asia/Shanghai. IANA names — not fixed offsets like UTC-8 — are what you want, because they encode daylight-saving rules automatically.

Locations that expose a timezone include:

{
  "destinationPort": {
    "name": "Los Angeles",
    "unlocode": "USLAX",
    "type": "port",
    "timezone": "America/Los_Angeles",
    "coordinates": { "latitude": 33.74, "longitude": -118.27 }
  }
}

Each event in history and timeline carries its own location — that's the time zone you use to localize that event's timestamp:

{
  "milestone": "DISCHARGED",
  "timestamp": "2026-06-10T18:00:00.000Z",
  "location": {
    "name": "Los Angeles",
    "unlocode": "USLAX",
    "type": "port",
    "timezone": "America/Los_Angeles",
    "coordinates": { "latitude": 33.74, "longitude": -118.27 }
  }
}

Converting a timestamp to local time

Pick the timestamp, pick the relevant location's timezone, and let a time zone-aware date library do the conversion.

JavaScript (Luxon)

import { DateTime } from 'luxon';

const event = container.history[0];
const local = DateTime
  .fromISO(event.timestamp, { zone: 'utc' })
  .setZone(event.location.timezone);

console.log(local.toFormat('yyyy-MM-dd HH:mm ZZZZ'));
// e.g. "2026-06-01 23:00 PDT"

Python (standard library)

from datetime import datetime
from zoneinfo import ZoneInfo

event = container["history"][0]
utc = datetime.fromisoformat(event["timestamp"].replace("Z", "+00:00"))
local = utc.astimezone(ZoneInfo(event["location"]["timezone"]))

print(local.strftime("%Y-%m-%d %H:%M %Z"))
# e.g. "2026-06-01 23:00 PDT"

Which time zone applies to which field

Milestones in history and timeline carry their own location, so always localize each event with its own location.timezone. For the top-level date fields, use the time zone of the facility the field describes:

Last Free Dates: read these carefully

Last Free Dates (LFDs) are calendar-day deadlines, not precise instants. We encode each one as the end of the local day at the responsible facility. So a Last Free Day of "June 11 in Los Angeles" is returned as:

2026-06-11T06:59:59.999Z   ← 23:59:59.999 on June 11 in America/Los_Angeles

import { DateTime } from 'luxon';

// Terminal demurrage LFD at the discharge port
const lfdDate = DateTime
  .fromISO(container.lastFreeDay, { zone: 'utc' })
  .setZone(container.destinationPort.timezone)
  .toFormat('yyyy-MM-dd');   // "2026-06-11"

The LFD fields

Rail moves change where the deadline lives

When a container has an inland rail leg, isRailMove is true and the relevant deadline moves inland to the rail ramp. Handle these cases explicitly:

• lastFreeDayAtRailStation is the rail-ramp demurrage deadline. Localize it with finalDestination.timezone (the rail facility's zone), not the ocean port zone.
• lineLastFreeDay applies to either the ocean terminal or the final rail station depending on the move. Choose the zone by isRailMove:

const lineLfdZone = container.isRailMove
  ? container.finalDestination.timezone   // rail: deadline is at the ramp
  : container.destinationPort.timezone;   // ocean: deadline is at the port

• etaAtDestination / etnAtDestination are only present on rail moves (isRailMove: true) and refer to the final rail facility, so localize them with finalDestination.timezone.
• On an active rail move, the terminal-level lastFreeDay may be omitted once the container has moved off the ocean terminal onto rail — at that point the rail deadline (lastFreeDayAtRailStation) is the one that matters. Don't assume lastFreeDay is always present.

Worked example

{
  "containerId": "MRKU2642087",
  "isRailMove": true,
  "etaAtTerminal": "2026-06-10T18:00:00.000Z",
  "etaAtDestination": "2026-06-12T08:00:00.000Z",
  "lastFreeDay": "2026-06-11T06:59:59.999Z",
  "lineLastFreeDay": "2026-06-12T06:59:59.999Z",
  "lastFreeDayAtRailStation": "2026-06-14T05:59:59.999Z",
  "destinationPort": { "name": "Los Angeles", "timezone": "America/Los_Angeles" },
  "finalDestination": { "name": "Salt Lake City", "timezone": "America/Denver" }
}

Rendered for the user:

Summary checklist

• Treat every timestamp as UTC and parse it with a time zone-aware library.
• Localize each history / timeline event with its own location.timezone.
• Localize ETAs and LFDs with the facility zone from the tables above.
• For LFDs, convert to local time before extracting the calendar date.
• Branch on isRailMove for lineLastFreeDay, and use finalDestination.timezone for rail-ramp fields.
• Handle a missing timezone gracefully.