Guides
Guides

Past and Future Milestones in the API

This guide explains how to retrieve both historical and upcoming milestones—including ETDs, ETAs, and transshipment events—using OpenTrack’s API.

Suggest Edits

Understanding the timeline Property

Every container payload returned by OpenTrack includes two key properties:

  • history: A list of milestones that have already occurred in the container’s journey (actual, historical events).
  • timeline: A superset of history that includes both actual (past) and estimated (future) milestones.

The timeline object includes additional value:

  • Estimated milestones such as ETAs and future transshipments
  • A status property on each milestone, which indicates whether the milestone is:
    • actual (historical/past), or
    • estimated (future)

🟢 Best Practice: We recommend using the timeline object for all new integrations, as it offers the most complete view.
(Note: The history object remains supported for backward compatibility.)

Milestone Status in the Timeline

Each milestone in the timeline object includes a status field to indicate whether it is a past event or an upcoming prediction.

Possible values of milestone statusDescriptionMilestone can be found in
ACTUALThis milestone has already occurred.history and timeline
ESTIMATEDThis milestone is predicted to occur in the future.timeline only

Future milestones you may see in the timeline

The timeline may contain ESTIMATED versions of any of OpenTrack’s container milestones.

  • Upcoming transshipment events
  • ETAs for rail and ocean arrival milestones
  • Other future container events (as the product evolves)

🔍 Note: For certain estimated milestones—like vessel berthing at the Port of Discharge (ocean ETA) or rail facility arrival (rail ETA)—OpenTrack may prioritize its predictive model over values reported by the ocean carrier.

👉 Learn more about Data Source Attribution via API

Example webhook payload including the timeline

The following example shows a webhook payload that includes the timeline. The data structure is identical to what you'd receive from a GET request to the [/container](https://developers.opentrack.co/reference/getcontainerstatus) endpoint:

{
    "event": "container.status.updated",
    "data": {
        "containerId": "CNTR123456",
        "etaAtTerminal": "2024-01-29T12:00:00.000Z",
        "timeline": [
            {
                "milestone": "VESSEL_DEPARTED_FROM_TRANSSHIPMENT_PORT",
                "timestamp": "2023-12-23T06:49:00.000Z",
                "location": {
                    "name": "Colombo",
                    "unlocode": "LKCMB",
                    "timezone": "Asia/Colombo",
                    "type": "locality",
                    "coordinates": {
                        "latitude": 6.9270786,
                        "longitude": 79.861243
                    }
                },
                "vessel": {
                    "name": "CMA CGM CASSIOPEIA",
                    "imo": "9410765",
                    "mmsi": "215196000"
                },
                "status": "ESTIMATED"
            },
            {
                "milestone": "VESSEL_BERTHED_AT_TRANSSHIPMENT_PORT",
                "timestamp": "2023-12-19T01:16:00.000Z",
                "location": {
                    "name": "Colombo",
                    "unlocode": "LKCMB",
                    "timezone": "Asia/Colombo",
                    "type": "locality",
                    "coordinates": {
                        "latitude": 6.9270786,
                        "longitude": 79.861243
                    }
                },
                "vessel": {
                    "name": "TIGER OCEAN",
                    "imo": "9793727",
                    "mmsi": "563071300"
                },
                "status": "ESTIMATED"
            },
            {
                "milestone": "VESSEL_DEPARTED",
                "timestamp": "2023-12-16T15:30:00.000Z",
                "location": {
                    "name": "ERNAKULAM/COCHIN",
                    "unlocode": "INCOK",
                    "timezone": "Asia/Calcutta",
                    "type": "port",
                    "coordinates": {
                        "latitude": 9.9816358,
                        "longitude": 76.2998842
                    }
                },
                "vessel": {
                    "name": "TIGER OCEAN",
                    "imo": "9793727",
                    "mmsi": "563071300"
                },
                "status": "ACTUAL"
            },
            {
                "milestone": "LOADED",
                "timestamp": "2023-12-16T07:57:00.000Z",
                "location": {
                    "name": "ERNAKULAM/COCHIN",
                    "unlocode": "INCOK",
                    "timezone": "Asia/Calcutta",
                    "type": "port",
                    "coordinates": {
                        "latitude": 9.9816358,
                        "longitude": 76.2998842
                    }
                },
                "vessel": {
                    "name": "TIGER OCEAN",
                    "imo": "9793727",
                    "mmsi": "563071300"
                },
                "status": "ACTUAL"
            },
            {
                "milestone": "FULL_INGATED",
                "timestamp": "2023-12-14T18:06:00.000Z",
                "location": {
                    "name": "ERNAKULAM/COCHIN",
                    "unlocode": "INCOK",
                    "timezone": "Asia/Calcutta",
                    "type": "port",
                    "coordinates": {
                        "latitude": 9.9816358,
                        "longitude": 76.2998842
                    }
                },
                "status": "ACTUAL"
            },
            {
                "milestone": "EMPTY_OUTGATED",
                "timestamp": "2023-12-14T04:45:00.000Z",
                "location": {
                    "name": "Kochi",
                    "unlocode": "INCOK",
                    "timezone": "Asia/Calcutta",
                    "type": "locality",
                    "coordinates": {
                        "latitude": 9.9312328,
                        "longitude": 76.26730409999999
                    }
                },
                "status": "ACTUAL"
            }
        ],
        "history": [
            {
                "milestone": "VESSEL_DEPARTED",
                "timestamp": "2023-12-16T15:30:00.000Z",
                "location": {
                    "name": "ERNAKULAM/COCHIN",
                    "unlocode": "INCOK",
                    "timezone": "Asia/Calcutta",
                    "type": "port",
                    "coordinates": {
                        "latitude": 9.9816358,
                        "longitude": 76.2998842
                    }
                },
                "vessel": {
                    "name": "TIGER OCEAN",
                    "imo": "9793727",
                    "mmsi": "563071300"
                }
            },
            {
                "milestone": "LOADED",
                "timestamp": "2023-12-16T07:57:00.000Z",
                "location": {
                    "name": "ERNAKULAM/COCHIN",
                    "unlocode": "INCOK",
                    "timezone": "Asia/Calcutta",
                    "type": "port",
                    "coordinates": {
                        "latitude": 9.9816358,
                        "longitude": 76.2998842
                    }
                },
                "vessel": {
                    "name": "TIGER OCEAN",
                    "imo": "9793727",
                    "mmsi": "563071300"
                }
            },
            {
                "milestone": "FULL_INGATED",
                "timestamp": "2023-12-14T18:06:00.000Z",
                "location": {
                    "name": "ERNAKULAM/COCHIN",
                    "unlocode": "INCOK",
                    "timezone": "Asia/Calcutta",
                    "type": "port",
                    "coordinates": {
                        "latitude": 9.9816358,
                        "longitude": 76.2998842
                    }
                }
            },
            {
                "milestone": "EMPTY_OUTGATED",
                "timestamp": "2023-12-14T04:45:00.000Z",
                "location": {
                    "name": "Kochi",
                    "unlocode": "INCOK",
                    "timezone": "Asia/Calcutta",
                    "type": "locality",
                    "coordinates": {
                        "latitude": 9.9312328,
                        "longitude": 76.26730409999999
                    }
                }
            }
        ],
        "account": {
            "domain": "your-domain.com"
        },
        "masterBill": {
            "number": "MBOL12345678"
        }
    },
    "changes": {
        "status": {
            "current": "VESSEL_DEPARTED",
            "previous": "LOADED"
        }
    }
}

Updated 3 months ago