GateHouse Maritime Webservice Documentation Statistics

Using the statistics:

In the following <stattype> can refer to each of the individual statistics:

  1. area (Area statistics)
  2. historicaltrack (Historical Tracks)
  3. multipassageline (Multiple Passage Lines)
  4. multiship (Ship Report for multiple ships)
  5. nmsp (Near Mist Ship 2 Point)
  6. nmss (Near Miss Ship 2 Ship)
  7. passageline (Passageline Report)
  8. pilotboat (Pilot Boat Operations Report)
  9. portcalls (Port Calls Report)
  10. transitpilot (Transit Pilot Report)
  11. trip (Trip Report, i.e. from one port to another or return to the departure port)

The base path for the statistics system is:

https://maritime.gatehouse.dk/api/jobserver/

The reference section specifying the details of each call can be found here:

GateHouse Statistics Webservice Reference

Normal operation

The normal operation for performing statistics using the webservice is to initiate the statistics calculation and then wait until the calculations are performed and the retrieve the result.

To start the statistics, call the relevant <stattype> POST for the statistics followed by a polling sequence of statistic/ GET until it reports completed. Then call <stattype>/result/ GET and finally statistic/ DELETE

/stat/stattype POST    - post data: {begin, end, execute, ++} - return {id}

Then loop (poll every few minutes, recommended between 1 to 5 minutes)

/stat/statistic GET   - or /stat/statistic/{id} GET return status: idle, running, completed, aborted
The status returned may have one of the following values:

Until it returns completed. Then get the result with:

/stat/stattype/result/{id} GET   - return the result

And finally delete the entry when it is no longer required. Since there may be imposed a limit on the number of completed results due to database size it is recommended to get the result data out of the system and the delete the entry.

/stat/statistic/{id} DELETE    - delete the entry

Examples

Transit Pilot operation

The Transit pilot operation is intended to find pilot operations including boarding and disembarking of a pilot outside of ports.

