Shipment location
The response of the Container Tracking API endpoint GET /shipment locates a shipment in three ways: the current coordinates of the shipment, the last AIS position of the vessel carrying it, and the status and events of its containers. The first two place the shipment on a map; the third tells where it is in its journey.
Current coordinates (recommended)
To place a container on a map, use routeData.coordinates in the GET /shipment response: it is the current position of the container.
- When the container is on board a vessel,
coordinatesis the position of the vessel. - When it is not,
coordinatesis the last known position of the container, usually its last location.
routeData.routeSegments lists the successive positions of the journey of the shipment, which draw that journey on a map. routeData is returned only when the request parameter route is true, its default value.
{
"routeData": {
"routeSegments": [
{
"path": [
{ "lat": 29.76328, "lng": -95.36327, "updatedAt": null },
{ "lat": 53.551052, "lng": 8.570912, "updatedAt": null },
{ "lat": 53.53615, "lng": 8.59298, "updatedAt": null }
],
"routeType": "SEA"
}
],
"coordinates": { "lat": 47.08643, "lng": -11.237754 }
}
}
AIS position of the vessel
The GET /shipment response also carries the AIS data of the vessel in routeData.ais, when the request parameters route and ais are both true. When ais.status is OK, ais.data.lastVesselPosition gives the last position of the vessel. Its updatedAt field tells when that position was received, so you can decide whether it is recent enough for your use.
{
"ais": {
"status": "OK",
"data": {
"lastEvent": {
"description": "Vessel departure",
"date": "2023-11-11T07:09:00Z",
"voyage": "344E"
},
"dischargePort": null,
"vessel": {
"name": "MAERSK OHIO",
"imo": 9298698,
"callSign": "KABP",
"mmsi": 367775000,
"flag": "US"
},
"lastVesselPosition": {
"lat": 51.28157,
"lng": 4.253457,
"updatedAt": "2023-11-28T10:28:00Z"
}
}
}
}
Coordinates or AIS position
The two positions come from different sources:
ais.data.lastVesselPositioncomes from AIS data, the satellite geopositioning of the vessel;routeData.coordinatescomes from the data of the shipping line.
Status and events
To locate a shipment by its progress rather than on a map, use the status and the events of the shipment.
For a quick check, metadata.shippingStatus gives the short status of the shipment: PLANNED, IN_TRANSIT, DELIVERED or UNKNOWN.
{
"metadata": {
"shipmentType": "CT",
"shipmentNumber": "MSKU0496560",
"sealine": "MAEU",
"sealineName": "Maersk",
"shippingStatus": "IN_TRANSIT",
"updatedAt": "2023-11-28T11:24:59Z"
}
}
For details, each entry of containers lists the events of the container. Each event gives a location, a facility, an event code, a status and a date: the last actual event tells where the container is and what happened to it.
{
"number": "MSKU0496560",
"isoCode": "45G1",
"status": "IN_TRANSIT",
"events": [
{
"location": {
"name": "Houston",
"state": "Texas",
"country": "United States",
"countryCode": "US",
"locode": "USHOU",
"coordinates": { "lat": 29.76328, "lng": -95.36327, "updatedAt": null },
"timezone": "America/Chicago"
},
"facility": {
"name": "Houston Barbours Cut Terminal",
"countryCode": "US",
"locode": "USUQF",
"bicCode": "USUQFGDQQ",
"smdgCode": null,
"coordinates": { "lat": null, "lng": null, "updatedAt": null }
},
"description": "Gate out",
"eventType": "EQUIPMENT",
"eventCode": "GTOT",
"status": "CEP",
"date": "2023-11-07T11:16:00Z",
"isActual": true,
"isAdditionalEvent": false,
"routeType": "LAND",
"transportType": null,
"vessel": null,
"voyage": null
}
]
}
The Status and event codes page lists every event code and status a container event can carry.