Port Analytics: Worked Examples

Eight questions a port operations or commercial team asks, each answered with one call. Five cover traffic volume, three cover berths.

Every window ends on T-1 (up to yesterday's date), so the numbers are final. Reuse the shape, not the dates. Historical data starts on 2025-01-01, so no example reaches back past it.

Weekly traffic at a port

Question: how did traffic at Rotterdam move week by week over the first half of the year?

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

{
  "port_information": {
    "id": "c750eef6-52c0-4c96-9def-90f7eb8914b4",
    "name": "Rotterdam",
    "unlocode": "NLRTM",
    "country_common_name": "Kingdom of the Netherlands"
  },
  "totals": {
    "arrivals": 17554,
    "departures": 17620,
    "vessels_per_day": 247,
    "max_vessels_per_day": 479,
    "avg_dwell_time": 31.4,
    "median_dwell_time": 22.8
  },
  "data": [
    {
      "period_key": "2026-01-11",
      "items": [{ "arrivals": 1264, "departures": 1284, "group_by_key": "none" }]
    },
    {
      "period_key": "2026-01-18",
      "items": [{ "arrivals": 1710, "departures": 1767, "group_by_key": "none" }]
    }
  ]
}

period_key is the Sunday that closes each week, not the Monday that opens it. max_vessels_per_day is the figure to reach for in capacity work: it is the worst day in the range rather than an average.

Which vessel types drive the traffic

Question: how did the composition of arrivals at Rotterdam change month by month?

Now each period carries one item per vessel type, which is the stacked bar shape:

{
  "period_key": "2026-01-31",
  "items": [
    { "arrivals": 412, "departures": 419, "group_by_key": "Container (FC)" },
    { "arrivals": 388, "departures": 381, "group_by_key": "Oil Tanker" },
    { "arrivals": 201, "departures": 204, "group_by_key": "Bulk Carrier" }
  ]
}

A type with no movements in a month is left out of that month rather than returned as zero. Build your series from the union of group_by_key values across the whole response, or a quiet month will shift the colours in your chart.

The overall type distribution

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

period_aggregation=NONE collapses the range to a single data point holding one item per type. That is the donut or pie shape, and it is the cheapest call of the three: one bucket rather than twelve.

One vessel type over time

Question: how did oil tanker traffic alone move through the year?

Filtering with vessel_types and grouping by NONE is not the same call as grouping by VESSEL_TYPE and reading one series out of the result. This one returns a single clean series, and totals describes the tankers alone rather than the whole port.

Vessel type names are ship type level-3 names and are case sensitive. Oil Tanker works; oil tanker does not.

Flag state and vessel class together

Question: how much Norwegian and British Handysize chemical tanker traffic did the port see?

Repeat flag_codes for each flag rather than passing a comma-separated list. Codes are ISO 3166-1 alpha-2 here. The berth detail endpoint takes alpha-3 codes in vessel_flag instead, which is the one inconsistency worth remembering across these three endpoints.

Filters combine as an AND: this returns Handysize chemical tankers that are Norwegian or British flagged.

The berths at a port

Question: which berths does Rotterdam have, who operates them, and where is dwell time worst?

{
  "kpi": {
    "total_berths": 184,
    "min_dwell_time": 1.2,
    "max_dwell_time": 412.7,
    "terminal_operators": 27
  },
  "terminals": [
    {
      "terminal_name": "ECT Delta Terminal",
      "berths": [
        {
          "berth_id": "8f14e45f-ceea-467a-9ba3-6b09c1d2e3f4",
          "berth_name": "Delta 1",
          "berth_type": "Quay",
          "length_m": 400,
          "max_loa_m": 399,
          "max_dwt": 165000,
          "depth_lw_m": 16.65,
          "min_dwell_time": 8.1,
          "avg_dwell_time": 26.3,
          "median_dwell_time": 22.0,
          "max_dwell_time": 91.5
        }
      ]
    }
  ]
}

The kpi block is the summary card. Ranking berths by avg_dwell_time or max_dwell_time across terminals is how you surface congestion, and the terminal grouping shows whether it follows an operator rather than a berth.

Narrow to one operator or one structural type when a port this size returns more than you want to render:

One berth, as a timeline

Question: what sat at this berth over the last quarter, and how much of the time was it idle?

A range of 90 days or less comes back with query.view_mode set to gantt, which is the signal to draw the visits-and-gaps timeline:

{
  "query": { "view_mode": "gantt", "dwell_series_granularity": "weekly" },
  "occupancy": {
    "gap_time_total": 386.5,
    "gap_time_avg": 12.9,
    "pagination": { "total_days": 90, "page": 1, "page_size": 14, "day_start": 1, "day_end": 14 },
    "visits": [
      {
        "imo_number": "9321483",
        "vessel_name": "EVER GIVEN",
        "ship_type_level_3": "Container (FC)",
        "vessel_flag_code": "PAN",
        "arrival_time": "2026-01-03T04:12:00Z",
        "departure_time": "2026-01-04T19:40:00Z",
        "hours_at_berth": 39.5
      }
    ],
    "gaps": [
      { "start_time": "2026-01-04T19:40:00Z", "end_time": "2026-01-05T06:15:00Z", "gap_duration": 10.6 }
    ]
  }
}

page_size counts days, not records. The default of 14 gives you a fortnight of the timeline at a time, and pagination.total_days tells you how many pages the range needs. This is the one paging model on the site that is not limit and offset.

One berth, as a table

Question: over a full year, which vessels accounted for the most time at this berth?

Past 90 days the response comes back with view_mode set to table and no gaps field at all.. Draw occupancy.top_vessels instead:

{
  "query": { "view_mode": "table", "dwell_series_granularity": "weekly" },
  "occupancy": {
    "top_vessels": [
      {
        "imo_number": "9321483",
        "vessel_name": "EVER GIVEN",
        "ship_type_level_3": "Container (FC)",
        "visit_count": 14,
        "total_dwell_time": 501.2,
        "avg_dwell_time": 35.8
      }
    ]
  }
}

A quiet period returns null, not zero

In dwell_time_series, a period with no visits carries null for its average and median. Charting it as 0 turns an empty week into a week where every vessel left instantly. Treat null as a break in the line.

Putting them together

A berth review reads as three calls. Start with arrivals-departures grouped by vessel type to see what the port handles and when it peaks. Move to berths to rank the berths by dwell and find the ones under pressure. Finish on berths/{berth_id} for the berths that stood out, where the occupancy timeline shows whether the problem is long visits or poor turnaround between them.

Keep the same date_start and date_end across all three and the numbers reconcile, because every one of them applies your filters before computing totals.

Port Analytics

The parameters, the response shapes and the error codes behind these calls.

Port Insights

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

Vessel Classes

The class names the vessel_class filter expects.

Weekly traffic at a port#

Which vessel types drive the traffic#

The overall type distribution#

One vessel type over time#

Flag state and vessel class together#

The berths at a port#

One berth, as a timeline#

One berth, as a table#

Putting them together#

Related#