Maritime Domain Awareness

Ship-to-Ship

The Ship-to-Ship endpoint is used to detect when ships carry out transferring of goods during a trip. Without knowing the occurrence of such events, it is impossible to determine how cargo moves between ports.

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

Content overview:
Detector Operations:

Create an STS Detector Configuration
Get single Detector Configuration
Get all Detector Configurations
Update Detector Configuration
Delete Detector Configuration

Event Operations:

Get all Events
Get all Current Events
Search Events by MMSI
Get Event by ID
Get Tracks from Event
Acknowledge Event

The base URL for the following endpoints is:

https://mdmdemo.gatehousemaritime.com/api/ingress/event-detection/

All code snippets in this guide will is written in Python.

List of parameters in the configurations:

“name”
- String
- Name of the configuration itself
“enabled”
- Boolean
- Whether the detector should actively look for S2S events for if it should remain inactive
“parameters”
- “distance_for_sts_meters”
  - Integer
  - The distance between two ships that starts the time interval of a S2S transfer event (In meters)
- “transfer_time_window_minutes”
  - Integer
  - The time window dictating how long the two ships should spent within the specified range of each other until it marks it as a S2S event.
“severity”
- String
- The severity level assigned to detected S2S events. Determines how the alert is classified and displayed. Accepted values: “Note”, “Warning”, “Alert”
“geometry”
- The geographic area in which the detector actively monitors for S2S events
- “geometry”
  - “type”
    - String
    - The GeoJSON geometry type. Accepted value: “Polygon”
  - “coordinates”
    - Array
    - A list of coordinate rings defining the polygon boundary. Each coordinate is a [longitude, latitude] pair. The first and last coordinate must be identical to close the polygon
- “properties”
  - “name”
    - String
    - A human-readable label for the shape (e.g. “TEST_SHAPE”)
- “type”
  - String
  - The GeoJSON object type. Accepted value: “Feature”
“acl”
- Array of strings
- Access Control List. A list of UUIDs representing the users or entities that have access to this configuration
“type”
- String
- The type of detection event this configuration targets. Accepted value: “s2s” (Ship-to-Ship)
“phone_numbers”
- Array of strings
- A list of phone numbers to notify when an S2S event is detected. Numbers should be in E.164 format (e.g. “+4512345678”)
“email_addresses”
- Array of strings
- A list of email addresses to notify when an S2S event is detected
“exclude_ports”
- Boolean
- Whether S2S events occurring within or near port areas should be excluded from detection. Set to true to filter out port activity, false to include it

List of Ship-to-Ship events parameters:

“id”
- Integer
- Internal numeric identifier for the S2S event record
“uuid”
- String
- Universally unique identifier for the event, in UUID v4 format (e.g. “3fb24f61-5f17-4a62-b3fc-2c963f66afa6”)
“created_at”
- String (ISO 8601)
- Timestamp of when the event record was first created
“created_by”
- String
- Username or identifier of the user or system that created the event record
“modified_at”
- String (ISO 8601)
- Timestamp of the most recent modification to the event record
“modified_by”
- String
- Username or identifier of the user or system that last modified the event record
“s2s_pair”
- Object containing positional data for both ships involved in the S2S event
- “first”
  - Data for the first ship in the pair
  - “activation_position”
    - “type”
      - String
      - GeoJSON geometry type. Accepted value: “Circle”, “Line”, “Point”, “Polygon”
    - “coordinates”
      - Array
      - The [longitude, latitude] position of the ship at the moment the proximity threshold was entered
  - “fired_position”
    - “type”
      - String
      - GeoJSON geometry type. Accepted value: “Circle”, “Line”, “Point”, “Polygon”
    - “coordinates”
      - Array
      - The [longitude, latitude] position of the ship at the moment the S2S event was confirmed and fired
  - “mmsi”
    - Integer
    - The Maritime Mobile Service Identity number uniquely identifying the first vessel
- “second”
  - Data for the second ship in the pair. Contains the same fields as “first”
  - “activation_position”
    - “type”
      - String
      - GeoJSON geometry type. Accepted value: “Circle”, “Line”, “Point”, “Polygon”
    - “coordinates”
      - Array
      - The [longitude, latitude] position of the ship at the moment the proximity threshold was entered
  - “fired_position”
    - “type”
      - String
      - GeoJSON geometry type. Accepted value: “Circle”, “Line”, “Point”, “Polygon”
    - “coordinates”
      - Array
      - The [longitude, latitude] position of the ship at the moment the S2S event was confirmed and fired
  - “mmsi”
    - Integer
    - The Maritime Mobile Service Identity number uniquely identifying the second vessel
