Container Trace
The List Container Trace endpoint returns an array of vessel movements for the provided container reference. Vessel Movements are identified using the latest update of the provided reference_id.
The data returned includes the vessel's identification information, such as its IMO (International Maritime Organization) and MMSI (Maritime Mobile Service Identity) numbers. The primary information provided is a series of timestamped location points, each including latitude, longitude, vessel heading, and vessel speed. These points track the vessel's position and movement over a period of time, allowing you to analyze its route and behavior.
By default the endpoint returns actual positions only — observed AIS reports of where the vessel has already been.
Example response:
{
"reference_id": "e7946bf4-255e-484d-8c9b-01365fffa31a",
"trace": [
{
"vessel_imo": "9864502",
"timestamp": "2023-01-05T16:33:34.000Z",
"latitude": 23.828665,
"longitude": 119.92941333333333,
"vessel_mmsi": "636019892",
"vessel_name": "YM CELEBRITY",
"vessel_heading": 8,
"vessel_speed": 16
},
{
"vessel_imo": "9864502",
"timestamp": "2023-01-05T17:30:46.000Z",
"latitude": 24.04188,
"longitude": 120.05223,
"vessel_mmsi": "636019892",
"vessel_name": "YM CELEBRITY",
"vessel_heading": 35,
"vessel_speed": 15.6
},
{
"vessel_imo": "9864502",
"timestamp": "2023-01-05T18:34:23.000Z",
"latitude": 24.21322333333333,
"longitude": 120.2681,
"vessel_mmsi": "636019892",
"vessel_name": "YM CELEBRITY",
"vessel_heading": 58,
"vessel_speed": 12.3
},
{
"vessel_imo": "9864502",
"timestamp": "2023-01-05T19:35:27.000Z",
"latitude": 24.27938,
"longitude": 120.449025,
"vessel_mmsi": "636019892",
"vessel_name": "YM CELEBRITY",
"vessel_heading": 8,
"vessel_speed": 1.3
},
{
"vessel_imo": "9864502",
"timestamp": "2023-01-05T20:34:46.000Z",
"latitude": 24.266593333333333,
"longitude": 120.50962833333334,
"vessel_mmsi": "636019892",
"vessel_name": "YM CELEBRITY",
"vessel_heading": 69,
"vessel_speed": 1.7
},
{
"vessel_imo": "9864502",
"timestamp": "2023-01-05T21:20:20.000Z",
"latitude": 24.267716666666665,
"longitude": 120.51265166666667,
"vessel_mmsi": "636019892",
"vessel_name": "YM CELEBRITY",
"vessel_heading": 21,
"vessel_speed": 0
},
{
"vessel_imo": "9864502",
"timestamp": "2023-01-05T22:32:24.000Z",
"latitude": 24.267715,
"longitude": 120.51265,
"vessel_mmsi": "636019892",
"vessel_name": "YM CELEBRITY",
"vessel_heading": 21,
"vessel_speed": 0
},
{
"vessel_imo": "9864502",
"timestamp": "2023-01-05T23:29:19.000Z",
"latitude": 24.267721666666667,
"longitude": 120.512645,
"vessel_mmsi": "636019892",
"vessel_name": "YM CELEBRITY",
"vessel_heading": 21,
"vessel_speed": 0
},
{
"vessel_imo": "9864502",
"timestamp": "2023-01-06T00:32:20.000Z",
"latitude": 24.267713333333333,
"longitude": 120.51265,
"vessel_mmsi": "636019892",
"vessel_name": "YM CELEBRITY",
"vessel_heading": 21,
"vessel_speed": 0
},
{
"vessel_imo": "9864502",
"timestamp": "2023-01-06T01:29:25.000Z",
"latitude": 24.267721666666667,
"longitude": 120.51265833333333,
"vessel_mmsi": "636019892",
"vessel_name": "YM CELEBRITY",
"vessel_heading": 21,
"vessel_speed": 0
},
{
"vessel_imo": "9864502",
"timestamp": "2023-01-06T02:26:24.000Z",
"latitude": 24.267718333333335,
"longitude": 120.51264833333333,
"vessel_mmsi": "636019892",
"vessel_name": "YM CELEBRITY",
"vessel_heading": 21,
"vessel_speed": 0
},
{
"vessel_imo": "9864502",
"timestamp": "2023-01-06T03:29:20.000Z",
"latitude": 24.267711666666667,
"longitude": 120.51264833333333,
"vessel_mmsi": "636019892",
"vessel_name": "YM CELEBRITY",
"vessel_heading": 21,
"vessel_speed": 0
},
{
"vessel_imo": "9864502",
"timestamp": "2023-01-06T04:32:24.000Z",
"latitude": 24.26771,
"longitude": 120.51266166666667,
"vessel_mmsi": "636019892",
"vessel_name": "YM CELEBRITY",
"vessel_heading": 21,
"vessel_speed": 0
},
{
"vessel_imo": "9864502",
"timestamp": "2023-01-06T05:17:22.000Z",
"latitude": 24.26771,
"longitude": 120.51266,
"vessel_mmsi": "636019892",
"vessel_name": "YM CELEBRITY",
"vessel_heading": 21,
"vessel_speed": 0
},
{
"vessel_imo": "9864502",
"timestamp": "2023-01-06T06:29:25.000Z",
"latitude": 24.267706666666665,
"longitude": 120.51264,
"vessel_mmsi": "636019892",
"vessel_name": "YM CELEBRITY",
"vessel_heading": 21,
"vessel_speed": 0
},
{
"vessel_imo": "9864502",
"timestamp": "2023-01-06T07:32:25.000Z",
"latitude": 24.267725,
"longitude": 120.51263333333333,
"vessel_mmsi": "636019892",
"vessel_name": "YM CELEBRITY",
"vessel_heading": 21,
"vessel_speed": 0
},
{
"vessel_imo": "9864502",
"timestamp": "2023-01-06T08:32:24.000Z",
"latitude": 24.267721666666667,
"longitude": 120.51260333333333,
"vessel_mmsi": "636019892",
"vessel_name": "YM CELEBRITY",
"vessel_heading": 21,
"vessel_speed": 0
},
{
"vessel_imo": "9864502",
"timestamp": "2023-01-06T09:08:26.000Z",
"latitude": 24.267738333333334,
"longitude": 120.51262166666666,
"vessel_mmsi": "636019892",
"vessel_name": "YM CELEBRITY",
"vessel_heading": 21,
"vessel_speed": 0
},
{
"vessel_imo": "9864502",
"timestamp": "2023-01-06T10:29:22.000Z",
"latitude": 24.267756666666667,
"longitude": 120.51262166666666,
"vessel_mmsi": "636019892",
"vessel_name": "YM CELEBRITY",
"vessel_heading": 21,
"vessel_speed": 0
},
{
"vessel_imo": "9864502",
"timestamp": "2023-01-06T11:29:22.000Z",
"latitude": 24.267731666666666,
"longitude": 120.51261833333334,
"vessel_mmsi": "636019892",
"vessel_name": "YM CELEBRITY",
"vessel_heading": 21,
"vessel_speed": 0
},
{
"vessel_imo": "9864502",
"timestamp": "2023-01-06T12:32:58.000Z",
"latitude": 24.282551666666667,
"longitude": 120.515715,
"vessel_mmsi": "636019892",
"vessel_name": "YM CELEBRITY",
"vessel_heading": 342,
"vessel_speed": 7.1
},
{
"vessel_imo": "9864502",
"timestamp": "2023-01-06T13:26:42.000Z",
"latitude": 24.267176666666668,
"longitude": 120.25516,
"vessel_mmsi": "636019892",
"vessel_name": "YM CELEBRITY",
"vessel_heading": 262,
"vessel_speed": 19.1
},
{
"vessel_imo": "9864502",
"timestamp": "2023-01-06T16:33:52.000Z",
"latitude": 23.423296666666666,
"longitude": 119.82885,
"vessel_mmsi": "636019892",
"vessel_name": "YM CELEBRITY",
"vessel_heading": 200,
"vessel_speed": 20
},
{
"vessel_imo": "9864502",
"timestamp": "2023-01-06T16:46:33.000Z",
"latitude": 23.355763333333332,
"longitude": 119.803665,
"vessel_mmsi": "636019892",
"vessel_name": "YM CELEBRITY",
"vessel_heading": 199,
"vessel_speed": 20.1
},
{
"vessel_imo": "9864502",
"timestamp": "2023-01-09T00:30:53.000Z",
"latitude": 11.828265,
"longitude": 109.81970833333334,
"vessel_mmsi": "636019892",
"vessel_name": "YM CELEBRITY",
"vessel_heading": 220,
"vessel_speed": 12.7
},
{
"vessel_imo": "9864502",
"timestamp": "2023-01-09T00:58:44.000Z",
"latitude": 11.743341666666666,
"longitude": 109.76462833333333,
"vessel_mmsi": "636019892",
"vessel_name": "YM CELEBRITY",
"vessel_heading": 225,
"vessel_speed": 12.9
},
{
"vessel_imo": "9864502",
"timestamp": "2023-01-09T02:19:41.000Z",
"latitude": 11.525448333333333,
"longitude": 109.55192833333334,
"vessel_mmsi": "636019892",
"vessel_name": "YM CELEBRITY",
"vessel_heading": 225,
"vessel_speed": 14
},
{
"vessel_imo": "9864502",
"timestamp": "2023-01-09T04:34:33.000Z",
"latitude": 11.131006666666666,
"longitude": 109.1952,
"vessel_mmsi": "636019892",
"vessel_name": "YM CELEBRITY",
"vessel_heading": 234,
"vessel_speed": 14.1
},
{
"vessel_imo": "9864502",
"timestamp": "2023-01-09T05:34:00.000Z",
"latitude": 10.996895,
"longitude": 109.02193,
"vessel_mmsi": "636019892",
"vessel_name": "YM CELEBRITY",
"vessel_heading": 239,
"vessel_speed": 12.5
},
{
"vessel_imo": "9864502",
"timestamp": "2023-01-09T06:34:00.000Z",
"latitude": 10.880455,
"longitude": 108.84461,
"vessel_mmsi": "636019892",
"vessel_name": "YM CELEBRITY",
"vessel_heading": 245,
"vessel_speed": 12.5
},
{
"vessel_imo": "9864502",
"timestamp": "2023-01-09T07:33:49.000Z",
"latitude": 10.771981666666667,
"longitude": 108.664225,
"vessel_mmsi": "636019892",
"vessel_name": "YM CELEBRITY",
"vessel_heading": 240,
"vessel_speed": 12.6
},
{
"vessel_imo": "9864502",
"timestamp": "2023-01-09T08:28:48.000Z",
"latitude": 10.679385,
"longitude": 108.48320166666667,
"vessel_mmsi": "636019892",
"vessel_name": "YM CELEBRITY",
"vessel_heading": 243,
"vessel_speed": 13.5
},
{
"vessel_imo": "9864502",
"timestamp": "2023-01-09T09:00:28.000Z",
"latitude": 10.615391666666667,
"longitude": 108.38067,
"vessel_mmsi": "636019892",
"vessel_name": "YM CELEBRITY",
"vessel_heading": 238,
"vessel_speed": 13.7
},
{
"vessel_imo": "9864502",
"timestamp": "2023-01-09T14:33:28.000Z",
"latitude": 10.251476666666667,
"longitude": 107.25961833333334,
"vessel_mmsi": "636019892",
"vessel_name": "YM CELEBRITY",
"vessel_heading": 279,
"vessel_speed": 11.8
},
{
"vessel_imo": "9864502",
"timestamp": "2023-01-09T15:33:49.000Z",
"latitude": 10.250766666666667,
"longitude": 107.247515,
"vessel_mmsi": "636019892",
"vessel_name": "YM CELEBRITY",
"vessel_heading": 101,
"vessel_speed": 9.9
},
{
"vessel_imo": "9864502",
"timestamp": "2023-01-09T15:59:08.000Z",
"latitude": 10.235655,
"longitude": 107.31746666666666,
"vessel_mmsi": "636019892",
"vessel_name": "YM CELEBRITY",
"vessel_heading": 100,
"vessel_speed": 10
}
]
}Projected trace points
By default, Container Trace tells you where a vessel has been. Setting the include_projected query parameter to true additionally returns where it is forecast to go — the observed AIS track with a predicted forward path appended to it.
GET /references/{referenceId}/trace?include_projected=trueinclude_projected defaults to false. Omitting it returns exactly the response shown above.
Access requirements
Projected points are returned only when all three of the following are true. If any one of them is false, the response is identical to the default — actual points only, and no kind field.
| Requirement | How it's set |
|---|---|
include_projected=true on the request | You set this per request; defaults to false |
The projected_trace feature is enabled for your organization | Enabled by Vizion — contact support |
V1 API updates (v1_api_updates) are enabled for your organization | Enabled by Vizion — contact support |
Because two of the three are account-level settings, include_projected=true on its own is not enough. Until your organization is enabled, sending the parameter is safe and simply has no effect.
The kind field
kind fieldWhen projected points are active, every point in the trace array carries a kind:
| Value | Meaning |
|---|---|
actual | An observed AIS position the vessel actually reported |
projected | A forecast position on the vessel's predicted forward path |
kind is absent entirely from the default response — it is not returned as null. Its presence is the signal that projected data is active for that request.
Points remain sorted by timestamp, so the actual history comes first and the projected tail follows it.
Example response with include_projected=true (abbreviated):
{
"reference_id": "e7946bf4-255e-484d-8c9b-01365fffa31a",
"trace": [
{
"vessel_imo": "9864502",
"timestamp": "2023-01-09T14:33:28.000Z",
"latitude": 10.251476666666667,
"longitude": 107.25961833333334,
"vessel_mmsi": "636019892",
"vessel_name": "YM CELEBRITY",
"vessel_heading": 279,
"vessel_speed": 11.8,
"kind": "actual"
},
{
"vessel_imo": "9864502",
"timestamp": "2023-01-09T15:59:08.000Z",
"latitude": 10.235655,
"longitude": 107.31746666666666,
"vessel_mmsi": "636019892",
"vessel_name": "YM CELEBRITY",
"vessel_heading": 100,
"vessel_speed": 10,
"kind": "actual"
},
{
"vessel_imo": "9864502",
"timestamp": "2023-01-10T04:00:00.000Z",
"latitude": 8.10442,
"longitude": 105.61873,
"vessel_mmsi": "636019892",
"vessel_name": "YM CELEBRITY",
"vessel_heading": 215,
"vessel_speed": 13.2,
"kind": "projected"
},
{
"vessel_imo": "9864502",
"timestamp": "2023-01-11T12:00:00.000Z",
"latitude": 3.41508,
"longitude": 104.19226,
"vessel_mmsi": "636019892",
"vessel_name": "YM CELEBRITY",
"vessel_heading": 201,
"vessel_speed": 12.9,
"kind": "projected"
}
]
}Projected points use the same shape as actual ones — kind is the only new field — and they carry the same vessel fields (vessel_name, vessel_mmsi, vessel_heading, vessel_speed), subject to the same nullability.
How far ahead projections extend
The forecast window is derived from the container's current vessel leg. It is not a request parameter and is not customer-tunable:
- When the leg has a scheduled arrival in the future, projections extend up to that scheduled arrival.
- Otherwise — for example when the scheduled arrival has already passed — projections extend up to 14 days from the time of the request.
Projections are forecasts, not observations. They are recomputed as new AIS reports and schedule updates arrive, so a position returned as projected today may be replaced by a different actual position tomorrow. Treat them as a forward-looking estimate for routing and ETA context, not as a movement record.
Paginating large traces
Adding a projected tail makes traces longer, so the endpoint supports opt-in offset pagination.
| Parameter | Input | Description | Default |
|---|---|---|---|
limit | Positive number, max 20000 | Page size. Providing limit is what turns pagination on. | None — the full trace is returned |
page | Positive number | Page to return, 1-indexed. Has no effect unless limit is also provided. | 1 |
include_metadata | true or false | Add a metadata block to the response | false |
This differs from Vizion's standard pagination in two ways worth noting:
- There is no default page size. Omit
limitand the completetracearray comes back in a single response, exactly as it always has. - The response is not re-keyed under
data. Thetracearray stays where it is;include_metadata=trueadds a siblingmetadataobject.
Example request:
GET /references/{referenceId}/trace?limit=500&page=2&include_metadata=true{
"reference_id": "e7946bf4-255e-484d-8c9b-01365fffa31a",
"trace": [
"… 500 points …"
],
"metadata": {
"page": 2,
"page_count": 7,
"per_page": 500,
"item_count": 3184
}
}Pagination works the same way whether or not projected points are active.
Backwards compatibility
Nothing about the existing response has changed. If you make the same request you make today, you get the same response you get today:
include_projected,page,limit, andinclude_metadataare all optional, and all default to the pre-existing behavior.- With
include_projectedomitted orfalse, nokindfield is emitted on any point and no projected positions are included. - With
limitomitted, the fulltracearray is returned unsliced and nometadataobject is added.
Full parameter and schema definitions are on the List Container Trace endpoint reference.
Enabling Container Trace
For access, please contact support.
Updated 1 day ago