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

[mintlify]

Summary

Close two recurring documentation gaps surfaced by assistant conversations: when transport event location/location_locode are null, and whether GET /containers/{id}/transport_events supports filtering.

Changes

• api-docs/in-depth-guides/event-timestamps.mdx: added a section explaining that location_locode is nullable on transport events (e.g. on estimated events or when the carrier omits location), that this is expected, and that values are not back-filled on the same event.
• api-docs/api-reference/containers/get-a-containers-transport-events.mdx: noted that the endpoint returns the full event history with no server-side filter parameter, so callers should filter client-side on attributes.event or attributes.data_source (e.g. for terminal-only events), and cross-linked the event timestamps guide.

Context

Multiple recent assistant threads asked why vessel_arrived events arrived with location: null/location_locode: null and whether to expect a later update, and whether a query parameter exists to fetch only terminal-related transport events. Both behaviors are confirmed against the OpenAPI schema (location_locode is nullable: true; the endpoint defines no filter parameter) but were not stated on the relevant pages.

Greptile Summary

This documentation-only PR closes two recurring gaps surfaced by assistant conversations: explaining when location_locode is null on transport events, and clarifying that GET /containers/{id}/transport_events has no server-side filtering.

• event-timestamps.mdx: Adds a new section describing the three reasons location_locode (and location) may be null, confirms the value is never back-filled on the original event, and cross-links to the existing null-timezone section.
• get-a-containers-transport-events.mdx: Adds a prose paragraph stating the endpoint returns the full event history with no filter query parameters, advises client-side filtering on attributes.event or attributes.data_source, and links to the event timestamps guide.

Confidence Score: 4/5

Safe to merge — both files are documentation only with no runtime impact.

The additions are accurate and well-targeted. The one substantive concern is in the transport events reference page, where filtering by attributes.event and filtering by attributes.data_source are presented as interchangeable approaches for the same "terminal-only events" goal — but events like vessel_arrived can originate from carrier data sources, so a data_source == "terminal" filter would silently miss them. This could lead developers down an incorrect implementation path. The event-timestamps.mdx additions are clear and correct.

The filtering guidance in get-a-containers-transport-events.mdx warrants a second look to ensure the attributes.event and attributes.data_source strategies are described as distinct tools rather than equivalent alternatives.

Important Files Changed

Filename	Overview
docs/api-docs/api-reference/containers/get-a-containers-transport-events.mdx	Added a prose section clarifying no server-side filtering is available and advising client-side filtering; the example conflates filtering by event name with filtering by data source in a way that could mislead users about vessel_arrived and vessel_berthed coverage.
docs/api-docs/in-depth-guides/event-timestamps.mdx	Added a well-structured section explaining nullable location_locode and location, with accurate reasoning for nulls and a correct cross-reference to the null-timezone section; minor grammatical nit in the opening sentence.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
A["GET /containers/{id}/transport_events"] --> B["Returns full event history\n(no server-side filter params)"]
B --> C{Client-side filtering}
C -->|by event name| D["attributes.event\ne.g. 'vessel_arrived', 'full_in'"]
C -->|by data source| E["attributes.data_source\ne.g. 'terminal', 'carrier'"]
B --> F{location_locode?}
F -->|not null| G["Use for timezone conversion\n(see Event Timestamps guide)"]
F -->|null| H["Location unknown\nDo NOT wait for back-fill"]
H --> I["timezone is also typically null\nTimestamp stored as-given in UTC"]
H --> J["A new actual event will arrive\nif carrier later provides location"]

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
A["GET /containers/{id}/transport_events"] --> B["Returns full event history\n(no server-side filter params)"]
B --> C{Client-side filtering}
C -->|by event name| D["attributes.event\ne.g. 'vessel_arrived', 'full_in'"]
C -->|by data source| E["attributes.data_source\ne.g. 'terminal', 'carrier'"]
B --> F{location_locode?}
F -->|not null| G["Use for timezone conversion\n(see Event Timestamps guide)"]
F -->|null| H["Location unknown\nDo NOT wait for back-fill"]
H --> I["timezone is also typically null\nTimestamp stored as-given in UTC"]
H --> J["A new actual event will arrive\nif carrier later provides location"]

Loading

Prompt To Fix All With AI

Fix the following 2 code review issues. Work through them one at a time, proposing concise fixes.
---### Issue 1 of 2
docs/api-docs/in-depth-guides/event-timestamps.mdx:45
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:```### Issue 2 of 2
docs/api-docs/api-reference/containers/get-a-containers-transport-events.mdx:9
**"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.

_{Reviews (1): Last reviewed commit: "docs: clarify null event locations and t..." | Re-trigger Greptile}

Greptile also left 2 inline comments on this PR.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
api	Building	Preview, Comment	Jun 29, 2026 4:09pm

[greptile-apps]

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!

[greptile-apps]

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

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
terminal49	🟢 Ready	View Preview	Jun 29, 2026, 4:22 PM