“mmsi_first”
- Integer
- Top-level shorthand for the MMSI of the first ship in the pair
“mmsi_second”
- Integer
- Top-level shorthand for the MMSI of the second ship in the pair
“fired_time”
- String (ISO 8601)
- Timestamp of when the S2S event was confirmed and the alert was triggered
“activation_time”
- String (ISO 8601)
- Timestamp of when the two ships first entered the proximity threshold, starting the time window
“deactivation_time”
- String (ISO 8601)
- Timestamp of when the two ships exited the proximity threshold, ending the monitored interval
“severity”
- String
- The severity level of the event as classified by the detector (e.g. “note”, “warning”, “alert”)
“name”
- String
- A human-readable label describing the event (e.g. “ship to ship north sea”)
“configuration_id”
- Integer
- Reference to the ID of the configuration that triggered this event
“activation_text”
- String
- A human-readable summary of the event, describing the two ships and the conditions that triggered the alert (e.g. “Ship X and ship Y sailed within 200 meters for 2 hours”)
“ack_state”
- String
- The acknowledgement state of the alert. Indicates whether an operator has reviewed or acted on the event (e.g. “undefined”)
“ack_state_modified_ts”
- String (ISO 8601)
- Timestamp of when the acknowledgement state was last changed
“ack_state_modified_by”
- String
- Username or identifier of the operator who last changed the acknowledgement state

It should be noted that for some of the endpoints, the ID of some configuration should be known beforehand.
If the ID is not known, see either “Get all Detector Configurations“, “Get all Events“, or “Search Events by MMSI” to try and search for the ID of the desired configuration.

Create an STS Detector Configuration

To create an STS detector configuration, create a POST request via the /configurations endpoint with a payload where all parameters in the payload define the configuration.

Endpoint:

GET /configurations

Below is a code snippet of setting up a detector configuration.

Code Example:

import requests
import json

URL = f"http://mdmdemo.gatehousemaritime.com/api/ingress/event-detection/configurations"
headers = {
    "Authorization": "Basic <credentials>",
    "Content-Type": "application/json",
}

payload = {
  "name": "test_configuration",
  "enabled": True,
  "parameters": {
    "distance_for_sts_meters": 200,
    "transfer_time_window_minutes": 20
  },
  "severity": "Note",
  "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"
  },
  "acl": [
    "3fa12234-5717-4562-b3fc-2c963f66afa6"
  ],
  "type": "s2s",
  "phone_numbers": [
    "+4531415161"
  ],
  "email_addresses": [
    "no-reply@gatehouse.com"
  ],
  "exclude_ports": False
}

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

Response Sample:

{
  "id": 11,
  "uuid": "9248c7fd-c6cf-428f-aefb-7358c5271c00",
  "created_at": "2026-05-29T10:30:36.675876Z",
  "created_by": "mae",
  "modified_at": "2026-05-29T10:30:36.675910Z",
  "modified_by": "mae",
  "name": "test_configuration",
  "enabled": true,
  "parameters": {
    "distance_for_sts_meters": 200,
    "transfer_time_window_minutes": 20
  },
  "severity": "Note",
  "shape_uuid": null,
  "geometry": {
    "type": "Polygon",
    "coordinates": [
      [
        [
          -78.77392578124999,
          27.39828335627755
        ],
        [
          -71.74267578125001,
          22.62129400565829
        ],
        [
          -73.63232421875,
          20.41381508026815
        ],
        [
          -80.97119140625001,
          24.3542846683067
        ],
        [
          -78.77392578124999,
          27.39828335627755
        ]
      ]
    ]
  },
  "owner": "de5091f5-c4d3-49b6-acbe-4cf190370439",
  "acl": [
    "3fa12234-5717-4562-b3fc-2c963f66afa6"
  ],
  "type": "s2s",
  "phone_numbers": [
    "+4531415161"
  ],
  "email_addresses": [
    "no-reply@gatehouse.com"
  ],
  "exclude_ports": false
}

Get single Detector Configuration

To get the specification of a configuration, construct a GET request via the /configurations/{id} endpoint, where the id of the configuration is specified in the URL.

