REST Documentation Watchdog

Note: This documentation applies to software release 137. The API in future releases will be different.

The Watchdog system can be used for getting events from the system when ships behave in a specified pattern

The base path:

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

The reference section can be found here:

GateHouse Webservice Reference

Two types of entities are part of the watchdog system:

  1. Watchdog Definitions: Definition of an area and a set of criteria for triggering watchdog events
  2. Watchdog Events: Event triggered by one or more ships entering/exiting/passing an area and fulfilling the requirements from the watchdog definition.

In the following the terms "definition" and "event" is used.

Predefined watchdog types:

  1. Polygon: A simple polygon (no intersections) defining an area. An event will be triggered when
    1. a ship enters the polygon
    2. a ship leaves the polygon.
  2. Port: An area around a port with a number of quay / pier / bollard areas. An event will be triggered when
    1. a ship enters the outer port area
    2. a ship is moored (i.e. slowed down) along a quay / pier
    3. a ship leaves the inner berth area
    4. a ship leaves the outer port area.
  3. Line: A simple 2 point line. An event will trigger whenever a ship passes over the line.

Create a Watchdog Definition

Create a watchdog definition. The watchdog server will trigger events based on this definition until it is deleted again. The watchdog definition will work for this active user (or as specified by the ACL). Multiple users can create similar watchdog definitions.

The definition of a watchdog will encompass a potentially large number of parameters. To simplify clients a number of predefined watchdog definitions are made.

To create a watchdog, use the 

/definition POST

message with the parameters specified below depending on the watchdog type.

If no "acl" is specified users this is a private watchdog for this user only. Notice this is the only mode currently supported.

A successful call returns 200 with body (for error codes see below)

{ "id" : 9876543210 }

To update an existing watchdog definition, call /definition PUT in the same way (note that you need to specify the id parameter in this case).

Get list of active Watchdog Definitions

To get the list of all active watchdog definitions call:

/definition GET

A successful call returns 200 with the list of active watchdog definitions in the body (for error codes see below)

{"records":[
  { "id" : 9876543210, "name" : "My Felixstowe Watchdog", "type" : "port", "port" : { "id" : 31560, "locode" : "GBFXT", "name" : "FELIXSTOWE" } }
]}

Note: Only definitions accessible to the authenticated user are returned.

To get a specific watchdog definition

/definition/{id} GET e.g: /definition/9876543210

A successful call returns 200 with the watchdog definition in the body (for error codes see below)

{ "id" : 9876543210, "name" : "My Felixstowe Watchdog", "type" : "port", "port" : { "id" : 31560, "locode" : "GBFXT", "name" : "FELIXSTOWE" } }

Delete a Watchdog Definition

/definition/{id} DELETE e.g: /definition/9876543210

A successful call returns 200 with an empty response in the body (for error codes see below)

Query and Wait for Watchdog Events

A client system can either poll for events or wait for events to happen.

Poll Watchdog Events

This will return the list of watchdog events that have triggered or untriggered since last call. To reset the time of call (e.g. in case of restart client or lost connection)

/event POST

with parameters:

{ "timestamp" : "2015-10-20T14:00:00Z" }

Reset the time for last call to /event GET to the specified timestamp. A successful call returns the input

{ "timestamp" : "2015-10-20T14:00:00Z" }

To get the list of events call

/event GET

A successful call returns 200 with the events that have occurred since the last call to /event GET in the body (for error codes see below)

Return value from /event:

{"records":[
  { watchdog : { "id" : 9876543210 }, 
    "event" : {
      "id" : 12345,
      "ship" : { "mmsi" : 〈mmsi〉, "imo", 〈imo〉, "callsign" : 〈callsign〉, "name" : 〈name of ship〉, ... }
      // Further event parameters depends on the type, See below but typically include
      "activated" : 〈GeoJSON-X〉
    } 
  }
]}

Note: Only events generated by watchdog definitions accessible to the authenticated user are returned.

Note: The call may return events that were also returned in an earlier call, this is a technical limitation. Use the id property to determine if the event was already processed.

Notice /event/{id} GET may be defined later.

GeoJSON-X (GeoJSON eXtended)

https://github.com/dret/GeoJSON-X

Example:

