Home → Blog

You need a reliable way to quantify container port congestion at Hong Kong (HKHKG) and wire it into your tooling to inform ETAs, booking windows, or schedule buffers. By the end of this guide, you will be able to query Hong Kong’s congestion/activity signal via the FreightPulse API, parse the result, and make practical integration decisions around caching, alerting, and data hygiene.

What FreightPulse’s HKHKG signal measures (and what it doesn’t)

FreightPulse’s port congestion endpoint for Hong Kong (HKHKG) is based on IMF PortWatch. It reflects recent port-call activity as a 7-day average versus a 90-day baseline for the same port. It is not a live AIS wait-time feed. Because PortWatch republishes on a weekly cadence, the data you receive is typically lagged by roughly 6–7 days (and can be a bit wider per the meta fields). Treat it as an operational trend signal, not an immediate queuing or anchorage-time measurement.

Illustration: Hong Kong (HKHKG) Congestion

The envelope returned by the API is a standard JSON object with a success flag and a data object. The data object contains a results array (per port) and meta blocks with source and methodology. For HKHKG, expect fields that let you:

Authentication, quotas, and base format

The endpoint is a simple GET with your API key in the X-API-Key header. Guests without a key can make up to 100 requests per day per IP. Responses are wrapped in an envelope of the form {"success":true,"data":{...}}. Keep the envelope intact when you cache or forward results so downstream services can reliably check success before drilling into results.

Quick start: cURL for Hong Kong (HKHKG)

Use the official HKHKG endpoint for Hong Kong. Copy and run this request:

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

Official sample response and field map

Below is the official JSON sample for HKHKG. Copy it into your tests if you need a stable fixture. Then read the short mapping guide that follows.

