Menu

Track ship to port

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" 
                }
            }
        }
    ]
}
Updated on 25 October, 2018