GET /configurations/{id}

The following is a code snippet requesting the API for a single detector’ specification

Code snippet:

import requests
import json

URL = f"http://mdmtest.gatehousemaritime.com/api/ingress/event-detection/configurations/11"
headers = {
    "Authorization": "Basic <credentials>",
    "Content-Type": "application/json",
}

response = requests.get(URL, headers=headers, timeout=100)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))

Response sample:

{
  "id": 11,
  "uuid": "9248c7fd-c6cf-428f-aefb-7358c5271c00",
  "created_at": "2026-05-29T10:30:36.675876Z",
  "created_by": "user",
  "modified_at": "2026-05-29T10:30:36.675910Z",
  "modified_by": "user",
  "name": "test_configuration",
  "enabled": true,
  "parameters": {
    "distance_for_sts_meters": 200,
    "transfer_time_window_minutes": 20
  },
  "severity": "Note",
  "shape_uuid": null,
  "geometry": {
    "type": "Polygon",
    "coordinates": [
      [
        [
          -78.77392578124999,
          27.39828335627755
        ],
        [
          -71.74267578125001,
          22.62129400565829
        ],
        [
          -73.63232421875,
          20.41381508026815
        ],
        [
          -80.97119140625001,
          24.3542846683067
        ],
        [
          -78.77392578124999,
          27.39828335627755
        ]
      ]
    ]
  },
  "owner": "de5099f5-c1d3-43b6-acbe-4cf190370439",
  "acl": [
    "3fa12234-5717-4562-b3fc-2c963f66afa6"
  ],
  "type": "s2s",
  "phone_numbers": [
    "+4531415161"
  ],
  "email_addresses": [
    "no-reply@gatehouse.com"
  ],
  "exclude_ports": false
}

Get all Detector Configurations

To get all detector configurations, construct a GET request via the /configurations endpoint without any payload.

GET /configurations

The following is a code snippet that gets all configurations from the system.

Code snippet:

import requests
import json

URL = f"http://mdmtest.gatehousemaritime.com/api/ingress/event-detection/configurations"
headers = {
    "Authorization": "Basic <credentials>",
    "Content-Type": "application/json",
}

response = requests.get(URL, headers=headers, timeout=100)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))

Response sample:

{
  "items": [
    {
      "id": 4,
      "uuid": "eca5b2f4-57e7-442d-9fb0-5391e90eb5cf",
      "created_at": "2026-05-19T06:20:56.993041Z",
      "created_by": "gh",
      "modified_at": "2026-05-19T06:20:56.993094Z",
      "modified_by": "gh",
      "name": "test_configuration",
      "enabled": true,
      "parameters": {
        "distance_for_sts_meters": 200,
        "transfer_time_window_minutes": 20
      },
      "severity": "Note",
      "shape_uuid": "75455072-bd4f-4cf5-a9a4-78190a65f6b1",
      "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
            ]
          ]
        ]
      },
      "owner": "3d33636a-8603-47c5-b9b8-440d6f6ccc73",
      "acl": [],
      "type": "s2s",
      "phone_numbers": [],
      "email_addresses": [],
      "exclude_ports": false
    },
    ...
  ]
}

Update Detector Configuration

To update a configuration in the system, a JSON formatted specification of the newly updated configuration should be known beforehand.

Then, construct a PUT request via the /configuration/{id} endpoint where the ID of the configuration is specified in the URL.

PUT /configurations/{id}

The following is a code snippet, updating a configuration already in the system.

Code snippet:

import requests
import json

URL = f"http://mdmtest.gatehousemaritime.com/api/ingress/event-detection/configurations/11"
headers = {
    "Authorization": "Basic <credentials>",
    "Content-Type": "application/json",
}

payload = {
  "name": "test_configuration",
  "enabled": True,
  "parameters": {
    "distance_for_sts_meters": 200,
    "transfer_time_window_minutes": 20
  },
  "severity": "Note",
  "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"
  },
  "acl": [
    "3fa12234-5717-4562-b3fc-2c963f66afa6"
  ],
  "type": "s2s",
  "phone_numbers": [
    "+4531415161"
  ],
  "email_addresses": [
    "no-reply@gatehouse.com"
  ],
  "exclude_ports": False
}

response = requests.put(URL, headers=headers, json=payload, timeout=100)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))

