Choosing the right zone endpoints

Part of Domain & Fleet is documented in Zones & Ports, because those endpoints answer for zones and ports from the same path.

Two families live there, and you will use both:

	What it does	Where it is documented for zones
Zone & Port Insights	The reads: search areas, read one, list what is inside it, get entry and exit traffic	Zone & Port Insights
Zone & Port Notifications	Subscriptions: be told when a vessel or fleet enters or leaves an area	Zone & Port Notifications

Reading zones through the shared endpoints

The four reads under /zone-port-insights/v1/ take a zone identifier as readily as a port one. For a zone, {id_type} is always id and {id} is the zone's UUID:

unlocode names a port, so it is never a zone route. Zone Insights walks through all four reads from the zone side.

Notifications

You create zone subscriptions through the zone-and-port notification endpoints. They are shared because the subscription model does not change with the kind of area: pass an identifier, choose a delivery method, and events arrive as they happen.

Pass the zone identifier and either a vessel or a fleet. Subscribing a fleet is what saves you work later: add a vessel to the fleet and it is covered without touching the subscription.

Notifications & Webhooks covers the delivery methods and the event types you can subscribe to.

Getting a zone identifier

Both the reads and the notification endpoints are keyed by an area identifier, so this is step one either way.

Search for the zone

The search returns zones and ports together, so filter by type and sub-type to narrow to a class of area, such as an emission control area, a war risk zone or a territorial sea, instead of paging everything.

Confirm it covers what you mean

Read the zone and check its extent, then call vessels-in-zone-or-port and see whether the result matches your expectation.

Subscribe once you trust the identifier

A subscription against the wrong zone is silent: no error and no events. Checking the zone first is cheaper than debugging the silence.

Zone & Port Types lists every type and sub-type, and how they combine as filters.

Aggregated counts are a separate endpoint

The reads return one row per vessel or per crossing. Zone Analytics returns counts of those crossings bucketed over time. It is a separate endpoint on a separate service, and part of Domain & Fleet.

Custom zones are not here

Defining your own area is a Domain & Fleet capability, not a shared one, and it is documented on the Domain & Fleet overview.

A custom zone is a circle or a polygon: a geometry, not a place. The API has no way to define a custom port, so custom zones belong to this package even though their path carries the /zone-port-insights/ prefix. The prefix says which service serves an endpoint, not which package owns it.

Domain & Fleet

The rest of the package: zone reads, custom zones and Fleet Management.

Zones & Ports

The section these endpoints live in.

Zone & Port Types

The taxonomy behind zone search and filtering.

Choosing Zone Endpoints

Reading zones through the shared endpoints#

Notifications#

Getting a zone identifier#

Aggregated counts are a separate endpoint#

Custom zones are not here#

Related#

Reading zones through the shared endpoints

Notifications

Getting a zone identifier

Aggregated counts are a separate endpoint

Custom zones are not here

Related