Home → Blog

You’re trying to answer a simple question for your ops team: how congested is Jebel Ali (AEJEA) right now, and how should we plan berthing and schedules? By the end of this post you’ll be able to programmatically pull the latest IMF PortWatch–based congestion activity for AEJEA from the FreightPulse API, interpret the fields that matter, and wire them into dashboards, alerts, and ETAs without confusing this signal with live AIS wait times.

What this dataset is (and isn’t) for AEJEA

The FreightPulse port congestion endpoint reports a normalized activity signal derived from IMF PortWatch. It compares the average port calls in the last seven days against a 90‑day baseline for the same port. This helps you understand whether call volume is running hot or cold relative to normal.

Illustration: Jebel Ali (AEJEA) Congestion

It is not a live anchorage or berth wait-time feed. There is an inherent lag (PortWatch republishes about weekly), so treat this as a near-term trend line rather than a minute-by-minute operational feed. Use it to shape planning and capacity conversations, not to predict whether a vessel will wait two hours versus six today.

AEJEA integration facts you should keep handy

If you need endpoint reference details beyond this article, see the Documentation.

Call the AEJEA port congestion endpoint

Use a simple GET with the UN/LOCODE in the port parameter. Include your API key via the X-API-Key header. Guest access without a key is available but limited by IP per day; for production systems you’ll want a key.

Official sample request for AEJEA:

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

The official JSON structure and what to read

The response is wrapped in a success/data envelope. Below is the official sample for AEJEA. Copy it as a field map example and test against the live endpoint to fetch the latest as_of.

