Zone screening and fleet monitoring API

Continuous monitoring, not one-off lookups. Watch an area, watch a group of vessels, and be told when something crosses a line you care about.

The other Insights categories answer a question when you ask it. This one keeps answering after you have asked once.

When to use it

You want to	Start at
Find the area you care about	Zone Insights
Define an area that does not exist yet	Custom Zones
See what is in that area, or what has passed through it	Zone Insights
Group vessels once and query them everywhere	Fleet Management
See what a fleet is made of, or what has happened across it recently	Fleet Management
Be told when a vessel enters, leaves or behaves unusually	Zone Notifications
Count how many vessels crossed it over a period, not which ones	Zone Analytics

What is in it

Zone Insights

Search zones, read one zone, list the vessels currently inside it, and get entry and exit traffic over a time range.

Custom Zones

Define your own area of interest as a circle or a polygon, then query and subscribe to it exactly like a published zone.

Fleet Management

Create fleets, add and remove vessels, and read a fleet's membership, composition and recent events. Define the group once and reuse it across queries and subscriptions.

Zone Analytics

Entry and exit counts for a zone over a period, bucketed by time and grouped by vessel type.

Custom zones

When no published area matches what you care about, define your own: a stretch of coastline, an approach corridor, a patch of water you monitor for your own reasons.

A custom zone is a circle or a polygon, created once and then usable anywhere an area identifier is accepted: queries, traffic, notifications. It is a geometry, not a place, so there is no way to define a custom port. That is why custom zones belong to this package and not to Zones & Ports.

A circle takes a centre and a radius, between 100 metres and 1,000 kilometres. A polygon takes WKT or GeoJSON. We reject the same geometry created twice under one account instead of duplicating it, and each account has a limit on how many custom zones it can hold.

A custom zone plus a fleet is the core screening pattern

Define the area, define the group of vessels, subscribe the group to the area. Add a vessel to the fleet later and it is covered without touching the subscription. Most compliance workflows reduce to those three steps.

Why fleets matter here

A fleet is a named group of vessels. Its value is that everything else accepts it: subscribe a fleet to zone events once and every vessel in it is covered, including vessels you add later. Without fleets you are managing a subscription per hull and reconciling them by hand.

Fleets live under /fleet-management/v2/fleets. Create one with its vessels in a single call, then pass its identifier wherever an endpoint would otherwise take a single IMO. Fleet Management covers these operations.

Paths you will call

https://api.polestar-production.com/zone-port-insights/v1/zones
https://api.polestar-production.com/zone-port-insights/v1/zones/{id}
https://api.polestar-production.com/zone-port-insights/v1/vessels-in-zone-or-port/{id_type}/{id}
https://api.polestar-production.com/zone-port-insights/v1/zone-and-port-traffic/{id_type}/{id}
https://api.polestar-production.com/zone-port-insights/v1/zones/custom
https://api.polestar-production.com/fleet-management/v2/fleets
https://api.polestar-production.com/maritime-analytics/v1/analytics/zones/{id_type}/{id}/entries-exits

The zone reads and custom zones carry the /zone-port-insights/ prefix because that is the service that answers them, and zone analytics sits behind /maritime-analytics for the same reason. The prefix says which service serves an endpoint, not which package it belongs to. On the reads, a zone is identified by ID or UNLOCODE, followed by its value.

A first call

List zones, then list your fleets.

Define the area before you define the alert

Zone identifiers are the input to almost everything else here, including notifications. Find or create the zone first, confirm it covers what you expect with vessels-in-zone-or-port, then subscribe. Debugging a silent subscription is harder than checking a zone.

Two parts of this package are documented elsewhere

The shared Zones & Ports section holds the endpoints that answer for zones and ports alike. They are part of this package, and their endpoint reference lives in that section alone, not under Domain & Fleet:

The zone reads: search zones (GET /zone-port-insights/v1/zones), read one zone (/zones/{id}), list the vessels inside a zone (vessels-in-zone-or-port), and get its entries and exits (zone-and-port-traffic)

Zone notifications: subscriptions to entries and exits, documented in Zone & Port Notifications

Zone Insights walks through the zone reads from the zone side.

Custom zones sit under /zone-port-insights/v1/ as well, but only this package can define an area, so their reference stays in this section.

Choosing Zone Endpoints is the Domain & Fleet reader's route through both.

Traffic events and analytics are different endpoints

zone-and-port-traffic returns the underlying entry and exit events, one row per crossing. Zone Analytics returns aggregates over them. If you want counts and distributions rather than the crossings themselves, you want the analytics endpoint.

Zones & Ports

The zone reads and zone notifications, shared with Port & Trade.

Zone & Port Types

Every zone type and sub-type, and how to filter by them.

Notifications & Webhooks

Fleet and zone subscriptions, and how they are delivered.

Domain & Fleet

When to use it#

What is in it#

Custom zones#

Why fleets matter here#

Paths you will call#

A first call#

Two parts of this package are documented elsewhere#

Related#