Check a Container | GateHouse Webservices Overview

In order to check for updates on a specific container, a GET request must be submitted to

https://oceantrack.gatehouse.com/api/container_info/get/containerNumber

where containerNumber is replaced by the container of interest.

We only accept GET requests on containers already submitted to our system which are associated with your account. While multiple GET requests may be submitted on-demand, containers are automatically updated every 8th hour, meaning that frequent requests are not necessary to receive the newest available data. Please note that a premium plan is required for PUSH functionality. Additionally, including Content-Type: application/json in the headers is necessary.

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.

Response

We carefully map every container event, or milestone, in accordance with the DCSA standard. Please see this article for an overview of the various container events, or milestones, we support. The overall structure is outlined in the snippet below. We consider each active tracking a shipment. A shipment contains the following three core components:

equipment denoting information about the container and static and dynamic data about the current vessel;
container_events listing all events container has recorded, each event including
- container_event, specifying the specific event and its scheduled, estimated, and actual timestamps;
- location, denoting the physical location of the given container event;
- vessel, denoting information relevant to the vessel associated with the container event; and
- voyage, denoting the voyage reference if the container_event relates to that.
voyage_events listing a complete, vessel-centric overview of the voyage the container has had, each event including
- voyage_event, specifying the specific voyage event and its scheduled, estimated, and actual timestamps;
- location, denoting the physical location of the given voyage event;
- vessel, denoting information to the vessel associated with the voyage event; and
- voyage, denoting the voyage reference associated with the voyage event.

The snippet below illustrates the general format.

{
    "shipment": {
        "equipment": {
            "container": {...},
            "vessel": {...}
        },
        "container_events": [
            {
                "container_event": {...},
                "location": {...},
                "vessel": {...},
                "voyage": {...}
            },
            ...
        ],
        "voyage_events": [
            {
                "voyage_event": {...},
                "location": {...},
                "vessel": {...},
                "voyage": {...}
            },
            ...
        ],
        "generated_at": ...
    }
}

equipment

The equipment block contains information about the specific container and the current vessel. If the container is not currently on a vessel, the vessel field will be null. Of course, the list of container_events and voyage_events will still contain vessel information even if the container is no longer on a vessel.

An example output could be:

"equipment": {
      "container": {
          "equipment_reference": "CRSU6117074",
          "equipment_code": "CRSU",
          "ocean_carrier": "CMA",
          "ocean_carrier_scac": "CMAU"
      },
      "vessel": {
          "static": {
              "name": "MARSTAL MAERSK",
              "imo": 9619971,
              "callsign": "OWJK2",
              "ship_type": "Cargo (Hazard A)",
              "width": 60,
              "length": 399
          },
          "dynamic": {
              "sog": 0.0,
              "cog": 338.0,
              "heading": 388,
              "draught": 15.5,
              "navigation_status": "Moored",
              "last_position": {
                  "latitude": 103.548,
                  "longitude": 1.35352,
                  "timestamp": 1623067698
              }
          }
     }
 }

Specifically, the following fields are included:

container provides general data about the specific container.
1. equipment_reference (string) denotes the container number.
2. equipment_code (string) denotes the SCAC associated with the container number.
3. ocean_carrier (string) denotes the name of the ocean carrier transporting the container.
4. ocean_carrier_scac (string) denotes the SCAC associated with the ocean carrier.
vessel provides general data about the vessel on which the container currently is being transported. If the container is not currently on a vessel, this field is null.
1. static provides metadata about the vessel.
  1. name (string) denotes the name of the vessel currently transporting the container.
  2. imo (integer) denotes the IMO associated with the vessel.
  3. callsign (string) denotes the callsign of the vessel.
  4. ship_type (string) denotes the AIS-based type of ship.
  5. width (integer) denotes the width of the vessel in meters.
  6. length (integer) denotes the length of the vessel in meters.
2. dynamic provides dynamic information about the vessel.
  1. sog (float) denotes the current speed over ground based on AIS.
  2. cog (float) denotes the current course over ground based on AIS.
  3. heading (integer) denotes the current heading based on AIS.
  4. draught (float) denotes the draught associated with the voyage based on AIS.
  5. navigation_status (string) denotes the current navigation status based on AIS.
  6. last_position provides a snapshot of where the vessel currently is.
    1. latitude (float) denotes the latitude of the vessel’s most recent position.
    2. longitude (float) denotes the longitude of the vessel’s most recent position.
    3. timestamp (integer) denotes the age of the positional information.

By default, all timestamps are in epoch local.

container_events

The container_events block contains a chronological list of all events associated with the container of interest. In each entry, the associated milestone or event per the given ocean carrier is remapped in accordance with the DSCA standard. This ensures a standardised output regardless of source(s).

Indeed, in some instances, multiple sources make up the list of events. Our internal mappings weigh the various sources depending on historical performance. Where possible, such as with embarked or arrival events, we further re-affirm the event and its specific timestamps using our internal, real-time AIS feeds.

Consequently, in some instances, we show events not otherwise displayed by various ocean carriers, terminals, or freight forwarders. Please refer to this article for more information about our mappings. In the event that some information is not immediately applicable or otherwise not available, e.g. the vessel for an event occurring on land, any associated fields are null.

An example output is seen below:

"container_events": [
     {
         "container_event": {
             "status": "LOADED",
             "actual_timestamp": 1621267200,
             "estimated_timestamp": 1621259500,
             "scheduled_timestamp": 1621167200,
             "retrieval_timestamp": 1623056517
         },
         "location": {
             "locode": "CNSHA",
             "name": "Port of Shanghai",
             "country": "China",
             "a2": "CN",
             "position": {
                 "latitude": 31.3546,
                 "longitude": 121.622
             }
         },
         "vessel": {
             "name": "CMA CGM RABELAIS",
             "imo": 9406635,
             "carrier": "CMA Carrier"
         },
         "voyage": {
             "voyage_number": "0BE9FW1MA"
         }
     },
     …]
 }

