Zone Analytics: Worked Examples

Five questions a compliance, underwriting or authority team asks about an area, each answered with one call.

Every window is historical on purpose. Reuse the shape, not the dates. All five use the same zone UUID; swap in your own from Zone Insights.

Weekly crossings of an emission control area

Question: how did traffic through the North Sea NOx ECA move week by week?

group_by=NONE with a period aggregation is the line chart shape: one point per week, each holding a single combined count.

{
  "zone_information": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "North Sea (NOx)",
    "zone_type": "Emission Control Areas (ECA)",
    "zone_sub_type": "NOX",
    "country_common_name": null
  },
  "totals": {
    "entries": 3812,
    "exits": 3795,
    "vessels_per_day": 54,
    "max_vessels_per_day": 102
  },
  "data": [
    {
      "period_key": "2026-01-11",
      "items": [{ "entries": 271, "exits": 269, "group_by_key": "none" }]
    },
    {
      "period_key": "2026-01-18",
      "items": [{ "entries": 364, "exits": 359, "group_by_key": "none" }]
    }
  ]
}

Entries and exits rarely match over a fixed window, and that is correct rather than a rounding problem: vessels inside the zone when the window opened will exit without a matching entry, and the reverse at the other end.

Who transits a war risk area

Question: which vessel types transited this JWC listed area, quarter by quarter?

Each period now carries one item per vessel type, which is the stacked bar shape:

{
  "period_key": "2026-03-31",
  "items": [
    { "entries": 812, "exits": 804, "group_by_key": "Oil Tanker" },
    { "entries": 447, "exits": 441, "group_by_key": "Bulk Carrier" },
    { "entries": 96, "exits": 94, "group_by_key": "Passenger" }
  ]
}

A type with nothing in a quarter is left out of that quarter rather than returned as zero. Build your series from the union of group_by_key values across the whole response.

Underwriting work usually wants this call with period_aggregation=MONTHLY and a rolling twelve month window, so exposure is readable against the month a policy was written.

The overall composition

Question: across the year, what share of crossings did each vessel type account for?

period_aggregation=NONE collapses the range to a single data point with one item per type.

Zones count all 16 vessel type categories, so this distribution includes passenger vessels, tugs, fishing and offshore support. Port Analytics covers 11 commercial types only, so the same question asked of a port returns a narrower picture.

Monitoring one flag state

Question: how much of the traffic through this zone was Russian flagged, month by month?

Filtering with flag_codes and grouping by NONE returns a single clean series for that flag, and totals describes it alone rather than the whole zone. Run the same call without the filter to get the denominator.

Repeat the parameter for several flags rather than passing a comma-separated list. Codes are ISO 3166-1 alpha-3.

Tankers of a given class

Question: how many VLCC movements crossed this zone, and which were the busiest vessels?

Filters combine as an AND, so this is oil tankers that are also VLCC class. Names are case sensitive: Oil Tanker works, oil tanker does not.

top_visitors is where a distribution turns into a list of hulls to look at:

{
  "top_visitors": [
    {
      "vessel_name": "FRONT ALTAIR",
      "imo_number": "9256793",
      "flag_code": "MHL",
      "flag_name": "Marshall Islands",
      "ship_type_level_3": "Oil Tanker",
      "vessel_class": "VLCC",
      "visit_count": 19
    }
  ]
}

It returns ten entries by default and up to 50, busiest first. Pass top_visitors_sort=ASC for the other end of the list, which is how you find the vessels that crossed once.

Go from the count to the crossing

These are counts. When one stands out, Call GET /zone-port-insights/v1/zone-and-port-traffic/{id_type}/{id} for the same zone, then find the ZONE_ENTRY and ZONE_EXIT events for that IMO in the returned list, with timestamps and positions. The analytics endpoint tells you where to look; the traffic endpoint tells you what happened.

Zone Analytics

The parameters, the response shape and the coverage rules behind these calls.

Zone Insights

The zone search that gives you an identifier, and the events these counts aggregate.

Custom Zones

Draw your own area, then run every call on this page against it.

Weekly crossings of an emission control area#

Who transits a war risk area#

The overall composition#

Monitoring one flag state#

Tankers of a given class#

Related#

Weekly crossings of an emission control area

Who transits a war risk area

The overall composition

Monitoring one flag state

Tankers of a given class

Related