Home → Blog

You’re planning sailings through Laem Chabang (THLCH) and need a single, dependable signal to decide whether to re-time port calls or flag risks in your schedule. By the end of this guide, you’ll query FreightPulse for THLCH congestion/activity, understand what the fields mean (and what they do not), and drop working code into your integration to cache, alert, and annotate sail plans.

What FreightPulse’s THLCH congestion actually measures

FreightPulse’s congestion endpoint for Laem Chabang (THLCH) is sourced from IMF PortWatch. The signal is lagged (typically about 6–7 days because PortWatch republishes the daily series weekly), and it represents a seven-day average of port-call volume compared to a 90-day baseline for the same port. In the payload you’ll see “activity” and a deprecated alias “congestion,” which reflect relative call volume, not vessel wait time at anchorage or berth.

Illustration: Laem Chabang (THLCH) Congestion

That distinction matters operationally: lower-than-usual calls can coincide with disruptions, holidays, or weather that also affect anchorage time, but this metric does not directly measure time-in-queue. Treat it as a reliable, standardized activity index you can trend and alert on, rather than a live AIS wait-time feed.

Endpoint, auth, and request envelope

Use an HTTP GET to the congestion endpoint with the UN/LOCODE:

Because the data is lagged by design, you don’t need to poll minute-by-minute. Daily pulls (or whenever PortWatch republishes) are sufficient for most workflows. Cache responses and key off the as_of date to avoid redundant work.

Copy-paste cURL for Laem Chabang (THLCH)

Here’s the exact cURL you can run. It queries Laem Chabang using its LOCODE (THLCH) and includes the correct auth header:

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

Official JSON example and the fields that matter

The response is wrapped in a success/data envelope. Below is the official sample for THLCH. Use it to shape your parser and to understand field locations and types.

{
    "success": true,
    "data": {
        "results": [
            {
                "port": "Laem Chabang",
                "locode": "TH LCH",
                "country": "Thailand",
                "activity": "moderate",
                "congestion": "moderate",
                "as_of": "2026-11-13",
                "metrics": {
                    "recent_avg_portcalls_per_day": 21,
                    "baseline_avg_portcalls_per_day": 18.9,
                    "ratio_vs_baseline": 1.11
                }
            }
        ],
        "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": "b0caeb0a-9a1e-43ec-b9f8-2f8ed99d1032"
    }
}

Fields you’ll likely wire into your app:

Python example: fetch, validate, and normalize THLCH

This sample calls the THLCH endpoint, validates the response envelope, extracts the activity and ratio_vs_baseline, and demonstrates a simple cache guard using the as_of date. Replace YOUR_API_KEY with your key, or omit the header to operate within the guest quota.

import os
import requests
from datetime import datetime

API_URL = "https://freightpulsehq.com/api/v1/port-congestion"
PORT = "THLCH"
API_KEY = os.getenv("FREIGHTPULSE_API_KEY", "YOUR_API_KEY")

def fetch_thlch():
headers = {"X-API-Key": API_KEY} if API_KEY else {}
resp = requests.get(API_URL, params={"port": PORT}, headers=headers, timeout=20)
resp.raise_for_status()
data = resp.json()

# Basic envelope validation
if not isinstance(data, dict) or not data.get("success") or "data" not in data:
raise ValueError("Unexpected response envelope")

payload = data["data"]
results = payload.get("results", [])
if not results:
raise ValueError("No results for THLCH")

r0 = results[0]
# Extract core fields
activity = r0.get("activity") # alias: "congestion"
as_of = r0.get("as_of") # "YYYY-MM-DD"
metrics = r0.get("metrics", {})
ratio_vs_baseline = metrics.get("ratio_vs_baseline")
recent = metrics.get("recent_avg_portcalls_per_day")
baseline = metrics.get("baseline_avg_portcalls_per_day")

# Parse as_of to a date (treat as UTC day tick)
as_of_date = datetime.strptime(as_of, "%Y-%m-%d").date() if as_of else None

# Example: Only update cache if as_of advanced
# (Persist last_as_of in your database/kv store; shown here as a variable)
# last_as_of = read_from_store("thlch_as_of")
# if last_as_of == as_of: return cached_value

normalized = {
"port": r0.get("port"),
"locode": r0.get("locode"),
"country": r0.get("country"),
"as_of": as_of,
"activity": activity,
"ratio_vs_baseline": ratio_vs_baseline,
"recent_calls_per_day": recent,
"baseline_calls_per_day": baseline,
"source": payload.get("meta", {}).get("source"),
"data_lag": payload.get("meta", {}).get("data_lag_days"),
}

return normalized

if __name__ == "__main__":
thlch = fetch_thlch()
print(f"[{thlch['as_of']}] THLCH activity={thlch['activity']} ratio={thlch['ratio_vs_baseline']}")

Interpreting THLCH activity reliably in your workflow

Map the categorical activity/congestion to user-facing labels and thresholds you can alert on. For example, you might render “moderate” with a neutral alert and only escalate to ops review when the ratio_vs_baseline exceeds a threshold (e.g., above 1.25 or below 0.75) for multiple consecutive days. Because the series is a seven-day average, single-day blips are already smoothed.

If you need to compare across ports, use ratio_vs_baseline rather than raw calls/day. Calls vary widely by port size and trade mix; the ratio is a normalized measure. Within a single port (like THLCH), both the recent and baseline call counts are useful for operational context.

Lag, caching, retries, and data hygiene

What not to infer from the THLCH endpoint

Do not treat activity/congestion as live anchorage or berth wait time; it is not a live AIS queue-length metric. Avoid interpolating to real-time or quoting arrival ETAs based solely on this number. Also, do not present a freight rate in USD and imply it is “today’s price” based on this series; the endpoint carries no pricing and should not be used to infer current market rates.

UI suggestions for Laem Chabang planners

Error handling and edge cases

Going from single-port to multi-port without surprises

If you later add other ports alongside THLCH, reuse the same endpoint pattern with the respective UN/LOCODEs. Normalize all ports to ratio_vs_baseline for apples-to-apples comparisons. Keep the as_of date visible across all rows to make the lag explicit and to help operators distinguish real operational calm from mere data recency.

Common pitfalls to avoid

Where to find the docs and get an API key

For additional parameters, schema notes, and product-wide behavior, see the Documentation. To raise quotas and get dedicated API access, create an account via Register.

FAQ

Is this a live AIS-based wait-time metric for Laem Chabang?

No. It’s an IMF PortWatch-derived activity index with a seven-day average vs a 90-day baseline. It’s typically 6–7 days lagged and does not measure anchorage or berth wait time.

How often should I refresh THLCH congestion?

Daily is sufficient. Key your cache to the as_of date. If it hasn’t advanced, skip updates.

Which field should I alert on: activity or ratio_vs_baseline?

Use ratio_vs_baseline for numeric thresholds and activity for categorical badges. Both are derived from the same series; activity is a human-readable bucket.

What units are in recent_avg_portcalls_per_day and baseline_avg_portcalls_per_day?

They are counts of port calls per day. ratio_vs_baseline is unitless (recent divided by baseline).

Can I use this data to quote freight rates?

No. Do not present a USD fare as a current price based on this endpoint. It does not provide pricing.

Get started

Point your integration at THLCH using the cURL above, wire up the Python example, and display the activity, ratio_vs_baseline, and as_of alongside your Laem Chabang schedules. When you’re ready for higher throughput and production keys, create an account at Register, and keep the Documentation handy for schema details and integration notes.