Response sample:

{
  "id": 11,
  "uuid": "9248c7fd-c6cf-428f-aefb-7358c5271c00",
  "created_at": "2026-05-29T10:30:36.675876Z",
  "created_by": "user",
  "modified_at": "2026-05-29T11:34:06.604824Z",
  "modified_by": "user",
  "name": "test_configuration",
  "enabled": true,
  "parameters": {
    "distance_for_sts_meters": 200,
    "transfer_time_window_minutes": 20
  },
  "severity": "Note",
  "shape_uuid": null,
  "geometry": {
    "type": "Polygon",
    "coordinates": [
      [
        [
          -78.77392578124999,
          27.39828335627755
        ],
        [
          -71.74267578125001,
          22.62129400565829
        ],
        [
          -73.63232421875,
          20.41381508026815
        ],
        [
          -80.97119140625001,
          24.3542846683067
        ],
        [
          -78.77392578124999,
          27.39828335627755
        ]
      ]
    ]
  },
  "owner": "de5090f5-c4d3-49b6-acbe-4cf190370439",
  "acl": [
    "3fa12234-5717-4562-b3fc-2c963f66afa6"
  ],
  "type": "s2s",
  "phone_numbers": [
    "+4531415161"
  ],
  "email_addresses": [
    "no-reply@gatehouse.com"
  ],
  "exclude_ports": false
}

Delete Detector Configuration

To delete a configuration, construct a DELETE request via the /configurations/{id} where the ID of the configuration is specified in the URL.

DELETE /configurations/{id}

The following is a code snippet, deleting a configuration in the system.

Code snippet:

import requests
import json

URL = f"http://mdmtest.gatehousemaritime.com/api/ingress/event-detection/configurations/11"
headers = {
    "Authorization": "Basic <credentials>",
    "Content-Type": "application/json",
}

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

Response sample:

Get all Events

To get all events from the system, construct a GET request via the /s2s-events endpoint where parameters are specified in the URL.

GET /s2s-events?page=value1&size=value2&time_period=value3

value1 and value2 are integers and value3 is a time range in the following format:

[2026-05-01T00:00:00Z,2026-05-12T23:59:59Z]

The following is a code snippet, getting all events in the system.

Code snippet:

import requests
import json

URL = f"http://mdmtest.gatehousemaritime.com/api/ingress/event-detection/s2s-events?page=1&size=3&time_range=[2026-05-20T00:00:00Z,2026-05-20T00:01:00Z]"
headers = {
    "Authorization": "Basic <credentials>",
    "Content-Type": "application/json",
}

response = requests.get(URL, headers=headers, timeout=100)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))

Response sample:

{
  "items": [
    {
      "id": 212169,
      "uuid": "01f2e288-a8dd-4517-aa67-3131071bfb53",
      "created_at": "2026-05-20T00:00:08.373817Z",
      "created_by": "sts_event_generator",
      "modified_at": "2026-05-20T00:22:37.945864Z",
      "modified_by": "sts_event_generator",
      "s2s_pair": {
        "first": {
          "mmsi": 211411230,
          "activation_position": {
            "type": "Point",
            "coordinates": [
              12.583934999999999,
              54.44511277777779
            ]
          },
          "fired_position": {
            "type": "Point",
            "coordinates": [
              12.583921666666667,
              54.44511833333333
            ]
          },
          "deactivation_position": {
            "type": "Point",
            "coordinates": [
              12.583945,
              54.445125
            ]
          }
        },
        "second": {
          "mmsi": 211186920,
          "activation_position": {
            "type": "Point",
            "coordinates": [
              12.583152083333333,
              54.44512375000006
            ]
          },
          "fired_position": {
            "type": "Point",
            "coordinates": [
              12.583158333333332,
              54.44511766666683
            ]
          },
          "deactivation_position": {
            "type": "Point",
            "coordinates": [
              12.583138333333334,
              54.44513333333333
            ]
          }
        }
      },
      "mmsi_first": 211411230,
      "mmsi_second": 211186920,
      "fired_time": "2026-05-19T23:57:01.916000Z",
      "activation_time": "2026-05-19T23:37:01.916000Z",
      "deactivation_time": "2026-05-20T00:22:37.937488Z",
      "severity": "Note",
      "name": "test_configuration",
      "configuration_id": 4,
      "activation_text": "Ship with mmsi 211411230 and ship with 211186920 sailed within 200 meters for 20 minutes",
      "ack_state": "undefined",
      "ack_state_modified_ts": null,
      "ack_state_modified_by": null
    },
    {
      "id": 212170,
      "uuid": "52944d97-37fc-4f73-a8b7-7fd02b17682b",
      "created_at": "2026-05-20T00:00:51.871114Z",
      "created_by": "sts_event_generator",
      "modified_at": "2026-05-20T08:06:33.786361Z",
      "modified_by": "sts_event_generator",
      "s2s_pair": {
        "first": {
          "mmsi": 211142620,
          "activation_position": {
            "type": "Point",
            "coordinates": [
              12.728904999999997,
              54.37112583333374
            ]
          },
          "fired_position": {
            "type": "Point",
            "coordinates": [
              12.729004999999999,
              54.37108500000003
            ]
          },
          "deactivation_position": {
            "type": "Point",
            "coordinates": [
              12.728921666666666,
              54.37113166666666
            ]
          }
        },
        "second": {
          "mmsi": 211543450,
          "activation_position": {
            "type": "Point",
            "coordinates": [
              12.728824999999997,
              54.37147333333333
            ]
          },
          "fired_position": {
            "type": "Point",
            "coordinates": [
              12.728825,
              54.37147333333333
            ]
          },
          "deactivation_position": {
            "type": "Point",
            "coordinates": [
              12.728825,
              54.371473333333334
            ]
          }
        }
      },
      "mmsi_first": 211142620,
      "mmsi_second": 211543450,
      "fired_time": "2026-05-19T23:59:14.385000Z",
      "activation_time": "2026-05-19T18:59:14.385000Z",
      "deactivation_time": "2026-05-20T08:06:33.776854Z",
      "severity": "Note",
      "name": "test_configuration2",
      "configuration_id": 5,
      "activation_text": "Ship with mmsi 211142620 and ship with 211543450 sailed within 100 meters for 300 minutes",
      "ack_state": "undefined",
      "ack_state_modified_ts": null,
      "ack_state_modified_by": null
    }
  ],
  "total": 121,
  "page": 1,
  "size": 2,
  "pages": 61
}

Get all Current Events

To get all current events from the system, construct a GET request via the /s2s-events/current endpoint without a payload.

GET /s2s-event?page=value1&size=value2&configuration_id=value3

All values (value1, value2, value3) are integers.

The following is a code snippet, getting all events in the system.

Code snippet:

import requests
import json

URL = f"http://mdmtest.gatehousemaritime.com/api/ingress/event-detection/s2s-events/current?page=1&size=2&configuration_id=4"
headers = {
    "Authorization": "Basic <credentials>",
    "Content-Type": "application/json",
}

response = requests.get(URL, headers=headers, timeout=100)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))

Response sample:

{
  "items": [
    {
      "id": 202649,
      "uuid": "e11dc8bd-1e17-4163-a427-1a92d7b2ca21",
      "created_at": "2026-05-19T06:32:58.260206Z",
      "created_by": "sts_event_generator",
      "modified_at": "2026-05-19T06:32:58.260304Z",
      "modified_by": "sts_event_generator",
      "s2s_pair": {
        "first": {
          "mmsi": 219005929,
          "activation_position": {
            "type": "Point",
            "coordinates": [
              8.599285416666667,
              57.121588750000015
            ]
          },
          "fired_position": {
            "type": "Point",
            "coordinates": [
              8.599295555555555,
              57.12158500000008
            ]
          },
          "deactivation_position": null
        },
        "second": {
          "mmsi": 219004002,
          "activation_position": {
            "type": "Point",
            "coordinates": [
              8.599662222222221,
              57.121191111111145
            ]
          },
          "fired_position": {
            "type": "Point",
            "coordinates": [
              8.59968111111111,
              57.12119166666667
            ]
          },
          "deactivation_position": null
        }
      },
      "mmsi_first": 219005929,
      "mmsi_second": 219004002,
      "fired_time": "2026-05-19T06:30:35.228000Z",
      "activation_time": "2026-05-19T06:10:35.228000Z",
      "deactivation_time": null,
      "severity": "Note",
      "name": "test_configuration",
      "configuration_id": 4,
      "activation_text": "Ship with mmsi 219005929 and ship with 219004002 sailed within 200 meters for 20 minutes",
      "ack_state": "undefined",
      "ack_state_modified_ts": null,
      "ack_state_modified_by": null
    },
    {
      "id": 202704,
      "uuid": "ccdea62a-7c8f-466c-b713-85d053db95b3",
      "created_at": "2026-05-19T06:33:06.791182Z",
      "created_by": "sts_event_generator",
      "modified_at": "2026-05-19T06:33:06.791301Z",
      "modified_by": "sts_event_generator",
      "s2s_pair": {
        "first": {
          "mmsi": 219018493,
          "activation_position": {
            "type": "Point",
            "coordinates": [
              8.12968333333333,
              56.00030555555636
            ]
          },
          "fired_position": {
            "type": "Point",
            "coordinates": [
              8.129649999999998,
              56.000299999999996
            ]
          },
          "deactivation_position": null
        },
        "second": {
          "mmsi": 219002786,
          "activation_position": {
            "type": "Point",
            "coordinates": [
              8.128905,
              56.000535555555565
            ]
          },
          "fired_position": {
            "type": "Point",
            "coordinates": [
              8.128906666666667,
              56.000532500000006
            ]
          },
          "deactivation_position": null
        }
      },
      "mmsi_first": 219018493,
      "mmsi_second": 219002786,
      "fired_time": "2026-05-19T06:30:35.228000Z",
      "activation_time": "2026-05-19T06:10:35.228000Z",
      "deactivation_time": null,
      "severity": "Note",
      "name": "test_configuration",
      "configuration_id": 4,
      "activation_text": "Ship with mmsi 219018493 and ship with 219002786 sailed within 200 meters for 20 minutes",
      "ack_state": "undefined",
      "ack_state_modified_ts": null,
      "ack_state_modified_by": null
    }
  ],
  "total": 1194,
  "page": 1,
  "size": 2,
  "pages": 597
}

Search Events by MMSI

To search for events in the system, construct a GET request via the /s2s-events/search endpoint where the parameters are specified in the URL.

GET /s2s-events/search?mmsi=value1&mmsi_other=value2&configuration_id=value3&page=value4&size=value5

All values in the parameters are integer values.

The following is a code snippet, getting all events in the system.

Code snippet:

import requests
import json

URL = f"http://mdmtest.gatehousemaritime.com/api/ingress/event-detection/s2s-events/current?mmsi=219018493&mmsi_other=219002786&configuration_id=4&page=1&size=2"
headers = {
    "Authorization": "Basic <credentials>",
    "Content-Type": "application/json",
}

response = requests.get(URL, headers=headers, timeout=100)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))

Response sample:

{
  "items": [
    {
      "id": 202649,
      "uuid": "e11dc8bd-1e17-4163-a427-1a92d7b2ca21",
      "created_at": "2026-05-19T06:32:58.260206Z",
      "created_by": "sts_event_generator",
      "modified_at": "2026-05-19T06:32:58.260304Z",
      "modified_by": "sts_event_generator",
      "s2s_pair": {
        "first": {
          "mmsi": 219005929,
          "activation_position": {
            "type": "Point",
            "coordinates": [
              8.599285416666667,
              57.121588750000015
            ]
          },
          "fired_position": {
            "type": "Point",
            "coordinates": [
              8.599295555555555,
              57.12158500000008
            ]
          },
          "deactivation_position": null
        },
        "second": {
          "mmsi": 219004002,
          "activation_position": {
            "type": "Point",
            "coordinates": [
              8.599662222222221,
              57.121191111111145
            ]
          },
          "fired_position": {
            "type": "Point",
            "coordinates": [
              8.59968111111111,
              57.12119166666667
            ]
          },
          "deactivation_position": null
        }
      },
      "mmsi_first": 219005929,
      "mmsi_second": 219004002,
      "fired_time": "2026-05-19T06:30:35.228000Z",
      "activation_time": "2026-05-19T06:10:35.228000Z",
      "deactivation_time": null,
      "severity": "Note",
      "name": "test_configuration",
      "configuration_id": 4,
      "activation_text": "Ship with mmsi 219005929 and ship with 219004002 sailed within 200 meters for 20 minutes",
      "ack_state": "undefined",
      "ack_state_modified_ts": null,
      "ack_state_modified_by": null
    },
    {
      "id": 202704,
      "uuid": "ccdea62a-7c8f-466c-b713-85d053db95b3",
      "created_at": "2026-05-19T06:33:06.791182Z",
      "created_by": "sts_event_generator",
      "modified_at": "2026-05-19T06:33:06.791301Z",
      "modified_by": "sts_event_generator",
      "s2s_pair": {
        "first": {
          "mmsi": 219018493,
          "activation_position": {
            "type": "Point",
            "coordinates": [
              8.12968333333333,
              56.00030555555636
            ]
          },
          "fired_position": {
            "type": "Point",
            "coordinates": [
              8.129649999999998,
              56.000299999999996
            ]
          },
          "deactivation_position": null
        },
        "second": {
          "mmsi": 219002786,
          "activation_position": {
            "type": "Point",
            "coordinates": [
              8.128905,
              56.000535555555565
            ]
          },
          "fired_position": {
            "type": "Point",
            "coordinates": [
              8.128906666666667,
              56.000532500000006
            ]
          },
          "deactivation_position": null
        }
      },
      "mmsi_first": 219018493,
      "mmsi_second": 219002786,
      "fired_time": "2026-05-19T06:30:35.228000Z",
      "activation_time": "2026-05-19T06:10:35.228000Z",
      "deactivation_time": null,
      "severity": "Note",
      "name": "test_configuration",
      "configuration_id": 4,
      "activation_text": "Ship with mmsi 219018493 and ship with 219002786 sailed within 200 meters for 20 minutes",
      "ack_state": "undefined",
      "ack_state_modified_ts": null,
      "ack_state_modified_by": null
    }
  ],
  "total": 1193,
  "page": 1,
  "size": 2,
  "pages": 597
}

