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.
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:
- Identify the port and its UN/LOCODE (Hong Kong, HK HKG).
- Read current activity/congestion labels (categorical buckets).
- Inspect the “as_of” date to understand freshness.
- Use metrics that compare recent port calls/day to baseline and compute a ratio_vs_baseline.
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.
- Auth header: X-API-Key: YOUR_API_KEY
- Guest quota: 100 requests/day per IP
- Envelope: {"success":true,"data":{...}}
- Method: GET
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:
- data.results[0].as_of: Date string (YYYY-MM-DD). Use this to display freshness and to decide whether to refresh a cached value. The source republishes weekly, so don’t poll minute-by-minute.
- data.results[0].activity and data.results[0].congestion: Categorical buckets; the latter is a deprecated alias of activity. Use one consistently in your UI and documentation; prefer activity.
- data.results[0].metrics.ratio_vs_baseline: Dimensionless ratio of recent (7-day avg) port calls to a 90-day baseline. Values above 1.0 mean more calls than usual; below 1.0 mean fewer.
- data.results[0].metrics.recent_avg_portcalls_per_day and baseline_avg_portcalls_per_day: Units are port calls per calendar day, averaged. Use these for numeric displays or thresholds.
- data.meta.data_lag_days: Guidance for expected lag. Always check as_of before alerting users.
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:
- congestion/activity: A categorical bucket to summarize recent conditions.
- as_of: The effective date of the metric window.
- metrics.ratio_vs_baseline: The numeric indicator to drive your thresholds.
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
- Units: recent_avg_portcalls_per_day and baseline_avg_portcalls_per_day are in port calls/day (averaged).
- Ratio: dimensionless (recent divided by baseline).
- as_of: date string (YYYY-MM-DD). Use it as the effective date for the 7-day window; do not assume intraday granularity.
Caching and refresh strategy
- Cache by port + as_of to avoid redundant fetches across services.
- Given weekly republishing, a daily check is usually sufficient. Consider refreshing more frequently only if you are also watching for the weekly update event.
- Respect the guest quota (100/day per IP). With thoughtful caching keyed to as_of, you’ll stay comfortably within limits even across multiple services.
Handling nulls and fallbacks
- If activity is missing, look for congestion (deprecated alias). Normalize it in your DTOs to a single “activity” concept.
- If ratio_vs_baseline is unavailable, display the categorical label and defer numeric comparisons until the metric reappears in a later refresh.
- Design your UI to show the as_of date prominently so users understand the lag.
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
- Confusing activity with live congestion: This series tracks relative call volumes, not minutes of waiting. Never present it as live anchorage times.
- Over-polling: Weekly publication means polling more than once per day rarely adds value. Use the as_of date to short-circuit fetches until a new value appears.
- Hardcoding a single result row: Keep parsing generic; results is an array. Even if you only request one port, write your code to gracefully handle multiple rows for future-proofing.
- Assuming currency, fares, or prices: This endpoint doesn’t return rates or USD fares. Don’t conflate the activity signal with pricing.
End-to-end flow for an operations dashboard
Data ingestion
- Fetch HKHKG daily using the GET endpoint with your X-API-Key.
- Normalize to a schema with fields: port, locode, as_of, activity, ratio_vs_baseline, recent_avg_portcalls_per_day, baseline_avg_portcalls_per_day, data_lag_hint, request_id.
- Persist keyed by port+as_of and mark the row immutable to retain history
Alerting and buffers
- Set alert thresholds on ratio_vs_baseline. Consider a hysteresis band to avoid flip-flopping near 1.0.
- Use activity label to gate UI badges (e.g., “Moderate activity” next to HKHKG).
- For voyage planning buffers, only revise when as_of advances to a new date.
Presentation
- Show the as_of date in the card header so users understand staleness at a glance.
- Display both the ratio and the recent/baseline port-call counts to communicate scale.
- Include a tooltip that reiterates: “Activity is port-call volume vs baseline; not live queue time.”
Troubleshooting and data quality checks
- Unexpected spikes or drops: Cross-check the data_lag_days hint and confirm as_of advanced. A sharp change can reflect publication timing rather than on-the-ground conditions.
- Empty results: Retry after a short delay and confirm that you used the correct parameter port=HKHKG. If persistent, rely on the previous cached row and surface a soft warning in logs.
- Auth failures: Ensure the header name is X-API-Key and that your runtime safely injects YOUR_API_KEY. Guests are limited to 100/day/IP.
- Field deprecation: Prefer activity over congestion. Keep a compatibility layer that maps congestion to activity in case your downstreams expect a single field.
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
-
Is this live congestion or wait-time data?
No. It’s IMF PortWatch-based activity (7-day average of port calls vs a 90-day baseline). It is not live AIS wait times or anchorage duration. -
What does as_of represent and how fresh is it?
as_of is the effective date of the recent-average window. PortWatch republishes weekly, so expect a lag of roughly 6–7 days; always read data.meta.data_lag_days and the as_of date. -
Which field should I display: activity or congestion?
Use activity. congestion is a deprecated alias of activity. If only congestion is present, map it to your activity display for consistency. -
What are the units and how should I threshold alerts?
recent_avg_portcalls_per_day and baseline_avg_portcalls_per_day are in port calls/day. ratio_vs_baseline is dimensionless. Choose thresholds around 1.0 (e.g., <0.9 or >1.1) according to your risk tolerance. -
Do I need an API key?
You can call as a guest without a key up to 100 requests/day per IP. For higher usage or production reliability, pass X-API-Key: YOUR_API_KEY.
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.