Keep an auditable vessel port and berth call log in Airtable

On a cron trigger every four hours, keep a clean port call and berth call log for my tracked fleet in Airtable, so we hold an auditable movement record for laytime and demurrage claims instead of rebuilding one from emails after the fact. Build this as a code workflow. Every step is deterministic (fetch two endpoints, diff against stored rows on a composite key, insert, notify), and there is no judgement call anywhere in the chain.

Keep the vessel watchlist as a configurable input at the top of the workflow, with vessels identified by IMO number. For each vessel on the watchlist, call the MarineTraffic Single Vessel Port Calls operation over a rolling seven day lookback ending at the current UTC time.

Also call MarineTraffic Single Vessel Berth Calls for the same vessel over the same seven day window, to capture berth level dockings and undockings. Treat this half as optional. The port calls service and the berth calls service are separately purchased MarineTraffic products, each with its own 40 character API key, so someone holding only the port calls subscription should still get a working arrival and departure log. If no berth calls key is configured, skip the berth half cleanly and carry on rather than failing the run.

Before writing anything, read the existing log with Airtable List Records so you know what is already stored. Filter that read to a window slightly wider than the lookback, around eight days, so the comparison stays bounded as the table grows. Page through the results using the offset value until Airtable stops returning one, because if you only read the first page the deduplication will silently miss rows that fell on a later page.

Deduplicate on the combination of IMO, port, event type and UTC timestamp. That composite key is the single most important detail in this workflow. The lookback windows overlap heavily by design: MarineTraffic is not a poll provider and emits no webhooks for this data, so a rolling window plus composite key dedupe is what substitutes for a real poll trigger. Getting the key right is what makes it safe to re-read the same week on every single run.

Write only the events that are not already stored, using Airtable Create Records, one row per arrival or departure. Each row carries vessel name, IMO, port, berth or terminal, event type and the UTC timestamp. Create Records accepts at most 10 records per request, so batch the new rows in chunks of 10, and stay under Airtable's limit of 5 requests per second per base.

Keep every timestamp in UTC and label the column that way, for example 'Event Time (UTC)', since a demurrage argument turns on timezone. All MarineTraffic timestamps are already UTC, so store them exactly as returned and never convert to local time. If a speed column is added later, note that MarineTraffic returns SPEED in knots multiplied by 10, so it needs dividing by 10 before storing. Most of these legacy MarineTraffic endpoints return the whole result set in a single response with no paging, so no pagination handling is needed on that side.

For each newly recorded berthing and unberthing, post a short message to our operations Slack channel using the Slack Bot Send a Message operation, so the team sees dockings as they land. One message per new berth event, naming the vessel, the port, the berth or terminal, whether it docked or undocked, and the UTC time. Keep quiet when a run finds nothing new: if there are no new events, write nothing and post nothing.