The following example will detect Transit Pilot operations between Skagen and Grenaa (does not normally happen), between Skagen and Klintholm and betwee Grenaa and Klintholm using any of the pilot boats listed (the mmsi's listed in the example are not valid).

/stat/pilot POST

{
 "name" : "Transit Pilot january 2016",
 "begin" : "2016-01-01",
 "end" : "2016-02-01",
 "shapes" : [
  {"type":"Polygon","properties" : { "label" : "skagen"}, "coordinates":[[[10.5, 57.9],[10.62, 57.72],[10.6, 57.6],[11.01, 57.6],[11.06, 57.9]]]},
  {"type":"Polygon","properties" : { "label" : "grenaa"}, "coordinates":[[[10.98, 56.48],[10.86, 56.26],[11.22, 56.19],[11.50, 56.45]]]},
  {"type":"Polygon","properties" : { "label" : "klintholm"}, "coordinates":[[[11.39, 54.77],[10.76, 54.83],[10.71, 54.72],[10.40, 54.72],[10.40, 54.46],[11.21, 54.47],[11.64, 54.04],[13.36, 54.71],[13.29, 55.19],[12.43, 54.92],[12.07, 54.84],[11.95, 54.54]]]}
 ],
 "intervals" : ["30:00:00"],
 "a_team":[219000001, 219000002, 219000003, 219000004]
}
Notice:

The result can look like this. Notice two pilot operations. The "index" is the index of the polygon in the "shapes" parameter and "label" is optional polygon label. The timestamp is the time of the pilot embarking or disembarking operation.

/stat/pilot/result/<id> GET
....
{
 "pilot": [
  { "index": 2, "label": "klintholm", "position": { "coordinates": [ 10.777, 54.695], "type": "Point"}, "ship": {"mmsi": 219000001 }, "timestamp": "2016-01-06T17:59:12Z" },
  { "index": 0, "label": "skagen", "position": { "coordinates": [ 10.849, 57.78 ], "type": "Point" }, "ship": { "mmsi": 219000003 }, "timestamp":"2016-01-07T11:34:43Z" }
 ],
 "ship": { "imo": 9327360, "mmsi": 212065000, "name": "BALTIC FAITH"}
}
.....

For non-transit pilot operations, i.e starts or ends in port use the Near Miss Ship 2 Ship (nmss) operation with appropriate parameters.

Near Miss Ship 2 Ship

The Near Miss Ship 2 Ship can be used to detect ships are coming close to each other either head on (collision risk) or in parallel (pilot boarding)

The following example is for pilot boarding

/stat/nmss/result/<id> POST
{
 "name" : "Grenaa Pilot", 
 "begin" : "2016-01-05T00:00:00Z",
 "end" : "2016-01-06T00:00:00Z",
 "distance" : {"max" : 300},
 "dcog":{"max":30}, 
 "dsog":{"max":2}, 
 "sog":{"min":2,"max":9}, 
 "shape" :{"type":"Polygon","coordinates":[[[10.98, 56.48],[10.86, 56.26],[11.22, 56.19],[11.50, 56.45]]]},
 "a_team":[219000001,219000002,219000003]
}

Notice
/stat/nmss/result/<id> GET
....
{
 "distance":7,
 "ship":[
  {"callsign":"OU 8853","cog":221,"draught":2,"imo":0,"mmsi":219000001,"position":{"coordinates":[11.09401666666667,56.40754666666666],"type":"Point"},"sog":7},
  {"callsign":"PBQH","cog":226,"draught":6.5,"imo":9393333,"mmsi":246541000,"name":"THUN GAZELLE","position":{"coordinates":[11.09413199766592,56.40756612003725],"type":"Point"},"sog":7}
 ],
 "timestamp":"2016-01-05T08:09:47Z" 
}
....

Multiple Ship Report

The following example show a ship report for some of the ferries between Dover and Calais

/stat/multiship POST
....
{
 "ships": [{"imo":9007283}, {"name" : "SPIRIT OF BRITAIN", "mmsi" : 235082716 } ]
 "name" : "Dover <=> Calais ferries", 
 "begin" : "2017-04-01T00:00:00Z",
 "end" : "2017-04-02T00:00:00Z" 
}

The result of a multi ship report.

/stat/portcalls/result/<id> GET
...
{
  "records" : [ { "description" : { "name" : "EXPRESS 1" }, "name" : "EXPRESS 1", "imo" : 1234 } , ....
  ]
}

Port calls

The port calls can be made from either all ships calling into specific ports or for all port calls for specific ships.

The following example show a port calls report for all ports in the English Channel for the month of April 2017.

/stat/portcalls POST
....
{
 "shape" : {"coordinates": [[[-3.784, 50.250 ],[-3.620,50.858],[0.720,51.248],[2.433,50.694],[-0.028,48.433],[-3.390,48.564],[-3.785,50.250]]],"type": "Polygon"},
 "begin" : "2017-04-01T00:00:00Z", 
 "end" : "2017-05-01T00:00:00Z" 
}

The following example show a port calls report for all port calls for the 3 ships operated by the ferry owner.

/stat/portcalls POST
....
{
 "name" : "Port calls Mols Line",
 "begin" : "2017-03-01", 
 "end" : "2017-03-02",
 "mmsi" : [219017081, 219018172, 219601000]
}

The following example shows a port calls report for Felixstowe and Hamburg ports.

/stat/portcalls POST
....
{
 "name" : "Port calls Mols Line",
 "begin" : "2017-03-01", 
 "end" : "2017-03-02",
 "ports" : [{"locode" : "GBFXT"}, { "locode" : "DEHAM"}]
}

The result of a port calls report is a list of all the port calls.

/stat/multiship/result/<id> GET
...
{
  "records" : [ { "ship" : { "name" : "EXPRESS 1" }, "port" : {"locode" : "USALB"} , "ata" : "2017-05-22", "atd" : "2017-05-23", "draught_a" : 7.4, "draught_d" : 7.2 }, .... ]
}

ata = Actual Time of Arrival
atd = Actual Time of Departure
draught_a = Draught on Arrival
draught_d = Draught on Departure

Codes

HTTP Status Codes

HTTP Status Codes

 

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