This endpoint allows the user to track specific vessels by their previous positions and, as a result, gain core information to analyze movement patterns, estimate arrival times, and monitor maritime activity over time.
This article details the input and output of the various endpoints used to perform actions for tracking specific vessels.
Content Overview:
The base URL for the following endpoints is:
https://demo.ghmaritime.com/api/portserver/For most of the endpoints, the MMSI of the vessel is required as the identifier of a vessel.
To get the MMSI of a ship, construct a POST request where the body specifies known information about the ship.
import requests
import json
URL = f'https://demo.ghmaritime.com/api/portserver/ship/info'
headers = {
"Authorization": "Basic <credentials>",
"Content-Type": "application/json",
}
payload = {
"ship": {
"name": "<ShipName>"
}
}
response = requests.post(URL, json=payload, headers=headers, timeout=10)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))The following is a list of parameters that can be altered in the code:
{
"ship": {
"a2": "LR",
"callsign": "5LCB4",
"country": "Liberia",
"destination": "NLRTM",
"draught": 9.9,
"eta": "2025-07-17T00:01:00Z",
"imo": 9307839,
"length": 207,
"mmsi": 636021061,
"name": "MSC NAISHA III",
"shiptype": 71,
"width": 30
}
}However, there is a multitude of parameters that can be used to define a ship; the following is a list of parameters that can be used to define a ship and get information about it.
To get the most current position of a vessel, construct a GET request where the MMSI number is concatenated in the URL.
GET /ship/position/{mmsi}The API will detect the latest known position of the vessel and return several known facts about the position and movement of the vessel.
import requests
import json
URL = f'https://demo.ghmaritime.com/api/portserver/ship/position/<mmsi>'
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))The following is a list of parameters that can be altered in the code:
{
"heading": 209,
"nav_status": 0,
"position": {
"coordinates": [
7.21105,
56.2692,
"2025-07-15T06:15:40Z",
211.3,
7.2
],
"extensions": [
"time",
"cog",
"sog"
],
"type": "Point"
},
"rot": 0,
"ship": {
"mmsi": 123
}
}The latest position of a vessel is specified in the position field of the JSON object; in this case, the latest known position is:
"position": {
"coordinates": [
7.21105,
56.2692,
"2025-07-15T06:15:40Z",
211.3,
7.2
]
}It is possible to gain the latest known position of a list of vessels by following the same method as defined for a single vessel; however, instead of specifying a single in the URL, a list of MMSI values are defined in the body of the request.
GET /ship/positionimport requests
import json
URL = f'https://demo.ghmaritime.com/api/portserver/ship/position/'
headers = {
"Authorization": "Basic <credentials>",
"Content-Type": "application/json",
}
payload = {
"mmsi": [
"<mmsi1>",
"<mmsi2>",
"<mmsi3>"
]
}
response = requests.get(URL, json=payload, headers=headers, timeout=10)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))The following is a list of parameters that can be altered in the code:
The historic position of a vessel can be determined by using either of the following methods.
There are two steps to getting the historic position of a vessel based on time.
The first step is to obtain the track ID, and the second is to use this ID to retrieve the vessel’s previous positions.
import requests
import json
URL = f'https://demo.ghmaritime.com/api/portserver/ship/historical/track'
headers = {
"Authorization": "Basic <credentials>",
"Content-Type": "application/json",
}
payload = {
"ship": {
"mmsi": "<mmsi>"
},
"begin": "{year}-{month}-{day}T{hour}:{minute}:{seconds}",
"end": "{year}-{month}-{day}T{hour}:{minute}:{seconds}",
"resolution": "{hour}:{minute}:{seconds}"
}
response = requests.post(URL, json=payload, headers=headers, timeout=10)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))The following is a list of parameters that can be altered in the code:
"Y-M-DTH:M:SZ", i.e. "2025-07-10T09:00:00Z""Y-M-DTH:M:SZ", i.e. "2025-07-14T09:00:00Z""Y-M-DTH:M:SZ", i.e. "2025-07-14T09:00:00Z"{
"id": 24895
}Then, the response containing the id is used for the second step of the process.
import requests
import json
URL = f'https://demo.ghmaritime.com/api/portserver/ship/historical/track/24895'
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)){
"distance": 1190482,
"ship": {
"mmsi": 255915978
},
"track": {
"coordinates": [
[
25.551538333333333,
60.30459166666667,
"2025-07-10T12:26:14Z",
347.5,
0.0
],
[
25.551568333333332,
60.30463833333334,
"2025-07-11T13:29:36Z",
347.5,
0.0
],
[
19.409586666666666,
57.57095666666667,
"2025-07-12T13:32:16Z",
216.8,
11.2
],
[
12.970071666666668,
54.84683833333333,
"2025-07-13T13:36:37Z",
253.0,
11.1
],
[
11.916095,
56.75774333333333,
"2025-07-14T08:56:17Z",
342.2,
12.0
]
],
"extensions": [
"time",
"cog",
"sog"
],
"type": "LineString"
}
}Then, the coordinates within the track field, will be the previous position within the defined time frame.
To get the previous positions of a vessel from its’ last known port call, construct a POST request where the body contains the MMSI of a vessel .
It will return an ordered list, chronologically, of its last visited ports, where the first index is the last visited port.
It is possible to use the ATA (Actual Time of Arrival) of the response, then follow the steps of Vessel: Historic Position: From Last Port Call and use the ATA to define the time frame and get the last known position of the vessel.
import requests
import json
URL = f'https://demo.ghmaritime.com/api/portserver/ship/historical/port'
headers = {
"Authorization": "Basic <credentials>",
"Content-Type": "application/json",
}
payload = {
"ship": {
"mmsi": "<mmsi>"
}
}
response = requests.post(URL, json=payload, headers=headers, timeout=10)
response.raise_for_status()
print(json.dumps(response.json(), indent=2)){
"records": [
{
"ata": "2025-07-09T16:41:33Z",
"atd": "2025-07-11T14:15:36Z",
"berthing_areas": [],
"port": {
"id": 27850,
"locode": "FITOK",
"name": "Port of Tolkkinen"
}
},
{
"ata": "2025-07-03T08:37:39Z",
"atd": "2025-07-04T13:50:20Z",
"berthing_areas": [],
"port": {
"id": 31250,
"locode": "BEANR",
"name": "Port of Antwerp"
}
},
...
{
"ata": "2025-05-15T09:59:30Z",
"atd": "2025-05-15T11:13:52Z",
"berthing_areas": [],
"port": {
"id": 2765,
"locode": "DEOSR",
"name": "Port of Ostermoor"
}
}
]
}
From the response, get the first index (from the top) and access its’ ATA and use this as the value for the "end" field in the steps of Vessel: Historic Position: From Last Port Call