You need dependable, developer-friendly congestion signals for Qingdao Port to keep transportation schedules and capacity plans on track. By the end of this guide, you’ll query CNQDG congestion from a single HTTP GET, parse the 7-day average vs 90-day baseline signal, and fold it into your applications with caching and alerting built in.
What the Qingdao congestion endpoint actually measures
This endpoint provides an IMF PortWatch-derived signal for Qingdao (CNQDG). It is lagged by roughly 6–7 days and reflects a seven-day average port-call activity versus a ninety-day baseline for the same port. It does not measure live AIS vessel queue length or anchorage wait times.
Key points you will use in your code and dashboards:
- Port congestion is IMF PortWatch, lagged ~6–7 days, 7-day avg vs 90-day baseline — not live AIS.
- Signal is updated daily on a rolling basis, but each day’s value refers to data that is roughly a week behind.
- The method is comparable across ports, but this article focuses on Qingdao (CNQDG) only.
Authentication, request shape, and rate limits
Requests are authenticated with an API key via an HTTP header. Guests without a key are allowed 100 requests per day per IP. Do not embed a real key in client-side code; use server-side calls or secrets management.
- Auth: header X-API-Key: YOUR_API_KEY. Guest without key: 100 requests/day per IP.
- HTTP method: GET
- Endpoint: https://freightpulsehq.com/api/v1/port-congestion?port=
- Port: Qingdao (CNQDG)
Responses use a standard JSON envelope:
- Envelope: {"success":true,"data":{...}}
For full parameter notes and any API-wide service behavior, see the Documentation.
Quick start: cURL for Qingdao (CNQDG)
Run this from a terminal to retrieve the current congestion snapshot for Qingdao. Replace the header value with a real key in production, or omit the header to use guest mode.
curl -H "X-API-Key: YOUR_API_KEY" "https://freightpulsehq.com/api/v1/port-congestion?port=CNQDG"If you build a transport-control dashboard, this call is your minimal source of truth for Qingdao’s recent congestion level.
Response model: fields you will actually use
The JSON below shows the field names and structure returned for CNQDG. Use the top-level envelope to verify success, then read the congestion classification, the as_of date, and the 7-day vs 90-day metrics. The data originates from IMF PortWatch and is lagged daily by approximately a week.
Live FreightPulse congestion for CNQDG.
Source: live
cURL:
JSON:
{
"success": true,
"data": {
"results": [
{
"port": "Qingdao Port",
"locode": "CN QDG",
"country": "China",
"congestion": "moderate",
"as_of": "2026-09-25",
"metrics": {
"recent_avg_portcalls_per_day": 28.7,
"baseline_avg_portcalls_per_day": 29.3,
"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": "70f9349a-4e74-40eb-b5c3-fd6d2754af50"
}
}How to interpret these fields in transportation planning:
- congestion: A categorical label such as “low”, “moderate”, or “high” derived from the ratio_vs_baseline. Useful for color-coding dashboards.
- as_of: The data date in YYYY-MM-DD for which the 7-day average applies. This is not a real-time timestamp.
- metrics.recent_avg_portcalls_per_day: The 7-day rolling average daily port calls. Unit: port calls per day.
- metrics.baseline_avg_portcalls_per_day: The 90-day baseline average daily port calls. Unit: port calls per day.
- metrics.ratio_vs_baseline: A scalar comparing recent activity to baseline. Values below 1.0 typically indicate softer activity versus baseline; above 1.0 indicates stronger.
Note: FreightPulse’s congestion is IMF PortWatch-based and lagged. It is not a live vessel wait-time metric. Use it to understand macro congestion pressure rather than to predict the exact queue at anchorage today.
Python example: fetch CNQDG and route a transportation decision
This snippet retrieves the CNQDG snapshot, reads the core fields, and emits a minimal decision signal you can wire into ETL or a scheduler. It also illustrates safe handling of the response envelope.
import os
import requests
API_URL = "https://freightpulsehq.com/api/v1/port-congestion"
PORT = "CNQDG"
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 reported unsuccessful response")
data = payload.get("data", {})
results = data.get("results", [])
if not results:
raise RuntimeError("No results for port CNQDG")
cnqdg = results[0]
congestion = cnqdg.get("congestion")
as_of = cnqdg.get("as_of")
metrics = (cnqdg.get("metrics") or {})
ratio = metrics.get("ratio_vs_baseline")
recent = metrics.get("recent_avg_portcalls_per_day")
baseline = metrics.get("baseline_avg_portcalls_per_day")
print(f"As of {as_of}, CNQDG congestion: {congestion}")
print(f"7-day vs 90-day ratio: {ratio} | recent: {recent} calls/day | baseline: {baseline} calls/day")
# Example routing rule for transportation ops:
# If congestion is 'high' or ratio is significantly < 1, consider advancing gate-in cutoff or diverting cargo.
if congestion == "high" or (isinstance(ratio, (int, float)) and ratio < 0.9):
action = "Diversion or buffer lead-time recommended"
elif congestion == "moderate":
action = "Monitor and add scheduling slack"
else:
action = "Proceed as planned"
print(f"Action: {action}")Design notes for planners and integrators
CNQDG is a high-throughput port with traffic patterns that exhibit day-of-week and seasonal effects. Because the FreightPulse signal is built on a seven-day rolling average, it already smooths short-term noise. Consider the following when integrating:
- Daily cadence: Poll once after each daily update, then cache.
- Data lag: The “as_of” date indicates which day the seven-day window ends on. It is typically ~6–7 days behind today’s calendar date.
- Alerting: Build simple thresholds on ratio_vs_baseline and the congestion label, and alert when the category changes day to day.
- Forecasting: Treat the ratio as a leading macro indicator for berth pressure rather than an immediate queuing metric.
Transport-specific interpretation of the ratio
ratio_vs_baseline compares recent activity to a 90-day norm:
- ratio ≈ 1.0: Activity close to baseline. Schedules and yard operations should be near normal for seasonal norms.
- ratio < 1.0: Recent port calls are below baseline. Depending on where the threshold sits, this can mean fewer arrivals or throughput than usual; dwell might still vary by terminal mix.
- ratio > 1.0: Elevated activity relative to baseline. Consider adding time buffers to gate-in, drayage appointments, and transshipment cutoffs.
Units: recent_avg_portcalls_per_day and baseline_avg_portcalls_per_day are expressed in port calls per day. Avoid interpreting them as vessel count-on-berth at any instant; they are daily averages over different windows.
Caching, retries, and operational hygiene
Because the signal updates daily with a lag and the payload is small, a simple daily refresh with short-term caching is sufficient:
- Cache key: port=CNQDG.
- TTL: 12 to 24 hours. Invalidate after the daily update or when “as_of” changes.
- Idempotence: The endpoint is read-only; safe to retry on transient 5xx.
- Timeouts: 10–20 seconds are reasonable for server-side requests.
- Backoff: Use exponential backoff with jitter on network or 5xx errors.
Pagination: This snapshot endpoint returns a single list with the requested port’s record. There is no pagination to manage for CNQDG lookups.
Dealing with calendars, weekends, and port operations
“as_of” is a date (YYYY-MM-DD). Even though weekends, holidays, or weather events can affect port calls, the seven-day smoothing reduces day-to-day whipsaw effects. You do not need to align the signal to business days. For planning:
- Use the “as_of” date to anchor your data warehouse time dimension.
- If you blend with live AIS or terminal advisories, label this series clearly as lagged macro congestion to avoid misinterpretation.
- When computing internal KPIs, pair “as_of” with your local timezone conventions in storage; the API date is not a local timestamp.
Error handling and validation for transportation pipelines
Build simple guards to protect your schedules and analytics when upstream data experiences transient anomalies:
- Schema checks: Verify that success is true and that data.results contains at least one object for CNQDG.
- Range checks: Ensure ratio_vs_baseline is a finite number. If missing, keep prior day’s ratio for continuity.
- Versioning: Log the “as_of” value and your fetch timestamp for auditing.
- Change detection: Fire alerts only when congestion or ratio crosses well-defined thresholds to avoid noisy notifications.
Security, environments, and usage limits
Store the X-API-Key in your secret manager. For client apps, go through a backend proxy to avoid exposing keys. Guests without a key can test up to 100 requests/day per IP, which is adequate for development or a small internal dashboard pilot. For production, provision a key through your organization and monitor request volume.
Notes specific to CNQDG JSON availability
No official congestion JSON is published for CNQDG outside of the API. For integration, rely on the endpoint’s envelope and field names shown here: congestion, ratio_vs_baseline, and as_of. Do not substitute values copied from other ports’ fixtures. The cURL and JSON example above demonstrates the field layout you should code against.
Frequently asked questions
Is this a live AIS queue or wait-time metric for Qingdao?
No. Port congestion is IMF PortWatch, lagged ~6–7 days, and reflects a 7-day average vs a 90-day baseline. It is not a live AIS wait-time signal.
How often should I refresh the CNQDG value?
Daily is sufficient. The series updates daily and is lagged; polling more frequently will not produce intraday changes in the congestion value.
What fields should I persist in my transportation data warehouse?
Persist as_of, congestion, metrics.recent_avg_portcalls_per_day, metrics.baseline_avg_portcalls_per_day, and metrics.ratio_vs_baseline. Also log the request timestamp and request_id from the top-level meta for traceability.
Does the endpoint support multiple ports in a single call?
This guide demonstrates a single-port request using the port query parameter. If you need portfolio views, call it once per port and aggregate on your side, then cache daily.
Can I use this to quote freight rates?
No. Do not quote a freight-rates USD fare as today’s price using this endpoint. It is a congestion signal only and not a pricing API.
Next step: integrate CNQDG into your transportation stack
Get an API key and wire the CNQDG endpoint into your scheduler, TMS, or control tower. Start with a daily cron, cache the result, and alert on category changes. Create your account at Register, and keep the docs handy at Documentation for implementation details and production rollout checklists.