Use container tracking APIs without confusing planned and actual events

A container feed reports a planned vessel departure, then a revised plan. A late gate-out event arrives afterwards. The dashboard marks the shipment “departed” because it treats every recent movement message as progress along one simple status list.

Map events by their meaning, object and journey before deriving milestones. Planned departure, actual gate-out and actual vessel departure are different facts. A reliable integration preserves them rather than forcing every message into a single increasing status.

Start with the partner's supported contract

Obtain the actual API version, schema, event definitions, identity fields, pagination or subscription behaviour and correction rules. Confirm which milestones the partner supplies for the relevant lanes and services.

DCSA's Track and Trace standards provide a shared basis for container-shipping event exchange. Adoption of a standard does not prove that a particular account has every event or that all partners implement the same version. DCSA — Track and Trace standards

Build a mapping register containing raw event type, classifier, object, location, transport leg, source identifier and the local milestone it may support. Keep unmapped values in a review queue rather than assigning the nearest familiar status.

The examples below use a proposed internal event model, not a payload copied from a particular API.

Four events that must remain distinct

Consider this illustrative journey. Local times are Asia/Kolkata.

G1 was received two hours and thirty minutes after its event time. Its timestamp is later than the planning messages, but gate-out does not establish vessel departure.

A1 is seventy minutes after the revised 06:00 plan. It is thirteen hours and ten minutes after the original 18:00 plan on the previous day. Preserve both comparisons when the business needs original-plan adherence and current-plan performance.

Normalise timestamps for computation while retaining the source offset. The gate-out time of 20 October at 23:30 with a +05:30 offset is 20 October at 18:00 UTC. Dropping the offset can change the date or measured delay.

Define the local milestone key

A container may appear on several legs, bookings or reuse cycles. Do not identify a milestone with container number alone. Include the journey association, leg or transport call, location and event meaning as required by the partner data.

Distinguish a vessel event from a confirmed container-on-vessel relationship. A vessel departing does not prove that a specific container was loaded unless the relevant evidence and mapping establish that connection.

For planned or estimated events, preserve the source's revision or supersession relationship where supplied. If it is absent, use a documented reconciliation rule and flag ambiguity. The latest message receipt is not a universal ordering authority.

Make ingestion recoverable

Persist the raw event and its source identity before acknowledging successful ingestion. Record mapping version, derived updates and processing outcome so the integration can explain how a milestone was produced.

Use a stable deduplication key appropriate to the provider. If no reliable event identifier exists, agree a composite rule and test collisions; a hash of a changing payload is not necessarily a stable business identity.

Polling needs a recoverable cursor and a strategy for late-created or corrected events. A simple “event time greater than last seen” filter can miss a newly delivered event describing an older occurrence. Use the provider's supported update or retrieval mechanism and reconcile overlap safely.

For subscriptions, retain delivery attempts and queryable outcomes. A notification may signal that data changed rather than contain the complete current record. Follow the documented retrieval semantics.

Separate data health from shipment performance

Show event coverage, feed age, rejected mappings and unresolved identities. Missing data is not evidence that the milestone did not happen. A control team may need a carrier check while the integration team investigates the feed.

Authorise each booking, container or shipment query for the requesting party. OWASP's object-level authorisation guidance is relevant even when the identifier itself is publicly visible on equipment. OWASP — Broken Object Level Authorization

Do not expose another client's document or shipment details merely because a user supplies a valid container number. Test the deployed access boundaries with authorised fixtures.

Evaluate the mapping with a fixed event set

Replay the four-event example in order, out of order and with duplicates. Add a corrected actual event, a reused equipment identity and an unknown location. Verify both the current milestone view and the retained history.

Acceptance means the system derives the same supported state from equivalent event sets, preserves uncertainty and can reconstruct every transformation. Test the effect on downstream alerts so a late actual gate-out does not falsely trigger “vessel departed.”

A manual mapping review is useful before building an integration. Native connectors can reduce implementation work, but their versions and event coverage need the same tests. A custom adapter should own mapping and recovery without becoming an unauthorised source of new physical events.

Let the event keep its meaning

The useful output is a trustworthy milestone history with a current planning view. Preserving classification and identity prevents a convenient status label from becoming a false operational fact.

Next actions

1. Document the partner's event contract and actual coverage.
2. Map each event by object, milestone, classifier and journey.
3. Test duplicates, late plans and corrected actuals.
4. Reconcile derived alerts and current state with the retained raw events.

For a tracking-API review, bring a small raw event sequence that currently produces an unexpected status or deadline.