Home → Blog

Port operations don’t live in isolation. A vessel’s berth time is the outcome of hundreds of upstream and downstream events: storms forming three days out, a lull in weekly port calls relative to baseline, a terminal’s truck velocity after a diesel price spike, and whether your chosen dray carrier is actually active and properly rated. Most teams try to piece this picture together with five or more data sources—AIS congestion pages, EIA fuel tables, a freight-rate marketplace, FMCSA lookups, and a smattering of alert feeds—and then wonder why their berth schedules still slip or their yard utilization keeps whipsawing.

This post shows how to use event correlation to shorten vessel berth times and lift terminal productivity, using one API that consolidates the critical signals your apps and control towers need. We will build a developer-grade understanding of how to combine lagged congestion indices, inland rate signals, carrier verification, and natural-disruption alerts into a repeatable decision loop for port ops and supply chain SaaS. You will leave with working calls, complete JSON examples, field-by-field meaning, and patterns for resilient clients and intelligent alerting.

The guiding principle: reducing berth time is about reducing uncertainty at handoff boundaries—anchorage to pilot, pilot to berth, berth to yard, and yard to gate. That’s a data problem. When your tools surface consistent, trustworthy signals across vessel activity, drayage capacity, fuel-driven cost shifts, and hazard proximity, you can move from firefighting to orchestration. That is where FreightPulse comes in.

Why FreightPulse for port ops and terminal productivity

Port ops and terminal apps need three things: fast access to external signals, consistent schemas across domains, and low integration overhead. FreightPulse is a single REST API that pulls together port activity, inland freight quotes, fuel prices, carrier verification, and natural-disruption alerts—so your teams don’t waste cycles stitching integrations or normalizing schemas before every line of business can derive value.

In short: FreightPulse provides the fastest path from zero to a production-grade, event-correlated port-ops signal layer—fuel, rates, congestion, carrier status, and hazard proximity—in a single, developer-friendly API.

Quick Start

Base URL: https://freightpulsehq.com/api/v1

All responses share a consistent envelope: {"success": true|false, "data": {...}, "error": "message" // on failure}. This makes it simple to unwrap payloads and centralize error handling middleware across your services.

First request: fetch current national and regional fuel prices. These values can feed your drayage fuel-surcharge calculators and inform “gate hour” staffing models during cost spikes. 


curl -s -H "X-API-Key: YOUR_API_KEY" \
"https://freightpulsehq.com/api/v1/fuel-prices"

{
"success": true,
"data": {
"timestamp": "2026-07-30T12:00:00Z",
"source": "EIA (U.S. Energy Information Administration)",
"currency": "USD",
"unit": "gallon",
"data": {
"diesel": {
"national_average": 3.847,
"change_week": -0.023,
"change_percent": -0.6,
"regions": {
"east_coast": 3.912,
"midwest": 3.756,
"gulf_coast": 3.623,
"rocky_mountain": 3.891,
"west_coast": 4.456,
"california": 4.892
},
"historical": {
"30d_avg": 3.82,
"90d_avg": 3.75,
"yoy_change_percent": -8.2
}
},
"gasoline": {
"national_average": 3.156,
"historical": {
"30d_avg": 3.1,
"90d_avg": 3.05,
"yoy_change_percent": 1.1
}
}
}
}
}

Key fields:

Core Endpoints for Event-Correlated Port Ops

1) Port Congestion Trends — GET /port-congestion

Purpose: Provide a 7-day average of portcalls versus a 90-day baseline from IMF PortWatch (a UN Global Platform AIS-derived dataset). This is not real-time AIS; expect a ~6–7 day lag. The benefit is repeatable, comparable trend indices across curated major ports—perfect for scheduling policies, anchorage risk scoring, and historical congestion analytics tied to ETB/ETD planning.

Key parameters: 


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

