Next Port

This article will detail the functionality of the nextport endpoint, what operations are available, and how they are constructed. It will use examples to illustrate the input and output of each endpoint.

Please note that the Next Port module is currently in a proof-of-concept phase.

• Port Arrivals
• Vessel Port Calls
• Port Clusters

The base url for the mentioned endpoints throughout the article is:

https://demo.ghmaritime.com/api/shiptracker

Port Arrivals

This endpoint will return a list of vessels that is predicted to dock next at the specified port.

To use this endpoint, either the locode of a single port or the uuid of a cluster of ports, should be known.

To get information about predicted arrivals to a specific port, use the port LOCODE as key like:

GET /nextport/arrivals/{LOCODE}

To get information about arrivals to any ports within a cluster of ports, use the cluster name as key like:

GET /nextport/arrivals/{CLUSTER}

In both cases, the result will be a list of records of vessels going towards the port(s) in the following format:

{"records":[
{"imo":IMO,"locode":LOCODE,"probability":PROBABILITY, "eta":ETA},
...
]}

Example. Notice the ETA is not always present, if it is unknown.

{"records":[
{"imo":9085546,"locode":"DKAAR","probability":0.921},
{"imo":9085541,"locode":"DKAAR","probability":0.88, "eta": "2021-05-01T12:00:00"},
...
]}

Vessel Port Call

The vessel port calls is the essential feature of the Next Port module. For all IMO vessels—excluding local vessels such as fishing vessels, tugboats and pilot boats—the system will make continuous estimates of the most probable ports for the next port call.

To get information about a specific vessel, use the following webservice call:

GET /nextport/ship/{IMO}

To get information about next port calls for a list of vessels, use the shiplist name as key

GET /nextport/shiplist/{SHIPLIST_NAME}

In both cases, the result will be a list of records of next port calls for a list of vessels. Notice how each vessel will be listed multiple times with the most probably ports

{"records":[
{"imo":IMO,"locode":LOCODE,"probability":PROBABILITY, "eta":ETA},
...
]}

Example. Notice the ETA is not always present, if it is unknown.

{"records":[
{"imo":9085546,"locode":"GBFXT","probability":0.921},
{"imo":9085546,"locode":"NLRTM","probability":0.88, "eta": "2021-05-01T12:00:00"},
...
]}

Port Clusters

The port clusters is a way of grouping ports in a given area to make it easier to handle port call predictions. Thus, a cluster of ports can be made from any criteria where geographical location is one such option. The system provides a set of predefined port clusters based on geography (country and distance between ports).

• Create
• Read
• Update
• Delete

Create Cluster

To create a cluster, use the following web service call:

POST /nextport/cluster
{"name":"name", "locodes":[LOCODE1, LOCODE2,...], "color":"ff0000", "threshold":0.80,"filter":"my_filter"}

The web service will respond with a Json-object, with the name of the cluster and its’ id.

Code Example:

import requests
import json

URL = (
    f"https://demo.ghmaritime.com/api/shiptracker/nextport/cluster"
)
headers = {
    "Authorization": "Basic <credentials>",
    "Content-Type": "application/json",
}

payload = {
    "name": "test",
    "locodes": [
        "USMIA",
        "DKAAL"
    ]
}

response = requests.post(URL, headers=headers, json=payload)
print(response.status_code)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))

Response Example:

{
    "id": "32caf180-e24f-4c83-ac5d-65fb1078cd",
    "name": "test"
}

Read Cluster

To get a list of clusters available for a given user, use the following webservice call

GET /nextport/cluster

which returns

{"clusters":[CLUSTER1,CLUSTER2,....]}

Code Example:

import requests
import json

URL = (
    f"https://demo.ghmaritime.com/api/shiptracker/nextport/cluster"
)
headers = {
    "Authorization": "Basic <credentials>",
    "Content-Type": "application/json",
}

response = requests.get(URL, headers=headers)
print(response.status_code)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))

Response Example:

The following is a response sample, where the record contains a single cluster, which uses the Port of Miami and the Port of Aalborg:

{
    "records": [
        {
            "id": "32caf180-e24f-4c83-ac5d-65fb1078cd",
            "locodes": [
                "USMIA",
                "DKAAL"
            ],
            "name": "test",
            "port_info": [
                {
                    "locode": "DKAAL",
                    "name": "Port of Aalborg"
                },
                {
                    "locode": "USMIA",
                    "name": "Port of Miami"
                }
            ]
        }
    ]
}

Update Cluster

To update and overwrite an existing cluster, use the following web service call:

PUT /nextport/cluster/test
{"locodes":[LOCODE1, LOCODE2,...], "color":"ff0000", "threshold":0.80,"filter":"my_filter"}

Notice that the fields color, threshold, and filter are optional.

Code Example:

Response Example:

{
    "id": "32caf180-e24f-4c83-ac5d-65fb107879cd"
}

Delete Cluster

To delete a cluster, use the following webservice call:

DELETE /nextport/cluster/test

The web service will respond with an empty Json-object.

Code Example:

import requests
import json

URL = (
    f"https://demo.ghmaritime.com/api/shiptracker/nextport/cluster/test"
)
headers = {
    "Authorization": "Basic <credentials>",
    "Content-Type": "application/json",
}

response = requests.delete(URL, headers=headers)
print(response.status_code)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))

Response Example:

{}