Route

This endpoint provides details on the inputs and outputs of operations used to calculate the ETA (Estimated Time of Arrival) between a source and a destination.

Content overview:

• Calculate Vessel:
  • ETA to Port
  • Predicted Route to a Port

The base URL for the endpoints of this article is as follows:

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

POST /ship/route &
GET /ship/route/{route_id}

Vessel ETA to port

To get a vessels’ ETA to a specific port, construct a POST request via the endpoint /ship/route, where the request body defines the source (vessel) and destination (port).

POST /ship/route

There are two steps to calculating a vessels’ ETA to a port.

The first step is to get the id of the job that is calculating the ETA.

The second step is to use the id to then gain information about the calculation.

The variables needed for this is:

• <credentials>
  • Your username and password for authentication as Base64-encoding
• <mmsi>
  • The MMSI identifier of a vessel.
• <locode>
  • The LOCODE identifier of a port.

Code Example:

import requests
import json

URL = f'https://demo.ghmaritime.com/api/portserver/ship/route'
headers = {
    "Authorization": "Basic <credentials>",
    "Content-Type": "application/json",
}

payload = {
    "source": {
        "ship": {
            "mmsi": "<mmsi>"
        }
    },
    "destination": {
        "port": {
            "locode": "<locode>"
        }
    }
}
  
response = requests.post(URL, json=payload, headers=headers, timeout=10)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))

Response Sample:

{
  "id": 12345
}

Then, use the id of the job via the following endpoint:

GET /ship/route/12345

Code Example:

import requests
import json

URL = f'https://demo.ghmaritime.com/api/portserver/ship/route/12345'
headers = {
    "Authorization": "Basic <credentials>",
    "Content-Type": "application/json",
}

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

Response Sample:

{
  "bs_ts": "2025-07-15T07:48:10Z",
  "distance": 433084,
  "eta": "2025-07-19T23:32:23Z",
  "route": {
    "coordinates": [
      [
        5.70945,
        56.9606
      ],
      [
        5.099999999999996,
        59.099999999999994
      ],
      ...
      [
        5.321388888888889,
        60.39694444444444
      ]
    ],
    "type": "LineString"
  },
  "sog": 2.1,
  "status": "ok"
}

In the response, the "eta" field defines the ETA from the vessel to the port and the "route" field defines the predicted route from the vessel to the port.

POST /ship/route &
GET /ship/route/{route_id}

Vessel ETA to point

To calculate the ETA from a vessels’ position to a point, construct a POST request via the endpoint /ship/route, where the request body containing the source (ship information) and destination (a latitude and longitude pair defining the point)

POST /ship/route

The payload containing the source and destination should be in the form as shown below:

payload = {
    "source": {"ship": {"mmsi": "<mmsi>"}},
    "destination": {
        "Position": {
            "type": "Point",
            "coordinates": [
                <lat&long>
            ],
        }
    }
}

• <mmsi>
  • The MMSI identifier of the vessel.
• <lat&long>
  • A latitude and Longitude pair describing the position of the point.

Using this construction, it is possible to get an ETA of any vessel to any arbitrary point, accessible by maritime vessels, on the map.

Code Example:

import requests
import json

URL = f"https://demo.ghmaritime.com/api/portserver/ship/route"
headers = {
    "Authorization": "Basic <credentials>",
    "Content-Type": "application/json",
}

payload = {
    "source": {"ship": {"mmsi": "211891740"}},
    "destination": {
        "position": {
            "type": "Point",
            "coordinates": [14.45354938507081, 55.19768445381493],
        }
    },
}

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

Response Sample:

{
  "id": 3181473981580344
}

This response indicates that the API successfully received the request and has handled it properly.

Once the system has computed the ETA, it is possible to construct a GET request via the endpoint /ship/route/{id} to then get the result of the computation.

GET /ship/route/3181473981580344

Code Example:

import requests
import json

URL = f"https://demo.ghmaritime.com/api/portserver/ship/route/3181473981580344"
headers = {
    "Authorization": "Basic <credentials>",
    "Content-Type": "application/json",
}

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

Response Sample:

{
  "bs_ts": "2025-07-15T12:44:47Z",
  "distance": 5247,
  "eta": "2025-07-15T12:44:47Z",
  "route": {
    "coordinates": [
      [
        14.5001,
        55.1588
      ],
      [
        14.45354938507081,
        55.19768445381493
      ]
    ],
    "type": "LineString"
  },
  "sog": 3,
  "status": "ok"
}

The response contains the ETA in the field "eta", along with various other data.

It should be noted that once the result has been returned by the API, the job will no longer be available. This means that once you have received the response, you are no longer able to get the result of that exact route computation again.