> ## Documentation Index
> Fetch the complete documentation index at: https://terminal49.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Event Timestamps

> Learn how Terminal49 stores transport event timestamps in UTC and how to convert them to local time using the matching IANA timezone field.

Through the typical container lifecycle, events occur across multiple timezones. Wherever you see a timestamp for a transport event, there should be a corresponding [IANA timezone](https://www.iana.org/time-zones).

Event timestamps are stored and returned in UTC. If you wish to present them in the local time you need to convert that UTC timestamp using the corresponding timezone.

### Example

If you receive a container model with the  attributes

```
  'pod_arrived_at': '2022-12-22T07:00:00Z',
  'pod_timezone': 'America/Los_Angeles',
```

then the local time of the `pod_arrived_at` timestamp would be `2022-12-21T23:00:00 PST -08:00`

## When the corresponding timezone is null

When an event occurs and Terminal49 cannot determine the location (and therefore the timezone), the system cannot store the event in true UTC.

In this scenario, Terminal49 takes the timestamp as given from the source and parses it in UTC.

### Example

```
  'pod_arrived_at': '2022-12-22T07:00:00Z',
  'pod_timezone': null,
```

then the local time of the `pod_arrived_at` timestamp would be `2022-12-22T07:00:00` and the timezone is unknown. (Assuming the source was returning localized timestamps)

## When `location` and `location_locode` are null

On transport events, both `location_locode` (and any related `location` object) are nullable. They may be `null` when:

* The event is **estimated** (`estimated: true`) and the carrier does not publish a location for the prediction.
* The carrier or data provider omits the location field on a given event — this varies by carrier and event type.
* Terminal49 could not normalize the source location to a known UNLOCODE.

This is expected behavior, not a delivery error. The location is not back-filled later for the same event — if a subsequent actual event (for example, `container.transport.vessel_arrived` replacing `container.transport.estimated.vessel_arrived`) includes a location, it will be delivered as a new event. Treat `location_locode == null` as "location unknown" rather than waiting for an update on the original event.

When `location_locode` is null, `timezone` is typically null as well; see [When the corresponding timezone is null](#when-the-corresponding-timezone-is-null) for how timestamps are stored in that case.

## System timestamps

Timestamps representing changes within the Terminal49 system (e.g. `created_at`, `updated_at`, `terminal_checked_at`) are stored and represented in UTC and do not have a time zone.