Skip to content
Documentation sections

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.

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, coordinates is the position of the vessel.
  • When it is not, coordinates is 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.lastVesselPosition comes from AIS data, the satellite geopositioning of the vessel;
  • routeData.coordinates comes 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.