In order to obtain the most complete list of events, please ensure to start tracking a container early in its journey. If a container is added towards the end of its journey, we are unable to retroactively provide accurate estimated and scheduled timestamps. If the only timestamp available to us upon checking a container the first time is the actual timestamp, both the estimated and scheduled will be the same.

Specifically, the following fields are included:

container_event provides general data about the specific container event:
1. status (string) describes the status of the container for the given event.
2. actual_timestamp (integer) denotes the actual timestamp of the event happening. Please note that this timestamp is only ever added after the fact. In instances related to vessel movement, we further affirm the specific timestamp using AIS data.
3. estimated_timestamp (integer) denotes the estimated timestamp of the event.
4. scheduled_timestamp (integer) denotes the timestamp originally scheduled by the ocean carrier.
5. retrieval_timestamp (integer) denotes the timestamp at which we first retrieved the event.
location provides general information about the location at which the event transpired:
1. locode (string) denotes the location code per the UNECE ECE/TRADE/459 standard.
2. name (string) denotes the human-readable name associated with the locode.
3. country (string) denotes the country associated with the locode.
4. a2 (string) denotes the A2 country code per the ISO-3166 standard.
5. position describes the position of the locode.
  1. latitude (float) denotes the latitude of the locode in decimal.
  2. longitude (float) denotes the longitude of the locode in decimal.
vessel denotes information about the vessel when and if applicable.
1. name (string) denotes the name of the vessel associated with the event.
2. imo (integer) denotes the IMO of the vessel.
3. carrier (string) denotes the name of the carrier owning the vessel.
voyage denotes information about the voyage associated with the vessel.
1. voyage_number (string) denotes the voyage number as provided by the ocean carrier.

By default, all timestamps are in epoch local.

voyage_events

The voyage_events block contains a chronological list of all voyage related events associated with the container of interest. As a general rule, the list of voyage events always contains the following entries:

Place of Origin as the first location on which we registered the container.
Port of Loading as the first port at which the container was loaded onto a vessel.
Port of Destination as the scheduled destination for the container.

However, because a container rarely travels directly between a Port of Loading and a Port of Destination, we further provide voyage information detailing every intermediate port the vessel transporting the container visit(s). This is thanks to an integration with our ETA 2.0 service alongside a number of other, internal AIS services. The inclusion of voyage details provides even greater transparency throughout the entire journey of an arbitrary container with actual, estimated, and scheduled timestamps being provided for every stop.

An example output of an intermediate port is seen below:

"voyage_events": [
     {
         "voyage_event": {
             "ata": null,
             "eta": 1624197600,
             "sta": 1624197600,
             "atd": null,
             "etd": 1624255200,
             "std": 1624255200,
             "schedule_date": 1623024000,
             "description": "Intermediate Port",
             "status": "PORT_CALL"
         },
         "location": {
             "locode": "MTMAR",
             "name": "Malta Freeport",
             "country": "Malta",
             "a2": "MT",
             "position": {
                 "latitude": 35.8261,
                 "longitude": 14.5458
             }
         },
         "vessel": {
             "imo": 9406635
         },
         "voyage": {
             "voyage_number": "0BE9FW1MA"
         }
     },
     …]
 }

Specifically, the following fields are included:

voyage_event provides general data about the specific voyage event.
1. ata (integer) denotes the actual time of arrival; enhanced with ETA2.0 and AIS.
2. eta (integer) denotes the estimated time of arrival.
3. sta (integer) denotes the scheduled time of arrival as published by the ocean carrier.
4. atd (integer) denotes the actual time of departure; enhanced with ETA2.0 and AIS.
5. etd (integer) denotes the estimated time of departure.
6. std (integer) denotes the scheduled time of departure as published by the ocean carrier.
7. schedule_date (integer) denotes the date the schedule was created.
8. description (string) denotes which type of port it is.
9. status (string) denotes the status of the event.
location provides general information about the location at which the event transpired:
1. locode (string) denotes the location code per the UNECE ECE/TRADE/459 standard.
2. name (string) denotes the human-readable name associated with the locode.
3. country (string) denotes the country associated with the locode.
4. a2 (string) denotes the A2 country code per the ISO-3166 standard.
5. position describes the position of the locode.
  1. latitude (float) denotes the latitude of the locode in decimal.
  2. longitude (float) denotes the longitude of the locode in decimal.
vessel denotes information about the vessel when and if applicable.
1. name (string) denotes the name of the vessel associated with the event.
2. imo (integer) denotes the IMO of the vessel.
3. carrier (string) denotes the name of the carrier owning the vessel.
voyage denotes information about the voyage associated with the vessel.
1. voyage_number (string) denotes the voyage number as provided by the ocean carrier.

By default, all timestamps are in UTC.

Errors

If you attempt to check a container which has not been submitted, or submit an incorrectly formatted container number, the following error is returned:

{
    "error": "ABCD1234567 is not actively being tracked"
}

Python Example

The following code snippet returns events for container ABCD1234567.

import json
import requests
from requests.auth import HTTPBasicAuth

response = requests.get(
    "https://oceantrack.gatehouse.com/api/container_info/ABCD1234567",
    headers={"Content-Type": "application/json"},
    auth=HTTPBasicAuth("user", "pass"))
  
print(json.loads(response.content))