Maritime Domain Awareness

Grounding

The Grounding detector is used to detect when a ship unintentionally makes contact with the seabed or an underwater obstruction. In marine informatics, grounding events serve as an important indicator of navigational safety and operational risk, as they identify when and where an impact occurs.

This article will explain how to interact with the Gatehouse Maritime API to create, read, update, or delete grounding detectors, with concrete code examples of how to do it.

Content overview:

Create grounding detector
Read events from a grounding detector
Update a grounding detector
Delete a grounding event detector

The base URL for the following endpoints is:

https://demo.ghmaritime.com/api/ingress/grounding

Create grounding detector

To create a grounding detector a configuration needs to be specified.

A configuration defines what type of events the grounding detector should notify the user about, how severe the event is, and where to send the alert.

The endpoint for creating configurations is:

/configurations

This is defined as a payload that uses several parameters.

The following is a list of parameters that can be configurated in the payload:

<name>:
- What the name of the detector should be
<enabled>:
- If the detector is enabled, it will send notifications to the user, and if it is not enabled, it will remain silent upon events.
<parameters>:
- The several parameters that defines what events the detector should notify about.
  - use_in_same_location:
    - Checks whether the vessel remains in the same geographic location where a potential grounding was detected.
  - use_stop_check:
    - Enable detection of an abnormal stop: verifies whether the ship suddenly stops or its movement pattern breaks.
  - use_shallow_waters:
    - Filters in only depths shallower than 20 m.
  - use_sog_decrease:
    - Monitors whether the ship’s Speed Over Ground (SOG) has decreased abnormally within the last 30 seconds. The threshold depends on vessel type and typically ranges between 4 and 10 knots.
  - use_nav_stat:
    - Use navigation status information to filter or weight detections. I.e. it ensures that a stop with nav-status ‘At anchor’ is not treated as a grounding.
  - validate_minutes:
    - Number of minutes to wait after the first detection before performing a double-check.
  - filter_ports:
    - Exclude port areas from consideration (groundings in port are not detected).
  - filter_anchorage_areas:
    - Filter out anchorage areas, e.g. a grounding cannot occur in an anchorage area
  - use_remains_grounded_check
    - Make use of double-check. (If this is false, then “validate_minutes” will be irrelevant)
<severity>:
- This value can be set to either “Note”, “Warning”, or “Alert”, depending on how the user wants to treat the event. The detector will notify the user of the type of severity, and it is the user’s responsibility to know how to react to different severity types.
<shape> & <geometry>:
- It is possible to either use an already defined shape by its uuid or specify a geometry by GeoJson notation. However, it is not possible to define both in a payload, either the shape uuid should be specified or the GeoJson should be defined for the geometry.
  - Shape uses an uuid to specify the already defined shape:
    - “1234abcd-12ab-12ab-12ab-123456abcedf”
  - Geometry uses a GeoJson format to specify a shape.
    - See GeoJson for structure
<phone_numbers>:
- This is an array of phone numbers that should get notified when the event occurs.
<email_addresses>:
- This is an array of emails that should get notified when the event occurs.
<message>:
- What information should the user know when they get the notification.
<groundings>:
- This is an array of groundings specified by their id.

GeoJson structure:

  "geometry": {
    "geometry": {
      "coordinates": [
        [
          [
            -78.77392578124999,
            27.39828335627755
          ],
          [
            -71.74267578125001,
            22.62129400565829
          ],
          [
            -73.63232421875,
            20.41381508026815
          ],
          [
            -80.97119140625001,
            24.3542846683067
          ],
          [
            -78.77392578124999,
            27.39828335627755
          ]
        ]
      ],
      "type": "Polygon"
    },
    "properties": {
      "name": "TEST_SHAPE"
    },
    "type": "Feature"
  }

This was the number of available parameters to be used in the payload. The following is an example of some test payload in python:

payload = {
  "name": "detector",
  "enabled": True,
  "parameters": {
    "use_in_same_location": True,
    "use_stop_check": True,
    "use_shallow_waters": True,
    "use_sog_decrease": True,
    "use_nav_stat": False,
    "validate_minutes": 15,
    "filter_ports": True,
    "filter_anchorage_areas": True,
    "use_remains_grounded_check": True
  },
  "severity": "Note",
  "shape": "2504644d-b0cd-4c25-984e-70376685c32a",
  "type": "grounding",
  "phone_numbers": ["12345678"],
  "email_addresses": ["some_mail@provider.com"],
  "message": "string",
  "groundings": []
}