{
    "success": true,
    "data": {
        "results": [
            {
                "port": "Jebel Ali",
                "locode": "AE JEA",
                "country": "United Arab Emirates",
                "activity": "high",
                "congestion": "high",
                "as_of": "2026-11-13",
                "metrics": {
                    "recent_avg_portcalls_per_day": 5.9,
                    "baseline_avg_portcalls_per_day": 4.7,
                    "ratio_vs_baseline": 1.24
                }
            }
        ],
        "global_summary": {
            "ports_high_activity": 1,
            "ports_moderate_activity": 0,
            "ports_low_activity": 0,
            "ports_high_congestion": 1,
            "ports_moderate": 0,
            "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": "2a5a320c-245c-48f1-9d6c-aba1892c6ddd"
    }
}

Fields you’ll actually use:

Interpreting AEJEA for operations

For Jebel Ali, ratio_vs_baseline above 1.0 indicates busier-than-usual call volume. In the sample, 1.24 means the last week’s daily call count is about 24% higher than the 90‑day baseline. This often correlates with tighter berth windows and stronger yard utilization, but it does not measure anchorage or wait time.

When presenting to planners, display both the categorical activity and the numeric ratio so users can compare across weeks. Keep the as_of date prominent; it explains why a chart might “lag” recent anecdotal reports.

Production-grade fetch: Python example

The snippet below calls the same endpoint, extracts the fields you need, and prints a compact summary you can feed into logs or metrics. It preserves the envelope and checks basic edge cases.

import os
import requests
from datetime import datetime

API_KEY = os.getenv("FREIGHTPULSE_API_KEY", "YOUR_API_KEY")
PORT = "AEJEA"
URL = f"https://freightpulsehq.com/api/v1/port-congestion?port={PORT}"

headers = {"X-API-Key": API_KEY}

def fetch_aejea_congestion():
r = requests.get(URL, headers=headers, timeout=20)
r.raise_for_status()
payload = r.json()
if not payload.get("success"):
raise RuntimeError("API returned success=false")
data = payload.get("data", {})
results = data.get("results", [])
if not results:
return None

row = results[0]
metrics = row.get("metrics", {})
return {
"port": row.get("port"),
"locode": row.get("locode"),
"as_of": row.get("as_of"), # YYYY-MM-DD
"activity": row.get("activity"),
"congestion": row.get("congestion"), # alias of activity
"recent_avg_calls_per_day": metrics.get("recent_avg_portcalls_per_day"),
"baseline_avg_calls_per_day": metrics.get("baseline_avg_portcalls_per_day"),
"ratio_vs_baseline": metrics.get("ratio_vs_baseline"),
"source": data.get("meta", {}).get("source"),
"data_lag_days": data.get("meta", {}).get("data_lag_days"),
}

def main():
result = fetch_aejea_congestion()
if not result:
print("No data returned for AEJEA")
return

print(
f"{result['port']} ({result['locode']}) as_of={result['as_of']} "
f"activity={result['activity']} ratio={result['ratio_vs_baseline']}"
)
print(
f"recent={result['recent_avg_calls_per_day']} calls/day | "
f"baseline={result['baseline_avg_calls_per_day']} calls/day"
)
print(f"source={result['source']} | lag={result['data_lag_days']}")

if __name__ == "__main__":
main()

How to present AEJEA activity in a dashboard

Translate the ratio into a simple, stable scale. For example: below 0.9 “low,” 0.9–1.1 “normal,” above 1.1 “high.” Do not hardcode thresholds without labeling the as_of date; users need to see both the category and the time reference.

Display:

Caching, refresh cadence, and reliability notes

Because the underlying series is republished about weekly and represents a 7-day average, it will not change intraday. You can cache per-port responses until you detect a new as_of value. A daily refresh is usually sufficient, but check responses for metadata changes when your job runs.

Consider these guardrails:

Error handling and edge cases to test

Minimal JavaScript fetch (optional)

If you prefer a browser-side prototype or a Node.js service, this minimal example pulls the same fields. For browsers, place your key server-side and proxy requests to avoid exposing credentials.

async function getAEJEA() {
const url = "https://freightpulsehq.com/api/v1/port-congestion?port=AEJEA";
const res = await fetch(url, {
headers: { "X-API-Key": "YOUR_API_KEY" }
});
if (!res.ok) throw new Error("HTTP " + res.status);
const payload = await res.json();
if (!payload.success) throw new Error("API success=false");

const row = (payload.data.results || [])[0];
if (!row) return null;

const m = row.metrics || {};
return {
as_of: row.as_of,
activity: row.activity,
congestion: row.congestion,
ratio_vs_baseline: m.ratio_vs_baseline,
recent_avg_calls_per_day: m.recent_avg_portcalls_per_day,
baseline_avg_calls_per_day: m.baseline_avg_portcalls_per_day,
source: payload.data.meta && payload.data.meta.source
};
}

getAEJEA()
.then(d => console.log("AEJEA:", d))
.catch(err => console.error(err));

Field-by-field checklist for AEJEA

Testing plan: make AEJEA robust in staging

1) Schema validation

Create a lightweight JSON schema that verifies success is boolean, data.results is an array, and the metrics fields are numbers when present. Reject responses that deviate, and log raw payloads for future diagnosis.

2) Deterministic rendering

When results is empty, render a neutral “Data not available (as_of n/a)” state. When populated, render all values from a single row to avoid mixing timestamps across renders.

3) Idempotent caches

Key cache entries by port and as_of. If the endpoint returns the same as_of twice in a row, avoid reprocessing charts and alerts.

FAQ

Is this a live queue-length or anchorage-wait metric?
No. It’s IMF PortWatch activity: a 7-day average of port calls vs a 90-day baseline. It does not measure time-at-anchor or berth wait.

How fresh is AEJEA data?
Expect a lag of several days. PortWatch republishes roughly once a week; always display the as_of field.

Which field should I alert on?
Use metrics.ratio_vs_baseline for numeric thresholds, and activity for categorical alerts. Include as_of in the alert message.

What’s the authentication model?
Pass your key in the X-API-Key header. Guests can make limited requests per IP each day; use a key for production.

Can I quote today’s freight rate alongside this?
Don’t present a USD freight rate as “today’s price” based on this dataset. It’s unrelated to instant rate discovery.

Ready to integrate AEJEA congestion into your stack? Get an API key and start querying with a single call. Register and check the Documentation for endpoint details and update cadence.