Home → Blog

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.

Illustration: Qingdao Congestion Today

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.

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:

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:

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.

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:

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

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)

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.