This endpoint provides details on the inputs and outputs of operations used to configurate detectors regarding certain events.
Content Overview:
The base URL for the endpoints specified in this article is as follows:
https://mdmdemo.gatehousemaritime.com/api/eventdetector/definitionTo create a detector for a specific area, send a POST request to the /definition endpoint. The request body should include the detector’s name, type, and the type’s geometry.
There are four types of event detectors that can be created, i.e.
It is also possible to create an event detector for grounding.
To see the documentation for this, see Grounding Docs.
Each type of detector has a set of keys that can be set in the payload.
To see the full list of fields that can be specified in the payload, see the Bottom of the Page.
The code examples used for these examples will be as simple as possible to reduce the complexity.
The response from the API will contain the id of the detector; to then see the events that the detector has recorded, follow the steps in Get Events from an Event Detector.
The following is a list of variables that can be altered in the code:
import requests
import json
URL = f'https://demo.ghmaritime.com/api/eventdetector/definition'
headers = {
"Authorization": "Basic <Credentials>",
"Content-Type": "application/json",
}
payload = {
"name": "<DetectorName>",
"type": "<DetectorType>",
"geometry": {
"type": "<ShapeType",
"coordinates": [
[
<Lat&Long>
]
]
}
}
response = requests.post(URL, json=payload, headers=headers, timeout=10)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))An example of the latitude and longitude pairs is:
[
14.62272389125424,
55.317776522840745
],
[
14.626843764301114,
54.97718058173854
],
[
15.240704848285489,
54.971663255365826
],
[
15.220105483051114,
55.317776522840745
],
[
14.62272389125424,
55.317776522840745
]{
"id": "b6c30335-d1e5-42ae-bf95-cb3d83bc144b"
}The above example uses a basic configuration of an event detector; However, there are several additional fields that can be specified, to make the detector more specialized.
The following list depicts the fields and a small description.
{
"name": "TestForAPI",
"id": null,
"type": "area",
"acl": ["4413eb2c-22ea-4a0d-9b20-1ded41cafb7e"],
"enabled": true,
"activity_filter": {
"static": {
"destination": true,
"name": true,
"draught": true,
"eta": true
},
"dynamic": { "nav_stat": true },
"fishing": true,
"transponder_off": "00:00:10"
},
"advanced_configuration": true,
"use_vessel_dimensions": true,
"entire_vessel": true,
"send_ship_notification": true,
"time_before_activation": "00:00:10",
"time_before_deactivation": "00:00:10",
"samples_before_activation": 1,
"samples_before_deactivation": 2,
"timeout_when_active": "00:00:10",
"ship_notification_text": "Beware",
"severity": "warning",
"shape": "75455072-bd4f-4cf5-a9a4-78190a65f6b1",
"geometry": {
"properties": {
"id": "75455072-bd4f-4cf5-a9a4-78190a65f6b1",
"parent_id": "00000000-0000-0000-0000-000000000000",
"name": "danmark",
"owner": "user",
"description": ""
},
"geometry": {
"type": "Polygon",
"coordinates": [
[
[5.899831189021413, 58.03520621855353],
[10.36028040777141, 59.59364040134716],
[12.44768275152141, 57.05662014150241],
[13.04094447027141, 55.44558682141025],
[14.90862025152142, 55.78064553353462],
[16.31487025152141, 56.22294935760851],
[18.90764368902141, 54.93130269412583],
[18.16057337652141, 54.53803392106619],
[14.20549525152141, 53.83087063282116],
[11.30510462652141, 54.05074053809781],
[5.592214001521413, 53.47927968203888],
[5.899831189021413, 58.03520621855353]
]
]
},
"type": "Feature"
},
"filter_id": "7cbe647f-90fb-49d1-ab46-9cwe0074cf91",
"filter_string": "valid_imo",
"ack_required": true,
"shiplist": { "active": true },
"activation_text": "Activation text",
"deactivation_text": "Deactivation text",
"check_direction": { "min_angle": 10, "max_angle": 19 },
"time_between_triggers": "00:00:10",
"notify": [
{ "who": "testemail@email.com", "action": "email" },
{ "who": "12345678", "action": "sms" }
],
"notify_on_activation": true,
"notify_on_deactivation": true,
"circle_center_cpa": true,
"check_cpa": false,
"cpa_limit": 0,
"tcpa_limit": 0
}
It is possible to specify special fields that relate only to the cable type.
These fields are:
import requests
import json
URL = f'https://mdmdemo.gatehousemaritime.com/api/eventdetector/definition'
headers = {
"Authorization": "Basic <Credentials>",
"Content-Type": "application/json",
}
payload = {
"name": "12312345",
"type": "cable",
"detect_anchored_drifting": True,
"detect_anchored_drifting_out": True,
"detect_anchored_witin": True,
"detect_drifting": True,
"detect_invalid_ais": True,
"detect_nav_status": True,
"detect_speed_drop": True,
"detect_exit_check": True,
"delta_sog_threshold": 5,
"drifting_chd_threshold": 1,
"drifting_sog_threshold": 3,
"drifting_time_threshold": 60,
"exit_check_threshold": 5,
"nav_status_ignore_threshold": 10,
"nav_status_trigger_threshold": 20,
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
14.62272389125424,
55.317776522840745
],
[
14.626843764301114,
54.97718058173854
],
[
15.240704848285489,
54.971663255365826
],
[
15.220105483051114,
55.317776522840745
],
[
14.62272389125424,
55.317776522840745
]
]
]
}
}
response = requests.post(URL, json=payload, headers=headers, timeout=10)
response.raise_for_status()
print(json.dumps(response.json(), indent=2)){
"id": "02356037-aec7-42u1-b4d9-76a8f4277e74"
}/definition{id}In order to delete a specific event detector, the id of the specific event detector should be known and make sure that the event detector with the specific id actually exists.
If the id is not known, follow the Get Definition of an Event Detector guide and once the definition is found, look for the id of the detector in the response.
To delete an active event detector from the system, construct a DELETE request via the /definition{id} endpoint, where the id variable in the url specifies the specific detector.
The API will respond with an empty JSON object if the request was successful.
import requests
import json
URL = (
f"https://demo.ghmaritime.com/api/eventdetector/definition/<id>"
)
headers = {
"Authorization": "Basic <Credentials>",
"Content-Type": "application/json",
}
response = requests.delete(URL, headers=headers)
print(response.status_code)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))200
{}/definitionThe API keeps track of all defined event detectors available to you.
To get a list of all definitions available to you, construct a GET request via the /definition endpoint, here the API will respond with a record of all event detectors available to you and their definitions.
import requests
import json
URL = (
f"https://mdmdemo.ghmaritime.com/api/eventdetector/definition"
)
headers = {
"Authorization": "Basic <credentials>",
"Content-Type": "application/json",
}
response = requests.get(URL, headers=headers)
print(response.status_code)
response.raise_for_status()
print(json.dumps(response.json(), indent=2)){
"records": [
{
"ack_required": false,
"activation_text": "criss",
"advanced_configuration": true,
"deactivation_text": "cross",
"enabled": false,
"entire_vessel": false,
"filter_string": "",
"geometry": {
"geometry": {
"coordinates": [
[
13.00659588417966,
55.57467980921433
],
[
12.54791668496091,
55.72036531472571
]
],
"type": "LineString"
},
"properties": {
"description": "",
"id": "0075ebd5-caca-4fc1-b582-d1d3cbf086be",
"name": "crosser",
"owner": "jsk",
"parent_id": "00000000-0000-0000-0000-000000000000"
},
"type": "Feature"
},
"id": "ebb3a0c5-0757-4c2a-8204-7211a28cc51e",
"name": "crosser",
"notify": [],
"notify_on_activation": true,
"notify_on_deactivation": true,
"owner": "jsk",
"send_ship_notification": true,
"severity": "note",
"shape": "0075ebd5-caca-4fc1-b582-d1d3cbf086be",
"ship_notification_text": "",
"shiplist": {
"active": false
},
"time_before_activation": "",
"time_before_deactivation": "",
"time_between_triggers": "",
"timeout_when_active": "",
"type": "line",
"use_vessel_dimensions": true,
"user_id": "d21c8922-1b13-4708-b3a4-613331d0a03e"
},
...
]
{/eventdetector/event?from_timestamp=<from>&to_timestamp=<to>As a prerequisite to getting the events of a event detector, it should be noted that an event detector should have been created beforehand and the id of the detector should also be known.
To get the events of event detectors, a GET request should be constructed via the /eventdetector/event?from_timestamp=<from>&to_timestamp=<to> endpoint. Additionally, it should be noted that there is no need to specify anything in the request body (payload).
The parameters from_timestamp and to_timestamp specifies the interval where the events occured and their values, <from> and <to>, should be in the ISO (UTC) format. The following is an example of the ISO format:
from: 2025-10-05T10:00:00Z
to: 2025-10-06T10:00:00ZIf no to_timestamp parameter is provided, the API will automatically set the value as the current time.
If none of the event detectors have signalled any events, the API will respond with an empty JSON file.
However, If the detectors have signalled events, the API will respond with a record (array) of event detectors and their recorded events.
The following is a simple code example of such a request:
import requests
import json
URL = (
f"https://demo.ghmaritime.com/api/eventdetector/event?from_timestamp=2025-10-06T10:00:00Z&to_timestamp=2025-10-0612:00:00Z"
)
headers = {
"Authorization": "Basic <credentials>",
"Content-Type": "application/json",
}
response = requests.get(URL, headers=headers)
print(response.status_code)
response.raise_for_status()
print(json.dumps(response.json(), indent=2)){
"records": [
{
"definition": {
"id": "572940fd-4cfd-4e10-bd88-6e9389bf764a"
},
"event": {
"activated": {
"coordinates": [
9.276185,
57.692275,
"2025-08-01T07:05:57Z",
74.1,
7.900000000000001
],
"extensions": [
"time",
"cog",
"sog"
],
"type": "Point"
},
"data_source_type": "ais-s",
"id": "e0b52523-fd60-42b4-b4db-34aaf55e040f",
"severity": "Note",
"ship": {
"callsign": "XP2671",
"cog": 74.1,
"destination": "AALBAEK",
"mmsi": 219011136,
"name": "HG 345 AMANDA",
"navstatus": "Fishing",
"shiptype": "Fishing",
"size": [
11.0,
3.0,
1.0,
3.0
],
"sog": 7.9,
"typeofmobile": "Class A"
}
}
},
{
"definition": {
"id": "17656425-8324-49de-9288-6680ea2d6dcb"
},
"event": {
"activated": {
"coordinates": [
8.630866666666666,
57.18155,
"2025-08-01T07:02:34Z",
214.39999999999998,
null
],
"extensions": [
"time",
"cog",
"sog"
],
"type": "Point"
},
"data_source_type": "ais-s",
"id": "7d346bea-d4b2-4b00-89b6-e38a7186dbd1",
"severity": "Note",
"ship": {
"callsign": "PLFQ",
"cog": 214.4,
"destination": "SIR A",
"draught": 1.5,
"eta": "2025-11-01T21:06:00Z",
"heading": 228,
"imo": 1234540,
"mmsi": 200000000,
"name": "IDN PARI 849",
"navstatus": "Reserved [WIG]",
"shiptype": "Fishing",
"size": [
6.0,
2.0,
1.0,
1.0
],
"typeofmobile": "Class B"
}
}
},
]
}/definition/<id>Before the request to the API is constructed, the id or name of the specific event detector should be known, since it is used in the URL of the request.
If the name or id is not known, follow the steps in Get Definitions of all Available Event Detectors and look through the response for the desired detector.
To get the definition of a single event detector, construct a GET request via the /definition/<id> endpoint, where the id variable in the URL specifies the id of the event detector.
The API will respond with a JSON object that contains the definition the specified event detector, i.e. its geometry, name, owner etc.
URL = (
f"https://demo.ghmaritime.com/api/eventdetector/definition/<id>"
)
headers = {
"Authorization": "Basic <credentials>",
"Content-Type": "application/json",
}
response = requests.get(URL, headers=headers)
print(response.status_code)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))200
{
"enabled": true,
"geometry": {
"coordinates": [
[
[
13.62272389125424,
55.31777652284075
],
[
14.62684376430111,
54.97718058173854
],
[
15.24070484828549,
54.97166325536583
],
[
15.22010548305111,
55.31777652284075
],
[
14.62272389125424,
55.31777652284075
]
]
],
"type": "Polygon"
},
"id": "46bba385-e11a-4d1f-aff2-272dcd763dad",
"name": "test123",
"owner": "mae",
"type": "area",
"user_id": "de5091f5-c4d3-49b6-acbe-4cf190370439"
}/definitionTo update a detector for a specific area, send a PUT request to the /definition endpoint. The request body should include the detector’s name, type (in this case, ‘area’), and the area’s geometry.
The response from the API will contain the id of the detector; to then see the events that the detector has recorded, follow the steps in Get Events from an Event Detector.
The following is a list of variables that can be altered in the code:
import requests
import json
URL = f'https://demo.ghmaritime.com/api/eventdetector/definition'
headers = {
"Authorization": "Basic <credentials>",
"Content-Type": "application/json",
}
payload = {
"name": "<DetectorName>",
"type": "area",
"geometry": {
"type": "<ShapeType",
"coordinates": [
[
<Lat&Long>
]
]
}
}
response = requests.put(URL, json=payload, headers=headers, timeout=10)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))An example of the latitude and longitude pairs is:
[
14.62272389125424,
55.317776522840745
],
[
14.626843764301114,
54.97718058173854
],
[
15.240704848285489,
54.971663255365826
],
[
15.220105483051114,
55.317776522840745
],
[
14.62272389125424,
55.317776522840745
]200
{
"id": "46bba385-e11a-4d1f-aff2-272dcd763dad"
}{
"activity_filter": {
"dynamic": {
"nav_stat": false,
},
"fishing": false,
"static": {
"destination": true
"name": false,
"draught": false,
"eta": false,
}
"transponder off": "01:00:00"
}
}This can use the same fields as Area, however it can not use “activity_filter”.