Create custom maritime zones by API

Draw your own area and it behaves like any other zone. Two endpoints, one to create and one to edit.

Custom zones are a Domain & Fleet capability. There is no custom port. The geometry you supply becomes a zone, and port-shaped questions stay with Port Insights.

The two endpoints

Endpoint	Does
`POST /zone-port-insights/v1/zones/custom`	Create a circular or polygon zone
`PUT /zone-port-insights/v1/zones/custom/{id}`	Edit one

Both keep the /zone-port-insights/ prefix because that is the service that answers them. Once created, you read a custom zone through the ordinary zone endpoints. GET /zone-port-insights/v1/zones/{id} returns its full definition including the geometry you supplied.

Two geometries

custom_type selects which shape the request carries, and the service reads only the matching detail object. Declaring one type and supplying the other is rejected.

Circle

Polygon

{
  "account_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "name": "Approaches: eastern anchorage",
  "description": "Watch area east of the anchorage boundary",
  "custom_type": "CIRCULAR",
  "circle_details": {
    "latitude": 51.949200,
    "longitude": 4.139600,
    "radius": 5000
  }
}

Latitude within [-90, 90], longitude within [-180, 180], each with 4 to 6 decimal places. Radius is in metres and must be between 100 m and 1000 km.

name is required, 1 to 100 characters. description is optional, but when supplied must be 5 to 150 characters, so a one-word description fails where omitting it entirely succeeds.

What a polygon has to satisfy

Four rules, each with its own rejection:

Closed. The last vertex must repeat the first

No self-intersections. The outline may not cross itself

Within the area bound. There is a maximum size

At least 50 m between adjacent vertices. A detailed coastline with closely spaced vertices will trip this.

The last one catches people out most. Geometry exported from a mapping tool often carries far more vertices than the area needs; thin it before sending.

Editing

PUT takes the same body as POST, with two things you cannot change:

account_id is fixed. A custom zone stays with the account that created it.

custom_type is fixed. A circle cannot become a polygon. Create a new zone with the correct custom_type; the old one remains until you have migrated off it.

An id that is not a custom zone is rejected with 400. You cannot edit a jurisdictional or system zone through this endpoint.

PUT returns 200, not 201. POST returns 201.

When a call is rejected

Response	Usually means
`400`	The geometry failed validation, the declared `custom_type` has no matching detail object, or the id is not a custom zone
`403`	The account is not yours, or the zone is outside your entitlement
`404`	No such custom zone (`PUT` only)
`409`	A zone with the same details already exists under that account
`422`	A field is outside its accepted range: name length, description length, radius, decimal places

The 409 is worth designing around. It matches on the details, not the name, so creating the same circle twice under different names is a conflict and not two zones. If you are generating zones programmatically, treat 409 as "already have it" and not as a failure.

Once it exists

A custom zone is an ordinary zone from then on. It appears in GET /zone-port-insights/v1/zones, resolves through GET /zone-port-insights/v1/zones/{id} with its geometry attached, answers vessels-in-zone-or-port and zone-and-port-traffic with id and its UUID, and can be named in a zone notification subscription by its id.

Draw the area, then confirm it before subscribing

Call vessels-in-zone-or-port on a new custom zone before you build anything on top of it. It is the cheapest way to see whether the geometry covers what you intended. A 200 with an empty vessel list still confirms the zone is real and visible to you.

Zone Insights

Reading a custom zone back, and who is inside it.

Zone & Port Notifications

Subscribing to entries and exits on the zone you drew.

Zone & Port Types

Where custom zones sit in the wider taxonomy.

Custom Zones

The two endpoints#

Two geometries#

What a polygon has to satisfy#

Editing#

When a call is rejected#

Once it exists#