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.
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
- 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: Jebel Ali (AEJEA)
- curl: curl -H "X-API-Key: YOUR_API_KEY" "https://freightpulsehq.com/api/v1/port-congestion?port=AEJEA"
- No official congestion JSON is published for AEJEA. Show the curl and field names (congestion, ratio_vs_baseline, as_of). Do not reuse the USLAX 0.85 fixture.
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:
- data.results[0].as_of: date of the PortWatch series (YYYY-MM-DD). Use this to label charts and caches.
- data.results[0].activity: categorical activity state derived from ratio vs baseline (e.g., “high”).
- data.results[0].congestion: deprecated alias of activity. Treat it as the same categorical value.
- data.results[0].metrics.recent_avg_portcalls_per_day: last-7-day average calls per day (unit: port calls/day).
- data.results[0].metrics.baseline_avg_portcalls_per_day: 90-day baseline calls/day.
- data.results[0].metrics.ratio_vs_baseline: recent/baseline ratio (unitless; 1.0 is “normal”).
- data.meta.source and data.meta.data_lag_days: provenance and expected refresh cadence; helps you set user expectations and caches.
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:
- as_of date as the x-axis tick or a badge.
- ratio_vs_baseline as a number with one or two decimals.
- recent_avg_portcalls_per_day and baseline in a tiny table so users can sanity-check the ratio.
- activity (or congestion alias) as the user-facing label.
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:
- Don’t merge with live AIS anchorage estimates as if they’re the same signal—keep them in separate panels.
- Don’t compute your own “wait time” from port-call counts. The methodology is explicitly about call volume.
- Log the entire success/data envelope for provenance checks and incident analysis.
Error handling and edge cases to test
- Empty results: results may be an empty array; handle nulls upstream without crashing charts.
- Envelope checks: always confirm success is true before reading data.
- Data lags: if your last-seen as_of is older than your internal SLA, surface a banner noting that the underlying source has not republished yet.
- Unit display: clearly label “calls/day” and “ratio” to avoid conversion mistakes.
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
- congestion and activity: same categorical signal; use activity internally and congestion only for backward compatibility.
- ratio_vs_baseline: your primary numeric KPI. Use it to color charts and to drive alerts.
- as_of: anchor every display. It is the only timeline reference you can trust from this endpoint.
- recent_avg_portcalls_per_day and baseline_avg_portcalls_per_day: display in tooltips for operator trust.
- meta.source and meta.data_lag_days: show once in an info panel so users understand update cadence.
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.