Start a Bill of Lading Tracking

In order to ease the process of tracking large quantities of containers, customers may choose to initiate tracking using Bill of Ladings.

What is a Bill of Lading?

A Bill of Lading (BoL, or simply BL) is a contractual document issued to the shipper which confirms the carrier’s receipt of the cargo, acknowledging goods being shipped or received for shipment and specifying the terms of delivery (as one of the evidences of the contract of carriage). The Bill of Lading is usually prepared based on shipping instructions, including cargo description, given by the shipper on forms issued by the carrier and is the title to the goods and can be a negotiable document.

Source: https://dcsa.org/, August 2021.

At the moment, we exclusively support Master Bill of Ladings. We thus kindly refer customers with House Bill of Lading numbers, or who are otherwise unable to obtain a Master Bill of Lading, to our container-based tracking.

In order to start tracking all containers associated with a specific Bill of Lading (hereinafter BoL), a POST request must be submitted to:

https://containerdemo.ghmaritime.com/api/container_info/track/

When submitting a BoL to our endpoint, we ask that any valid SCAC associated with the specific carrier is also supplied. Indeed, as several carriers share similar BoL formats, specifying the specific carrier is pertinent for our ability of identifying your containers. Please refer to our list of supported carriers and SCACs for BoL tracking.

Note that Basic Authentication in the form of a username and password is necessary to submit a successful request. If you do not have any authentication details, please contact us.

With this in mind, any POST request to the above endpoint must contain a payload with the following fields:

{
  "equipmentIdentifier": {
    "type": "BOL_ID",
    "value": "ABCD12345678"
  },
  "carrierSCACCode": "SCAC"
}

We further require Content-Type: application/json to be specified in the header. Any submitted SCAC must be valid and of length four. We require SCACs to adhere to the NMFTA standard.

Upon successfully submitting a BoL for tracking, the following response is returned with status 200:

{
    "success": "true",
    "message": "Started tracking of ABCD12345678 successfully!"
}

Any container associated with the BoL ABCD12345678 will then be tracked until its current shipment has completed as determined by the BoL. In most cases, it is possible to request information on a specific BoL within an hour of initial submission, after which data for all containers will be automatically refreshed every 8th hour. Kindly note that requesting data immediately after initiating tracking will produce an incomplete result: Only once all containers associated with the BoL has been checked and verified will complete data be returned. Please note that a premium plan is necessary for PUSH functionality.

Errors

Two types of errors can occur:

1. The BoL is already being tracked;
2. or, an invalid BoL or SCAC was submitted.

In both cases, an appropriate error message is returned and the BoL is not queued for tracking.

Python Example

The following code snippet submits COSCO BoL 12345678900 for tracking.

import requests
from requests.auth import HTTPBasicAuth

payload = {
	"equipmentIdentifier": {
		"type": "BOL_ID",
		"value": "12345678900"},
	"carrierSCACCode": "COSU"
}

response = requests.post(
    "https://containerdemo.ghmaritime.com/api/container_info/track/",
    headers={"Content-Type": "application/json"},
    auth=HTTPBasicAuth("user", "pass"),
    data=payload)
  
print(response)

If the carrier associated with the BoL is unknown, please refer to container-based tracking.