Zone and port event notification API

Subscribe to a place instead of a ship. A subscription names the zones or ports you care about and pushes an event whenever any vessel enters or leaves one.

This is the area-shaped counterpart to Vessel Notifications, and the two are configured differently enough that reading across from one to the other will catch you out.

How this differs from vessel notifications

Both live under /notifications/v1/, both use the same envelope, and both deliver the same three ways. The filter object is where they part company.

	Vessel subscriptions	Zone & port subscriptions
Path	`/notifications/v1/vessels`	`/notifications/v1/zones-and-ports`
`filters` shape	Nested. One key per event type, each with its own `active` flag and options	Flat. One object with `event_types`, `vessels`, `zones_ports` and `flag_codes`
Scoped by	A single `imo`, or a `fleet_id`	A list of zone and port IDs, optionally narrowed to particular vessels
Turning an event type on	`"zones": { "active": true, ... }`	Adding it to the `event_types` array

There is no per-event-type active flag here

On a vessel subscription each event type carries its own active switch. On a zone and port subscription the event types are entries in one event_types array: adding an entry enables it, removing it disables it. Sending the nested vessel-style shape here will not do what you expect.

Event types

Ten event types, named in event_types:

Event	Fires when
`ZONE_ENTRY`, `ZONE_EXIT`	A vessel enters or leaves a watched zone
`PORT_AREA_ARRIVAL`, `PORT_AREA_DEPARTURE`	A vessel crosses the boundary of a watched port
`PORT_ARRIVAL`, `PORT_DEPARTURE`	A vessel stops inside a watched port, or starts moving again
`BERTH_ARRIVAL`, `BERTH_DEPARTURE`	A vessel arrives at or leaves a berth in a watched port
`NEW_INBOUND`	A vessel reports a watched port as its destination for the first time on a voyage
`ETA_CHANGE`	A vessel inbound to a watched port changes its reported ETA

Berth events fire for ports only, never for other zone types such as an EEZ. A berth notification also tells you which berth it was.

NEW_INBOUND fires once per voyage. Later AIS messages that repeat the same destination do not raise it again, so pair it with ETA_CHANGE to follow an inbound vessel until it arrives. Both come from what the vessel reports about itself, not from what we observed, so they will not always end in an arrival.

The filter object

Four keys, all optional, and they narrow in combination:

Key	Takes	Effect when omitted
`event_types`	Event names from the table above	All supported event types
`zones_ports`	Zone and port IDs, as UUIDs	All areas available to you
`vessels`	IMO numbers, scoping the subscription to particular ships	Every vessel
`flag_codes`	An object with `incl` and `excl` arrays of ISO 3166-1 alpha-3 codes	No flag-state filtering

flag_codes is the one to note. It is an object, not an array, and it holds both directions:

"flag_codes": { "incl": ["ZMB", "MUS"], "excl": [] }

Zone and port IDs come from the search endpoint described on Zone & Port Search.

Screening enrichment

settings.vessel_screening is optional and adds a compliance dimension to an area subscription:

"vessel_screening": {
  "active": true,
  "severity_filter": ["HIGH"]
}

With it switched on, notifications carry screening information about the vessel that triggered them, and severity_filter restricts which severities generate a notification at all. Use it to narrow a busy terminal subscription down to the arrivals that warrant a look.

Three ways to receive events

Webhook: push, immediate

Set notification_callback_url on the subscription. We POST each notification to that URL as JSON the moment it is generated. This is the route for system-to-system integration, and the one to prefer where you can accept an inbound request.

Email: immediate or batched

Pull: you ask

Webhook and email are not exclusive. Setting both delivers immediately to your system and batches a human-readable copy to the people who need to review it.

Managing subscriptions

Call	Does
`GET /notifications/v1/zones-and-ports`	Lists your subscriptions. `active` shows only live or only paused ones; `limit` and `offset` page
`GET /notifications/v1/zones-and-ports/{id}`	Returns one
`PUT /notifications/v1/zones-and-ports/{id}`	Replaces the configuration. Send the complete `settings` object, not just the part you are changing
`DELETE /notifications/v1/zones-and-ports/{id}`	Removes it permanently

To pause instead of deleting, send the subscription back with "active": false. It stops generating notifications and keeps its filters, so you can switch it on again unchanged.

Changes take effect immediately and are not applied retrospectively. Notifications already generated are unaffected by a filter change.

Zone & Port Notifications: Worked Examples

A terminal watch, a flag-filtered subscription and reading events back.

Notifications & Webhooks

Endpoint requirements, delivery behaviour and retry handling.

Zone & Port Types

The vocabulary behind the areas you can subscribe to.

Zone & Port Notifications

How this differs from vessel notifications#

Event types#

The filter object#

Screening enrichment#

Three ways to receive events#

Managing subscriptions#

Related#