Understand how to get shipment route from the container tracking API
In your integration, you might want to display the route of your shipment. To achieve this, you will need to parse our Container Tracking API response and retrieve the coordinates you need, then use them with a map tool.
POL/POD information
If you only want to display the locations of the Port of Loading and Port of Discharge, we recommend using the route object.
Display example with MapBox
This route object is a simplified representation of the following:
- the first location of the shipment (PRE POL)
- the port of loading (POL)
- the port of discharge (POD)
- the last location of the shipment (POST POD)
About Route dates
Dates in route object are the dates of the FIRST event we have for the location. Whereas for POD, it is usually the vessel arrival, for POL it is most often the Gate in.
To get more information on event dates, refer to the containers.events dates.
"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
}
}All shipment locations
If you wish to display all locations that your shipment will visit (including transhipment ports), and even label them or link them in the proper order, we recommend using the locations object.
Example display with MapBox
About intermediate port calls
Shipping lines don't usually provide information about intermediate port calls in their container tracking data. Therefore, you will rarely find that information in our Container Tracking services.
The Location object will display, in chronological order, the all the locations that your shipment will visit.
"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 tracked
In other cases, you might want to display an example of a route that could be followed by the vessel from Port of Loading until Port of Discharge, inluding stops at transhipment ports. This information is available in the routeData.routeSegments.
Display example with MapBox
The route segments give a succession of paths (between locations) that show a potential route. You can use it freely to display on a map.
Route and Current Vessel position
Our route Data segments take into account the latest data we have about the container voyage. It does not take into account the current vessel position.
"routeSegments": [
{
"path": [
{
"lat": 53.41042,
"lng": -2.97761
},
{
"lat": 53.40698,
"lng": -2.88649
},
{
"lat": 53.40112,
"lng": -2.79663
},
{
"lat": 53.40996,
"lng": -2.70704
},
{
"lat": 53.42094,
"lng": -2.61771
},
{
"lat": 53.43287,
"lng": -2.52819
},
{
"lat": 53.44628,
"lng": -2.43865
},
{
"lat": 53.50852,
"lng": -2.37358
},
{
"lat": 53.5393,
"lng": -2.28838
},
{
"lat": 53.57658,
"lng": -2.20644
},
{
"lat": 53.5992,
"lng": -2.11851
},
{
"lat": 53.6293,
"lng": -2.03304
},
{
"lat": 53.64482,
"lng": -1.94431
},
{
"lat": 53.66215,
"lng": -1.8551
},
{
"lat": 53.6852,
"lng": -1.83852
}
],
"routeType": "LAND"
},
{
"path": [
{
"lat": 53.6852,
"lng": -1.83852
},
{
"lat": 53.41042,
"lng": -2.97761
}
],
"routeType": "LAND"
},
{
"path": [
{
"lat": 53.4106,
"lng": -2.9779
},
{
"lat": 53.5385,
"lng": -3.4113
},
{
"lat": 53.5438,
"lng": -3.4305
},
{
"lat": 53.5485,
"lng": -3.4497
},
{
"lat": 53.5527,
"lng": -3.4692
},
{
"lat": 53.9737,
"lng": -5.6105
},
{
"lat": 53.9752,
"lng": -5.6249
},
{
"lat": 53.9741,
"lng": -5.6391
},
{
"lat": 53.9703,
"lng": -5.653
},
{
"lat": 51.9755,
"lng": -10.98
},
{
"lat": 51.9714,
"lng": -10.9935
},
{
"lat": 51.9689,
"lng": -11.0072
},
{
"lat": 51.9681,
"lng": -11.0213
},
{
"lat": 52.1795,
"lng": -55.0714
},
{
"lat": 52.1787,
"lng": -55.085
},
{
"lat": 52.1759,
"lng": -55.0983
},
{
"lat": 52.1713,
"lng": -55.1111
},
{
"lat": 50.0112,
"lng": -59.9788
},
{
"lat": 50.0065,
"lng": -59.9917
},
{
"lat": 50.0037,
"lng": -60.0049
},
{
"lat": 50.0027,
"lng": -60.0186
},
{
"lat": 50.0027,
"lng": -62.3996
},
{
"lat": 50.0024,
"lng": -62.415
},
{
"lat": 50.0016,
"lng": -62.4303
},
{
"lat": 50.0003,
"lng": -62.4456
},
{
"lat": 49.697,
"lng": -65.3696
},
{
"lat": 49.6952,
"lng": -65.3849
},
{
"lat": 49.6929,
"lng": -65.4001
},
{
"lat": 49.69,
"lng": -65.4152
},
{
"lat": 49.4944,
"lng": -66.3649
},
{
"lat": 49.4898,
"lng": -66.3855
},
{
"lat": 49.4845,
"lng": -66.4059
},
{
"lat": 49.4786,
"lng": -66.4262
},
{
"lat": 49.1901,
"lng": -67.3511
},
{
"lat": 49.185,
"lng": -67.3662
},
{
"lat": 49.1793,
"lng": -67.3812
},
{
"lat": 49.173,
"lng": -67.3959
},
{
"lat": 48.5465,
"lng": -68.7712
},
{
"lat": 48.5405,
"lng": -68.783
},
{
"lat": 48.5337,
"lng": -68.7941
},
{
"lat": 48.526,
"lng": -68.8048
},
{
"lat": 46.9582,
"lng": -70.7785
},
{
"lat": 46.9508,
"lng": -70.7893
},
{
"lat": 46.945,
"lng": -70.8008
},
{
"lat": 46.9408,
"lng": -70.8131
},
{
"lat": 46.6701,
"lng": -71.8478
},
{
"lat": 46.666,
"lng": -71.8618
},
{
"lat": 46.661,
"lng": -71.8755
},
{
"lat": 46.6552,
"lng": -71.8889
},
{
"lat": 46.0668,
"lng": -73.1337
},
{
"lat": 46.0598,
"lng": -73.1464
},
{
"lat": 46.0512,
"lng": -73.1579
},
{
"lat": 46.0411,
"lng": -73.1683
},
{
"lat": 45.7468,
"lng": -73.4313
},
{
"lat": 45.7373,
"lng": -73.4408
},
{
"lat": 45.7288,
"lng": -73.4512
},
{
"lat": 45.7214,
"lng": -73.4626
},
{
"lat": 45.7315,
"lng": -73.445
},
{
"lat": 45.7237,
"lng": -73.4556
},
{
"lat": 45.7139,
"lng": -73.4637
},
{
"lat": 45.7021,
"lng": -73.4694
},
{
"lat": 45.5165,
"lng": -73.5323
},
{
"lat": 45.5043,
"lng": -73.5393
},
{
"lat": 45.499,
"lng": -73.5497
},
{
"lat": 45.5006,
"lng": -73.5636
},
{
"lat": 45.5088,
"lng": -73.5878
}
],
"routeType": "SEA"
},
{
"path": [
{
"lat": 45.50884,
"lng": -73.58781
},
{
"lat": 45.5174,
"lng": -73.58654
},
{
"lat": 45.34806,
"lng": -74.13694
},
{
"lat": 45.08052,
"lng": -74.65162
},
{
"lat": 44.98972,
"lng": -75.06472
},
{
"lat": 44.52366,
"lng": -75.83516
},
{
"lat": 44.34449,
"lng": -76.29442
},
{
"lat": 44.15547,
"lng": -77.4696
},
{
"lat": 44.00695,
"lng": -77.8925
},
{
"lat": 43.85583,
"lng": -79.02306
},
{
"lat": 43.70222,
"lng": -79.31806
},
{
"lat": 43.705,
"lng": -79.71361
},
{
"lat": 43.73155,
"lng": -79.76242
}
],
"routeType": "LAND"
},
{
"path": [
{
"lat": 43.73155,
"lng": -79.76242
},
{
"lat": 43.705,
"lng": -79.71361
},
{
"lat": 43.1475,
"lng": -81.57028
},
{
"lat": 43.17222,
"lng": -81.85222
},
{
"lat": 42.96155,
"lng": -82.41427
},
{
"lat": 43.03861,
"lng": -83.20167
},
{
"lat": 43.00333,
"lng": -83.68472
},
{
"lat": 42.66167,
"lng": -84.70944
},
{
"lat": 42.32472,
"lng": -85.21889
},
{
"lat": 42.28153,
"lng": -85.66345
},
{
"lat": 41.83194,
"lng": -86.28333
},
{
"lat": 41.62397,
"lng": -87.38488
},
{
"lat": 41.95945,
"lng": -87.76111
},
{
"lat": 42.62415,
"lng": -88.9768
},
{
"lat": 42.79267,
"lng": -89.03124
},
{
"lat": 43.02674,
"lng": -89.30803
},
{
"lat": 43.51583,
"lng": -89.42694
},
{
"lat": 43.555,
"lng": -89.50528
},
{
"lat": 43.97523,
"lng": -90.48925
},
{
"lat": 43.86944,
"lng": -91.33417
},
{
"lat": 44.37348,
"lng": -92.07103
},
{
"lat": 44.532513,
"lng": -92.4583
},
{
"lat": 44.60028,
"lng": -92.62333
},
{
"lat": 45.28583,
"lng": -93.53972
},
{
"lat": 45.35583,
"lng": -93.82845
},
{
"lat": 45.54222,
"lng": -94.10889
},
{
"lat": 45.68917,
"lng": -94.855
},
{
"lat": 46.08778,
"lng": -95.83194
},
{
"lat": 46.38889,
"lng": -96.23444
},
{
"lat": 46.66222,
"lng": -96.44278
},
{
"lat": 46.87056,
"lng": -96.79861
},
{
"lat": 47.57892,
"lng": -98.84362
},
{
"lat": 48.26972,
"lng": -101.42722
},
{
"lat": 49.05909,
"lng": -102.6148
},
{
"lat": 49.25996,
"lng": -103.17803
},
{
"lat": 50.24061,
"lng": -104.9002
},
{
"lat": 50.42255,
"lng": -105.87926
},
{
"lat": 50.49287,
"lng": -106.8958
},
{
"lat": 49.93439,
"lng": -109.35717
},
{
"lat": 49.98774,
"lng": -110.52538
},
{
"lat": 50.23249,
"lng": -111.29876
},
{
"lat": 50.7588,
"lng": -112.50621
},
{
"lat": 50.86944,
"lng": -113.63167
},
{
"lat": 51.19583,
"lng": -114.46139
},
{
"lat": 51.12476,
"lng": -115.239
},
{
"lat": 51.46472,
"lng": -116.2975
},
{
"lat": 51.25639,
"lng": -116.70444
},
{
"lat": 51.46528,
"lng": -117.08667
},
{
"lat": 51.50623,
"lng": -117.4721
},
{
"lat": 51.26167,
"lng": -117.52917
},
{
"lat": 51.07569,
"lng": -117.88237
},
{
"lat": 50.94672,
"lng": -118.28869
},
{
"lat": 50.92798,
"lng": -118.79546
},
{
"lat": 50.70064,
"lng": -119.33617
},
{
"lat": 50.7508,
"lng": -119.61486
},
{
"lat": 50.62528,
"lng": -120.02972
},
{
"lat": 50.72712,
"lng": -121.17089
},
{
"lat": 50.19086,
"lng": -121.54906
},
{
"lat": 49.60833,
"lng": -121.43389
},
{
"lat": 49.44944,
"lng": -121.44487
},
{
"lat": 49.30244,
"lng": -121.60528
},
{
"lat": 49.15552,
"lng": -122.30571
},
{
"lat": 49.32306,
"lng": -123.115
},
{
"lat": 49.24966,
"lng": -123.11934
}
],
"routeType": "LAND"
}
]💡Tips and tricks
Crossing meridian 180
Some map tools (such as mapbox) can have a weird behaviour when you display a route that cross the pacific ocean.
To avoid that issue, in the path that crosses that meridian, just add 360 to the longitude when it becomes negative)
You can test your implementation with the Demo container ZZZZ0000000.
"path":[
{
"lat": 33.2347,
"lng": 135.7899
},
{
"lat": 37.12,
"lng": -157.5674
}
]
Should become
"path":[
{
"lat": 33.2347,
"lng": 135.7899
},
{
"lat": 37.12,
"lng": 202.4326
}
]More details (including a JS code snippet) on this tutorial : https://docs.mapbox.com/mapbox-gl-js/example/line-across-180th-meridian/