{ "type" : "Point", "extensions" : ["time", "cog", sog"], "coordinates" : [10.5, 55.2, "2016-02-09T10:25:00Z", 120.4, 8.4]}

Wait for Watchdog Events

Works the same way as /event GET but will block until an event occurs or a configured time has passed (about 2 minutes depending on firewalls). Will return immediately if events have occurred since last call.

/wait GET

Return value, same as above for /event

Note: Only events generated by watchdog definitions accessible to the authenticated user are returned.

The watchdog types

The following optional parameters are common for all watchdog types:

"name": 〈name〉
"acl": [〈users/groups〉]
"filter": 〈filter string〉
"shiplist": { "active" :〈boolean〉, "timeout" : 〈integer〉 }
"notify": { "who": [ 〈users/groups〉 ], "action": "email" }
"nof_samples": 〈integer〉

If a name is specified, it must be unique.

If shiplist.active is true, the system will maintain a shiplist named WD_〈name〉 containing all ships for which the watchdog is currently active. For a Line watchdogs, ships are removed from the list after a timeout specified by shiplist.timeout (the unit is seconds, and the default value is 30 minutes).

The allowed values for action are email, sms, and emailsms.

Polygon watchdogs

To create a polygon watchdog call /definition POST with the following parameters:

{ "type": "polygon", "polygon": 〈geojson〉 }

The return value from a triggered watchdog for /event or /wait includes:

"event" : { "ship" : 〈see above〉, "activated" : 〈GeoJSON-X〉, "deactivated": 〈GeoJSON-X〉, "timeout" : true }

"activated" indicates the ship entered the area, "deactivated" indicates the ship left the area. If "timeout" is set this indicates that the watchdog has deactivated due to a timeout.

Line watchdogs

To create a line watchdog call /definition POST with the following parameters:

{"type": "line", "line": 〈geojson〉 }

The return value from a triggered watchdog for /event or /wait includes:

"event": { "ship": 〈see above〉, "activated": 〈GeoJSON-X〉}

Port watchdogs

To create a port watchdog call /definition POST with the following parameters:

{"type" : "port", "config" : { "id" : 31560, "locode" : "GBFXT", "name" : "FELIXSTOWE" } }

At least one of the parameters for the port parameters (locode, name or id) must be included (the id is from World Port Index and can be retrieved from /api/portserver/port/list)

The return value from a triggered watchdog for /event or /wait includes:

"event" : { "ship" : 〈see above>, "activated" : 〈GeoJSON-X〉, "deactivated": 〈GeoJSON-X〉, "timeout" : true, "berth" : 〈berth area〉 }

"activated" indicates when the ship entered the area, "deactivated" indicates when the ship left the area. If "timeout" is set this indicates that the watchdog has deactivated due to a timeout.

If "berth" is not present, this indicates that the ship entered or left the outer port area. If "berth" is present, this indicates that the ship is either moored at the berth area or has left the berth area.

Circle watchdogs

To create a circle watchdog, call /definition POST with the following parameters:

{ "type": "circle", "circle": { "center" : 〈geojson〉, "radius":  〈radius〉}

The radius is specified in meters.

The return value from a triggered watchdog has the same format as for a polygon watchdog.

Polygon watchdogs (predefined polygon)

To create a polygon watchdog using a predefined polygon, call /definition POST with the following parameters:

{ "type": "polygon", "shapeuid": 〈uuid〉 }

When retrieving the definition for a watchdog of this type, it will have the following format:

{"records":[
  { "id" : 9876543210, "name" : "Predefined Polygon Watchdog", "type" : "polygon", "polygon" : { "shapeuid": 〈uuid〉, "polygon": 〈geojson〉 } }
]}

Line watchdogs (predefined line)

To create a line watchdog using a predefined line, call /definition POST with the following parameters:

{"type": "line", "shapeuid": 〈uuid〉 }

When retrieving the definition for a watchdog of this type, it will have the following format:

{"records":[
  { "id" : 9876543210, "name" : "Predefined Line Watchdog", "type" : "line", "line" : { "shapeuid": 〈uuid〉, "line": 〈geojson〉 } }
]}

Circle watchdogs (predefined circle)

To create a circle watchdog using a predefined circle, call /definition POST with the following parameters:

{"type" : "circle", "shapeuid" : 〈uuid〉 }

When retrieving the definition for a watchdog of this type, it will have the following format:

{"records":[
  { "id" : 9876543210, "name" : "Predefined Circle Watchdog", "type" : "line", "shapeuid" : 〈uuid〉, "circle" : { "center" :〈geojson〉, "radius" : 1000 }
]}

Cable watchdogs (predefined polygon)

To create a cable watchdog using a predefined polygon, call /definition POST with the following parameters:

{ "type": "cable", "shapeuid": 〈uuid〉 }

Basic boolean parameters for cable watchdog:

detectinvalidais
detectspeeddrop
doexitcheck
detectanchoreddrifting
detectanchoredwithin
detectanchoreddriftingout
detectnavstatus
detectdrifting

Advanced parameters for cable watchdog:

navstatustriggerthreshold
navstatusignorethreshold
deltasogthreshold
driftingsogthreshold
driftingchdthreshold
driftingtimethreshold
exitchecktriggerlost
exitcheckthreshold

Ship list

When defining a watchdog it is possible to specify that a ship list shall be created for the watchdog. The ship list will contain all ships with an active event. To create a ship list for a watchdog, add the following field when defining the watchdog:

"shiplist" : { "active" : true }

When defining a line watchdog, it is possible to specify how long a ship shall be included in the ship list [HHH:MM:SS]:

"shiplist" : { "timeout" : "hhh:mm:ss" }

HTTP Status Codes

HTTP Status Codes

 

Generated on 2022-02-10T12:48:05+01:00