The "Track and Port handling" can be used for general ship and goods tracking and port related operations, pilot and tug boat services.
The base path for the Track and Port system is:
https://maritime.gatehouse.dk/api/portserver/Notice the base URL may change depending on the host system.
The reference section can be found here:
Track and Port Handling webservice referenceSeveral different calls are available:
Track a ship towards a destination (port or position).
To activate the track for ship, call the /ship/track API with information about the source (ship IMO, Name, MMSI or Callsign. Supply as much information as possible) and the destination (Port name, Port Locode or Lon/Lat position).
/ship/track POSTThe call will return an ID. To track the ships, call the /ship/track GET
/ship/track GET either with or without an IDThis will return the information for a (list of) ship. In addition the ETA to the destination is calculated based on the available AIS data. It is recommended to call /ship/track GET (without an ID) periodically to get the list of ships that the GateHouse system is tracking. Use this information to synchronize and call /ship/track/<ID> DELETE to remove ships that no longer needs to be tracked. Notice the importance of removing old / stale tracks. They may interfere with other later arrivals of the same ship. To update information about a ship arrival, such as the ETA reported from the ship or the color for displaying the arrival use the /ship/track/<ID> PUT operation.
The list of ships is shared among the users within the same user group.
Additional information can be stored in the track and later retrieved. The information can be stored and updated with the /ship/track POST and PUT operations. The information must be stored in an "erp": {} field in the call. For port operations this can be further interpreted:
"erp" : { "warp" : [ {"eta" : "2015-09-01", "quay_id" : 123 }, {"eta" : "2015-09-02T12:00:00Z", "quay_id" : 124 }] }This will be interpreted as an arrival and a subsequent warp in the port.
By calling /port/arrivals/{port_id}, the information can be retrieved. Also, an object ready for drawing can be created if an empty "geo" : {} is added in a warp such as:
"erp" : { "warp" : [ {"eta" : "2015-09-01", "quay_id" : 123, "geo" {} }, .....Then /port/arrivals/{port_id} will return an object like:
"erp" : { "warp" : [ {"eta" : "2015-09-01", "quay_id" : 123, "geo" { 〈GEOJSON〉 } }, .....Defining one or more waypoints, the portserver will interpret the defined points as "sub destinations", which means that the calculated route will pass through the points toward the final destination. When waypoints are defined the track result will contain an array of waypoint ETA\'s that will map to the defined list of waypoints.
POST ship/track
Payload:
{
"source": {
"ship": {
"mmsi": 636017655,
"name": "SCF ANADYR"
}
},
"destination": {
"position": {
"coordinates": [
14.77551555633545,
55.35848617553711
],
"type": "Point"
}
},
"erp": {
"waypoints": [
{
"position": {
"coordinates": [
10.69979572296143,
57.80120849609375
],
"type": "Point"
}
},
{
"position": {
"coordinates": [
11.05123615264893,
56.00580596923828
],
"type": "Point"
}
},
{
"position": {
"coordinates": [
11.05123615264893,
55.3460693359375
],
"type": "Point"
}
},
{
"position": {
"coordinates": [
11.28186321258545,
54.57012939453125
],
"type": "Point"
}
}
]
}
}
Response:
{
"id": 1166242489212937
}
GET ship/track/1166242489212937
{
...
"waypoints": [
{
"eta": "2017-09-28T14:36:51Z"
},
{
"eta": "2017-09-28T23:27:20Z"
},
{
"eta": "2017-09-29T02:32:28Z"
},
{
"eta": "2017-09-29T06:38:34Z"
}
]
...
}
Create a new track with a ship source to a port destination. Notice the "erp" information is optional but will be used for displaying the relevant in aisWeb, eg. color and quay used for berthing.:
POST ship/track
Payload:
{
"source": {
"ship": {
"imo": 9313917
}
},
"destination": {
"port": {
"id": 31560
}
},
"erp" : {
"warp" : [{ "quay" : [{ "name" :"412"}, {"name" : "414"} ], "starboard" : true, "eta" : "2016-07-10T12:00:00Z" }, "color":"FFFF00"],
"attributes" : [{"key" : "Require Pilot", "value" : "No"},{"key" : "Last port", "value" : "Singapore"}]
}
}
{
id: 753610758727604
}
To update the "erp" information e.g a change in ETA or color or attributes call PUT where 753610758727604 is the ID returned from POST
Payload:
{
"erp" : {
"warp" : [{ "quay" : [{ "name" :"412"}, {"name" : "414"} ], "starboard" : true, "eta" : "2016-07-10T14:00:00Z", "color":"FF0000" }],
"attributes" : [{"key" : "Require Pilot", "value" : "Yes"},{"key" : "Last port", "value" : "Singapore"}]
}
}
{
id: 753610758727604
}
Get information about the created track based on the response track id:
GET ship/track/753610758727604
Response:
{
"destination": {
"port": {
"id": 31560,
"locode": "GBFXT",
"name": "FELIXSTOWE"
}
},
"eta": "2016-02-24T14:45:00Z",
"id": 7.536107587276e+14,
"position": {
"coordinates": [
-5.60761,
48.7511
],
"properties": {
"timestamp": "2016-02-23T07:43:10Z"
},
"type": "Point"
},
"source": {
"ship": {
"a2": "DK",
"callsign": "OZCX2",
"flag": "DA",
"imo": 9313917,
"length": 294,
"mmsi": 219196000,
"name": "SEAGO FELIXSTOWE"
}
}
}
NOTE: The ETA value will not exist immediately after ship/track POST. Will be added when calculation is complete!
Create a new track with a ship source to a point destination. Notice in this case the erp information is mostly for reporting ETA as reported by the ship:
POST ship/track
Payload:
{
"id": null,
"source": {
"ship": {
"name": "MAX MOLS"
}
},
"destination": {
"position": {
"coordinates": [
10.726548917138,
57.754442521999
],
"type": "Point"
}
},
"erp" : {
"warp" : [{"eta" : "2016-07-10T14:00:00Z"}]
}
}
{
id: 758574082975548
}
POST ship/track
Payload:
{
"id": null,
"source": {
"ship": {
"name": "KATEXPRESS 1",
"mmsi": 219017081
}
},
"destination": {
"position": {
"coordinates": [
11.299497485161,
55.974128399244
],
"type": "Point"
}
}
}
Delete created track by id:
DELETE ship/track/753610758727604
Reference: /ship/track
Return a list of the ships currently within a given polygon area.
Notice the operation may take several seconds to complete and thus the POST will return a HTTP code 202 to indicate the operation is in progress. The subsequent GET operation will also return HTTP code 202 until the operation is completed. GET will then return HTTP code 200 along with the result. Notice that the result will be automatically deleted after the GET operation has responded with HTTP code 200. Thus it is not required for the client to issue the DELETE request.
{{plantuml(png)
Client -> Server: Req: POST /ship/area JSON: { ”polygon” : {<geojson>} }
Server -> Client: Resp: HTTP: 202 JSON: { ”id” : 1234 }
Client -> Server: Req: GET /ship/route/1234
Server -> Client: Resp: HTTP: 202
Client -> Server: Req: GET /ship/route/1234
Server -> Client: Resp: HTTP: 202
Client -> Server: Req: GET /ship/route/1234
Server -> Client: Resp: HTTP: 200 JSON: { ”records” : [ {<ship>}, {<ship>} ] }
}}
To get the list of ships inside a given polygon at a given time call with the polygon. This will return a list of ships inside the polygon area. Because it may take several seconds to collect the information the function will immediately return HTTP code 202 and an 64 bit ID indicating processing is in progress. Call GET every few seconds with the supplied ID until it return HTTP code != 202.
/ship/area POST { "polygon" : {"type":"Polygon", "coordinates":[[[10.1, 55.2], [10.3, 55.1], [10.2, 55.2]]]} }
Return HTTP code 202:
{"id":123456789}
Call again with the id until the GET call return other than 202.
/ship/area/123456789 GET
HTTP code 200 indicates successful operation with the result in the response in the format:
{ "records" : [ { "ship" : { "name" : "FOO", ..... }, "position" : { "type" : "Point", .... } }, { "ship" : { "name" : "BAR", ..... }, "position" : { "type" : "Point", .... } } ]}
Notice the position reports may be a minute or more old depending the on whether the data is collected from satellite or ground station. This is NOT a real time data stream.
Edit
Reference: /ship/area
Calculate a route between 2 positions (ports, ships or positions)
{{plantuml(png)
Client -> Server: POST /ship/route JSON: { ”ship” : {}, ”source” : {}, ”destination” : {} }
Server -> Client: HTTP: 202 JSON: { ”id” : 1234 }
Client -> Server: GET /ship/route/1234
Server -> Client: HTTP: 202
Client -> Server: GET /ship/route/1234
Server -> Client: HTTP: 202
Client -> Server: GET /ship/route/1234
Server -> Client: HTTP: 200 JSON: { ”id” : 1234, "route":{"coordinates":[[44.958,12.786],[44.942,12.758]... }
}}
To perform a calculation of a route from A to B where both A and B can be either a position, a port or a ship use the following examples as quidelines {"ship":{"draught":7.7},"source":{"position":{"type":"Point","coordinates":[1.493025,50.967135]}},"destination":{"position":{"type":"Point","coordinates":[11.21775,57.53724]}}}
/ship/route POSTThis should return http code 202 and an id
{"id":123456789}Use this to subsequently call GET with the id.
/ship/route/123456789 GETThis will return http code 202 until the operation has completed at which point you will get a 200 and a result object
{"distance":4297712,"route":{"coordinates":[[44.95801333741476,12.78599394160974],[44.94166666666667,12.75833333333333], .......],"type":"LineString"}}The distance value is in meters (Notice! In an early trial version this parameter was called length).
To calculate a route from a ship to a port use:
{"source":{"ship":{"imo":9625968}},"destination":{"port":{"locode":"FIHEL"}}}'and between two ports
{"ship":{"draught":7.7},"source":{"port":{"locode":"FIHEL"}},"destination":{"port":{"locode":"GIGIB"}}}POST ship/route
Payload:
{
"ship": {
"draught": 7.7
},
"source": {
"position": {
"type": "Point",
"coordinates": [
-5.316076038538302,
36.02804643376291
]
}
},
"destination": {
"port": {
"id": 31560,
"name": "FELIXSTOWE"
}
}
}
{
id: 790473660753791
}
Get information about the calculated route based on id:
GET ship/route/790473660753791
Response:
{
"distance": 2441751,
"route": {
"coordinates": [
[-5.316076038538302,36.02804643376291],
… removed 60 positions …
[1.318912629263974,51.93757234947513]
],
"type": "LineString"
},
"status": "ok"
}
Reference: /ship/route
Reference: /ship/historical/trip
Get the static information for a given ship
Reference: /ship/info
Get the most current position for a given ship
Reference: /ship/position
Select a given ship in aisWeb from another system
Reference: /ship/select
Get a track for a given ship and time period
Reference: /ship/historical/trip
Get a list of world ports (single data object example with felixstowe):
Response:
{ "records" :
[ …
{
"country": "United Kingdom",
"id": 31560,
"locode": "GBFXT",
"name": "FELIXSTOWE"
}
… ] }
Reference: /port/list
Reference: /port/info
Get list of tracks created with destination felixstowe:
GET port/arrivals/31560
Response:
[ … track list … ]
Reference: /port/arrivals
Timestamps are always exchanged in ISO extended format in UTC time, e.g. "2016-01-16T14:00:00Z" even though aisWeb will display timestamps in local time in a human-readable format.
The tracking code is an identifier assigned for each ship being tracked.
| Code | Message | Description |
| 0 | Idle or initialized. The track has not yet been picked up. Will typically happen right after initiating the track and if the system is under heavy load. | |
| 1 | Tracked. This is the normal state for a ship being tracked towards a destination. | |
| 2 | Predicted. The ship has been picked up by the tracker, but have not had valid position updates for > 15 minutes. This is typical in areas covered by satellite. | |
| 3 | Too slow. The ship is being tracked but is laying still. It does not make sense to attempt to calculate an ETA. | |
| 9 | End of predicted route. The ship has been predicted to have reached its destination, but no valid position updates > 15 minutes. | |
| 12 | Arriving | The ship is arriving at the destination. For a port that means it is entering the port area but is still at speed. |
| 14 | Arrived | The ship has arrived at the destination. For a port that means it is laying still inside the port. The tracking is stopped |
| 16 | Departed | The ship has departed the destination. The tracking is stopped |
| 18 | Canceled | The ship track has been canceled |
| 19 | Expired | No additional AIS reports have been received for too long. The ship track is considered lost |
| 21 | Source not found | |
| 22 | Destination not found | |
| 23 | Route not found. Source and destination were found, but it was not possible to find a route. Could be due to draught | |
| 24 | Invalid Track | |
| 29 | System Error |