Shipment route
To display the route of a shipment in your own application, parse the response of the Container Tracking API endpoint GET /shipment, retrieve the coordinates you need and pass them to a map tool. The response offers three levels of detail: the route block for the key locations, the locations list for every location, and routeData.routeSegments for a possible path between them.
Port of loading and port of discharge
To display only the port of loading (POL) and the port of discharge (POD), use the route block of the response. It is a simplified view of the shipment made of four locations:
prepol— the first location of the shipment, before the port of loading;pol— the port of loading;pod— the port of discharge;postpod— the last location of the shipment, after the port of discharge.
Each one carries the location, with its coordinates, and a date.
{
"route": {
"prepol": {
"location": {
"name": "Elland",
"state": "England",
"country": "United Kingdom",
"countryCode": "GB",
"locode": "GBEND",
"coordinates": { "lat": 53.41, "lng": -1.5 },
"timezone": "Europe/London"
},
"date": "2024-08-12T05:00:00+01:00",
"actual": true,
"predictiveEta": null
},
"pol": {
"location": {
"name": "LIVERPOOL",
"state": "England",
"country": "United Kingdom",
"countryCode": "GB",
"locode": "GBLIV",
"coordinates": { "lat": 53.4224, "lng": -3.00837 },
"timezone": "Europe/London"
},
"date": "2024-08-13T04:18:00+01:00",
"actual": true,
"predictiveEta": null
},
"pod": {
"location": {
"name": "MONTREAL",
"state": "Quebec",
"country": "Canada",
"countryCode": "CA",
"locode": "CAMTR",
"coordinates": { "lat": 45.557, "lng": -73.5167 },
"timezone": "America/Toronto"
},
"date": "2024-08-23T06:34:00-04:00",
"actual": true,
"predictiveEta": null
},
"postpod": {
"location": {
"name": "VANCOUVER",
"state": "British Columbia",
"country": "Canada",
"countryCode": "CA",
"locode": "CAVAN",
"coordinates": { "lat": 49.3036, "lng": -123.048 },
"timezone": "America/Vancouver"
},
"date": "2024-09-06T02:48:01-07:00",
"actual": false,
"predictiveEta": null
}
}
}
Every location of the shipment
To display every location the shipment visits, transhipment ports included, and to label them or link them in order, use the locations list of the response. It gives every location of the shipment, with its coordinates.
{
"locations": [
{
"name": "LIVERPOOL",
"state": "England",
"country": "United Kingdom",
"countryCode": "GB",
"locode": "GBLIV",
"coordinates": { "lat": 53.4224, "lng": -3.00837 },
"timezone": "Europe/London"
},
{
"name": "Elland",
"state": "England",
"country": "United Kingdom",
"countryCode": "GB",
"locode": "GBEND",
"coordinates": { "lat": 53.41, "lng": -1.5 },
"timezone": "Europe/London"
},
{
"name": "MONTREAL",
"state": "Quebec",
"country": "Canada",
"countryCode": "CA",
"locode": "CAMTR",
"coordinates": { "lat": 45.557, "lng": -73.5167 },
"timezone": "America/Toronto"
},
{
"name": "Brampton",
"state": "Ontario",
"country": "Canada",
"countryCode": "CA",
"locode": "CABRP",
"coordinates": { "lat": 43.6834, "lng": -79.7663 },
"timezone": "America/Toronto"
},
{
"name": "VANCOUVER",
"state": "British Columbia",
"country": "Canada",
"countryCode": "CA",
"locode": "CAVAN",
"coordinates": { "lat": 49.3036, "lng": -123.048 },
"timezone": "America/Vancouver"
}
]
}
Possible route of the shipment
To display a route the vessel could follow from the port of loading to the port of discharge, stops at transhipment ports included, use routeData.routeSegments. It is returned when the request parameter route is true, its default value.
The route segments are a succession of paths between locations. Each segment holds a path — an array of coordinates — and a routeType, SEA or LAND. Together they draw a possible route of the shipment, free to display on a map.
The excerpt below keeps the first coordinates of one segment out of five; a real path holds many more points.
{
"routeData": {
"routeSegments": [
{
"path": [
{ "lat": 53.41042, "lng": -2.97761 },
{ "lat": 53.40698, "lng": -2.88649 },
{ "lat": 53.40112, "lng": -2.79663 }
],
"routeType": "LAND"
}
]
}
}
Crossing the 180th meridian
Map tools such as Mapbox draw a route crossing the Pacific Ocean the wrong way round: between a point at longitude 135 and a point at longitude -157, the line runs across the whole map instead of crossing the 180th meridian.
To avoid it, in a path that crosses the 180th meridian, add 360 to the longitude of every point where it becomes negative. The free test shipment ZZZZ0000000 lets you test the correction.
This path, as returned by the API:
{
"path": [
{ "lat": 33.2347, "lng": 135.7899 },
{ "lat": 37.12, "lng": -157.5674 }
]
}
becomes, once corrected:
{
"path": [
{ "lat": 33.2347, "lng": 135.7899 },
{ "lat": 37.12, "lng": 202.4326 }
]
}
The Mapbox tutorial Draw a line across the 180th meridian shows the same correction in JavaScript.