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.
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:
- Method: GET
- URL: https://freightpulsehq.com/api/v1/port-congestion?port=THLCH
- Auth: header X-API-Key: YOUR_API_KEY
- Guest access without a key: up to 100 requests/day per IP
- Envelope format: {"success": true, "data": {...}}
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:
- data.results[0].activity and data.results[0].congestion: categorical signal describing relative call activity (e.g., low, moderate, high). congestion is an alias of activity.
- data.results[0].as_of: the date (YYYY-MM-DD) the metric refers to. Treat it as a daily tick republished weekly; do not assume it’s a live timestamp.
- data.results[0].metrics.ratio_vs_baseline: numeric ratio of last 7 days vs the prior 90-day baseline for the same port (e.g., 1.11 means 11% above baseline).
- data.results[0].metrics.recent_avg_portcalls_per_day and baseline_avg_portcalls_per_day: absolute call counts per day used to compute the ratio. Units are port calls/day.
- data.meta.source and data.meta.data_lag_days: provenance and typical lag window, which you can show in a tooltip to set user expectation.
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
- Lag window: Expect about 6–7 days on average, but the metadata indicates a broader 4–11 day window. Always display the as_of date next to the signal.
- Caching: Cache by port and as_of. If as_of has not changed since your last fetch, keep your cached value. A daily refresh is adequate for most operations dashboards.
- Timeouts and retries: Network errors happen. Use conservative timeouts (10–20s) and at most 2–3 retries with backoff. The data does not change intra-day; avoid hammering the endpoint.
- Guest quota: Without a key, you’re limited to roughly 100 requests/day per IP. With a key, apply the X-API-Key header. Store your key securely.
- Timestamps and timezone: as_of is a YYYY-MM-DD date tick. Treat it as a date sourced from PortWatch’s daily series; do not assume intraday timestamps or infer local time.
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
- Badge the port row: Show “moderate” with a color code and a tooltip explaining source, lag, and as_of.
- Sparkline: Plot ratio_vs_baseline over the last few published dates (if you store history). A flat or rising line above 1.0 can trigger review of berth windows.
- Drilldown: Expose recent_avg_portcalls_per_day and baseline_avg_portcalls_per_day on hover/click for ops specialists who want raw volumes.
- Export: When exporting a schedule for THLCH, append the as_of date so external stakeholders know the recency of the signal.
Error handling and edge cases
- Empty results: Handle cases where data.results is empty. Fallback to “unknown” state with no alert; do not reuse stale values without checking as_of.
- Schema changes: Read fields defensively via .get and gate critical path logic on presence of as_of and ratio_vs_baseline.
- Unit checks: All call counts are per-day integers/floats. The ratio is unitless. Do not cast to percentages in storage; compute percentages at render time.
- Global summary: data.global_summary is optional context. For single-port THLCH workflows, you can ignore it or use it to annotate a global map view.
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
- Polling too frequently: The source is republished weekly; more frequent polling burns quota without fresher data.
- Conflating activity with delay: Elevated activity may correlate with delays, but it is not a measured wait time. Always phrase tooltips accordingly.
- Hiding the as_of: Omitting the date leads users to assume “live” conditions. Always show it.
- Hard-coding thresholds: Expose thresholds in config, not code, so ops can tune alert sensitivity for THLCH without redeploying.
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.