Home → Blog

You’re trying to answer a concrete question for Savannah (USSAV): is congestion up or down versus normal, and can you automate that signal reliably without scraping ship-by-ship AIS waits? By the end of this post you’ll call the FreightPulse Port Congestion endpoint for USSAV, understand its 6–7 day lag, and extract the 7-day average vs 90-day baseline fields you need to power alerts or dashboards.

What this dataset measures (and what it does not)

The FreightPulse port congestion endpoint for Savannah reports recent port-call activity levels sourced from IMF PortWatch, not live anchorage or berth waiting times. The signal is a 7-day average of port calls compared against a 90-day baseline for the same port. Lower recent activity can correlate with disruptions, but it does not directly measure vessel wait duration offshore or at berth.

Illustration: Savannah Congestion Today

Practically, you will consume three fields to operationalize the metric:

The lag: IMF PortWatch republishes weekly

Expect a lag of roughly 6–7 days for Savannah relative to “today.” PortWatch republishes the daily series in weekly batches, so the most recent date you see in as_of can be several days behind the calendar. This is by design and avoids confusing PortWatch’s research-grade rollups with live AIS-based wait time feeds.

Actionably, treat as_of as the authoritative “data freshness” indicator. Do not label this data as live or near-real-time AIS wait times. If you need a streaming wait-time product, treat that as a separate source entirely.

Reference: API facts for Savannah (USSAV)

Call the endpoint for Savannah

Use the port query parameter with the UN/LOCODE-like identifier USSAV. The service responds with a JSON envelope and a data.results array. For Savannah, expect a single-element results array keyed to the specific port.

Copy-pasteable cURL:

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

Official JSON example and the fields you’ll use

Below is the official sample for USSAV. Use it to shape your parser and tests.

{
    "success": true,
    "data": {
        "results": [
            {
                "port": "Savannah",
                "locode": "US SAV",
                "country": "United States",
                "activity": "moderate",
                "congestion": "moderate",
                "as_of": "2026-11-13",
                "metrics": {
                    "recent_avg_portcalls_per_day": 5.4,
                    "baseline_avg_portcalls_per_day": 5.8,
                    "ratio_vs_baseline": 0.94
                }
            }
        ],
        "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": "1068a442-33a9-4466-8812-8f6302694e10"
    }
}

Field usage:

Minimal Python integration: fetch, validate lag, and extract the ratio

This example requests Savannah’s congestion, checks the as_of date so you don’t present it as live, and returns the qualitative band and ratio_vs_baseline ready for alerting or dashboards.

import os
import requests
from datetime import datetime, timezone

API_KEY = os.getenv("FREIGHTPULSE_API_KEY", "YOUR_API_KEY")
URL = "https://freightpulsehq.com/api/v1/port-congestion?port=USSAV"

def fetch_savannah_congestion():
headers = {"X-API-Key": API_KEY}
resp = requests.get(URL, headers=headers, timeout=20)
resp.raise_for_status()
payload = resp.json()

if not payload.get("success"):
raise RuntimeError("API returned success=false")

data = payload.get("data", {})
results = data.get("results", [])
if not results:
raise ValueError("No results for USSAV")

item = results[0]

# Required fields
as_of = item.get("as_of")
congestion_band = item.get("congestion") # alias of activity
metrics = item.get("metrics", {})
ratio = metrics.get("ratio_vs_baseline")

if as_of is None or ratio is None or congestion_band is None:
raise KeyError("Missing required fields: as_of, congestion, or metrics.ratio_vs_baseline")

# Parse the as_of (date string, not a timestamp)
as_of_date = datetime.strptime(as_of, "%Y-%m-%d").date()

return {
"as_of": as_of_date.isoformat(),
"congestion": congestion_band,
"ratio_vs_baseline": ratio,
}

if __name__ == "__main__":
try:
result = fetch_savannah_congestion()
print(f"Savannah (USSAV) as_of={result['as_of']} congestion={result['congestion']} ratio_vs_baseline={result['ratio_vs_baseline']}")
except Exception as e:
raise

How to interpret Savannah’s ratio_vs_baseline

Use the ratio for a direction-of-travel signal, not a literal measure of queueing or dwell:

Do not relabel the qualitative “congestion” band as “anchorage wait.” It is a categorical view of activity vs baseline.

Being explicit about time, caching, and updates

Error handling and guardrails for production

Embedding Savannah’s congestion into dashboards and alerts

Common triggers for Savannah (USSAV):

When integrating with notifications, include the port code (USSAV) and the as_of date in the message body so recipients know the observation window.

Key implementation details that save time

Security and access

Authenticate with X-API-Key: YOUR_API_KEY. Store your key in a secret manager or environment variable and inject it at runtime. Avoid embedding live keys in frontend code or mobile apps; proxy calls through your backend when building public dashboards for Savannah.

Operational playbook for Savannah (USSAV)

1) Fetch and validate freshness

Call the endpoint once per day on your data pipeline schedule. If the as_of date has advanced, propagate the new value through your cache and refresh dashboards. If not, suppress updates.

2) Normalize fields for your warehouse

3) Alert thresholds that respect the lag

Use multi-update smoothing (e.g., two consecutive publications) before paging on-call. The weekly republishing cadence means single-point moves shouldn’t immediately drive escalations.

Troubleshooting Savannah-specific pulls

FAQ

Does this tell me how many hours ships are waiting outside Savannah?
No. The dataset reports port-call activity (7-day average vs 90-day baseline) from IMF PortWatch. It does not measure anchorage or berth wait times.

How fresh is Savannah’s congestion data?
Expect a lag of about 6–7 days, as PortWatch republishes the daily series weekly. Always display the as_of date to indicate freshness.

What fields should I store to monitor changes over time?
Store as_of, congestion (activity band), metrics.ratio_vs_baseline, metrics.recent_avg_portcalls_per_day, and metrics.baseline_avg_portcalls_per_day. Use as_of as your partition key.

Do I need an API key?
You can make up to 100 requests per day per IP without a key. For production use, add X-API-Key: YOUR_API_KEY to increase reliability and capacity.

Why does the endpoint return an array for a single port?
The API standardizes responses as a results list. For USSAV queries, read results[0] and still code defensively for empty arrays during upstream refresh windows.

Ready to wire Savannah (USSAV) into your ops and planning flows? Create an account to get your API key and move this integration into production: Register. For field-by-field specs and more examples, see the Documentation.