{
"success": true,
"data": {
"results": [
{
"port": "Los Angeles-Long Beach",
"locode": "US LAX",
"country": "United States",
"congestion": "moderate",
"as_of": "2026-08-14",
"metrics": {
"recent_avg_portcalls_per_day": 8.7,
"baseline_avg_portcalls_per_day": 10.2,
"ratio_vs_baseline": 0.85
}
}
]
}
}

Field interpretation:

2) Natural-Disruption Proximity — GET /disruptions

Purpose: Consolidate natural-hazard signals (cyclones, earthquakes, severe weather, etc.) from GDACS, USGS, and NOAA/NWS, with filtering by port radius. This is a direct input to any “anchorage risk” or “yard safety” policy and a prime candidate for automated escalation workflows in a TMS or terminal OS.

Key parameters: 


curl -s -H "X-API-Key: YOUR_API_KEY" \
"https://freightpulsehq.com/api/v1/disruptions?port=USLAX&severity=high"

{
"success": true,
"data": {
"results": [
{
"id": "gdacs:TC:1001305",
"type": "cyclone",
"severity": "moderate",
"title": "Tropical Cyclone SAUDEL-26",
"country": "Japan",
"starts_at": "2026-08-18T12:00:00+00:00",
"source": "GDACS"
}
]
}
}

Field interpretation:

3) Inland Rate and Velocity Signals — GET /freight-rates

Purpose: Retrieve live US FTL quotes (via Warp) in the same shape as your other FreightPulse payloads. This is invaluable for drayage planning and for forecasting gate/backyard utilization as costs and transit days shift. Ocean and air modes are limited to Asian origins into US destinations.

Key parameters (trucking): 


curl -s -H "X-API-Key: YOUR_API_KEY" \
"https://freightpulsehq.com/api/v1/freight-rates?mode=trucking&origin_zip=10001&destination_zip=90210&pickup_date=2026-08-24"

{
"success": true,
"data": {
"mode": "trucking",
"service": "FTL (53' dry van)",
"source": "Warp",
"price_usd": 7207.92,
"transit_days": 4,
"pickup_date": "2026-08-24",
"delivery_date": "2026-08-28"
}
}

Field interpretation:

4) Carrier Verification — GET /carriers

Purpose: Query FMCSA SAFER (trucking) or FMC OTI/NVOCC (ocean) records to ensure the carriers attached to your discharge plans are valid, active, and safe. This helps avoid last-minute gate denials or re-dispatches that balloon berth time indirectly through yard churn.

Key parameters: 


curl -s -H "X-API-Key: YOUR_API_KEY" \
"https://freightpulsehq.com/api/v1/carriers?q=54283"

{
"success": true,
"data": {
"type": "trucking",
"query": "54283",
"results": [
{
"dot_number": 54283,
"legal_name": "SWIFT TRANSPORTATION COMPANY OF ARIZONA LLC",
"status": "active",
"safety_rating": "S",
"drivers": 12883,
"address": {
"city": "Phoenix",
"state": "AZ",
"country": "US"
}
}
]
}
}

Field interpretation:

5) Fuel Price Intelligence — GET /fuel-prices

Purpose: Feed cost models that cascade into dray selection, staffing, and yard flow. Diesel volatility translates into carrier acceptance behavior, which can shift the time trucks dwell at gates and ramps.

No required parameters. Response fields already shown in Quick Start. In practice, pair /fuel-prices with /freight-rates to monitor whether “cost up, acceptance down” conditions threaten your planned discharge windows. Add weekly deltas to your anomaly detectors so your terminal’s labor planner can anticipate spikes.

6) Historical Series — GET /historical

Purpose: Retrieve daily congestion series for curated ports and weekly national fuel series. This unlocks trend dashboards, forecasting models, and regression baselines for “What policy shortens berth time under repeated congestion regimes?” questions.

Key parameters: 


curl -s -H "X-API-Key: YOUR_API_KEY" \
"https://freightpulsehq.com/api/v1/historical?metric=port_congestion:USLAX&period=90d"

