You need a dependable way to track congestion at Qingdao (CNQDG) so you can plan berthing windows and schedule containers without relying on rumor or live AIS chatter. By the end of this post you will be able to query FreightPulse’s API for Qingdao, understand what the IMF PortWatch lag means for the numbers you see, and ship a small integration that parses the congestion fields you actually need.
What FreightPulse reports for Qingdao and why it lags
FreightPulse’s port congestion for Qingdao (CNQDG) is sourced from IMF PortWatch. The series is lagged roughly 6–7 days and expresses a 7‑day average compared against a 90‑day baseline. This is not a live AIS wait-time feed; it is an aggregated, methodologically consistent indicator designed to smooth day-to-day noise.
In practice, you will read three fields for each observation if data is available for CNQDG: congestion (the 7‑day average level), ratio_vs_baseline (how the 7‑day average compares to the last 90 days), and as_of (the date the observation pertains to). Always treat these as historical indicators with a short lag and do not use them as a live operational queue length.
Getting access, headers, and the response envelope
Authentication is simple: send your API key in the header X-API-Key. Guests without a key can make up to 100 requests per day per IP, which is often enough to prototype. Every response is wrapped in an envelope shaped like {"success":true,"data":{...}} so you can check success before touching the payload.
- Auth header: X-API-Key: YOUR_API_KEY
- Guest limit: 100 requests/day per IP
- Envelope: {"success":true,"data":{...}}
- Endpoint: /api/v1/port-congestion?port=CNQDG
If you are building beyond a quick test, register for an API key so you can deploy with predictable limits: Register. For endpoint specifics and field references, see the Documentation.
CNQDG endpoint: cURL you can copy and run
The port you care about is Qingdao, code CNQDG. Use the following cURL to fetch its congestion series from FreightPulse:
Live FreightPulse congestion for CNQDG.
Source: live
cURL:
curl -H "X-API-Key: YOUR_API_KEY" "https://freightpulsehq.com/api/v1/port-congestion?port=CNQDG"
At the moment, no official congestion JSON is published specifically for CNQDG. The live sample below shows what you may see when data is not yet available due to an upstream IMF PortWatch issue. When data is available, the data.results array will contain entries with the fields you care about: congestion, ratio_vs_baseline, and as_of.
JSON:
{
"success": true,
"data": {
"results": [],
"available": false,
"reason": "Error querying IMF PortWatch"
},
"meta": {
"request_id": "94773023-5cc5-47ed-8f32-6387ed9b1483"
}
}
What to expect when available for CNQDG:
- data.results: an array of time-stamped observations for Qingdao.
- Each result item should include:
- congestion: the 7‑day average congestion level (unitless indicator derived from IMF PortWatch).
- ratio_vs_baseline: comparison of the 7‑day average to the trailing 90‑day baseline.
- as_of: the date the observation refers to (lagged ~6–7 days).
- data.available: a boolean indicating whether the series is currently retrievable.
- data.reason: a short diagnostic string when available is false.
- meta.request_id: a trace ID you can log for support.
Parsing CNQDG in Python
The snippet below calls the same endpoint as the cURL above, checks the envelope, and safely extracts congestion, ratio_vs_baseline, and as_of if present. It also handles the case where IMF PortWatch data is temporarily unavailable for Qingdao.
Python example
import os
import requests
from typing import List, Dict
API_URL = "https://freightpulsehq.com/api/v1/port-congestion"
PORT = "CNQDG"
API_KEY = os.getenv("FREIGHTPULSE_API_KEY", "YOUR_API_KEY")
def fetch_qingdao_congestion() -> Dict:
headers = {"X-API-Key": API_KEY}
r = requests.get(API_URL, headers=headers, params={"port": PORT}, timeout=20)
r.raise_for_status()
payload = r.json()
if not isinstance(payload, dict) or "success" not in payload:
raise ValueError("Unexpected response envelope")
return payload
def read_latest_observation(results: List[Dict]) -> Dict:
# Results are expected to be time-ordered or include as_of for sorting.
if not results:
return {}
# When multiple observations are present, pick the latest as_of date.
# We avoid assumptions about timezone by treating as_of as a date string.
try:
latest = sorted(results, key=lambda x: x.get("as_of", ""))[-1]
except Exception:
latest = results[-1]
return {
"as_of": latest.get("as_of"),
"congestion": latest.get("congestion"),
"ratio_vs_baseline": latest.get("ratio_vs_baseline"),
}
if __name__ == "__main__":
data = fetch_qingdao_congestion()
if not data.get("success"):
raise SystemExit("Request failed")
d = data.get("data", {})
if not d.get("available", True):
# Upstream lag or transient issue (e.g., "Error querying IMF PortWatch").
print(f"CNQDG congestion unavailable: {d.get('reason')}")
else:
results = d.get("results", [])
obs = read_latest_observation(results)
if not obs:
print("CNQDG congestion: no observations returned")
else:
print(f"Qingdao (CNQDG) as_of={obs['as_of']} "
f"congestion={obs['congestion']} "
f"ratio_vs_baseline={obs['ratio_vs_baseline']}")
Notes for production:
- Timeouts: the example uses 20s; adjust to your environment.
- Caching: since the series lags 6–7 days and represents a 7‑day average, you can safely cache responses per port for hours without losing fidelity.
- Idempotence: reads are safe to retry; add exponential backoff when data.available is false.
Interpretation: 7‑day average vs 90‑day baseline for Qingdao
The congestion field represents a 7‑day average produced from IMF PortWatch inputs. The ratio_vs_baseline compares that 7‑day average to the preceding 90‑day baseline for Qingdao (CNQDG). Use these together to answer two distinct questions: how high congestion is on a smoothed basis, and how unusual it is relative to the recent norm.
- congestion: read as a smoothed level; do not treat as minutes, hours, or vessel counts.
- ratio_vs_baseline: contextualizes the level; greater than 1 means above the 90‑day norm, less than 1 below the norm. Do not invent or assume a specific ratio when it is not provided by the API.
- as_of: grounds the reading in time; plan for this date to be ~6–7 days in the past.
Since this is not a live AIS wait-time or queue-length data set, do not use it to promise same-day berthing or to price same-week demurrage. It is best suited for planning, risk assessment, and week-over-week comparisons for CNQDG.
Working with unavailable data for CNQDG
The official sample above shows available=false with reason "Error querying IMF PortWatch". This typically indicates a transient upstream issue or a window where CNQDG has no published congestion ticks at the moment you query. Your integration should:
- Check data.available before reading data.results.
- Log meta.request_id for support or audit trails.
- Retry with backoff (e.g., 15–60 minutes) instead of rapid-fire polling.
- Fall back to a previously cached observation for dashboards, clearly labeled with as_of.
If you display charts, annotate gaps explicitly rather than extrapolating. Because the series is lagged and smoothed, filling missing points with assumptions can mislead users about recent changes at Qingdao.
Operational tips that save time
- Field names you will actually use: congestion, ratio_vs_baseline, as_of, available, reason, and meta.request_id.
- Timestamps: as_of is a date-like field tied to the observation window. Treat it as authoritative for “when the reading applies.” If no timezone is included, handle it as date-only and avoid timezone math.
- Units and currency: congestion and ratio_vs_baseline are unitless indicators. There is no USD fare or freight-rate price in this endpoint; do not present a fare as if it were today’s price.
- Pagination: this endpoint returns a focused set of results for the requested port. If pagination exists in the future, consult the Documentation. Do not assume pages today.
- Caching: daily caching is often acceptable. For alerting, requery once or twice per day, because the signal lags ~6–7 days.
- Non-trading days equivalent: maritime data does not follow exchange holidays, but because the series is a 7‑day average, weekends are inherently blended into the metric.
- Guest usage: without an API key you are limited to 100 requests/day per IP. That’s enough for prototyping or a low-frequency job. Use an API key before you go to production.
JavaScript alternative (Node) if you prefer fetch
If your stack is JavaScript, this minimal example mirrors the Python logic and reads the same fields for CNQDG.
import fetch from "node-fetch";
const API_URL = "https://freightpulsehq.com/api/v1/port-congestion?port=CNQDG";
const API_KEY = process.env.FREIGHTPULSE_API_KEY || "YOUR_API_KEY";
async function getQingdao() {
const res = await fetch(API_URL, {
headers: { "X-API-Key": API_KEY },
timeout: 20000
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const payload = await res.json();
if (!payload || payload.success !== true) throw new Error("Bad envelope");
const data = payload.data || {};
if (data.available === false) {
console.warn(`CNQDG unavailable: ${data.reason}`);
return null;
}
const results = Array.isArray(data.results) ? data.results : [];
if (results.length === 0) {
console.log("CNQDG: no observations returned");
return null;
}
// Choose latest by as_of if present
results.sort((a, b) => String(a.as_of).localeCompare(String(b.as_of)));
const latest = results[results.length - 1];
return {
as_of: latest.as_of,
congestion: latest.congestion,
ratio_vs_baseline: latest.ratio_vs_baseline
};
}
getQingdao()
.then(obs => {
if (obs) {
console.log(`Qingdao (CNQDG) as_of=${obs.as_of} congestion=${obs.congestion} ratio_vs_baseline=${obs.ratio_vs_baseline}`);
}
})
.catch(err => {
console.error(err);
process.exitCode = 1;
});
End-to-end checklist for Qingdao (CNQDG)
- Use the correct port code: CNQDG.
- Authenticate with X-API-Key. Guests: 100 requests/day per IP.
- Call /api/v1/port-congestion?port=CNQDG.
- Expect the envelope {"success":true,"data":{...}}.
- Read data.available; short-circuit if false and note data.reason.
- From data.results, extract congestion, ratio_vs_baseline, as_of.
- Cache results and clearly label the lag (~6–7 days) in your UI.
- Never present this as live AIS wait times or quote a freight-rate USD fare as a “today” price.
FAQ
Is FreightPulse congestion for Qingdao live?
No. It is derived from IMF PortWatch, lagged about 6–7 days, representing a 7‑day average versus a 90‑day baseline. It is not a live AIS queue or wait-time feed.
What fields should I store?
Store as_of, congestion, ratio_vs_baseline, and the port code (CNQDG). Optionally keep available and reason for operational logs, plus meta.request_id to trace support issues.
Why am I seeing available=false?
This indicates an upstream issue or a temporary gap (e.g., "Error querying IMF PortWatch"). Retry with backoff and keep your last known observation cached and labeled.
How often should I poll?
Because the series is lagged and smoothed, polling once or twice per day is typically sufficient. Respect rate limits; guests are limited to 100 requests/day per IP.
Can I use this to quote today’s freight rate or a live dwell time?
No. Do not quote a freight-rates USD fare as today’s price, and do not present congestion as a live AIS wait time. Use it for planning and comparative analysis at CNQDG.
Set up your Qingdao (CNQDG) congestion integration in minutes. Create an API key and start shipping code today: Register. If you need field-by-field details for your stack, the Documentation covers parameters, response envelopes, and examples for CNQDG.