Home → Blog

You need a reliable way to quantify and monitor port congestion at Guangzhou (Nansha) so planning teams can reroute or adjust schedules before delays hit operations. By the end of this guide, you will query FreightPulse’s Port Congestion API for Guangzhou (Nansha), interpret its 7-day average vs 90-day baseline metrics from IMF PortWatch, and integrate those signals into transportation scheduling, ETAs, and exception workflows.

What this API measures (and what it does not)

The FreightPulse Port Congestion API reports a congestion level derived from IMF PortWatch data. It computes a 7-day average of port calls and compares it to a 90-day baseline for the same port. This provides a standardized signal of relative activity and capacity stress.

Illustration: Guangzhou (Nansha) Port Congestion API

It is not a live AIS wait-time feed. The dataset is lagged about 6–7 days and updates daily. Use it to track trend and relative status—not to time tug dispatch or minute-by-minute berth availability.

Authentication, request envelope, and limits

Authentication uses an API key in the request header. The response envelope wraps data under a success flag.

For API keys, see the Register page. For usage notes, see the Documentation.

Quickstart: curl request for Guangzhou (Nansha)

Copy and run the following request. Replace YOUR_API_KEY if you have one; otherwise the guest limit applies.

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

Official sample response for CNGGZ

The block below shows the response shape and key fields to read in your code. Values are from IMF PortWatch and represent a 7-day average against a 90-day baseline, lagged ~6–7 days.

{
"success": true,
"data": {
"results": [
{
"port": "Guangzhou (Nansha)",
"locode": "CN GGZ",
"country": "China",
"congestion": "moderate",
"as_of": "2026-09-25",
"metrics": {
"recent_avg_portcalls_per_day": 27.1,
"baseline_avg_portcalls_per_day": 27.8,
"ratio_vs_baseline": 0.98
}
}
],
"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": "64b528db-1340-49f2-af89-e2abaa2c53f7"
}
}

What to read in your integration:

Python example: fetch and interpret congestion for Guangzhou (Nansha)

This Python snippet requests the CNGGZ record, extracts the congestion level and ratio_vs_baseline, and converts the categorical level into a programmatic severity you can log or alert on.

import os
import requests

API_URL = "https://freightpulsehq.com/api/v1/port-congestion"
PORT = "CNGGZ"
API_KEY = os.getenv("FREIGHTPULSE_API_KEY", "YOUR_API_KEY")

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")

results = payload.get("data", {}).get("results", [])
if not results:
raise ValueError("No results for port CNGGZ")

record = results[0]

congestion_level = record.get("congestion") # e.g., "moderate"
as_of = record.get("as_of") # e.g., "2026-09-25"
metrics = record.get("metrics", {})
ratio = metrics.get("ratio_vs_baseline") # e.g., 0.98
recent = metrics.get("recent_avg_portcalls_per_day")
baseline = metrics.get("baseline_avg_portcalls_per_day")

# Map to severity integer for alerts/dashboards.
severity_map = {"low": 1, "moderate": 2, "high": 3}
severity = severity_map.get(congestion_level, 0)

print(f"Port: Guangzhou (Nansha) [{PORT}]")
print(f"As of: {as_of}")
print(f"Congestion: {congestion_level} (severity={severity})")
print(f"7d avg vs 90d baseline ratio: {ratio}")
print(f"Recent avg port calls/day: {recent} | Baseline: {baseline}")

How to use this signal in a transportation stack

Because the metric is lagged and normalized, treat it as a planning and monitoring input rather than a real-time dispatch driver. Here are practical patterns for Guangzhou (Nansha):

Operational details that save time

Error handling and validation

Validate the envelope and the required fields before using values downstream. Recommended checks:

Building a simple decision rule for Guangzhou (Nansha)

Below is a lightweight rule-set you can implement around the CNGGZ signal:

These bounds are examples of how to read the ratio; choose thresholds based on historical service reliability for your lanes to and from Guangzhou (Nansha).

Data lineage and reproducibility

The meta block reports lineage and methodology so you can reproduce or audit calculations internally:

When investigating anomalies, capture and store meta.request_id with your logs to trace upstream requests during incident reviews.

Embedding in dashboards and alerts

For transportation control towers, bind the congestion string to a color scale and display the ratio as a numeric overlay. Use as_of to annotate staleness. Example alert triggers:

Because the data is lagged, avoid paging on-call for single-day spikes; prioritize consecutive-day confirmations.

Security and deployment notes

Testing strategies

Change management

Keep your parser tolerant to new fields within data.results elements and meta blocks. Iterate arrays defensively even for single-port queries to future-proof multi-port expansions. When introducing new thresholds for operations, perform a shadow period where both old and new rules run, and audit the difference in alerts before cutting over.

Reference: essential endpoints and fields

FAQ

Is this live AIS wait time for Guangzhou (Nansha)?
No. It is IMF PortWatch-derived, lagged ~6–7 days, reporting a 7-day average vs a 90-day baseline. It does not measure anchorage or berth waiting minutes.

How often should I poll the endpoint?
Daily is sufficient. Results update once per day with a ~6–7 day lag, so more frequent polling offers no benefit for most integrations.

Can I rely on guest access?
Yes for low-volume use (100 requests/day per IP). For scheduled jobs, multiple environments, or dashboards, use an API key via the X-API-Key header.

What do I alert on: congestion or ratio_vs_baseline?
Use both. congestion is categorical and easy for operations to read; ratio_vs_baseline provides numeric precision for thresholds and trend scoring.

Which timezone does as_of use?
as_of is an ISO date for the latest available 7-day window; treat it as a date without a timezone offset for daily planning and caching.

Ready to integrate Guangzhou (Nansha) congestion into your transportation workflows? Create an API key and start shipping your daily job within minutes: Register. For additional implementation details and envelope fields, see the Documentation.