Vessel Tracking
As a core component of the API’s capabilities, vessel tracking allows users to gather crucial historical information about the positions and port calls of individual vessels or groups of vessels.
To get insights into predictions on a vessels’ future port calls, see the NextPort article.
This article will cover several key features of the vessel tracking endpoint, as listed below:
- Get latest position of a vessel or a group of vessels
- Get historic positions of a vessel
- Get port calls (ATA/ATD) for a vessel
This article will consider the following URL as its’ base url:
http://demo.ghmaritime.com/api/portserver/Prerequisite
For most of the endpoints, the MMSI is required for the request to the API.
However, it is possible to acquire the MMSI of a vessel via the API, given that other information is known about the vessel.
To do this, construct a POST request with a request body specifying the known information about the vessel and call the API via the /ship/info endpoint.
The API will respond with a JSON object containing several information parameters regarding the vessel.
Visualization of this process is depicted below:
Vessel: Latest Position
Getting the latest available coordinates of a specific vessel, is done by constructing a GET request via the endpoint /ship/position/{id}, where the variable id is the MMSI number of the vessel.
The API will return a JSON object with several fields of information, i.e. direction, navigation status etc.; However, most importantly it contains the coordinates of the vessel, represented in the latitude and longitude format, and the date of which the last signal was registered.
If the API finds no ship with the given information, it will respond with an error code: 422
Visualization of getting the latest vessel position:
Group of Vessels
It is also possible to get the latest positions of a group of vessels, rather than tracking several ships, one at a time.
To do this, call the API via the same endpoint /ship/position, however rather than specifying the id of the vessel in the url, the list of vessels should be specified in the request body.
The format of the list should be a series of MMSI- or IMO identifiers.
Visualization of getting the latest position from a list of vessel identifiers:
Vessel: Historic Position
There are two ways to define the period of the positions, respectively by time and last port call
Defined by Time
The API stores historic positions of each vessel allowing the user to acquire information on previous positions of a vessel.
To get the historic positions, construct a POST request via the endpoint /ship/historical/track, where the request body contains ship identifiers, i.e. mmsi and name, begin and end date, in the format {year}-{month}-{day}T{hour}:{minute}:{second}Z, and the resolution, meaning the interval between recorded samples by the API.
The API should respond with a JSON object that contains the id a track.
Then, using the id from the response, it is possible to get historical coordinates by constructing a GET request via the endpoint /ship/historical/track/{id}.
If done correctly, the API will respond with a JSON object that contains each point in the track, the ship information, and the distance, which is calculated as the summated distance between each point.
Visualization of collecting historical positions of a vessel, based on a track within the defined time period:
Defined by Last Port Call
The API tracks the ports previously visited by a vessel, enabling users to retrieve information about key locations along its’ trip.
To get the last visited port of a specific vessel, construct a POST request via the endpoint /ship/historical/port along with a JSON-encoding of the ships name and MMSI number, as the request body.
The API will respond with a JSON object containing a list with the most recently visited ports in chronological order.
Visualization of getting a historic position of a vessel from the last port call:
From this response, simply access the first index of the list. This will be the last port visited by the vessel.
The object now contains information about the last visited port by the vessel, meaning that the ATA is describing the position of the vessel, when it made its’ last port call.
Then, to get previous positions of the vessel from that timestamp, follow the instructions from Vessel: Historic Position: Defined by Time and in that process, use the timestamp to define the time-period.
Vessel: Port Calls (ATA/ATD)
To be continued…