Get Event by ID

To get an event by id from the system, construct a GET request via the /s2s-events/{id} endpoint without a payload.

GET /s2s-events/{id}

The following is a code snippet, getting all events in the system.

Code snippet:

import requests
import json

URL = f"http://mdmtest.gatehousemaritime.com/api/ingress/event-detection/s2s-events/202618"
headers = {
    "Authorization": "Basic <credentials>",
    "Content-Type": "application/json",
}

response = requests.get(URL, headers=headers, timeout=100)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))

Response sample:

{
  "id": 202618,
  "uuid": "649090f7-6cd2-4876-af91-7979f17bcc4d",
  "created_at": "2026-05-19T06:32:51.088712Z",
  "created_by": "sts_event_generator",
  "modified_at": "2026-05-19T15:01:48.828178Z",
  "modified_by": "sts_event_generator",
  "s2s_pair": {
    "first": {
      "mmsi": 259447000,
      "activation_position": {
        "type": "Point",
        "coordinates": [
          8.421122777777777,
          55.478232777777826
        ]
      },
      "fired_position": {
        "type": "Point",
        "coordinates": [
          8.421095833333334,
          55.47826416666688
        ]
      },
      "deactivation_position": {
        "type": "Point",
        "coordinates": [
          8.42114,
          55.47830166666667
        ]
      }
    },
    "second": {
      "mmsi": 245204000,
      "activation_position": {
        "type": "Point",
        "coordinates": [
          8.420021666666665,
          55.47900166666677
        ]
      },
      "fired_position": {
        "type": "Point",
        "coordinates": [
          8.420061666666669,
          55.47904499999999
        ]
      },
      "deactivation_position": {
        "type": "Point",
        "coordinates": [
          8.42001,
          55.479005
        ]
      }
    }
  },
  "mmsi_first": 259447000,
  "mmsi_second": 245204000,
  "fired_time": "2026-05-19T06:30:35.228000Z",
  "activation_time": "2026-05-19T06:10:35.228000Z",
  "deactivation_time": "2026-05-19T15:01:48.821813Z",
  "severity": "Note",
  "name": "test_configuration",
  "configuration_id": 4,
  "activation_text": "Ship with mmsi 259447000 and ship with 245204000 sailed within 200 meters for 20 minutes",
  "ack_state": "undefined",
  "ack_state_modified_ts": null,
  "ack_state_modified_by": null
}

Get Tracks from Event

To the tracks from the event, construct a GET request via the /s2s-events/{id}/tracks endpoint without a payload.

GET /s2s-events/{id}/tracks

The following is a code snippet, getting all events in the system.

Code snippet:

import requests
import json