{
"success": true,
"data": {
"metric": "port_congestion:USLAX",
"period": "90d",
"series": [
{ "date": "2026-06-01", "value": 0.92 },
{ "date": "2026-06-08", "value": 0.88 },
{ "date": "2026-06-15", "value": 0.85 },
{ "date": "2026-06-22", "value": 0.83 },
{ "date": "2026-06-29", "value": 0.87 }
]
}
}

Field interpretation:

How to correlate events to shorten berth times

The core idea behind event correlation is to align lagged and live signals into a coherent operational picture that drives earlier, better decisions. Here is a practical flow your terminal OS or SaaS app can implement:

  1. Baseline congestion regime. Pull /port-congestion daily for your target port and store the ratio_vs_baseline time series via /historical. Define regime thresholds (e.g., sustained ratio < 0.9 = “below normal,” 0.9–1.1 = “normal,” > 1.1 = “above normal”).
  2. Monitor hazard proximity. Subscribe your back end to periodic /disruptions queries with port filters. When a severe hazard enters the radius window, elevate risk for inbound voyages and tighten the berthing plan’s slack buffers.
  3. Couple hinterland cost and capacity. Query /freight-rates for your dray lanes and /fuel-prices weekly. If diesel increases and FTL quotes jump while congestion is elevated, expect yard throughput to degrade as carriers reprice or reject. Your policy can pre-authorize contingency carriers validated by /carriers.
  4. Automate alerts and tasking. When a policy threshold triggers (e.g., cyclone near port AND congestion “high” AND rate delta > X%), push Slack/email alerts with clear “next best action” tasks (adjust berthing slots, re-sequence discharge, add labor).
  5. Backtest and iterate. Use /historical to evaluate how your plan would have performed under past regimes and tune buffer times that minimize berth time without overshooting yard capacity.

This correlation loop works because all inputs share a consistent schema and can be fetched and stored using the same client plumbing, logging, and retries—no custom per-vendor code that obscures the signal chain.

Implementation patterns: reliability, performance, and observability

Beyond endpoint usage, robust operational apps need disciplined client behavior. Here are patterns that work well for FreightPulse:

Observability checklist:

Complete endpoint catalog with field-by-field guidance

GET /fuel-prices

Purpose: Weekly national and PADD-region diesel/gasoline. Business value: forecast dray costs, inform carrier acceptance strategies, adjust terminal staffing when truck velocity may change.

Important fields:

Error handling: On failure, you will receive {"success": false, "error": "Human-readable message."}. Consider serving a cached prior value and flagging UI components to “degraded” state.

GET /freight-rates

Purpose: Live quotes and transit days to coordinate yard turns and minimize berth overflow risk. Missing required params return HTTP 200 with available:false in data rather than an error—treat that as a soft validation failure in your UI. 


curl -s -H "X-API-Key: YOUR_API_KEY" \
"https://freightpulsehq.com/api/v1/freight-rates?mode=trucking&origin_zip=60601&destination_zip=77001"

{
"success": true,
"data": {
"mode": "trucking",
"service": "FTL (53' dry van)",
"source": "Warp",
"price_usd": 2187.45,
"transit_days": 2,
"pickup_date": "2026-08-24",
"delivery_date": "2026-08-26"
}
}

Best practices:

GET /port-congestion

Purpose: Trend index to contextualize berthing expectations. Not real-time AIS; lagged 6–7 days. Suitable for policy design and macro-level alerting. Use the ratio_vs_baseline for analytics; it is unitless and portable.

Example with filtering by label: 


curl -s -H "X-API-Key: YOUR_API_KEY" \
"https://freightpulsehq.com/api/v1/port-congestion?country=United%20States&congestion=high"

{
"success": true,
"data": {
"results": [
{
"port": "Savannah",
"locode": "US SAV",
"country": "United States",
"congestion": "high",
"as_of": "2026-08-14",
"metrics": {
"recent_avg_portcalls_per_day": 14.3,
"baseline_avg_portcalls_per_day": 11.9,
"ratio_vs_baseline": 1.20
}
}
]
}
}