Now it is possible to create a configuration through the API, where the API will simultaneously create an event detector with the configuration.

Example code (python):

import requests
import json

URL = (
    f"https://demo.ghmaritime.com/api/ingress/grounding/configurations"
)

headers = {
  "Authorization": "Basic <credentials>",
  "Content-Type": "application/json"
}

payload = {
  "name": "detector",
  "enabled": True,
  "parameters": {
    "use_in_same_location": True,
    "use_stop_check": True,
    "use_shallow_waters": True,
    "use_sog_decrease": True,
    "use_nav_stat": False,
    "validate_minutes": 15,
    "filter_ports": True,
    "filter_anchorage_areas": True,
    "use_remains_grounded_check": True
  },
  "severity": "Note",
  "shape": "2504644d-b0cd-4c25-984e-70376685c32a",
  "type": "grounding",
  "phone_numbers": ["12345678"],
  "email_addresses": ["some_mail@provider.com"],
  "message": "string",
  "groundings": []
}


response = requests.post(URL, headers=headers, json=payload)
print(response.status_code)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))

Response sample:

201
{
  "id": 35,
  "uuid": "cb3598ed-8442-4b90-9ebf-d2af320ae857",
  "created_at": "2025-11-17T08:56:02.783582Z",
  "created_by": "user",
  "modified_at": "2025-11-17T08:56:02.783660Z",
  "modified_by": "user",
  "name": "detector",
  "enabled": false,
  "parameters": {
    "use_in_same_location": true,
    "use_stop_check": true,
    "use_shallow_waters": true,
    "use_sog_decrease": true,
    "use_nav_stat": false,
    "validate_minutes": 15,
    "filter_ports": true,
    "filter_anchorage_areas": true,
    "use_remains_grounded_check": true
  },
  "severity": "Note",
  "shape": "2504644d-b0cd-4c25-984e-70376685c32a",
  "geometry": null,
  "acl": [],
  "acl_put": [],
  "type": "grounding",
  "phone_numbers": [
    "12345678"
  ],
  "email_addresses": [
    "some_mail@provider.com"
  ],
  "message": "string",
  "groundings": []
}

Now, an event detector has been created with the specified definition.

Read events from a grounding detector

To read events from a grounding detector, create a GET request via the /groundings/{ID} endpoint where the id variable is the id of the grounding detector. Additionally, it is possible to get all events by constructing a request via the /groundings endpoint where id is not specified but several parameters are specified instead.

Events from specific grounding detector

As a prerequisite for this, the id of the detector should be known. If it is not known, see Get Definitions of all available Event Detector to find the id of the wanted detector.

Endpoint url:

/groundings/{ID}

Now, it is possible to use the id of the detector to get the events from the detector.

Example code (python):

import requests
import json

URL = (
    f"https://demo.ghmaritime.com/api/ingress/grounding/groundings"
)

headers = {
  "Authorization": "Basic <credentials>",
  "Content-Type": "application/json"
}

parameters = {
  "id": "<uuid>"
}

response = requests.get(URL, headers=headers, params=parameters)
print(response.status_code)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))

Response sample:

200
{
  "items": [
    {
      "id": 4,
      "uuid": "81587c04-2f9d-4acb-91fa-d01fe44fe1c3",
      "created_at": "2025-04-01T09:48:52.135822Z",
      "created_by": "grounding",
      "modified_at": "2025-09-29T07:29:00.262567Z",
      "modified_by": "grounding",
      "mmsi": 123456789,
      "grounding_point": {
        "type": "Point",
        "coordinates": [
          102.0,
          0.5
        ]
      },
      "grounding_time": "2021-01-01T00:00:00Z",
      "release_time": "2025-09-29T03:02:25Z",
      "vessel_name": "MAZUNTE",
      "imo": 7738618,
      "call_sign": null,
      "configuration_ids": [
        2,
        36,
        5,
        19,
        28,
        29
      ],
      "configurations": []
    }
  ],
  "total": 1,
  "page": 1,
  "size": 50,
  "pages": 1
}

Update a grounding detector

To update a grounding detector, construct a PUT request via the /configurations/{ID} endpoint where the request body specifies the new updated detector.

Endpoint url:

/configurations/{ID}

To see the descriptions of the parameters for the configurations, go to this list.

Additionally, the id of the detector should be known, if it is not known, see Get Definitions of all available Event Detector to get the id of the detector.

The following is an example of the payload that defines the configuration of the detector:

payload = {
  "name": "detector",
  "enabled": True,
  "parameters": {
    "use_in_same_location": True,
    "use_stop_check": True,
    "use_shallow_waters": True,
    "use_sog_decrease": True,
    "use_nav_stat": False,
    "validate_minutes": 15,
    "filter_ports": True,
    "filter_anchorage_areas": True,
    "use_remains_grounded_check": True
  },
  "severity": "Note",
  "shape": "2504644d-b0cd-4c25-984e-70376685c32a",
  "acl": [
    "<uuid>"
  ],
  "acl_put": [
    "<uuid>"
  ],
  "type": "grounding",
  "phone_numbers": ["12345678"],
  "email_addresses": ["some_mail@provider.com"],
  "message": "string",
  "groundings": []
}

It is important to note that the request body must contain the acl and acl_put fields where they should contain the uuid of the event detector that is being updated.

Example code (python):

import requests
import json

URL = (
    f"http://mdmtest.gatehouse.local/api/ingress/grounding/configurations/<configuration_id>"
)

headers = {
  "Authorization": "Basic <credentials>",
  "Content-Type": "application/json"
}

payload = {
  "name": "detector",
  "enabled": True,
  "parameters": {
    "use_in_same_location": True,
    "use_stop_check": True,
    "use_shallow_waters": True,
    "use_sog_decrease": True,
    "use_nav_stat": False,
    "validate_minutes": 15,
    "filter_ports": True,
    "filter_anchorage_areas": True,
    "use_remains_grounded_check": True
  },
  "severity": "Note",
  "shape": "2504644d-b0cd-4c25-984e-70376685c32a",
  "acl": [
    "5c5fe6f3-fc4d-4418-9b22-658fd7d63d71"
  ],
  "acl_put": [
    "5c5fe6f3-fc4d-4418-9b22-658fd7d63d71"
  ],
  "type": "grounding",
  "phone_numbers": ["12345678"],
  "email_addresses": ["some_mail@provider.com"],
  "message": "string",
  "groundings": []
}

response = requests.get(URL, headers=headers, params=parameters)
print(response.status_code)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))

Response sample:

200
{
  "id": 36,
  "uuid": "6c5fe6f3-fc4d-4418-9b22-658fd7d63d71",
  "created_at": "2025-11-17T09:08:01.153926Z",
  "created_by": "mae",
  "modified_at": "2025-11-17T10:08:08.381781Z",
  "modified_by": "mae",
  "name": "detector",
  "enabled": true,
  "parameters": {
    "use_in_same_location": true,
    "use_stop_check": true,
    "use_shallow_waters": true,
    "use_sog_decrease": true,
    "use_nav_stat": false,
    "validate_minutes": 15,
    "filter_ports": true,
    "filter_anchorage_areas": true,
    "use_remains_grounded_check": true
  },
  "severity": "Note",
  "shape": "2504644d-b0cd-4c25-984e-70376685c32a",
  "geometry": null,
  "acl": [
    "6c5fe6f3-fc4d-4418-9b22-658fd7d63d71"
  ],
  "acl_put": [
    "6c5fe6f3-fc4d-4418-9b22-658fd7d63d71"
  ],
  "type": "grounding",
  "phone_numbers": [
    "12345678"
  ],
  "email_addresses": [
    "some_mail@provider.com"
  ],
  "message": "string",
  "groundings": []
}

Now, the detector in the system should have been updated with the specified changes.

Delete a grounding event detector

To delete a grounding event detector, construct a DELETE request via the /configurations/{ID} endpoint, where id is the identification number of the detector.

Endpoint URL:

/configurations/{id}

The API will only respond with a response status, and not a Json object.

It should be mentioned that in order to delete a detector, the id of the detector should be known. If this is not the case, see Get Definitions of all available Event Detector to get the id of the detector.

Example code:

import requests
import json

URL = (
    f"http://mdmtest.gatehouse.local/api/ingress/grounding/configurations/1"
)

headers = {
  "Authorization": "Basic <credentials>",
  "Content-Type": "application/json"
}

response = requests.delete(URL, headers=headers)
print(response.status_code)
response.raise_for_status()

Response sample:

Now, the event detector should be deleted from the system.

Updated on 17 November, 2025

Next Port

I want to

Customer Stories

Maritime Domain Awareness

Grounding

Create grounding detector

Example code (python):

Response sample:

Read events from a grounding detector

Events from specific grounding detector

Example code (python):

Response sample:

Update a grounding detector

Example code (python):

Response sample:

Delete a grounding event detector

Example code:

Response sample: