Zone API: definitions, occupancy, traffic

Four endpoints for working with areas: find a zone, read its definition, see who is inside it now, and read its entry and exit history.

A zone is any monitored area: a jurisdictional boundary, a war risk area, an emission control area, or one you drew yourself.

The four endpoints

Endpoint	Answers
`GET /zone-port-insights/v1/zones`	Which zones can I see?
`GET /zone-port-insights/v1/zones/{id}`	What exactly does this zone cover?
`GET /zone-port-insights/v1/vessels-in-zone-or-port/{id_type}/{id}`	Who is inside right now?
`GET /zone-port-insights/v1/zone-and-port-traffic/{id_type}/{id}`	Who crossed the boundary over this period?

The same four serve ports, which is why they are documented in the shared Zones & Ports section. The identifier you pass decides whether you get a zone answer or a port answer. For a zone, that identifier is always its internal UUID: {id_type} is ID. UNLOCODE is the port spelling and has no zone equivalent.

Finding a zone

The search returns zones and ports in one list, so filter by type to keep to the areas you mean. types and sub_type are both repeatable, combine with AND, and are validated against the taxonomy on Zone & Port Types. name_contains adds a case-insensitive substring match on the name.

Filtering by type instead of by id is usually the better instinct. "Every war risk area" stays correct as the list changes; a hard-coded set of ids does not.

Reading a definition

GET /zone-port-insights/v1/zones/{id} takes the zone UUID and returns its full definition. If the zone is a custom zone owned by your account, the response also carries its custom detail: the geometry you supplied when you created it. A custom zone owned by another account returns 403.

An out-of-scope zone returns 403, not 404

We check access against the zone ids your account is entitled to, and an id outside them comes back as 403. The two mean different things: 404 is no such zone, 403 is a zone that exists and your subscription does not cover.

A 403 tells you the identifier is real, so the fix is commercial and not a bug hunt in your code.

Who is inside now

Returns the vessels inside the boundary at the moment of the call. Each one carries when it entered, the position it entered at, and its latest known position. zone_port_information describes the zone itself. Paging is the only filter, so narrow by speed or status on your side.

Entries and exits over a window

zone-and-port-traffic returns ZONE_ENTRY and ZONE_EXIT events for one zone across a time range:

timestamp_start is required: UTC, yyyy-MM-ddTHH:mm:ss, optional trailing Z, never in the future. timestamp_end defaults to the time of the request, and we treat a value in the future as the current time. event_type is optional and repeatable.

The endpoint accepts zone events and port events, because it answers for both kinds of area. The berth events belong to Port Insights, and we reject a request for one of those with a 422 instead of returning nothing.

An empty event list is still a useful response. zone_port_information is populated whenever the id names a zone you may see, whether or not anything crossed its boundary. An empty result confirms the zone is real, visible to you, and quiet over that window.

Two ways to ask the same question

vessels-in-zone-or-port and zone-and-port-traffic look similar and are not.

	Returns	Use when
`vessels-in-zone-or-port`	A snapshot: who is inside now	You want current state: occupancy, congestion, who to contact
`zone-and-port-traffic`	A history: who crossed the boundary, and when	You want change over time: throughput, dwell, a compliance timeline

A vessel that entered and left inside your window appears twice in zone-and-port-traffic and not at all in vessels-in-zone-or-port.

Zone Analytics is the third way to ask it: the same crossings returned as counts bucketed over time, not as events. Reach for it when you would otherwise pull every crossing and count them yourself.

Subscribe instead of polling

Calling zone-and-port-traffic on a schedule to spot new crossings is the pattern Zone & Port Notifications replaces. One subscription covers entries and exits for a set of zones, with flag filters and optional screening, delivered by webhook or digest.

Paging

limit defaults to 100 and accepts 1 to 500; offset defaults to 0. That holds on the search, vessels-in-zone-or-port and zone-and-port-traffic. See Pagination & Filtering.

Custom Zones

Drawing your own area and monitoring it like any other zone.

Choosing Zone Endpoints

Getting a zone identifier, and subscribing to the zone once you have one.

Zone & Port Types

The type and sub-type vocabulary the filters expect.

Zone Insights

The four endpoints#

Finding a zone#

Reading a definition#

Who is inside now#

Entries and exits over a window#

Two ways to ask the same question#

Paging#

Related#

The four endpoints

Finding a zone

Reading a definition

Who is inside now

Entries and exits over a window

Two ways to ask the same question

Paging

Related