From b99f54d069ca344ac9c60588d5d8d4d31950c90b Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Mon, 29 Jun 2026 16:09:27 +0000 Subject: [PATCH] docs: clarify null event locations and transport_events filtering --- .../containers/get-a-containers-transport-events.mdx | 6 +++++- docs/api-docs/in-depth-guides/event-timestamps.mdx | 12 ++++++++++++ 2 files changed, 17 insertions(+), 1 deletion(-) diff --git a/docs/api-docs/api-reference/containers/get-a-containers-transport-events.mdx b/docs/api-docs/api-reference/containers/get-a-containers-transport-events.mdx index 857f4709..78f65c34 100644 --- a/docs/api-docs/api-reference/containers/get-a-containers-transport-events.mdx +++ b/docs/api-docs/api-reference/containers/get-a-containers-transport-events.mdx @@ -4,4 +4,8 @@ description: "List normalized transport events for a single container — vessel og:title: Retrieve Transport Events | Terminal49 API Documentation og:description: Fetch detailed transport event data for containers, providing real-time updates on shipment status through Terminal49's API. openapi: get /containers/{id}/transport_events ---- \ No newline at end of file +--- + +This endpoint returns the container's full normalized transport event history — vessel, rail, transshipment, terminal/gate, delivery, and document events — across the entire journey. It does not support filtering by event type, data source, or timestamp via query parameters. To narrow results to a subset (for example, terminal-only events such as `full_in`, `full_out`, `empty_out`, `empty_in`, `vessel_discharged`, `vessel_arrived`, or `vessel_berthed`), fetch the full list and filter client-side on `attributes.event` or `attributes.data_source`. + +Some events may have a `null` `location_locode` and `timezone` — most commonly on estimated events. See [Event Timestamps](/api-docs/in-depth-guides/event-timestamps) for details on how to interpret those timestamps. diff --git a/docs/api-docs/in-depth-guides/event-timestamps.mdx b/docs/api-docs/in-depth-guides/event-timestamps.mdx index 6df22f88..787acb7d 100644 --- a/docs/api-docs/in-depth-guides/event-timestamps.mdx +++ b/docs/api-docs/in-depth-guides/event-timestamps.mdx @@ -40,5 +40,17 @@ then the local time of the `pod_arrived_at` timestamp would be `2022-12-22T07:00 +## 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. \ No newline at end of file