URL = f"http://mdmtest.gatehousemaritime.com/api/ingress/event-detection/s2s-events/202618/tracks"
headers = {
    "Authorization": "Basic <credentials>",
    "Content-Type": "application/json",
}

response = requests.get(URL, headers=headers, timeout=100)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))

Response sample:

[
  {
    "type": "FeatureCollection",
    "s2s_event_id": 202618,
    "mmsi": 245204000,
    "features": [
      {
        "type": "Feature",
        "geometry": {
          "type": "Point",
          "coordinates": [
            8.420021666666665,
            55.47900111111119
          ]
        },
        "properties": {
          "vertex_index": 0,
          "timestamp": "2026-05-19T06:11:00Z",
          "sog": 0.0,
          "cog": 7.0,
          "is_estimated": true
        }
      },
      {
        "type": "Feature",
        "geometry": {
          "type": "Point",
          "coordinates": [
            8.420026111111111,
            55.47899500000064
          ]
        },
        "properties": {
          "vertex_index": 1,
          "timestamp": "2026-05-19T06:13:00Z",
          "sog": 0.0,
          "cog": 7.0,
          "is_estimated": true
        }
      },
      ...
    ],
    ...
  }
]

Acknowledge Event

To acknowledge an event in the system, construct a POST request via the /s2s-events/{id}/ack endpoint without a payload.

GET /s2s-events/{id}/ack

The following is a code snippet, getting all events in the system.

Code snippet:

import requests
import json

URL = f"http://mdmtest.gatehousemaritime.com/api/ingress/event-detection/s2s-events/202618/ack"
headers = {
    "Authorization": "Basic <credentials>",
    "Content-Type": "application/json",
}

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

Response sample:

{
  "id": 202618,
  "uuid": "649090f7-6cd2-4876-af91-7979f17bcc4d",
  "created_at": "2026-05-19T06:32:51.088712Z",
  "created_by": "sts_event_generator",
  "modified_at": "2026-05-29T13:13:31.016373Z",
  "modified_by": "user",
  "s2s_pair": {
    "first": {
      "mmsi": 259447000,
      "activation_position": {
        "type": "Point",
        "coordinates": [
          8.421122777777777,
          55.478232777777826
        ]
      },
      "fired_position": {
        "type": "Point",
        "coordinates": [
          8.421095833333334,
          55.47826416666688
        ]
      },
      "deactivation_position": {
        "type": "Point",
        "coordinates": [
          8.42114,
          55.47830166666667
        ]
      }
    },
    "second": {
      "mmsi": 245204000,
      "activation_position": {
        "type": "Point",
        "coordinates": [
          8.420021666666665,
          55.47900166666677
        ]
      },
      "fired_position": {
        "type": "Point",
        "coordinates": [
          8.420061666666669,
          55.47904499999999
        ]
      },
      "deactivation_position": {
        "type": "Point",
        "coordinates": [
          8.42001,
          55.479005
        ]
      }
    }
  },
  "mmsi_first": 259447000,
  "mmsi_second": 245204000,
  "fired_time": "2026-05-19T06:30:35.228000Z",
  "activation_time": "2026-05-19T06:10:35.228000Z",
  "deactivation_time": "2026-05-19T15:01:48.821813Z",
  "severity": "Note",
  "name": "test_configuration",
  "configuration_id": 4,
  "activation_text": "Ship with mmsi 259447000 and ship with 245204000 sailed within 200 meters for 20 minutes",
  "ack_state": "acknowledged",
  "ack_state_modified_ts": "2026-05-29T13:13:31.011026Z",
  "ack_state_modified_by": "user"
}

Updated on 29 May, 2026

AtoN

I want to

Customer Stories

Maritime Domain Awareness

Ship-to-Ship

List of parameters in the configurations:

List of Ship-to-Ship events parameters:

Create an STS Detector Configuration

Code Example:

Response Sample:

Get single Detector Configuration

Code snippet:

Response sample:

Get all Detector Configurations

Update Detector Configuration

Code snippet:

Response sample:

Delete Detector Configuration

Code snippet:

Response sample:

Get all Events

Code snippet:

Response sample:

Get all Current Events

Code snippet:

Response sample:

Search Events by MMSI

Code snippet:

Response sample:

Get Event by ID

Code snippet:

Response sample:

Get Tracks from Event

Code snippet:

Response sample:

Acknowledge Event

Code snippet:

Response sample: