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.
Practically, you will consume three fields to operationalize the metric:
- as_of: reporting date for the latest available PortWatch update
- congestion: qualitative activity band (low, moderate, high); a legacy alias of activity
- metrics.ratio_vs_baseline: numeric ratio of recent activity vs baseline
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)
- 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: Savannah (USSAV)
- curl: curl -H "X-API-Key: YOUR_API_KEY" "https://freightpulsehq.com/api/v1/port-congestion?port=USSAV"
- No official congestion JSON is published for USSAV. Show the curl and field names (congestion, ratio_vs_baseline, as_of). Do not reuse the USLAX 0.85 fixture.
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:
- data.results[0].as_of: Date string (YYYY-MM-DD) for the most recent PortWatch publication covering Savannah.
- data.results[0].congestion: A qualitative band; corresponds to activity. This is not a wait-time label.
- data.results[0].metrics.ratio_vs_baseline: Numeric multiplier vs the port’s 90-day baseline. Values below 1.0 indicate fewer recent calls than baseline; above 1.0 indicates more.
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:
- ratio_vs_baseline < 1.0: Fewer recent calls than the port’s 90-day baseline. Could reflect weather closures, labor actions, or ships holding offshore. Investigate further if it persists for multiple updates.
- ratio_vs_baseline ≈ 1.0: Close to typical call volume. Expect normal throughput signals.
- ratio_vs_baseline > 1.0: Above-baseline port calls, potentially indicating catch-up operations or schedule bunching.
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
- Dates and timezone: as_of is a YYYY-MM-DD date string. The series is republished weekly by PortWatch. When displaying, include the as_of date so users understand data is lagged.
- Update cadence: The endpoint reflects the latest PortWatch drop for Savannah. You don’t need to poll aggressively; check once daily or on your own scheduler and update only when as_of changes.
- Caching: Cache per port keyed by as_of. If a new call returns the same as_of, skip downstream refreshes to avoid noisy churn.
- Multiple results: The endpoint returns an array; for a specific port request, expect one element, but your parser should still index results[0] defensively.
Error handling and guardrails for production
- Network resiliency: Set explicit timeouts and retry with backoff on transient 5xx or network timeouts.
- Schema changes: Read fields by name (congestion, as_of, metrics.ratio_vs_baseline). Validate presence before using them.
- Rate limits: Guests (no key) have 100 requests per day per IP. Use the X-API-Key header for higher headroom and stable throughput.
- User messaging: Always display the as_of date next to any Savannah congestion indicator. Avoid wording that implies live AIS waits.
Embedding Savannah’s congestion into dashboards and alerts
Common triggers for Savannah (USSAV):
- Daily check with a rule like: if ratio_vs_baseline < 0.85 for two consecutive updates, flag “below-normal calls; investigate ops impact.”
- Display a compact UI: “Savannah, as_of 2026-11-13 — congestion: moderate; activity ratio: 0.94.”
- Expose raw numbers alongside the band: recent_avg_portcalls_per_day and baseline_avg_portcalls_per_day help operations teams contextualize the ratio.
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
- Base units: Port calls per day for the recent average and baseline; ratio is unitless.
- No currency fields: This endpoint does not return freight rates or USD fares. Don’t conflate it with pricing feeds.
- Envelope schema: Responses are wrapped in {"success": true, "data": {...}}. Check success before dereferencing data.
- Source metadata: data.meta describes the PortWatch source and weekly republication behavior. Surface it in diagnostics, not in your primary UI.
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
- port: "Savannah"
- port_code: "USSAV" (from your request path)
- as_of: date string
- congestion_band: string ("low", "moderate", "high")
- ratio_vs_baseline: float
- recent_avg: float
- baseline_avg: float
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
- Empty results: If data.results is empty, back off and retry later; it can happen during upstream refresh windows.
- Mismatched labels: Remember congestion is a deprecated alias of activity. For UI clarity you can relabel it internally as activity_band while preserving the raw field.
- Unexpected spikes: If ratio_vs_baseline jumps, confirm the as_of change and cross-check recent_avg_portcalls_per_day to ensure it aligns with expectations for Savannah’s shipping calendar.
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.