You need to track whether Guangzhou (Nansha) is busier or quieter than usual so you can route bookings and set expectations with shippers and terminals. By the end of this article, you’ll call the FreightPulse API for Guangzhou (Nansha) (CNGGZ), parse the lagged IMF PortWatch congestion proxy correctly, and productionize alerts without mistaking it for live AIS wait times.
What the Guangzhou (Nansha) congestion signal actually measures
The FreightPulse port congestion endpoint for Guangzhou (Nansha) is based on IMF PortWatch, not vessel wait time from live AIS. The signal is a 7-day average of port calls compared to a 90-day baseline for the same port. Lower recent activity than baseline can reflect closures, storms, holidays, or ships waiting offshore, but it is not a direct measure of anchorage or berth wait time.
The data is lagged by about 6–7 days in typical conditions. In practice, the PortWatch weekly republication cycle can surface a 4–11 day lag; always read the as_of field to understand the reference date of the metrics you are using.
Auth, request limits, and envelope
Authentication uses the X-API-Key header. Use YOUR_API_KEY for development; do not hardcode secrets in client-side apps. Guests without a key are rate-limited to 100 requests per day per IP.
- Header: X-API-Key: YOUR_API_KEY
- Response envelope: {"success": true, "data": {...}}
Because the series is republished weekly, cache responses by the port code and as_of date to avoid unnecessary calls and to maintain a stable audit trail for downstream decisions.
Make a request for Guangzhou (Nansha)
Use the following cURL to retrieve the current congestion proxy for Guangzhou (Nansha) (CNGGZ). Note the response includes both human-readable activity/congestion and the underlying metrics with the recent vs. baseline comparison.
Live FreightPulse congestion for CNGGZ.
Source: live
curl -H "X-API-Key: YOUR_API_KEY" "https://freightpulsehq.com/api/v1/port-congestion?port=CNGGZ"
Official sample response and how to read it
The example below shows the response structure you will parse. activity is a categorical summary of the same signal that ratio_vs_baseline quantifies. congestion is a deprecated alias of activity retained for backward compatibility.
{
"success": true,
"data": {
"results": [
{
"port": "Guangzhou (Nansha)",
"locode": "CN GGZ",
"country": "China",
"activity": "moderate",
"congestion": "moderate",
"as_of": "2026-11-06",
"metrics": {
"recent_avg_portcalls_per_day": 26.7,
"baseline_avg_portcalls_per_day": 27.4,
"ratio_vs_baseline": 0.97
}
}
],
"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": "fdba8d3a-1e9a-4801-8aff-217eb5434c52"
}
}
Fields you will actually use:
- data.results[0].as_of: The reference date for the 7-day window (format YYYY-MM-DD). Use this to align your dashboards and caches.
- data.results[0].metrics.ratio_vs_baseline: A numeric ratio of recent to baseline activity (e.g., 0.97 means recent port-call volume is 97% of baseline).
- data.results[0].activity or data.results[0].congestion: A categorical label derived from the ratio for quick status displays; avoid using it for threshold math.
- data.results[0].metrics.recent_avg_portcalls_per_day and baseline_avg_portcalls_per_day: Useful for context, reporting, and alert payloads.
- data.meta.data_lag_days: A human-readable lag range; do not treat it as a numeric field. Always respect as_of for logic.
Working example in Python: fetch and normalize CNGGZ
This Python script calls the same endpoint, validates the envelope, guards against missing fields, and normalizes the output so you can persist it to a warehouse table keyed by port and as_of.
import os
import sys
import json
import datetime
import requests
API_KEY = os.getenv("FREIGHTPULSE_API_KEY", "YOUR_API_KEY")
PORT = "CNGGZ"
URL = f"https://freightpulsehq.com/api/v1/port-congestion?port={PORT}"
HEADERS = {"X-API-Key": API_KEY}
def fetch_port_congestion():
resp = requests.get(URL, headers=HEADERS, timeout=20)
try:
payload = resp.json()
except Exception as e:
raise RuntimeError(f"Invalid JSON: {e}; status={resp.status_code}; text={resp.text[:500]}")
if not isinstance(payload, dict) or not payload.get("success", False):
raise RuntimeError(f"API indicated failure or unexpected envelope: {json.dumps(payload)[:500]}")
data = payload.get("data") or {}
results = data.get("results") or []
if not results:
raise RuntimeError("No results for port CNGGZ. Try again later or check docs.")
row = results[0]
# Extract and validate fields
port = row.get("port")
locode = row.get("locode")
as_of = row.get("as_of") # Expect 'YYYY-MM-DD' per sample
activity = row.get("activity")
congestion = row.get("congestion") # Deprecated alias
metrics = row.get("metrics") or {}
recent = metrics.get("recent_avg_portcalls_per_day")
baseline = metrics.get("baseline_avg_portcalls_per_day")
ratio = metrics.get("ratio_vs_baseline")
# Minimal normalization and type-safety
if as_of is None:
raise RuntimeError("Missing as_of in response.")
try:
# Keep as a date string in storage; this ensures idempotency for the weekly republish cycle.
datetime.datetime.strptime(as_of, "%Y-%m-%d")
except ValueError:
raise RuntimeError(f"as_of is not YYYY-MM-DD: {as_of}")
normalized = {
"port_code": PORT,
"port_name": port,
"locode": locode,
"as_of": as_of,
"activity_label": activity,
"congestion_label": congestion,
"recent_avg_portcalls_per_day": recent,
"baseline_avg_portcalls_per_day": baseline,
"ratio_vs_baseline": ratio,
"source": (data.get("meta") or {}).get("source"),
"data_lag_note": (data.get("meta") or {}).get("data_lag_days"),
"request_id": (payload.get("meta") or {}).get("request_id"),
"fetched_at_utc": datetime.datetime.utcnow().isoformat(timespec="seconds") + "Z",
}
return normalized
if __name__ == "__main__":
try:
out = fetch_port_congestion()
print(json.dumps(out, ensure_ascii=False, indent=2))
except Exception as e:
print(f"ERROR: {e}", file=sys.stderr)
sys.exit(1)
Parsing strategy: lag, labels, and thresholds that won’t bite you
Because the series is lagged, never label dashboards “live congestion.” Label clearly as “7-day avg activity vs 90-day baseline (PortWatch, lagged; see as_of).” A good pattern is to route operations using the numeric ratio_vs_baseline while displaying the categorical activity for humans.
- Use ratio_vs_baseline for logic and alerts, e.g., notify if ratio falls below a threshold relevant to your lead times.
- Show activity for status: low, moderate, high. Treat congestion as a backward-compatible alias only.
- Respect as_of for time alignment; persist snapshots keyed by (port_code, as_of) to prevent mixing weeks.
If your system needs live berth/anchorage waits, integrate a separate live AIS source. Keep this endpoint dedicated to the PortWatch activity proxy so you don’t conflate signals.
Field-by-field behavior you should account for
Here is how core fields behave and how to handle them in code and analytics pipelines.
- port and locode: Identifiers for display and enrichment. Store both; some users prefer UN/LOCODE-based joins.
- as_of: The date anchor for the 7-day window. Format is YYYY-MM-DD. Do not assume time-of-day or timezone; treat it as a date.
- metrics.recent_avg_portcalls_per_day: Floating-point average of daily port calls over the recent 7 days (units: calls/day).
- metrics.baseline_avg_portcalls_per_day: 90-day rolling baseline (units: calls/day).
- metrics.ratio_vs_baseline: Dimensionless ratio recent/baseline. Thresholds should be defined in your business context, not assumed.
- activity and congestion: Categorical summaries. Keep for UX and backward compatibility. Do not reverse-engineer categories; rely on the numeric ratio for math.
- data.meta.data_lag_days: Human-readable guidance on refresh cadence; do not parse as a number.
Operational guidance: caching, retries, and idempotency
Because PortWatch republishes weekly, the as_of date is stable until the next refresh. Implement client-side caching keyed by port and as_of. This avoids re-fetching the same snapshot and ensures reproducible analytics. If you fetch hourly, short-circuit updates unless as_of changes.
- Cache key: port=CNGGZ + as_of string.
- Retry policy: Standard transient network retry with exponential backoff; avoid aggressive polling since data updates weekly.
- Idempotency: Write your warehouse upsert on (port_code, as_of) to prevent duplicates when backfilling.
- Rate limits: Guests without an API key are limited to 100 requests per day per IP; add your key via X-API-Key to avoid hitting the limit in CI or schedulers.
Additional JSON examples for parsing and testing
The following examples are complete responses you can use to validate parsers and tests. These examples mirror the official structure and values to ensure your code handles the exact field names and nesting consistently.
{
"success": true,
"data": {
"results": [
{
"port": "Guangzhou (Nansha)",
"locode": "CN GGZ",
"country": "China",
"activity": "moderate",
"congestion": "moderate",
"as_of": "2026-11-06",
"metrics": {
"recent_avg_portcalls_per_day": 26.7,
"baseline_avg_portcalls_per_day": 27.4,
"ratio_vs_baseline": 0.97
}
}
],
"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": "fdba8d3a-1e9a-4801-8aff-217eb5434c52"
}
}
{
"success": true,
"data": {
"results": [
{
"port": "Guangzhou (Nansha)",
"locode": "CN GGZ",
"country": "China",
"activity": "moderate",
"congestion": "moderate",
"as_of": "2026-11-06",
"metrics": {
"recent_avg_portcalls_per_day": 26.7,
"baseline_avg_portcalls_per_day": 27.4,
"ratio_vs_baseline": 0.97
}
}
],
"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": "fdba8d3a-1e9a-4801-8aff-217eb5434c52"
}
}
{
"success": true,
"data": {
"results": [
{
"port": "Guangzhou (Nansha)",
"locode": "CN GGZ",
"country": "China",
"activity": "moderate",
"congestion": "moderate",
"as_of": "2026-11-06",
"metrics": {
"recent_avg_portcalls_per_day": 26.7,
"baseline_avg_portcalls_per_day": 27.4,
"ratio_vs_baseline": 0.97
}
}
],
"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": "fdba8d3a-1e9a-4801-8aff-217eb5434c52"
}
}
Integration checklist for Guangzhou (Nansha) dashboards
- Request: GET /api/v1/port-congestion?port=CNGGZ with X-API-Key header.
- Verify: success == true and results list non-empty.
- Extract: as_of, metrics.ratio_vs_baseline, recent_avg_portcalls_per_day, baseline_avg_portcalls_per_day, activity.
- Display: “Guangzhou (Nansha) activity (7d vs 90d; lagged) as_of 2026-11-06: moderate (0.97).”
- Cache: Upsert by (port_code=CNGGZ, as_of) to enforce idempotency.
- Alerting: Trigger if ratio_vs_baseline crosses your materiality threshold; include as_of in the alert payload.
- Docs: Keep a link to the API reference in your runbooks.
Troubleshooting and defensive coding
Empty results: If data.results is empty, do not assume the port is closed. Treat as a temporary unavailability; retry later and surface a warning in dashboards. Keep your last-known-good snapshot for continuity, but mark it stale after your chosen SLA (for example, 14 days after as_of).
Type mismatches: Treat numeric fields as floats and labels as strings. Don’t parse data_lag_days as a number; display it verbatim or ignore it in logic. If you must compute your own lag, use (today - as_of) in days based on your server clock.
Do not infer live wait times: This API does not provide anchorage or berth delay in hours. If stakeholders request “live” congestion, clarify that this endpoint measures activity vs baseline, with a weekly lag.
Compliance notes and gotchas to avoid
- Do not quote freight rate USD fares from other sources as “today’s price” when presenting these metrics; this endpoint is unrelated to rate quotes.
- Present Guangzhou (Nansha) data only when the port parameter is CNGGZ; do not substitute sibling ports to fill dashboards.
- Keep the authentication header exactly as X-API-Key with YOUR_API_KEY in examples. Never embed real keys in public repositories.
Quick reference: Guangzhou (Nansha) endpoint and docs
- Endpoint: https://freightpulsehq.com/api/v1/port-congestion?port=CNGGZ
- Auth header: X-API-Key: YOUR_API_KEY
- Docs: Documentation
FAQ
Is this “live” congestion for Guangzhou (Nansha)?
No. It is a PortWatch-based activity proxy (7-day average of port calls vs a 90-day baseline) with a lag. Use as_of to understand the reference date.
Which field should I alert on?
Use metrics.ratio_vs_baseline for thresholds. Include as_of in notifications. Show activity as a human-readable label in the alert text.
What timezone is as_of in?
The sample shows a date (YYYY-MM-DD) without a time component. Treat it as a date-only anchor; do not assume a timezone.
How often should I poll the endpoint?
Because PortWatch republishes weekly, polling more than once per day rarely adds value. Cache by as_of and short-circuit updates until it changes.
What happens without an API key?
Guests are limited to 100 requests per day per IP. For scheduled jobs and CI, add your key using the X-API-Key header.
Get access
Start integrating Guangzhou (Nansha) congestion into your ops stack. Create an account and get an API key here: Register. Then copy the cURL above, read the fields described here, and wire up your alerts and dashboards with the lag-aware logic outlined in this guide.