Home → Blog

You’re planning sailings through Kaohsiung (locode TWKHH) and need a reliable way to quantify how busy the port has been recently so you can route, schedule, or inform customers with defensible data. By the end of this guide you’ll query FreightPulse’s port-congestion endpoint for TWKHH, interpret the results correctly, and wire them into a dashboard or alert service without confusing lagged PortWatch signals for live AIS wait times.

What this “congestion” signal actually measures for Kaohsiung

The FreightPulse port-congestion endpoint for Kaohsiung sources IMF PortWatch. The metric is a 7-day average of port calls compared to a 90-day baseline for the same port. Higher activity can indicate more ships arriving than usual; lower activity can indicate fewer calls than usual, which might include closures, re-routes, or vessels waiting offshore. This is not a live vessel waiting-time series.

Illustration: Kaohsiung (TWKHH) Congestion

PortWatch data is lagged, typically by about 6–7 days. The endpoint also returns a descriptive meta block that may show a wider range for republishing lag. Always treat the “as_of” date in the response as the reference day for the 7-day average and baseline comparison.

Endpoint, auth, and response envelope

Use a simple GET against a single endpoint with the TWKHH locode:

The response envelope is consistent across ports:

In the results array you’ll read the fields you actually use for operational logic:

Per FreightPulse, do not treat this as a live anchorage-wait estimate. It is an activity signal derived from port calls. If you need live AIS wait times, use a different data source; this one is lagged per PortWatch’s publication schedule and should be cached accordingly in your systems.

Quickstart: call TWKHH with cURL

Live FreightPulse congestion for TWKHH.

Source: live

cURL:

curl -H "X-API-Key: YOUR_API_KEY" "https://freightpulsehq.com/api/v1/port-congestion?port=TWKHH"

Official sample response and field mapping

JSON:

{
    "success": true,
    "data": {
        "results": [
            {
                "port": "Kaohsiung",
                "locode": "TW KHH",
                "country": "Taiwan Province of China",
                "activity": "moderate",
                "congestion": "moderate",
                "as_of": "2026-11-13",
                "metrics": {
                    "recent_avg_portcalls_per_day": 28.7,
                    "baseline_avg_portcalls_per_day": 27.5,
                    "ratio_vs_baseline": 1.05
                }
            }
        ],
        "global_summary": {
            "ports_high_activity": 0,
            "ports_moderate_activity": 1,
            "ports_low_activity": 0,
            "ports_high_congestion": 0,
            "ports_moderate": 1,
            "ports_low": 0
        },
        "meta": {
            "source": "IMF PortWatch (portwatch.imf.org) - UN Global Platform AIS data",
            "data_lag_days": "4-11 (PortWatch republishes the daily series once a week; check as_of)",
            "methodology": "activity is port-call volume, not congestion: last 7 days' avg calls vs a 90-day baseline for the same port. low means fewer calls than usual, which can be a closure or ships waiting offshore. It does not measure vessel wait or anchorage time. congestion is a deprecated alias of activity."
        }
    },
    "meta": {
        "request_id": "f025ebd7-525c-4150-84aa-1b5ec6b8f277"
    }
}

How to use these fields in your logic:

Python example: fetch Kaohsiung and normalize the signal

This example calls the TWKHH endpoint, checks the envelope, and returns a normalized object your services can store or push to a dashboard.

import os
import sys
import json
import urllib.request

API_URL = "https://freightpulsehq.com/api/v1/port-congestion?port=TWKHH"
API_KEY = os.getenv("FREIGHTPULSE_API_KEY", "YOUR_API_KEY")

def fetch_twkhh():
req = urllib.request.Request(API_URL)
req.add_header("X-API-Key", API_KEY)
with urllib.request.urlopen(req, timeout=20) as resp:
raw = resp.read().decode("utf-8")
payload = json.loads(raw)
if not payload.get("success"):
raise RuntimeError("API returned success=false")
data = payload.get("data", {})
results = data.get("results", [])
if not results:
raise RuntimeError("No results for TWKHH")
r0 = results[0]
metrics = r0.get("metrics", {})
# Build a compact record you can store in a db or forward to Grafana
return {
"port": r0.get("port"),
"locode": r0.get("locode"),
"label": r0.get("congestion") or r0.get("activity"),
"as_of": r0.get("as_of"),
"ratio_vs_baseline": metrics.get("ratio_vs_baseline"),
"recent_avg_calls_per_day": metrics.get("recent_avg_portcalls_per_day"),
"baseline_avg_calls_per_day": metrics.get("baseline_avg_portcalls_per_day"),
"source": data.get("meta", {}).get("source"),
"data_lag_days": data.get("meta", {}).get("data_lag_days")
}

if __name__ == "__main__":
try:
record = fetch_twkhh()
print(json.dumps(record, indent=2))
except Exception as e:
print(f"Error: {e}", file=sys.stderr)
sys.exit(1)

Interpreting TWKHH safely in products and ops

Keep these constraints in your UX copy and alerting logic so shippers and planners don’t confuse the metric:

Caching, retries, and change detection

Best-effort operational practices for TWKHH:

UI wiring for Kaohsiung (TWKHH)

For a simple dashboard card:

For alerting into Slack/Teams, include the as_of date and the ratio. Example threshold: alert when the label changes or when the ratio delta exceeds ±0.10 compared to your last stored point, to avoid noisy alerts driven by small fluctuations.

Testing and monitoring your integration

Before pushing to production:

Common pitfalls to avoid

Reference: schema notes for developers

FAQ

Is the Kaohsiung congestion value live?

No. It comes from IMF PortWatch and is lagged by several days. Use the as_of date as your reference and communicate the lag to end users.

What does ratio_vs_baseline represent?

It is the 7-day average of port calls divided by the 90-day baseline for Kaohsiung. Values above 1.00 indicate more calls than the recent baseline; below 1.00 indicate fewer.

Can I use this to estimate berth or anchorage wait times?

No. The signal is based on port-call counts, not vessel dwell or queue times. For live wait times, use a different data set designed for AIS event tracking.

How often should I poll the endpoint for TWKHH?

Daily is sufficient for most use cases. Cache responses for at least 24 hours and re-poll on your preferred schedule. Respect the 100 requests/day per IP limit if you are not using an API key.

What should I display in a customer-facing widget?

Show the label (low/moderate/high), the ratio_vs_baseline as a percent, recent vs baseline calls per day, and the as_of date with a footnote that the series is lagged and sourced from IMF PortWatch via FreightPulse.

Build your Kaohsiung congestion monitor now. Create an account to get an API key and ship your integration today: Register. For field-by-field details and additional endpoints, read the Documentation.