Threat Zones

Threat zones are geofenced maritime areas monitored by Turqoa for vessel incursions, anomalous behavior, and policy violations. Each zone has its own geometry, alert rules, and response configuration.

Creating Threat Zones

Threat zones can be created through the Command Center UI or the API. Each zone requires a geometry, type, and alert configuration.

Via API

curl -X POST https://api.turqoa.com/v1/maritime/zones \
  -H "Authorization: Bearer $TURQOA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "LNG Terminal Exclusion Zone",
    "type": "exclusion",
    "geometry": {
      "type": "Polygon",
      "coordinates": [
        [
          [-0.0520, 51.4810],
          [-0.0420, 51.4810],
          [-0.0420, 51.4870],
          [-0.0520, 51.4870],
          [-0.0520, 51.4810]
        ]
      ]
    },
    "alert_level": "critical",
    "active": true,
    "schedule": {
      "always_on": true
    }
  }'

Via Configuration File

threat_zones:
  - name: LNG Terminal Exclusion Zone
    type: exclusion
    geometry:
      type: Polygon
      coordinates:
        - [[-0.0520, 51.4810], [-0.0420, 51.4810], [-0.0420, 51.4870], [-0.0520, 51.4870], [-0.0520, 51.4810]]
    alert_level: critical
    active: true
    schedule:
      always_on: true

  - name: Cargo Berth Restricted Area
    type: restricted
    geometry:
      type: Polygon
      coordinates:
        - [[-0.0600, 51.4750], [-0.0500, 51.4750], [-0.0500, 51.4800], [-0.0600, 51.4800], [-0.0600, 51.4750]]
    alert_level: high
    active: true
    authorized_vessels:
      - mmsi_list: [123456789, 987654321]
      - vessel_types: [pilot, tug, port_authority]
    schedule:
      days: [mon, tue, wed, thu, fri]
      hours: "06:00-22:00"
      timezone: Europe/London

Geofence Configuration

Supported Geometry Types

Type	Use Case	Definition
Polygon	Irregular zones (berths, terminals)	Array of coordinate pairs forming a closed ring
Circle	Radar coverage areas, anchorages	Center point + radius in meters
MultiPolygon	Complex zones with disconnected areas	Array of polygons
Corridor	Shipping lanes, approach channels	Centerline + width in meters

Polygon Zone

{
  "geometry": {
    "type": "Polygon",
    "coordinates": [
      [
        [-0.0520, 51.4810],
        [-0.0420, 51.4810],
        [-0.0420, 51.4870],
        [-0.0520, 51.4870],
        [-0.0520, 51.4810]
      ]
    ]
  }
}

Circle Zone

{
  "geometry": {
    "type": "Circle",
    "center": [-0.0470, 51.4840],
    "radius_meters": 500
  }
}

Corridor Zone

{
  "geometry": {
    "type": "Corridor",
    "centerline": [
      [-0.0800, 51.4700],
      [-0.0600, 51.4750],
      [-0.0400, 51.4800]
    ],
    "width_meters": 200
  }
}

Buffer Zones

Every threat zone supports an optional buffer that generates a pre-alert when a vessel approaches:

buffer:
  enabled: true
  distance_meters: 200
  alert_level: medium
  message: "Vessel approaching exclusion zone"

Alert Levels

Each zone is assigned an alert level that determines the default response behavior:

Alert Level	Operator Notification	Drone Dispatch	Escalation	Logging
Info	No	No	No	Yes
Low	Dashboard only	No	No	Yes
Medium	Push notification	Optional	No	Yes
High	Push + audio alarm	Automatic	Supervisor	Yes
Critical	All channels	Immediate	All stakeholders	Yes

Custom Alert Rules

Override default behavior per zone:

alert_rules:
  - zone: LNG Terminal Exclusion Zone
    on_entry:
      alert_level: critical
      actions:
        - notify_operator
        - dispatch_drone: alarm_verification
        - escalate_to: [security_manager, port_authority]
        - lock_gates: [gate_3, gate_4]
    on_dwell:
      threshold_minutes: 5
      alert_level: critical
      actions:
        - notify_operator
        - escalate_to: [coast_guard]
    on_exit:
      alert_level: info
      actions:
        - log_event
        - close_incident

Dwell Time Analysis

Dwell time tracking identifies vessels that linger in or near sensitive areas longer than expected. The system continuously monitors vessel positions against zone boundaries.

How It Works

When a vessel enters a zone, a dwell timer starts
If the vessel remains in the zone beyond the configured threshold, an alert fires
Dwell time is recalculated every AIS update (typically every 2--10 seconds)
If the vessel exits and re-enters within a configurable reset window, the previous dwell time carries over

Configuration

dwell_time:
  enabled: true
  thresholds:
    - zone_type: exclusion
      max_dwell_minutes: 0  # immediate alert on entry
    - zone_type: restricted
      max_dwell_minutes: 15
    - zone_type: monitoring
      max_dwell_minutes: 60
    - zone_type: anchorage
      max_dwell_minutes: 1440  # 24 hours

  reset_window_minutes: 30  # re-entry within 30 min continues the timer
  
  escalation:
    - after_minutes: 15
      action: notify_supervisor
    - after_minutes: 30
      action: escalate_to_port_authority
    - after_minutes: 60
      action: escalate_to_coast_guard

Dwell Time API

Query current dwell times for all vessels in a zone:

curl https://api.turqoa.com/v1/maritime/zones/zone_abc123/dwell \
  -H "Authorization: Bearer $TURQOA_API_KEY"

{
  "zone_id": "zone_abc123",
  "zone_name": "Cargo Berth Restricted Area",
  "vessels": [
    {
      "mmsi": 123456789,
      "vessel_name": "MV Nordic Star",
      "entered_at": "2026-04-06T08:15:00Z",
      "dwell_minutes": 42,
      "authorized": true,
      "alert_status": "none"
    },
    {
      "mmsi": 555123456,
      "vessel_name": "Unknown",
      "entered_at": "2026-04-06T09:30:00Z",
      "dwell_minutes": 7,
      "authorized": false,
      "alert_status": "active"
    }
  ]
}

Zone Monitoring Rules

Beyond entry/exit and dwell time, zones support advanced monitoring rules:

Speed Rules

Alert when a vessel exceeds or drops below speed thresholds within a zone:

speed_rules:
  - zone: Approach Channel
    max_speed_knots: 8
    min_speed_knots: 2
    alert_on_violation: true
    alert_level: high

AIS Integrity Rules

Alert when vessels exhibit suspicious AIS behavior inside a zone:

ais_rules:
  - zone: LNG Terminal Exclusion Zone
    alert_on:
      - ais_loss_seconds: 120     # AIS signal lost for 2+ minutes
      - position_jump_nm: 0.5     # Position jumps more than 0.5 NM
      - heading_speed_mismatch: true  # Heading doesn't match COG/SOG
    alert_level: critical

Vessel Type Rules

Restrict which vessel types may enter a zone:

vessel_type_rules:
  - zone: Passenger Terminal
    allowed_types: [passenger, tug, pilot]
    denied_types: [tanker, cargo]
    alert_on_denied_entry: true
    alert_level: high

Time-Based Rules

Activate different rules based on time of day or day of week:

time_rules:
  - zone: Container Terminal
    schedules:
      - name: business_hours
        days: [mon, tue, wed, thu, fri]
        hours: "07:00-19:00"
        max_vessels: 5
        alert_level: medium
      - name: after_hours
        days: [mon, tue, wed, thu, fri]
        hours: "19:00-07:00"
        max_vessels: 1
        alert_level: high
      - name: weekend
        days: [sat, sun]
        max_vessels: 0
        alert_level: critical