Home → Blog

Logistics teams moving containers through Tianjin Xin Gang often ask a specific, technical question: “How congested is the port right now relative to its normal operating baseline?” By the end of this guide, you will be able to query FreightPulse’s Transportation API for Tianjin’s congestion signal, understand how the 7-day average vs 90-day baseline is computed, and integrate the response into your scheduling, ETD/ETA buffers, or carrier allocation logic.

What the Tianjin congestion signal measures and when to use it

The FreightPulse port congestion endpoint for Tianjin Xin Gang provides a standardized congestion level derived from IMF PortWatch. It compares the last 7 days of port calls to a 90-day baseline for the same port. This is a lagged indicator (~6–7 days), updated daily as new AIS-derived aggregates are published. It is not a live vessel wait-time feed, and it does not measure anchorage queues in real time.

Illustration: Tianjin Xin Gang Port Congestion API

Use this signal when you need a consistent, time-series-quality indicator to inform transportation planning, weekly capacity reviews, or near-term risk flags. Do not use it as a live AIS or berth-occupancy proxy. For operations that require minute-by-minute anchorage status, treat this as a complementary macro signal rather than a substitute.

Endpoint overview: GET /api/v1/port-congestion

Endpoint:

Core fields returned for Tianjin Xin Gang:

Envelope:

ORIGIN CATALOG FACTS (authoritative quick-reference)

Quickstart: cURL request you can paste into a terminal

Authenticate with an API key in the X-API-Key header. Guests may omit the header, but are limited to 100 requests/day per IP. Replace YOUR_API_KEY with your key if you have one.

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

Notes:

Official JSON example and how to read it

Below is the official sample response for Tianjin. Copy it into your test fixtures if needed. Remember this is a lagged macro signal, not live AIS wait times.

{
"success": true,
"data": {
"results": [
{
"port": "Tianjin Xin Gang",
"locode": null,
"country": "China",
"congestion": "moderate",
"as_of": "2026-09-25",
"metrics": {
"recent_avg_portcalls_per_day": 29.9,
"baseline_avg_portcalls_per_day": 29.7,
"ratio_vs_baseline": 1
}
}
],
"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": "b0502b4e-0227-41b5-a502-6e3555496584"
}
}

What you will actually use in code:

JavaScript example: fetch Tianjin congestion and normalize for planning

This example queries the endpoint, extracts Tianjin’s congestion, and converts the ratio_vs_baseline into a simple numeric score you can plug into a scheduling buffer rule. Keep the X-API-Key header as shown.

async function fetchTianjinCongestion() {
const url = "https://freightpulsehq.com/api/v1/port-congestion?port=Tianjin";
const res = await fetch(url, {
headers: {
"X-API-Key": "YOUR_API_KEY"
}
});
if (!res.ok) {
throw new Error(`HTTP ${res.status}`);
}
const json = await res.json();
if (!json.success || !json.data || !Array.isArray(json.data.results) || json.data.results.length === 0) {
throw new Error("Malformed response");
}

const tianjin = json.data.results[0];
const level = tianjin.congestion; // "low" | "moderate" | "high" (categorical)
const asOf = tianjin.as_of; // "YYYY-MM-DD", lagged ~6-7 days
const ratio = tianjin.metrics?.ratio_vs_baseline; // number (dimensionless)

// Example: map congestion to a buffer multiplier for schedules (illustrative only)
const bufferByLevel = { low: 1.00, moderate: 1.05, high: 1.12 };
const multiplier = bufferByLevel[level] ?? 1.00;

return {
port: tianjin.port,
asOf,
level,
ratio,
recentAvg: tianjin.metrics?.recent_avg_portcalls_per_day,
baselineAvg: tianjin.metrics?.baseline_avg_portcalls_per_day,
planningBufferMultiplier: multiplier
};
}

// Usage
fetchTianjinCongestion()
.then(data => {
console.log("Tianjin congestion snapshot:", data);
})
.catch(err => {
console.error("Failed to load Tianjin congestion:", err);
});

Implementation notes:

Operational guidance: cadence, caching, and integration boundaries

Update cadence and lag:

Caching and polling:

Error handling and envelopes:

Units and formats:

Building production checks for Tianjin integration

1) Schema and content validation

2) Thresholding and alerting

3) Display and UX

End-to-end workflow example for transportation planning

Documentation and onboarding

For endpoint references and integration details, see the official docs and register for an API key:

FAQ

Is this a live anchorage or berth wait-time feed?
No. It is a lagged, daily-updated signal from IMF PortWatch that compares the last 7 days of port calls to a 90-day baseline. It is not live AIS wait-time data.

How often should I poll for Tianjin Xin Gang?
Once per day is typically sufficient because the underlying dataset updates daily and reflects data with a ~6–7 day lag.

What should I display to users?
Show congestion, ratio_vs_baseline, recent and baseline port calls, and the as_of date. Make it clear that the value is lagged and not a real-time queue length.

What happens if my request has no API key?
Guest access is allowed with 100 requests/day per IP. For higher volumes or multi-port coverage, include X-API-Key: YOUR_API_KEY in the header.

Do I need to handle pagination?
For a single-port query like Tianjin, parse data.results[0]. If you query multiple ports in one call, process the results array; the response format shows an envelope but does not require pagination parameters for the single-port use case documented here.

Get a working key and wire Tianjin Xin Gang’s congestion signal into your transportation planning today. Create your account on the Register page, then keep the docs open for field-by-field references at Documentation.