Home → Blog

You need a programmatic way to monitor container traffic pressure at Kaohsiung (TWKHH) so operations and booking windows aren’t blindsided by slowdowns. By the end of this guide, you’ll query a Transportation-specific congestion API for Kaohsiung, parse its fields, and turn a 7-day average vs 90-day baseline signal into actionable thresholds you can wire into alerts, ETAs, and schedule buffers.

What this signal measures (and what it does not)

The FreightPulse Port Congestion endpoint exposes a lagged congestion indicator for Kaohsiung built on IMF PortWatch data. The metric compares the most recent 7 days of port calls against a 90-day baseline for the same port. This is a throughput proxy, not a real-time anchorage or wait-time feed.

Illustration: Kaohsiung Port Congestion API

Key facts you should incorporate in your integration and UI copy:

Endpoint, method, and authentication

Use a simple GET request to query the congestion status for Kaohsiung (locode TWKHH). Authentication is via an HTTP header. If you don’t provide a key, the guest quota allows up to 100 requests/day per IP.

Official curl request (copy/paste):

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

If you are building a cron job, prefer GET with a single query param port=TWKHH and include your key as a header. Using header authentication keeps logs and monitors simpler and consistent across your Transportation microservices.

Response shape and fields you will use

Below is the official sample JSON for Kaohsiung. Integrations should not hard-code these values, but you can rely on the same schema and field names in your code paths.

{
"success": true,
"data": {
"results": [
{
"port": "Kaohsiung",
"locode": "TW KHH",
"country": "Taiwan Province of China",
"congestion": "moderate",
"as_of": "2026-10-02",
"metrics": {
"recent_avg_portcalls_per_day": 28.6,
"baseline_avg_portcalls_per_day": 27.3,
"ratio_vs_baseline": 1.04
}
}
],
"global_summary": {
"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": "~6-7 (daily updates, not real-time)",
"methodology": "congestion level is an approximation: last 7 days' avg port calls vs 90-day baseline for the same port. Does not measure vessel wait/anchorage time."
}
},
"meta": {
"request_id": "07c28714-bf93-42cc-8cc1-8b3478db39a4"
}
}

What your code should read:

Envelope and metadata:

JavaScript quickstart: fetch Kaohsiung congestion and compute an operational flag

The following Node.js example calls the same GET endpoint, checks the success flag, and extracts the congestion label, as_of date, and ratio_vs_baseline for downstream logic. It also shows a minimal classification helper you can adapt for alerting.

import fetch from 'node-fetch';

const API_URL = 'https://freightpulsehq.com/api/v1/port-congestion?port=TWKHH';
const API_KEY = 'YOUR_API_KEY'; // put your key here if you have one. Guests: 100 requests/day per IP.

function classifyCongestion(ratio) {
// Example thresholds; tune to your SLA tolerance.
if (ratio === null || ratio === undefined) return 'unknown';
if (ratio >= 1.15) return 'elevated';
if (ratio >= 0.95 && ratio < 1.15) return 'normal';
return 'below-normal';
}

async function getKaohsiungCongestion() {
const res = await fetch(API_URL, {
method: 'GET',
headers: {
'X-API-Key': API_KEY
},
// Keep timeouts conservative since the feed is not real-time
});

if (!res.ok) {
throw new Error(`HTTP ${res.status} from FreightPulse`);
}

const json = await res.json();

if (!json.success || !json.data || !Array.isArray(json.data.results)) {
throw new Error('Unexpected response envelope');
}

const rec = json.data.results[0];
if (!rec) {
throw new Error('No results for port TWKHH');
}

const congestion = rec.congestion; // e.g., "moderate"
const asOf = rec.as_of; // ISO date string
const ratio = rec.metrics?.ratio_vs_baseline ?? null;

const operationalFlag = classifyCongestion(ratio);

return {
port: rec.port,
locode: rec.locode,
congestion,
asOf,
ratioVsBaseline: ratio,
operationalFlag
};
}

getKaohsiungCongestion()
.then(data => {
console.log('Kaohsiung congestion snapshot:', data);
// Example output you can feed into your Transport ops UI or alerting system.
// {
// port: 'Kaohsiung',
// locode: 'TW KHH',
// congestion: 'moderate',
// asOf: 'YYYY-MM-DD',
// ratioVsBaseline: 1.04,
// operationalFlag: 'normal'
// }
})
.catch(err => {
console.error('Error fetching congestion:', err);
});

Notes for production:

Interpreting TWKHH congestion and turning it into actions

For Transportation planners, the congestion label gives an immediate operational hint, while the ratio_vs_baseline provides a tunable numeric threshold for automations.

Remember that this is a throughput proxy. It won’t tell you current anchorage wait times, so never message end customers that it represents minute-by-minute conditions. It is reliable for directional planning, capacity cues, and scorecards.

Error handling, retries, and stability

Design for transient failures and schema stability:

If you expect to chain this signal into downstream systems (e.g., ETL into a data lake), store the entire JSON in raw form, then transform into curated columns: as_of, port, locode, congestion, recent_avg_portcalls_per_day, baseline_avg_portcalls_per_day, ratio_vs_baseline, and ingestion_timestamp.

Operational cadence: updates, scheduling, and testing

Because updates are daily and lagged, your scheduler can run once or a few times per day. Typical cadence:

Testing tips:

Embedding in Transportation apps and dashboards

For Transport network control towers or port call planning tools, present Kaohsiung’s congestion at the same visual level as schedule variance and berth window utilization. Suggestions:

In alert feeds or emails, include as_of and ratio so on-call staff can judge whether the signal reflects a persistent trend or a single-week anomaly.

Common pitfalls and how to avoid them

Where to find parameters, schema notes, and changes

This guide focused on the Kaohsiung (TWKHH) endpoint and the fields your Transportation systems will actually use. For a broader view of documented fields, envelope details, and any pagination or schema updates, refer to the official docs:

Documentation

FAQ

Is this live AIS wait-time data?
No. It is a lagged (~6–7 days) 7-day average vs 90-day baseline signal derived from IMF PortWatch AIS data. It does not measure anchorage or berth wait times.

How often should I poll the endpoint for Kaohsiung?
Daily is typical, with an optional midday refresh. Cache responses for several hours since values are not real-time.

What fields should I store for downstream analytics?
Store as_of, port, locode, congestion, recent_avg_portcalls_per_day, baseline_avg_portcalls_per_day, ratio_vs_baseline, plus the raw payload and an ingestion timestamp.

Can I call without an API key?
Yes, as a guest you get 100 requests per day per IP. For higher throughput or service-to-service calls, use the X-API-Key header with your key.

How should I set alert thresholds?
Use ratio_vs_baseline for numeric rules and the congestion label for human-readable badges. Start with conservative ranges (e.g., 1.10 and 1.20) and tune based on your SLA and historical performance.

Get a production key and wire Kaohsiung congestion into your Transportation dashboards and planners in minutes. Create your account here: Register.