Use cases:

GET /carriers

Purpose: Validate carriers before assigning them to yard moves or gate slots. Ocean lookups via FMC directory help confirm NVOCC/OTI status for bookings connected to your terminal’s discharge list. 


curl -s -H "X-API-Key: YOUR_API_KEY" \
"https://freightpulsehq.com/api/v1/carriers?q=MAERSK&type=ocean"

{
"success": true,
"data": {
"type": "ocean",
"query": "MAERSK",
"results": [
{
"org_number": "OTI-012345",
"legal_name": "MAERSK A/S",
"status": "active",
"address": {
"city": "Copenhagen",
"country": "DK"
}
}
]
}
}

Policy tips:

GET /disruptions

Purpose: Proximity-filtered hazard alerts. Operational focus: anticipate tug delays, pilotage constraints, and gate slowdowns due to weather. 


curl -s -H "X-API-Key: YOUR_API_KEY" \
"https://freightpulsehq.com/api/v1/disruptions?type=severe_weather&port=USLAX"

{
"success": true,
"data": {
"results": [
{
"id": "nws:SW:LA:2026-08-20-01",
"type": "severe_weather",
"severity": "high",
"title": "High Wind Warning",
"country": "United States",
"starts_at": "2026-08-20T06:00:00+00:00",
"source": "NOAA/NWS"
}
]
}
}

Integration ideas:

GET /historical

Purpose: Timeseries for analysis and forecasting. You can stitch weekly diesel series with daily port-congestion ratios to regress berth-time anomalies on macro factors. 


curl -s -H "X-API-Key: YOUR_API_KEY" \
"https://freightpulsehq.com/api/v1/historical?metric=fuel_price_diesel_national&period=1y"

{
"success": true,
"data": {
"metric": "fuel_price_diesel_national",
"period": "1y",
"series": [
{ "date": "2025-09-01", "value": 4.105 },
{ "date": "2025-09-08", "value": 4.162 },
{ "date": "2025-09-15", "value": 4.201 }
]
}
}

Best practices:

Real-world use cases to implement now

Data modeling and schema tips

Create a core entity model that accommodates both lagged and live signals:

With this model:

Client examples: cURL, JavaScript, and Python

cURL requests were shown above. Here are brief snippets in JavaScript (fetch) and Python (requests) to illustrate production-friendly patterns with standardized envelope handling and caching. 


// JavaScript (Node.js) - simple GET with envelope handling
import fetch from "node-fetch";

async function fpGet(path, params = {}) {
const url = new URL(`https://freightpulsehq.com/api/v1/${path}`);
for (const [k, v] of Object.entries(params)) url.searchParams.set(k, v);
const res = await fetch(url.toString(), {
headers: { "X-API-Key": process.env.FP_KEY }
});
const body = await res.json();
if (!body.success) throw new Error(body.error || "Unknown FreightPulse error");
return body.data;
}

// Example: get LA/LB congestion
(async () => {
const data = await fpGet("port-congestion", { port: "USLAX" });
console.log(data.results[0].metrics.ratio_vs_baseline);
})();


# Python - requests + basic cache and error handling
import os, time, json, requests
from functools import lru_cache

BASE = "https://freightpulsehq.com/api/v1"
HEADERS = {"X-API-Key": os.getenv("FP_KEY")}

def fp_get(path, params=None):
r = requests.get(f"{BASE}/{path}", headers=HEADERS, params=params, timeout=15)
r.raise_for_status()
body = r.json()
if not body.get("success", False):
raise RuntimeError(body.get("error", "FreightPulse error"))
return body["data"]

@lru_cache(maxsize=256)
def get_port_congestion(locode):
return fp_get("port-congestion", {"port": locode})

if __name__ == "__main__":
data = get_port_congestion("USLAX")
print(json.dumps(data, indent=2))

