Choosing the right port endpoints

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

Two families live there, and you will use both:

	What it does	Where it is documented for ports
Zone & Port Insights	The reads: search ports, read one, list what is inside it, get arrival and departure traffic	Zone & Port Insights
Zone & Port Notifications	Subscriptions: be told when a vessel or fleet arrives at or leaves a port	Zone & Port Notifications

Reading ports through the shared endpoints

The four reads under /zone-port-insights/v1/ take a port identifier as readily as a zone one. For a port, {id_type} is unlocode with the port's UN/LOCODE, or id with its UUID:

unlocode is the shortcut: if your data already carries a UN/LOCODE, you can skip the search. Port Insights walks through all four reads from the port side.

Notifications

You create port 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 port identifier and either a vessel or a fleet. A port subscription can carry berth events as well as arrivals and departures, and berth events fire for ports only.

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

Getting a port identifier

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

Search for the port

Narrow by name or UN/LOCODE instead of paging the whole list. The search returns zones as well as ports, so a name alone can match both.

Take the identifier from the response

Each result carries the identifier the other endpoints expect, along with the port's type and sub-type.

Check it before you build on it

Call vessels-in-zone-or-port with it and confirm the result is the port you meant. A subscription against the wrong identifier is silent: no error and no events.

Zone & Port Types lists every port type and sub-type. A port is an area with a port type, which is why one endpoint family answers for ports and zones alike.

Aggregated counts are a separate endpoint

The reads return one row per vessel or per movement. Port Analytics returns counts of those movements bucketed over time, plus berth dwell statistics. It is a separate endpoint on a separate service, and part of Port & Trade.

Port-only endpoints

Inbound vessels and berth traffic are Port & Trade endpoints, not shared ones, and they are documented on Port Insights.

Both carry the /zone-port-insights/ prefix all the same. The prefix says which service serves an endpoint, not which package owns it.

Custom zones are not part of Port & Trade. A custom zone is a circle or a polygon, never a port, so defining your own area is a Domain & Fleet capability and is documented there.

Port & Trade

The rest of the package: port reads, inbound vessels, berth traffic and Port Analytics.

Zones & Ports

The section these endpoints live in.

Zone & Port Types

The taxonomy behind port search and filtering.

Choosing Port Endpoints

Reading ports through the shared endpoints#

Notifications#

Getting a port identifier#

Aggregated counts are a separate endpoint#

Port-only endpoints#

Related#

Reading ports through the shared endpoints

Notifications

Getting a port identifier

Aggregated counts are a separate endpoint

Port-only endpoints

Related