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.
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:
- Method: GET
- URL: https://freightpulsehq.com/api/v1/port-congestion?port=TWKHH
- Auth: Header X-API-Key: YOUR_API_KEY (guest usage without a key is limited to 100 requests/day per IP)
The response envelope is consistent across ports:
- success: boolean
- data: object containing results, global_summary, and meta
- meta: top-level request metadata (e.g., request_id)
In the results array you’ll read the fields you actually use for operational logic:
- port: Kaohsiung
- locode: TW KHH
- congestion (alias of activity): low | moderate | high
- as_of: YYYY-MM-DD (the reference date of the 7-day average vs 90-day baseline)
- metrics: ratio_vs_baseline plus the underlying recent and baseline port-call averages
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:
- data.results[0].congestion (or activity): a discrete label you can display or map to colors in a UI (e.g., moderate → amber).
- data.results[0].metrics.ratio_vs_baseline: a scalar (e.g., 1.05) useful for thresholds and alerts.
- data.results[0].metrics.recent_avg_portcalls_per_day and baseline_avg_portcalls_per_day: context for operators who want to see actual call counts per day (units: calls/day).
- data.results[0].as_of: date string (YYYY-MM-DD). Treat as UTC; it denotes the latest day included in the 7-day average.
- data.meta.data_lag_days: informs cache TTLs and user messaging. The series is not live and is republished weekly.
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:
- Lag and cadence: The series is lagged (about 6–7 days is typical); the meta block may present a broader range. Do not present it as “live.” In UI, show the as_of date prominently.
- Meaning of “moderate” or “low”: These labels reflect relative port-call activity against the past 90 days, not line-haul delays or anchor-wait durations.
- Units: counts per day. There is no currency in this endpoint. Do not quote freight rates here as “today’s price.”
- Baseline comparability: The baseline is port-specific. Avoid comparing raw ratios between unrelated ports without caveats.
Caching, retries, and change detection
Best-effort operational practices for TWKHH:
- Cache TTL: At least 24 hours. The input series is republished weekly; daily fetches are generally sufficient.
- Guest quota: Without an API key you have a limit of 100 requests/day per IP. Use an API key in server-side jobs.
- Idempotence: This endpoint is read-only; safe to retry on transient network failures with exponential backoff (e.g., start at 500 ms up to ~10 s).
- Change detection: Compare previous as_of and ratio_vs_baseline; only notify users when label changes (low→moderate→high) or ratio crosses a threshold you define (e.g., ±0.10 from baseline). Persist the last-seen record per port.
- Timezones: Treat as_of as a UTC date (YYYY-MM-DD). Do not convert to local time for arithmetic; it’s a day-level index.
UI wiring for Kaohsiung (TWKHH)
For a simple dashboard card:
- Title: Kaohsiung (TWKHH)
- Badge: congestion/activity label (low/moderate/high), color-coded
- Metric line: ratio_vs_baseline ×100% with sign vs 1.00 (e.g., +5%)
- Context: recent_avg_calls_per_day vs baseline_avg_calls_per_day
- Footnote: “Source: IMF PortWatch via FreightPulse; 7-day avg vs 90-day baseline; as of YYYY-MM-DD (lagged)”
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:
- Schema checks: Validate the presence of success, data.results[0], and metrics.ratio_vs_baseline. Fail closed with a clear message if missing.
- Out-of-band checks: Log data.meta.source and data.meta.data_lag_days with each pull to detect methodology changes.
- Observability: Emit a metric for ratio_vs_baseline and a tag for label=low|moderate|high to graph over time.
- Backfills: If you miss a few days, the as_of date will jump; that’s expected. Store the full JSON for auditability.
Common pitfalls to avoid
- Confusing activity with delays: The label is derived from port-call volumes, not berth occupancy or anchorage dwell.
- Assuming minute-level freshness: The signal is lagged; avoid phrases like “right now” in user-facing text.
- Cross-port benchmarking without normalization: A 1.05 ratio at Kaohsiung is not directly comparable to another port’s 1.05 without context.
- Over-polling: Weekly republication means daily or even every-other-day pulls are fine. Respect rate limits.
Reference: schema notes for developers
- Envelope: {"success": true, "data": {...}} as shown in the sample.
- Primary fields to read: congestion (or activity), metrics.ratio_vs_baseline, as_of, metrics.recent_avg_portcalls_per_day, metrics.baseline_avg_portcalls_per_day.
- Global summary: data.global_summary provides a snapshot across all ports; not required if you only care about TWKHH.
- Deprecated alias: congestion is a deprecated alias of activity but remains present for compatibility. Prefer activity if both exist, but keep handling for congestion to avoid breaking changes.
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.