Track and Port Handling

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 reference

Using the Track and Port Handling

Several different calls are available:

/ship/track

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 POST

The call will return an ID. To track the ships, call the /ship/track GET

/ship/track GET either with or without an ID

This 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〉 } }, .....

POST ship/track (via waypoints)

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" 
        }
    ]
    ...
}

POST ship/track (ship -> port)

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"}]
   }
}

Response:
{ 
  id: 753610758727604
}

PUT ship/track/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"}]
   }
}

Response:
{ 
  id: 753610758727604
}

GET ship/track

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!

POST ship/track (ship -> position)

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"}]
   }
}

Response:
{ 
  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 ship/track

Delete created track by id:
DELETE ship/track/753610758727604

Reference: /ship/track

/ship/area

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 8f188bcc5b585d4d786fd189c0ba827fb3a1a91ac8a11cb5cb9b71ef731fe2bb

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

/ship/route

Calculate a route between 2 positions (ports, ships or positions)

Plantuml a99669ced5436aa239ad4424801c583fe49b91753d7bedbed75acc631e2172d0

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 POST

This should return http code 202 and an id

{"id":123456789}

Use this to subsequently call GET with the id.

/ship/route/123456789 GET

This 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"}}}

Example POST ship/route (position -> port)

POST ship/route
Payload:

{
  "ship": {
    "draught": 7.7
  },
  "source": {
    "position": {
      "type": "Point",
      "coordinates": [
        -5.316076038538302,
        36.02804643376291
      ]
    }
  },
  "destination": {
    "port": {
      "id": 31560,
      "name": "FELIXSTOWE" 
    }
  }
}

Response:
{ 
  id: 790473660753791
}

Example GET ship/route

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

/ship/historical/trip

Reference: /ship/historical/trip

/ship/info

Get the static information for a given ship

Reference: /ship/info

/ship/position

Get the most current position for a given ship

Reference: /ship/position

/ship/select

Select a given ship in aisWeb from another system

Reference: /ship/select

/ship/historical/trip

Get a track for a given ship and time period

Reference: /ship/historical/trip

/port/list

Get a list of world ports (single data object example with felixstowe):

Example: GET port/list

Response:

{ "records" :
[ …
{
  "country": "United Kingdom",
  "id": 31560,
  "locode": "GBFXT",
  "name": "FELIXSTOWE" 
}
… ] }

Reference: /port/list

/port/info

Reference: /port/info

/port/arrivals

Example GET port/arrivals

Get list of tracks created with destination felixstowe:
GET port/arrivals/31560
Response:

[ … track list … ]

Reference: /port/arrivals

Standard formats

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.

Tracking Codes

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

HTTP Status Codes

HTTP Status Codes

 

Generated on 2020-05-06T10:53:09+02:00