For production, consider:

Error scenarios and defensive programming

FreightPulse uses clear HTTP semantics and a consistent error envelope to keep handling straightforward. Expect:

Recommended approach:

Performance tips and operational best practices

Putting it together: sample correlation pipeline 


// Pseudocode for an hourly correlation job

// 1) Pull congestion and classify regime
const lax = await fpGet("port-congestion", { port: "USLAX" });
const ratio = lax.results[0].metrics.ratio_vs_baseline;
const regime = ratio > 1.1 ? "high" : (ratio < 0.9 ? "low" : "normal");

// 2) Pull hazard proximity
const hazards = await fpGet("disruptions", { port: "USLAX", severity: "high" });

// 3) Pull inland signal for a top dray lane
const rates = await fpGet("freight-rates", {
mode: "trucking", origin_zip: "90744", destination_zip: "92335"
});

// 4) Pull latest diesel
const fuel = await fpGet("fuel-prices");

// 5) Synthesize a playbook decision
const hazardActive = hazards.results.length > 0;
const dieselUp = fuel.data.diesel.change_percent > 3.0; // example threshold
const highCost = rates.price_usd > 2500; // lane-specific threshold

if ((regime === "high" && hazardActive) || (regime !== "low" && dieselUp && highCost)) {
// escalate: re-sequence berths, add crane, notify ops
emitIncident({
port: "USLAX",
regime,
hazardActive,
laneCost: rates.price_usd
});
}

This minimal pipeline delivers concrete actions from four data classes in minutes, not months of integration.

FAQ

How often do FreightPulse fuel prices update?

Fuel prices follow the cadence of EIA’s weekly reporting and are exposed with national and PADD breakdowns. You can safely poll weekly for planning and recalc your drayage surcharge tables or cost-to-serve models on update.

Can I look up ocean carriers as well as trucking carriers?

Yes. Use GET /carriers with type=ocean to query FMC OTI/NVOCC directory records, and type=trucking (default) to query FMCSA SAFER data. Each record includes status and key attributes that you can map into your gate controls and booking flows.

Does the port congestion data reflect real-time vessel wait times?

No. Port congestion is a lagged approximation (about 6–7 days) using a 7-day average of portcalls versus a 90-day baseline. It’s ideal for trends, planning, threshold alerts, and benchmarking, not for minute-by-minute queue length estimation.

Can I filter natural-disruption alerts by proximity to a port?

Yes. Use the port parameter on GET /disruptions to filter hazard events within a defined radius (300km; 100km for US weather). This is the fastest way to wire actionable hazard proximity into your terminal or control tower.

What happens if required parameters are missing on freight quotes?

For GET /freight-rates, missing required parameters return a success envelope with data indicating that a quote is not available instead of a hard error. Treat this as a UI validation scenario and prompt the user for the missing inputs.

Conclusion and call to action

Shortening berth times and lifting terminal productivity are not about one magical dataset; they’re about connecting the right events at the right time. With congestion trends, hazard proximity, inland rate signals, fuel cost context, and carrier verification flowing through a single, consistent API, your port ops and SaaS tools can finally automate the decisions that matter—before delays show up at the anchorage or gate.

As a senior developer advocate focused on operational outcomes, my recommendation is simple: start with one correlation loop. Pull /port-congestion for your primary port, watch /disruptions on a 30-minute cadence, and wire /freight-rates plus /fuel-prices into a single “risk and cost” panel. Add /carriers gating to lock in serviceable partners. Iterate weekly with data-backed postmortems using /historical. Your team will see measurable berth-time reductions as policies mature.

If you are building a terminal OS, a forwarder dashboard, or an enterprise control tower, you can ship value in days, not quarters. Explore the endpoints and examples above, then plug them into your pipelines. FreightPulse is ready when you are—one API, one schema, all the signals. Try FreightPulse for free and start correlating the events that shorten berths and improve throughput.