{
    "success": true,
    "data": {
        "results": [
            {
                "port": "Hong Kong",
                "locode": "HK HKG",
                "country": "Hong Kong SAR",
                "activity": "moderate",
                "congestion": "moderate",
                "as_of": "2026-11-13",
                "metrics": {
                    "recent_avg_portcalls_per_day": 39.7,
                    "baseline_avg_portcalls_per_day": 37.7,
                    "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": "982a7548-08be-462a-9286-b7de22ea1890"
    }
}

Field notes you will actually use:

Why you won’t see live AIS wait times here

The FreightPulse HKHKG signal is derived from IMF PortWatch’s port-call volumes, not live queue lengths or time-at-anchorage. Treat “activity” as an operational climate indicator: fewer calls can mean disruptions or off-port waiting; higher calls can mean heavier traffic or catch-up operations. For decisions that need real-time berth/anchorage waits, pair this with a live AIS source in your own stack; do not treat activity as a latency proxy.

When the JSON looks different or sparse

For Hong Kong, you may sometimes see limited or differently structured signals depending on the publication window. At minimum, expect the key fields used to interpret the series:

If your integration depends on any single field, read it defensively (e.g., prefer activity, fall back to congestion if present) and monitor the meta block for data lag to guide refresh cadence.

Production-grade integration in JavaScript

This example fetches HKHKG, lifts the key fields, and shows a conservative cache strategy keyed by as_of. It’s designed to be copy-pasteable and safe for server environments. If you run it in a browser, proxy the request to avoid exposing YOUR_API_KEY.

/**
* Fetch Hong Kong (HKHKG) congestion/activity and return a normalized object.
* Notes:
* - Data is lagged (see data.meta.data_lag_days). Always check `as_of`.
* - Results is an array; we take the first match.
* - Units: port calls per day (averaged). ratio_vs_baseline is dimensionless.
*/
async function fetchHkhkgActivity(apiKey) {
const url = 'https://freightpulsehq.com/api/v1/port-congestion?port=HKHKG';
const res = await fetch(url, {
headers: { 'X-API-Key': apiKey }
});

if (!res.ok) {
throw new Error(`HTTP ${res.status} while fetching HKHKG`);
}

const body = await res.json();
if (!body || body.success !== true || !body.data || !Array.isArray(body.data.results)) {
throw new Error('Malformed response envelope');
}

const row = body.data.results[0];
if (!row) {
return {
port: 'Hong Kong',
locode: 'HK HKG',
has_data: false,
reason: 'No results array element present'
};
}

const act = row.activity || row.congestion || null;
const asOf = row.as_of || null;
const metrics = row.metrics || {};
const ratio = metrics.ratio_vs_baseline ?? null;

return {
port: row.port || 'Hong Kong',
locode: row.locode || 'HK HKG',
as_of: asOf,
activity: act,
ratio_vs_baseline: ratio,
recent_avg_portcalls_per_day: metrics.recent_avg_portcalls_per_day ?? null,
baseline_avg_portcalls_per_day: metrics.baseline_avg_portcalls_per_day ?? null,
data_lag_hint: body.data.meta ? body.data.meta.data_lag_days : null,
request_id: body.meta ? body.meta.request_id : null
};
}

// Example usage
(async () => {
try {
const apiKey = process.env.FREIGHTPULSE_API_KEY || 'YOUR_API_KEY';
const hk = await fetchHkhkgActivity(apiKey);

// Cache key: port + as_of to avoid recomputing when the weekly series hasn't changed.
const cacheKey = `hkhkg:${hk.as_of || 'unknown'}`;
console.log('cache_key=', cacheKey);
console.log('HKHKG activity=', hk.activity, 'ratio=', hk.ratio_vs_baseline, 'as_of=', hk.as_of);

// Example thresholding: alert if ratio drops notably below baseline
if (hk.ratio_vs_baseline !== null && hk.ratio_vs_baseline < 0.9) {
console.warn('Heads-up: HKHKG activity materially below baseline — investigate potential disruption.');
}
} catch (err) {
console.error('Failed to load HKHKG activity:', err);
}
})();

Operational guidance for HKHKG consumers

Interpreting ratios and categories

Use ratio_vs_baseline to drive numeric thresholds in alerting and buffers. For example, you might treat 0.95–1.05 as “steady,” below 0.9 as “notably lower than usual,” and above 1.1 as “notably higher than usual.” The activity/congestion category is a useful quick label, but the ratio gives you the numeric detail needed for automation.

Units, dates, and time granularity

Caching and refresh strategy

Handling nulls and fallbacks

Python example with defensive parsing

Here’s a Python snippet using requests to query HKHKG and extract the working fields for downstream use. It applies the same normalization pattern and prepares a simple dict you can serialize to your cache or database.

import os
import requests

def fetch_hkhkg_activity(api_key: str) -> dict:
url = "https://freightpulsehq.com/api/v1/port-congestion?port=HKHKG"
headers = {"X-API-Key": api_key}
r = requests.get(url, headers=headers, timeout=20)
r.raise_for_status()
body = r.json()

if not body or body.get("success") is not True:
raise ValueError("API error or unsuccessful response")

data = body.get("data", {})
results = data.get("results", []) or []
row = results[0] if results else None

if not row:
return {
"port": "Hong Kong",
"locode": "HK HKG",
"has_data": False,
"reason": "No results returned"
}

metrics = row.get("metrics", {}) or {}
normalized = {
"port": row.get("port", "Hong Kong"),
"locode": row.get("locode", "HK HKG"),
"as_of": row.get("as_of"),
"activity": row.get("activity") or row.get("congestion"),
"ratio_vs_baseline": metrics.get("ratio_vs_baseline"),
"recent_avg_portcalls_per_day": metrics.get("recent_avg_portcalls_per_day"),
"baseline_avg_portcalls_per_day": metrics.get("baseline_avg_portcalls_per_day"),
"data_lag_hint": (data.get("meta") or {}).get("data_lag_days"),
"request_id": (body.get("meta") or {}).get("request_id")
}
return normalized

if __name__ == "__main__":
api_key = os.getenv("FREIGHTPULSE_API_KEY", "YOUR_API_KEY")
hk = fetch_hkhkg_activity(api_key)
print(hk)
# Suggested cache key: f"hkhkg:{hk.get('as_of') or 'unknown'}"

Common pitfalls when shipping HKHKG into production

End-to-end flow for an operations dashboard

Data ingestion

Alerting and buffers

Presentation

Troubleshooting and data quality checks

Full request you can copy into your runbook

Use the cURL command below in cron jobs, GitHub Actions, or your internal CLI tools. The header and URL are exactly what you need for Hong Kong.

FAQ

Ship your HKHKG integration now. Create an account to get an API key, production reliability, and access to more docs: Register. For endpoint details and field definitions, see the Documentation.