Start a Bill of Lading Tracking

In order to ease the process of tracking large quantities of containers, GateHouse Maritime now enables customers to initiate tracking of an arbitrary number of containers using a single Bill of Lading number.

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://oceantrack.gatehouse.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. If you accidentally submitted a request with an incorrect SCAC. 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 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 container within an hour of initial submission, after which all containers will be automatically refreshed every 8th hour. Any requests in the interim will thus always yield the same, most recent update. 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://oceantrack.gatehouse.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.