Home → Blog

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.

Illustration: Colombo Congestion Today

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

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:

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:

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:

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

Copy guidance to avoid user confusion

Polling cadence

Field mapping cheat sheet

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

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.