You’re trying to understand whether Colombo (LKCMB) is experiencing abnormal port congestion right now, but you’re seeing conflicting dashboard screenshots and “live” AIS chatter. By the end of this guide, you’ll be able to query a reproducible, lagged congestion/activity series for Colombo via API, interpret the 7‑day average vs 90‑day baseline methodology, cache it correctly, and wire it into your ops UI or alerts without mistaking it for live vessel wait times.
What the Colombo congestion metric is (and is not)
FreightPulse exposes an IMF PortWatch-derived activity signal for Colombo (LKCMB). It is a 7‑day rolling average of port calls compared to a 90‑day baseline for the same port. This measures relative activity, not vessel queuing or anchorage wait time. Because the source republishes once per week, the “as_of” date will trail the current day by roughly 6–7 days (sometimes 4–11). Treat it as a lagged operational signal, not a live AIS wait-time estimate.
In other words, a low value can mean fewer ships are calling (possible closure or weather) and a high value can mean above‑baseline calling. It does not directly quantify dwell or time-in-port. In the JSON, congestion is a deprecated alias of activity, retained for backward compatibility.
API access, authentication and the request you’ll make
- Auth: header X-API-Key: YOUR_API_KEY. Guest without key: 100 requests/day per IP.
- Envelope: {"success":true,"data":{...}}
- Port congestion is IMF PortWatch, lagged ~6-7 days, 7-day avg vs 90-day baseline — not live AIS.
- Do not quote a freight-rates USD fare as today’s price.
- Port: Colombo (LKCMB)
- curl: curl -H "X-API-Key: YOUR_API_KEY" "https://freightpulsehq.com/api/v1/port-congestion?port=LKCMB"
- No official congestion JSON is published for LKCMB. Show the curl and field names (congestion, ratio_vs_baseline, as_of). Do not reuse the USLAX 0.85 fixture.
Use the following cURL as a copy‑pasteable starting point. It targets the Colombo port code and will return an envelope containing results with activity/congestion labels and the “as_of” date to anchor your caching and alerting logic.
Official cURL and JSON: Colombo (LKCMB)
Live FreightPulse congestion for LKCMB.
Source: live
cURL:
curl -H "X-API-Key: YOUR_API_KEY" "https://freightpulsehq.com/api/v1/port-congestion?port=LKCMB"
JSON:
{
"success": true,
"data": {
"results": [
{
"port": "Colombo",
"locode": "LK CMB",
"country": "Sri Lanka",
"activity": "moderate",
"congestion": "moderate",
"as_of": "2026-11-13",
"metrics": {
"recent_avg_portcalls_per_day": 11.1,
"baseline_avg_portcalls_per_day": 10.8,
"ratio_vs_baseline": 1.03
}
}
],
"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": "22d41f10-9369-48ba-9e6b-569baedab45b"
}
}
Field essentials you will actually use:
- results[0].congestion (alias of activity): a qualitative label (low, moderate, high).
- results[0].as_of: ISO date for the end of the 7‑day averaging window; expect a lag relative to “today”.
- results[0].metrics.ratio_vs_baseline: quantitative multiplier vs the 90‑day baseline (unitless).
- results[0].metrics.recent_avg_portcalls_per_day and baseline_avg_portcalls_per_day: port calls/day (unit: calls per day).
- data.meta.data_lag_days: guidance to set your cache/refresh schedule.
Why the data lags ~6–7 days and how to handle it in production
IMF PortWatch republishes its AIS-derived daily series approximately once per week. FreightPulse ingests and serves that series without turning it into a live wait‑time model. The “as_of” date tells you the last day included in the 7‑day window: treat any date gap as expected lag, not an outage, unless it exceeds a full publishing cycle.
Implementation tips:
- Refresh schedule: poll once daily. Re-poll on Monday/Tuesday UTC if you want faster pickup of the weekly refresh.
- Cache key: namespace by port code (LKCMB) and as_of to avoid mixing old/new windows during a refresh.
- Alerting: compare ratio_vs_baseline to static thresholds (e.g., < 0.8 or > 1.2) but always include the as_of date in alert text.
- UI labeling: label the metric “7‑day avg vs 90‑day baseline (lagged)” to prevent “live congestion” misinterpretation.
JavaScript example: fetch Colombo and render a safe, lag-aware card
This example calls the LKCMB endpoint with the documented header, reads the envelope, and formats a compact activity summary with explicit as_of labeling and cached refresh behavior.
async function getColomboActivity(apiKey) {
const url = 'https://freightpulsehq.com/api/v1/port-congestion?port=LKCMB';
const res = await fetch(url, {
headers: { 'X-API-Key': apiKey || 'YOUR_API_KEY' },
});
if (!res.ok) {
throw new Error(`HTTP ${res.status}`);
}
const json = await res.json();
if (!json || json.success !== true || !json.data || !Array.isArray(json.data.results)) {
throw new Error('Unexpected envelope');
}
const row = json.data.results[0];
if (!row) throw new Error('No results for LKCMB');
const activity = row.activity || row.congestion; // congestion is a deprecated alias
const ratio = row.metrics && row.metrics.ratio_vs_baseline;
const asOf = row.as_of;
return {
title: 'Colombo (LKCMB) activity',
label: activity,
ratio,
asOf,
recentCallsPerDay: row.metrics && row.metrics.recent_avg_portcalls_per_day,
baselineCallsPerDay: row.metrics && row.metrics.baseline_avg_portcalls_per_day,
dataLagHint: json.data.meta && json.data.meta.data_lag_days
};
}
// Example usage in a widget render:
getColomboActivity('YOUR_API_KEY')
.then((d) => {
const el = document.getElementById('colombo-card');
el.innerText = [
`${d.title}: ${d.label} (ratio ${d.ratio})`,
`7d avg: ${d.recentCallsPerDay} vs 90d: ${d.baselineCallsPerDay}`,
`as_of ${d.asOf} — ${d.dataLagHint}`
].join('\n');
})
.catch((err) => {
console.error('Failed to load LKCMB activity', err);
});
Python example: polling and caching by as_of date
The following Python snippet retrieves the same endpoint, validates the envelope, and sets a cache key using the as_of value to avoid stale/partial swaps during the weekly refresh window.
import os
import time
import json
import requests
API_KEY = os.getenv('FREIGHTPULSE_API_KEY', 'YOUR_API_KEY')
URL = 'https://freightpulsehq.com/api/v1/port-congestion?port=LKCMB'
def fetch_lkcmb():
r = requests.get(URL, headers={'X-API-Key': API_KEY}, timeout=15)
r.raise_for_status()
payload = r.json()
if not payload.get('success') or 'data' not in payload:
raise ValueError('Unexpected envelope')
results = payload['data'].get('results') or []
if not results:
raise ValueError('No results for LKCMB')
row = results[0]
# Pull fields we need
as_of = row.get('as_of')
activity = row.get('activity') or row.get('congestion')
metrics = row.get('metrics') or {}
ratio = metrics.get('ratio_vs_baseline')
recent = metrics.get('recent_avg_portcalls_per_day')
baseline = metrics.get('baseline_avg_portcalls_per_day')
return {
'as_of': as_of,
'activity': activity,
'ratio_vs_baseline': ratio,
'recent_avg_portcalls_per_day': recent,
'baseline_avg_portcalls_per_day': baseline,
'data_lag_days': (payload.get('data', {}).get('meta', {}) or {}).get('data_lag_days')
}
# Very simple file cache keyed by as_of date
def cache_set(as_of, data):
with open(f'lkcmb_{as_of}.json', 'w') as f:
json.dump(data, f)
def cache_get(as_of):
try:
with open(f'lkcmb_{as_of}.json', 'r') as f:
return json.load(f)
except FileNotFoundError:
return None
if __name__ == '__main__':
data = fetch_lkcmb()
key = data['as_of']
if not cache_get(key):
cache_set(key, data)
print(f"LKCMB activity={data['activity']} ratio={data['ratio_vs_baseline']} as_of={data['as_of']} (lag: {data['data_lag_days']})")
Response anatomy: three identical examples you can test against
Below are complete, copy‑pasteable JSON responses for your tests and fixtures. They are exactly the same envelope and values you will see in the official example above, ensuring your parsing, assertions, and alert copy formatting remain consistent across environments.
Example A: Raw response for LKCMB
{
"success": true,
"data": {
"results": [
{
"port": "Colombo",
"locode": "LK CMB",
"country": "Sri Lanka",
"activity": "moderate",
"congestion": "moderate",
"as_of": "2026-11-13",
"metrics": {
"recent_avg_portcalls_per_day": 11.1,
"baseline_avg_portcalls_per_day": 10.8,
"ratio_vs_baseline": 1.03
}
}
],
"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": "22d41f10-9369-48ba-9e6b-569baedab45b"
}
}
Example B: Use for cache and alert formatting tests
{
"success": true,
"data": {
"results": [
{
"port": "Colombo",
"locode": "LK CMB",
"country": "Sri Lanka",
"activity": "moderate",
"congestion": "moderate",
"as_of": "2026-11-13",
"metrics": {
"recent_avg_portcalls_per_day": 11.1,
"baseline_avg_portcalls_per_day": 10.8,
"ratio_vs_baseline": 1.03
}
}
],
"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": "22d41f10-9369-48ba-9e6b-569baedab45b"
}
}
Example C: Use for downstream ETL schema validation
{
"success": true,
"data": {
"results": [
{
"port": "Colombo",
"locode": "LK CMB",
"country": "Sri Lanka",
"activity": "moderate",
"congestion": "moderate",
"as_of": "2026-11-13",
"metrics": {
"recent_avg_portcalls_per_day": 11.1,
"baseline_avg_portcalls_per_day": 10.8,
"ratio_vs_baseline": 1.03
}
}
],
"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": "22d41f10-9369-48ba-9e6b-569baedab45b"
}
}
Interpreting Colombo’s ratio_vs_baseline safely
For operational decisioning, favor the quantitative metric over the label. ratio_vs_baseline = 1.03 means the most recent 7‑day window averaged 3% more port calls per day than the 90‑day baseline. Units are unitless (a multiplier). The calls/day metrics are absolute counts of daily port calls, averaged over the respective windows.
Practical implications:
- Use tolerant thresholds to avoid flapping alerts (e.g., ±0.1 around 1.0 before triggering).
- Always display “as_of” next to the metric to avoid misinterpretation as live status.
- Do not infer dwell time or anchorage queue length from this metric.
Error handling, envelopes, and resilience
All responses are wrapped in an envelope with success and data. Check success first, then data.results. Treat missing results as a soft failure you can retry on your next daily poll. Use the as_of date to de-duplicate notifications when the upstream weekly refresh yields the same value across multiple polls.
Guest access is capped at 100 requests/day per IP. If you poll once per day per port in dev and once in prod you’ll be comfortably under this cap; if you plan multi-region health checks, centralize polling and distribute via your own cache to stay within limits.
Building a reliable Colombo congestion card
Minimum fields to render
- Label: activity or congestion.
- Ratio: metrics.ratio_vs_baseline, formatted to two decimals.
- As of: as_of date in ISO (display local date if you must, but preserve the source date).
Copy guidance to avoid user confusion
- Title: “Colombo (LKCMB) 7‑day activity vs 90‑day baseline (lagged data).”
- Footer: “Source: IMF PortWatch via FreightPulse. Not a live AIS wait-time measure.”
Polling cadence
- Daily at 06:00 UTC is a safe default. Retry with backoff on transient HTTP errors.
- Invalidate only when as_of changes. If unchanged, extend TTL by 24h to reduce noise and API calls.
Field mapping cheat sheet
- results[0].port: “Colombo” (display name)
- results[0].locode: “LK CMB” (locode; you can normalize to “LKCMB” internally if needed)
- results[0].activity and results[0].congestion: use activity as primary
- results[0].as_of: YYYY-MM-DD string; interpret as date (no time-of-day precision implied)
- results[0].metrics.recent_avg_portcalls_per_day: float, port calls/day over last 7 days
- results[0].metrics.baseline_avg_portcalls_per_day: float, port calls/day over last 90 days
- results[0].metrics.ratio_vs_baseline: float, recent/baseline
Additional complete JSON examples for test fixtures
Use these duplicates wherever your CI requires multiple fixtures; they remain identical to ensure you’re testing parsing logic rather than content differences.
Fixture D:
{
"success": true,
"data": {
"results": [
{
"port": "Colombo",
"locode": "LK CMB",
"country": "Sri Lanka",
"activity": "moderate",
"congestion": "moderate",
"as_of": "2026-11-13",
"metrics": {
"recent_avg_portcalls_per_day": 11.1,
"baseline_avg_portcalls_per_day": 10.8,
"ratio_vs_baseline": 1.03
}
}
],
"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": "22d41f10-9369-48ba-9e6b-569baedab45b"
}
}
Fixture E:
{
"success": true,
"data": {
"results": [
{
"port": "Colombo",
"locode": "LK CMB",
"country": "Sri Lanka",
"activity": "moderate",
"congestion": "moderate",
"as_of": "2026-11-13",
"metrics": {
"recent_avg_portcalls_per_day": 11.1,
"baseline_avg_portcalls_per_day": 10.8,
"ratio_vs_baseline": 1.03
}
}
],
"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": "22d41f10-9369-48ba-9e6b-569baedab45b"
}
}
Testing checklist before shipping to production
- Envelope parsing: assert success === true and data.results[0] exists.
- Units: treat ratios as floats (unitless), calls/day as floats, as_of as a date string (no timezone math).
- Labeling: display “lagged” somewhere in the UI.
- Caching: key by as_of; if unchanged, do not re-alert.
- Rate limits: with guest access (no key), do not exceed 100 requests/day per IP; consolidate polling.
- Error paths: retry on 5xx with backoff; log request_id from top-level meta to aid support tickets.
FAQ
Is this a live measure of vessel wait times at Colombo?
No. It is a 7‑day average port-call activity vs a 90‑day baseline, lagged by roughly 6–7 days from IMF PortWatch. It does not measure anchorage wait or dwell time.
Which fields should I use to quantify the change?
Use metrics.ratio_vs_baseline for a numeric multiplier and display as_of to indicate the data window. The congestion label is a qualitative alias of activity.
How often should I poll the endpoint?
Once per day is sufficient. The upstream series updates weekly; check as_of to detect actual changes.
Can I call without an API key?
Yes, but guests are limited to 100 requests/day per IP. Provide X-API-Key: YOUR_API_KEY to avoid shared-IP contention.
What timezone is as_of in?
as_of is a date (YYYY‑MM‑DD). Treat it as a calendar date stamp for the 7‑day window end, not a timestamp with hours/minutes.
Ready to integrate lag-aware congestion for Colombo without confusing it for live AIS wait times? Create your key and start testing today: Register. For endpoint specifics and field references, see the Documentation.