Find a destination port or point which will be used for ETA calculation.
Lets say that we know that SHIN SAPPORO MARU (MMSI: 432355000) is heading for Port of Newcastle (AUNTL).
First we need to get the id of the destination port which we can find by requesting a complete list of the world ports and search for “Port of Newcastle” Australia:
GET /port/list
[ ... { "country": "Australia", "id": 53610, "locode": "AUNTL", "name": "Port of Newcastle" }, ... ]
Now knowing the destination port id we can create the track request:
POST /ship/track
Payload:
{ "source": { "ship": { "mmsi": 432355000 } }, "destination": { "port": { "id": 53610 } } }
Response:
{ "id": 1224996640088073 }
Sending the request we will get the track id as response which we can use to extract the desired data:
GET /ship/track/1224996640088073
Response:
{ "code": 1, "destination": { "port": { "id": 53610, "locode": "AUNTL", "name": "Port of Newcastle" } }, "eta": "2018-01-02T00:00:00Z", "id": 1224996640088073, "position": { "coordinates": [ 141.631, 30.6224, "2017-12-20T06:40:21Z", 158.8, 12.3 ], "extensions": [ "time", "cog", "sog" ], "type": "Point" }, "source": { "ship": { "a2": "JP", "callsign": "JPQG", "flag": "JA", "imo": 9257412, "length": 235, "mmsi": 432355000, "name": "SHIN SAPPORO MARU" } } }
When “code” becomes 1 (see Tracking Codes) the eta has been calculated and can be found in the root of the json object (“eta”: “2018-01-02T00:00:00Z”).
Additional information about the current position of the ship can be found in the root parameter “position” which presents a GeoJSON-X object. Besides the last known position of the ship a timestamp is telling when the last position is registered, together with COG and SOG.
To get a visual representation of the position of the ship one of the 3rd party tools (see Useful Tools) can be recommend.
"position": { "coordinates": [ 141.631, 30.6224, "2017-12-20T06:40:21Z", 158.8, 12.3 ], "extensions": [ "time", "cog", "sog" ], "type": "Point" },
To past the position data into 3rd party tool, normally it will be necessary to strip the extra data from the GeoJSON-X object:
{ "coordinates": [ 141.631, 30.6224 ], "type": "Point" }
When active tracking of the ship is no more needed disable/delete the tracking by calling:
DELETE /ship/track/1224996640088073
From a port administrators point of view, a list of all tracks to the port can be obtained with the following request based on the port id:
GET /port/arrivals/53610
Response:
{
"records": [
{
"code": 1,
"destination": {
"port": {
"id": 53610,
"locode": "AUNTL",
"name": "Port of Newcastle"
}
},
"eta": "2018-01-02T00:00:00Z",
"id": 1224996640088073,
"position": {
"coordinates": [
141.631,
30.6224,
"2017-12-20T06:40:21Z",
158.8,
12.3
],
"extensions": [
"time",
"cog",
"sog"
],
"type": "Point"
},
"source": {
"ship": {
"a2": "JP",
"callsign": "JPQG",
"flag": "JA",
"imo": 9257412,
"length": 235,
"mmsi": 432355000,
"name": "SHIN SAPPORO MARU"
}
}
}
]
}