You’re routing containers via Port Klang (MYPKG) and need a dependable congestion signal you can automate into ETAs, allocation logic, or booking holds. By the end of this guide, you’ll query congestion for MYPKG via API, parse the fields you actually need, and ship a safe integration that accounts for data lag and averaging windows.
What this dataset measures (and what it does not)
The congestion signal you’ll query here is sourced from IMF PortWatch and republished through FreightPulse. It is a lagged indicator: a 7-day average of port calls compared against a 90-day baseline for the same port. It is not live AIS wait times or anchorage delays, and it does not measure time-in-port. A lower-than-baseline activity reading can appear during closures or slowdowns even if vessels are queued offshore. Keep this distinction in mind when wiring alerts or ETAs.
Key facts before you integrate
- Auth: header X-API-Key: YOUR_API_KEY. Guest requests without a key are allowed (100 requests/day per IP).
- Response envelope: {"success":true,"data":{...}}
- Port congestion is IMF PortWatch, lagged ~6–7 days, 7-day average vs 90-day baseline — not live AIS.
- Do not quote a freight-rates USD fare as today’s price (this endpoint does not return fares).
- Port covered in this guide: Port Klang (MYPKG).
- cURL you can copy/paste:
curl -H "X-API-Key: YOUR_API_KEY" "https://freightpulsehq.com/api/v1/port-congestion?port=MYPKG" - No official congestion JSON is published for MYPKG outside this API. Your integration should read the fields congestion, ratio_vs_baseline, and as_of from the response structure below.
How to query Port Klang (MYPKG) congestion
The endpoint is a simple GET with the UN/LOCODE. For Port Klang, use MYPKG. Authentication goes in the X-API-Key header. If you are just testing locally, you can start without a key (guest quota applies), then add a key once you move to automation.
Copy-paste cURL
Live FreightPulse congestion for MYPKG.
Source: live
cURL:
JSON:
{
"success": true,
"data": {
"results": [
{
"port": "Port Klang",
"locode": "MY PKG",
"country": "Malaysia",
"activity": "moderate",
"congestion": "moderate",
"as_of": "2026-11-13",
"metrics": {
"recent_avg_portcalls_per_day": 29.9,
"baseline_avg_portcalls_per_day": 31.7,
"ratio_vs_baseline": 0.94
}
},
{
"port": "Pelabuhan Sungai Udang",
"locode": "MY PKG",
"country": "Malaysia",
"activity": "moderate",
"congestion": "moderate",
"as_of": "2026-11-13",
"metrics": {
"recent_avg_portcalls_per_day": 2.1,
"baseline_avg_portcalls_per_day": 1.8,
"ratio_vs_baseline": 1.19
}
}
],
"global_summary": {
"ports_high_activity": 0,
"ports_moderate_activity": 2,
"ports_low_activity": 0,
"ports_high_congestion": 0,
"ports_moderate": 2,
"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": "deda4f5f-86b4-4eb0-8dcd-d3326de854d9"
}
}
What to read from the response
- data.results[].congestion (string): a categorical label aligned with activity. It’s an alias of activity and is considered deprecated in the meta. Use for quick labels if needed.
- data.results[].metrics.ratio_vs_baseline (number): the core signal. 1.0 means in line with the 90-day baseline; values below 1.0 indicate fewer port calls than baseline; above 1.0 indicates more port calls than baseline.
- data.results[].as_of (date, YYYY-MM-DD): the effective date of the 7-day average; expect this to lag real time by roughly 6–7 days. Always show this to users next to any indicator.
- data.meta.source and data.meta.data_lag_days: document-level context about origin and lag; useful for tooltips and audit logs.
Python example: fetch MYPKG congestion and normalize the output
The snippet below queries the endpoint, extracts ratio_vs_baseline and as_of for Port Klang, and returns a compact dict your app can cache and render. It also checks the top-level success flag and guards against missing fields.
import os
import requests
API_URL = "https://freightpulsehq.com/api/v1/port-congestion"
PORT = "MYPKG"
API_KEY = os.getenv("FREIGHTPULSE_API_KEY", "YOUR_API_KEY")
def fetch_port_klang_congestion():
headers = {"X-API-Key": API_KEY}
params = {"port": PORT}
resp = requests.get(API_URL, headers=headers, params=params, timeout=15)
resp.raise_for_status()
payload = resp.json()
if not payload.get("success"):
raise RuntimeError("API returned success=false")
data = payload.get("data", {})
results = data.get("results", []) or []
# Filter for Port Klang specifically (the response may include nearby terminals)
klang = next((r for r in results if r.get("port") == "Port Klang"), None)
if not klang:
# Fallback: take the first result if exact match not found
klang = results[0] if results else None
if not klang:
raise RuntimeError("No results found for MYPKG")
metrics = klang.get("metrics", {}) or {}
ratio = metrics.get("ratio_vs_baseline")
as_of = klang.get("as_of")
label = klang.get("congestion") or klang.get("activity")
if ratio is None or as_of is None:
raise RuntimeError("Missing required fields ratio_vs_baseline or as_of")
return {
"port": klang.get("port"),
"locode": klang.get("locode"),
"as_of": as_of, # YYYY-MM-DD (no timezone)
"ratio_vs_baseline": ratio, # unitless ratio
"label": label # string category aligned with activity
}
if __name__ == "__main__":
summary = fetch_port_klang_congestion()
print(summary)
Interpreting Port Klang (MYPKG) results in your app
Use ratio_vs_baseline for any quantitative rule. Because it’s a ratio, you can wire simple thresholds without tuning for absolute volume. For example, flag “below-normal activity” when ratio_vs_baseline < 0.9 and display a heads-up to planners. Keep in mind that fewer port calls can accompany a queue offshore, so combine this with your own vessel tracking or carrier advisories if you need wait-time estimates.
- Ratio units: unitless (e.g., 0.94 = 94% of baseline activity).
- Volume units: recent_avg_portcalls_per_day and baseline_avg_portcalls_per_day are daily port-call counts (ships/day).
- Timestamps: as_of is a calendar date (YYYY-MM-DD). There’s no timezone offset because it represents a 7-day average ending on that date.
- Lag: expect a 6–7 day lag typical for PortWatch weekly republishes. The response meta includes a broader 4–11 day range description — always display the as_of date near the metric.
Caching, retries, and update cadence
The series updates roughly weekly when PortWatch republishes. In most dashboards, caching the latest successful response for 24 hours is safe and avoids burning through the guest quota. On job pipelines, schedule a daily refresh and replace the cached document only if success is true.
- Timeouts: 10–15 seconds is a reasonable client timeout. Retry idempotent GETs on network timeouts with backoff.
- Idempotency: GET is safe to retry.
- Pagination: The response returns an array under data.results. No pagination parameters are documented; expect all relevant rows for the specified port in a single response.
- Versioning: No version query parameter is documented. Pin your client to the fields used here and validate presence of ratio_vs_baseline and as_of.
Common UI patterns for supply and operations teams
- Badge with label and date: Show the categorical label (e.g., “moderate”) and the as_of date beside it. Clicking opens a tooltip that explains the 7-day vs 90-day method and that this is not a live wait-time feed.
- Color thresholds on ratio_vs_baseline: For example, < 0.85 = alert color, 0.85–1.05 = neutral, > 1.05 = high-activity. Keep thresholds explicit in your code for auditability.
- Side-by-side with ETA risk: If your TMS predicts a late berth, show the ratio to give planners context. Make it clear the ratio is about call volume, not queue duration.
Production hardening checklist
- Display as_of wherever you display congestion so users understand lag.
- Store the last success=true payload and serve it if a call fails.
- Log meta.source and data.meta.data_lag_days once per import for traceability.
- Guard against empty data.results arrays and missing metrics fields.
- Avoid mixing datasets: do not label this as live AIS wait time.
Troubleshooting and validation
If you see an unexpected drop or spike at MYPKG, confirm the as_of date first. If it’s older than a week, you may be looking at the last published window from PortWatch. When automating alerts, suppress duplicate notifications if as_of hasn’t changed.
- Mismatch between activity and your live AIS: This is expected; one is a lagged call-volume ratio; the other is near-real-time vessel location.
- Multiple entries in results: Some responses may list nearby terminals or facilities under the same LOCODE. Filter on port == "Port Klang" for the main terminal group, or aggregate if you intentionally track sub-areas.
- HTTP 429 or quota issues: Add an API key and use server-side caching. Guests are limited to 100 requests/day per IP.
Security and deployment notes
- Never hardcode production API keys in client-side code. Keep the X-API-Key in server-side environments or secure secrets stores.
- For CI/CD, validate that your service starts even if the endpoint is temporarily unavailable by using a cached last-known-good response.
- Instrument metrics around success rate, median latency, and freshness (days since as_of).
Field reference: what you likely need to persist
- port (string): “Port Klang” to display the exact facility group name.
- locode (string): “MY PKG” for audits and joins to your port master data.
- as_of (date): store as a date; when aggregating, key by port+as_of.
- metrics.ratio_vs_baseline (float): your primary numeric signal.
- metrics.recent_avg_portcalls_per_day and metrics.baseline_avg_portcalls_per_day (floats): optional diagnostics for planners who want absolute counts.
- congestion/activity (string): optional categorical label for quick UI badges.
Extending to alerts and pipelines
Once the basic fetch is in place, add an alerting job that compares today’s ratio_vs_baseline vs the last saved as_of. Trigger a notification only when as_of advances and the ratio crosses a threshold. Include the as_of date and remind users this is a 7-day average vs a 90-day baseline, lagged from real time.
Where to go next
- Register for an API key to get beyond the guest limit: Register
- Read the docs for updated field notes and integration tips: Documentation
FAQ
Is this a live anchorage or dwell-time feed?
No. It’s a 7-day average of port-call volume vs a 90-day baseline (from IMF PortWatch). It does not measure time-in-port or anchorage wait times.
How fresh is the data for Port Klang?
Expect a lag of roughly 6–7 days. Always show the as_of date and treat it as authoritative for freshness.
What thresholds should I use for alerts?
Keep it simple: for example, alert when ratio_vs_baseline < 0.9 (below-normal activity). Tune thresholds to your tolerance, but anchor the logic on ratio_vs_baseline.
Do I need an API key?
You can start without one (guest: 100 requests/day per IP). For production or higher volume, pass X-API-Key: YOUR_API_KEY in the request header.
Can I quote freight rates based on this response?
No. This endpoint does not return rates or fares. Avoid implying any USD price as “today’s price” from this dataset.
Set up a lightweight job to pull MYPKG congestion daily, cache the latest success=true response, and display ratio_vs_baseline with the as_of date in your planning tools. When you’re ready to move beyond the guest cap and ship this in production, grab an API key here: Register.