You need a reliable way to programmatically check port traffic and congestion for Singapore so your systems can decide when to route, delay, or notify. By the end of this post you will be able to call a real congestion endpoint for Singapore (SGSIN), parse the key fields in Python, and ship this data into your planning or monitoring pipeline.
What this API returns for Singapore traffic
The congestion endpoint measures recent port-call activity relative to a longer baseline, using AIS-derived data from IMF PortWatch. It is updated daily but lagged by about 6–7 days; it does not provide live AIS vessel wait times or anchorage durations. The result is an envelope with a success flag and a data object containing per-port results, including the fields you will actually use in automation: congestion status, ratio_vs_baseline, and as_of.
- 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: Singapore (SGSIN)
Endpoint and authentication
To query Singapore, call a single GET endpoint. Provide the port code in the port query parameter and pass your API key in the X-API-Key header. If you do not have a key yet, guests are rate-limited by IP; for production, register and use a key.
- Method: GET
- Path: /api/v1/port-congestion
- Query parameters: port=SGSIN
- Header: X-API-Key: YOUR_API_KEY
Documentation: Documentation. To get an API key: Register.
Copy-paste cURL for SGSIN
Run this from a terminal to fetch the current congestion envelope for Singapore. Replace YOUR_API_KEY with your key if you have one; otherwise you will be treated as a guest with shared limits.
curl -H "X-API-Key: YOUR_API_KEY" "https://freightpulsehq.com/api/v1/port-congestion?port=SGSIN"Official JSON sample and field meanings
The response is wrapped as {"success": true, "data": {...}}. Below is a live-format example for SGSIN. You will typically read fields like data.results[].congestion, data.results[].as_of, and data.results[].metrics.ratio_vs_baseline.
Live FreightPulse congestion for SGSIN.
Source: live
cURL:
JSON:
{
"success": true,
"data": {
"results": [
{
"port": "Singapore",
"locode": "SG SIN",
"country": "Singapore",
"activity": "moderate",
"congestion": "moderate",
"as_of": "2026-10-30",
"metrics": {
"recent_avg_portcalls_per_day": 115,
"baseline_avg_portcalls_per_day": 117,
"ratio_vs_baseline": 0.98
}
},
{
"port": "Serangoon Harbor",
"locode": "SG SIN",
"country": "Singapore",
"activity": "high",
"congestion": "high",
"as_of": "2026-10-30",
"metrics": {
"recent_avg_portcalls_per_day": 9,
"baseline_avg_portcalls_per_day": 7.4,
"ratio_vs_baseline": 1.21
}
}
],
"global_summary": {
"ports_high_activity": 1,
"ports_moderate_activity": 1,
"ports_low_activity": 0,
"ports_high_congestion": 1,
"ports_moderate": 1,
"ports_low": 0
},
"meta": {
"source": "IMF PortWatch (portwatch.imf.org) - UN Global Platform AIS data",
"data_lag_days": "~6-7 (daily updates, not real-time)",
"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": "85580b4d-e4cc-4428-bace-7336ff77fc9c"
}
}What to read programmatically:
- results[].congestion: a categorical traffic/congestion label (low, moderate, high). Alias of activity per the methodology notes.
- results[].as_of: data date (YYYY-MM-DD). This is the date for which the 7-day average is computed; it is lagged ~6–7 days from the request date.
- results[].metrics.ratio_vs_baseline: numeric ratio of recent 7-day average port calls vs the 90-day baseline.
- results[].metrics.recent_avg_portcalls_per_day and baseline_avg_portcalls_per_day: integers/floats indicating counts of port calls per day.
Python: fetch and parse congestion for Singapore
This Python snippet calls the same endpoint, asserts success, and extracts the key traffic fields you’ll use to alert or display status for SGSIN.
import os
import requests
from datetime import datetime
API_URL = "https://freightpulsehq.com/api/v1/port-congestion"
PORT_CODE = "SGSIN"
headers = {
"X-API-Key": os.environ.get("FREIGHTPULSE_API_KEY", "YOUR_API_KEY")
}
params = {
"port": PORT_CODE
}
resp = requests.get(API_URL, headers=headers, params=params, timeout=20)
resp.raise_for_status()
payload = resp.json()
if not payload.get("success"):
raise RuntimeError("API indicated failure")
data = payload["data"]
results = data.get("results", [])
# For Singapore, the first result commonly represents the primary port of Singapore.
for entry in results:
port_name = entry.get("port")
as_of = entry.get("as_of") # e.g., "2026-10-30"
congestion = entry.get("congestion") # "low" | "moderate" | "high"
metrics = entry.get("metrics", {})
ratio_vs_baseline = metrics.get("ratio_vs_baseline")
recent_avg = metrics.get("recent_avg_portcalls_per_day")
baseline_avg = metrics.get("baseline_avg_portcalls_per_day")
# Convert as_of to a date object if you need date math
as_of_date = None
if as_of:
as_of_date = datetime.strptime(as_of, "%Y-%m-%d").date()
print({
"port": port_name,
"as_of": as_of,
"congestion": congestion,
"ratio_vs_baseline": ratio_vs_baseline,
"recent_avg_portcalls_per_day": recent_avg,
"baseline_avg_portcalls_per_day": baseline_avg
})How to operationalize SGSIN traffic data
Because the data is not real-time and is computed from a 7-day average against a 90-day baseline, you should cache it and update on a daily cadence. The as_of field is the authoritative date for the snapshot you are using, and it can be several days behind the current calendar date.
- Polling: Schedule a daily job, ideally after the source updates, to refresh your cache for SGSIN.
- Caching: Retain the last successful response and serve it until the next daily refresh to avoid rate limit friction.
- Alerting: Trigger alerts on significant changes in ratio_vs_baseline (for example, crossings such as < 0.9 or > 1.1), rather than on single-day noise.
- Display: Show congestion as categorical traffic plus the ratio_vs_baseline for quantitative context; add as_of to make the lag explicit to end users.
Understanding activity vs. congestion in this model
The methodology computes activity from port-call volumes. Congestion is a legacy alias for the activity label. A lower-than-usual call volume can coincide with genuine congestion if vessels are queuing offshore rather than completing calls, but this endpoint does not measure anchorage wait times directly.
- activity/congestion: categorical label derived from recent_avg_portcalls_per_day vs baseline_avg_portcalls_per_day.
- ratio_vs_baseline: a direct numeric indicator (1.0 means at baseline; 1.2 means 20% above baseline; 0.8 means 20% below baseline).
- Interpretation caveat: Fewer port calls may reflect closures, weather, or schedule shifts; not necessarily smoother traffic.
Error handling, retries, and rate limits
The API returns an HTTP 200 with success=true for normal results. Use HTTP error codes and the success flag to distinguish transport vs. logical failures. If you are using a guest request without an API key, expect a shared daily limit of 100 requests per IP; production workloads should authenticate with a key.
- Timeouts: Use client-side timeouts (e.g., 20 seconds in Python requests) and retry idempotent GETs with exponential backoff.
- Idempotency: Reads are safe to retry; do not parallelize excessively to avoid rate limiting.
- Throttling: Cache the response for at least one day; the underlying dataset is updated daily with a ~6–7 day lag.
Data hygiene and units you should know
Unlike pricing APIs, there is no currency here. Units are counts of port calls per day. The main temporal field is as_of, which is a date string in YYYY-MM-DD. No timezone conversion is necessary for this date string, but your system clock should be consistent (UTC recommended) for cache invalidation and scheduling. There is no pagination parameter documented for this single-port query; expect a compact payload.
- Counts: recent_avg_portcalls_per_day, baseline_avg_portcalls_per_day are numerical counts (int/float).
- Date: as_of uses ISO date format (YYYY-MM-DD) without time-of-day.
- Lag: ~6–7 days between event occurrence and availability within this endpoint.
- Caching window: safe to cache for 24 hours; invalidate when your daily job runs.
Validation checklist for SGSIN integration
- Authenticate with X-API-Key: YOUR_API_KEY or operate within the guest 100 requests/day per IP constraint.
- Always check payload.get("success") before parsing data.results.
- Read congestion, as_of, and metrics.ratio_vs_baseline for your traffic logic. Keep the ratio numeric; do not format into percentages until UI time.
- Persist the as_of date with your record so you can reason about data currency.
- Never present rates or fares as “today’s price” based on this endpoint; it measures traffic, not freight pricing.
Common pitfalls and how to avoid them
- Assuming real-time: The dataset is derived from IMF PortWatch and is lagged ~6–7 days. Mitigate by surfacing as_of and avoiding hour-by-hour decisions.
- Equating low activity to low congestion: Low activity can also occur during disruptions; interpret alongside operational context.
- Forgetting to handle empty results: Code defensively for an empty results array and preserve last-known-good values.
- Ignoring method changes: congestion is a deprecated alias for activity in the methodology notes; rely on ratio_vs_baseline for quantitative triggers.
FAQ
Is this traffic/congestion data real-time?
No. It is updated daily and lagged by approximately 6–7 days from the observation date. The as_of field tells you which date the metrics represent.
What does ratio_vs_baseline mean for Singapore?
It is the recent 7-day average of port calls divided by the 90-day baseline for the same port. A value near 1.0 means activity is typical; above 1.0 indicates higher-than-usual activity; below 1.0 indicates lower-than-usual activity.
Where do I find the congestion label?
Use results[].congestion for the categorical label and results[].metrics.ratio_vs_baseline for the numeric context. Also read results[].as_of to know the data date.
Do I need an API key to check SGSIN traffic?
No, but without a key you are limited to 100 requests per day per IP. For production systems, use X-API-Key: YOUR_API_KEY after registering.
Does this measure vessel wait times or anchorage delays?
No. It measures port-call activity levels, not queue or wait durations. Use the ratio and category as a proxy for traffic conditions, with the methodology caveats in mind.
Next step
Set up your daily job to pull Singapore traffic via the endpoint above, cache the response, and alert when ratio_vs_baseline crosses the thresholds that matter to your operations. Get your key at Register and review the parameter details in the Documentation.