Track ocean container milestones via carrier and terminal APIs and handle milestone code variance

Steps

1. Identify the ocean carrier(s) and determine whether they publish a DCSA Track & Trace compliant API — the nine DCSA member carriers (MSC, Maersk, CMA CGM, Hapag-Lloyd, ONE, Evergreen, Yang Ming, HMM, ZIM) have published DCSA-compliant APIs; non-members (e.g., COSCO, OOCL) use proprietary event naming and require separate integration.
2. Subscribe to container events using the DCSA T&T API standard (current production version v2.2) where available, or integrate the carrier's proprietary API; events are expressed as a combination of event type code (e.g., LOAD, DISC, ARRI, DEPA, GTIN, GTOT, AVPU) and a classifier (ACT for actual, PLN for planned, EST for estimated).
3. For non-DCSA carriers and terminal operators, map their proprietary milestone names to a normalized internal schema — maintain a carrier-keyed mapping table, as the same physical event (e.g., vessel arrival at berth) is labeled differently across carriers and portals even among DCSA members.
4. Ingest events from aggregator services (e.g., Vizion, project44 Ocean, Ocean Insights) to consolidate multi-carrier tracking into a single API call when managing a large, multi-carrier booking portfolio.
5. Normalize timestamps to UTC, store events in a milestone log keyed on (container_number, event_code, event_timestamp), and use upsert logic to handle re-transmitted or corrected events.
6. Handle non-happy-path milestones such as rolled bookings (cargo bumped to a later vessel), transshipments (unexpected port addition), customs holds, and split moves — define explicit internal states for each to avoid treating absence of an expected milestone as silence.