GateHouse Maritime Webservice Documentation Statistics¶

Using the statistics:¶

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

area (Area statistics)
historicaltrack (Historical Tracks)
multipassageline (Multiple Passage Lines)
multiship (Ship Report for multiple ships)
nmsp (Near Miss Ship To Point)
nmss (Near Miss Ship To Ship)
passageline (Passageline Report)
pilotboat (Pilot Boat Operations Report)
portcalls (Port Calls Report)
transitpilot (Transit Pilot Report)
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, wait until the calculations are performed, and then 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:

idle: The job is registered but is not yet started. Either because execute was set false, or no job resources are available at the moment and the job is placed in a queue.
running: The job is currently executing. A percent value is also returned (although it should not be considered precise).
completed: The job has completed successfully
aborted: The job was aborted

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 "shapes" should contain at least two no-overlapping polygons. The "label" is optional but it is included in the response.
The "intervals" can also be defined as a 3*3 matrix i.e. an array with 9 values to make individual time limits.
The timestamps "begin" and "end" can be either dates or timestamps like "2016-01-06" or "2016-01-06T00:00:00Z" and always in UTC time.
The Additional parameters with defaults can also be overridden: { "sog" : { "min" : 0, "max" :9 }, "dsog" : { "min" : 0, "max" : 3 }, "dcog" : { "min" : 0, "max" :30 }}

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

The timestamps "begin" and "end" can be either dates or timestamps like "2016-01-06" or "2016-01-06T00:00:00Z" and always in UTC time.

/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 shows 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/multiship/result/<id> GET
...
{
  "records" : [ { "description" : { "name" : "EXPRESS 1" }, "name" : "EXPRESS 1", "imo" : 1234 } , ....
  ]
}

Note: The first record in the result will have a time stamp before the specified "begin" time. The record is added to indicate the vessel name and data as this is not available in all records.

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