Skip to content

Draft improvements from assistant conversations: event location nulls & event filtering#284

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mintlify merged 1 commit into from
Jun 29, 2026
Merged

Draft improvements from assistant conversations: event location nulls & event filtering #284

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion docs/api-docs/api-reference/containers/get-a-containers-transport-events.mdx
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -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
---
---

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`.

@greptile-appsgreptile-appsBotJun 29, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2"Terminal-only events" label may confuse filtering strategies. The sentence presents filtering by attributes.event and filtering by attributes.data_source as equivalent alternatives for getting "terminal-only" events, but they select along different dimensions. Events like vessel_arrived and vessel_berthed in the example list can originate from carrier data sources (not just terminal data sources), so a user who filters attributes.data_source == "terminal" expecting to capture all vessel_arrived events will silently miss carrier-sourced ones. Consider separating the two strategies — one for filtering by event name and one for filtering by data source — so readers understand they answer different questions.

Prompt To Fix With AI
This is a comment left during a code review.
Path: docs/api-docs/api-reference/containers/get-a-containers-transport-events.mdx
Line: 9
Comment:
**"Terminal-only events" label may confuse filtering strategies.** The sentence presents filtering by `attributes.event` and filtering by `attributes.data_source` as equivalent alternatives for getting "terminal-only" events, but they select along different dimensions. Events like `vessel_arrived` and `vessel_berthed` in the example list can originate from carrier data sources (not just terminal data sources), so a user who filters `attributes.data_source == "terminal"` expecting to capture all `vessel_arrived` events will silently miss carrier-sourced ones. Consider separating the two strategies — one for filtering by event name and one for filtering by data source — so readers understand they answer different questions.
How can I resolve this? If you propose a fix, please make it concise.

Fix in Codex


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.
12 changes: 12 additions & 0 deletions docs/api-docs/in-depth-guides/event-timestamps.mdx
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -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:

@greptile-appsgreptile-appsBotJun 29, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Minor grammatical awkwardness: "both X (and Y)" uses a parenthetical where a straight conjunction is cleaner and less ambiguous.

Suggested change
On transport events, both `location_locode`(and any related `location` object) are nullable. They may be `null` when:
On transport events, both `location_locode` and any related `location` object are nullable. They may be `null` when:
Prompt To Fix With AI
This is a comment left during a code review.
Path: docs/api-docs/in-depth-guides/event-timestamps.mdx
Line: 45
Comment:
Minor grammatical awkwardness: "both X (and Y)" uses a parenthetical where a straight conjunction is cleaner and less ambiguous.
```suggestionOn transport events, both `location_locode` and any related `location` object are nullable. They may be `null` when:```
How can I resolve this? If you propose a fix, please make it concise.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

Fix in Codex


- 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.
Loading