Home → Blog

TEU turnaround time is the heartbeat metric for freight forwarders and 3PLs managing ocean boxes across complex, multi-leg transportation networks. When containers dwell too long at port or inland terminals, detention and demurrage charges balloon, asset utilization falls, and customer SLAs slip. Developers and operators alike often struggle to assemble a clear picture across port congestion, inland trucking capacity, fuel cost trends, and carrier vetting data—typically stitching together several siloed data sources that don’t talk to each other.

This post shows how to instrument container flow with a single, developer-friendly data surface: FreightPulse. We will combine container dwell and congestion signals, nearby natural-disruption alerts, verified trucking capacity data, and live full-truckload (FTL) quotes to reduce TEU turnaround times—without building a patchwork of AIS, EIA, FMCSA, FMC, and weather feeds. You will learn how to plug congestion and disruption signals into your workflow, pre-book drayage with live FTL quotes when a port is tightening up, and alert stakeholders before delays cascade.

The focus is practical: get to a deployable plan quickly. We will walk through the core endpoints, realistic responses, error handling, and design patterns that help freight forwarders and supply-chain teams move from reactive firefighting to proactive flow control.

Why FreightPulse

FreightPulse consolidates logistics intelligence behind one REST API so developers can move faster with fewer dependencies. Instead of juggling port congestion approximations, AIS feeds, carrier directories, fuel price series, and ad-hoc rate-quote scrapers, you consume normalized JSON across endpoints designed for production use.

Taken together, these advantages compress the time from “we need to reduce dwell 12% this quarter” to “we shipped a congestion-aware drayage recommender in production,” all while avoiding the complexity of wiring together multiple unrelated data vendors.

Quick Start

Base URL:

https://freightpulsehq.com/api/v1

All endpoints return the same high-level envelope: 

{
"success": true,
"data": { ... }
}

If you include an X-API-Key header, you’ll receive authenticated responses; unauthenticated exploration is also supported for light testing. Here is a first request to check national fuel prices—a foundational cost input for drayage and long-haul decisions: 

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

Sample JSON response: 

{
"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:

With a single call, your operations tooling can ground rate decisions against current and historical diesel benchmarks.

Core Endpoints

1) Port Congestion — Container dwell risk signal

Endpoint:

GET /port-congestion

Purpose: Provides a 7-day average of port calls compared to a 90-day baseline (ratio vs baseline). This is a lagged approximation (typically 6–7 days) based on IMF PortWatch AIS data for curated ports. Use it to flag tightening capacity and dwell risk trends—not to track live vessel queues.

Key parameters:

Example: 

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

Response: 

{
"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
}
}
]
}
}

How to use:

Best practices:

2) Disruptions — Natural hazards near ports

Endpoint:

GET /disruptions

Purpose: Consolidates natural-hazard alerts (cyclones, earthquakes, severe weather, etc.) from sources such as GDACS, USGS, and NOAA/NWS. This is particularly useful for spotting risks that can turn moderate congestion into unexpected dwell spikes within hours or days.

Key parameters:

Example (high-severity events near Los Angeles/Long Beach): 

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

Response: 

{
"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"
}
]
}
}

How to use:

Best practices:

3) Freight Rates — Pre-book inland legs during congestion build-ups

Endpoint:

GET /freight-rates

Purpose: Fetch live FTL trucking quotes for US lanes (via Warp) in the same schema family as your congestion and fuel signals. During congestion tiers rising at gateway ports, quickly score and pre-book drayage or long-haul repositioning to keep TEUs moving.

Key parameters (trucking mode):

Example (New York, NY 10001 to Beverly Hills, CA 90210): 

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

Response: 

{
"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"
}
}

How to use:

Best practices:

4) Fuel Prices — Power accurate drayage surcharge models

Endpoint:

GET /fuel-prices

Purpose: Integrate national and PADD-level diesel benchmarks (EIA) for surcharge calculations and budget baselines. Tie surcharge updates to a deterministic data cadence instead of ad-hoc spreadsheets.

No required parameters. Example shown in Quick Start.

Implementation tips:

5) Carriers — Verify trucking partners before dispatch

Endpoint:

GET /carriers

Purpose: Look up US trucking carriers (FMCSA SAFER) or ocean NVOCC/OTI filings (FMC). Before committing containers to a motor carrier for drayage, verify the DOT number, status, and safety indicators.

Key parameters:

Example (trucking, DOT lookup): 

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

Response: 

{
"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"
}
}
]
}
}

How to use:

6) Historical Series — Build predictive dashboards

Endpoint:

GET /historical

Purpose: Pull historical diesel or port-congestion series to build trend dashboards and forecasting features. This is essential for separating signal from noise when deciding whether to accelerate a drayage move.

Key parameters:

Example (30-day national diesel series): 

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

Response: 

{
"success": true,
"data": {
"metric": "fuel_price_diesel_national",
"period": "30d",
"series": [
{ "date": "2026-07-27", "value": 5.257 },
{ "date": "2026-08-03", "value": 5.343 }
]
}
}

How to use:

Interpreting Responses and Field Semantics

Every FreightPulse response shares a consistent envelope: success (boolean) and either data or error. This simplifies your client code: parse the envelope once and dispatch by endpoint. Below are additional details that matter in production when building transportation systems focused on reducing TEU dwell.

End-to-End Flow: From Port Risk to Drayage Booking

To connect the dots and actually reduce TEU turnaround time:

  1. Check /port-congestion for gateway ports relevant to your sailings. If congestion is moderate or high, record ratio_vs_baseline and as_of.
  2. Query /disruptions filtered by port to see if severe weather or seismic events may compound delays during your container’s pickup window.
  3. If risk is rising, request /freight-rates for candidate inland lanes (port ZIP to ramp/DC ZIP). Forecast detention cost against the quote’s price_usd and transit_days.
  4. Use /fuel-prices and /historical diesel trends to update surcharge models and sanity-check rapidly changing quotes against macro fuel signals.
  5. Before confirming drayage, verify the carrier via /carriers. Confirm status is active and safety_rating meets your compliance floors.

This pipeline replaces manual monitoring and guesswork with a deterministic playbook you can automate. It also creates a shared source of truth for operations, procurement, and customer-support teams handling ETA communications.

Practical Code Examples

cURL: End-to-end sampling 

# 1) Congestion at Los Angeles/Long Beach
curl -s -H "X-API-Key: YOUR_API_KEY" \
"https://freightpulsehq.com/api/v1/port-congestion?port=USLAX"

# 2) High-severity disruptions near the same port
curl -s -H "X-API-Key: YOUR_API_KEY" \
"https://freightpulsehq.com/api/v1/disruptions?port=USLAX&severity=high"

# 3) Live FTL quote for a likely drayage/linehaul to a DC ZIP
curl -s -H "X-API-Key: YOUR_API_KEY" \
"https://freightpulsehq.com/api/v1/freight-rates?mode=trucking&origin_zip=90744&destination_zip=85001"

Python: Risk scoring and decision rule 

import requests
import math

BASE = "https://freightpulsehq.com/api/v1"
HEADERS = {"X-API-Key": "YOUR_API_KEY"}

def get_json(path, params=None):
r = requests.get(f"{BASE}{path}", headers=HEADERS, params=params, timeout=20)
r.raise_for_status()
payload = r.json()
if not payload.get("success"):
raise RuntimeError(payload.get("error", "Unknown error"))
return payload["data"]

def congestion_risk_score(port_locode):
data = get_json("/port-congestion", {"port": port_locode})
if not data.get("results"):
return 0.0
m = data["results"][0]["metrics"]
ratio = m.get("ratio_vs_baseline", 1.0)
# Lower ratio could indicate reduced port calls vs baseline; normalize risk
# Invert and cap: risk = max(0, 1 - ratio)
return max(0.0, 1.0 - ratio)

def disruption_risk_boost(port_locode):
data = get_json("/disruptions", {"port": port_locode, "severity": "high"})
# Simple boost per high-severity event (cap at 0.3)
boost = min(0.3, 0.05 * len(data.get("results", [])))
return boost

def expected_dwell_cost(days, daily_detention=150.0):
return days * daily_detention

def should_prebook_drayage(port_locode, origin_zip, dest_zip, detention_per_day=150.0):
base_risk = congestion_risk_score(port_locode)
boost = disruption_risk_boost(port_locode)
risk = min(1.0, base_risk + boost)

# Map risk to expected delay days (simple heuristic)
expected_delay_days = 0.0
if risk >= 0.7:
expected_delay_days = 3.0
elif risk >= 0.4:
expected_delay_days = 1.5
elif risk >= 0.2:
expected_delay_days = 1.0

dwell_cost = expected_dwell_cost(expected_delay_days, detention_per_day)

quote = get_json("/freight-rates", {
"mode": "trucking",
"origin_zip": origin_zip,
"destination_zip": dest_zip
})

price = quote.get("price_usd", 0.0)
# Decision: prebook if dwell cost >= 10% of the lane price (tunable)
decision = dwell_cost >= 0.1 * price
return {
"risk_score": risk,
"expected_delay_days": expected_delay_days,
"dwell_cost": dwell_cost,
"lane_price": price,
"prebook": decision
}

print(should_prebook_drayage("USLAX", "90744", "85001"))

This snippet ties congestion and disruption risk to a cost-aware drayage decision. In practice, refine the mapping between ratio_vs_baseline and expected_delay_days by correlating with your historical dwell data.

Error Handling, Reliability, and Observability

Robust transportation systems need predictable failure modes. FreightPulse returns structured errors you can log, alert on, and retry appropriately.

Common error response 

{
"success": false,
"error": "Human-readable message."
}

Best practices:

Real-World Use Cases

1) Congestion-aware drayage prebooking for port-to-DC moves

A freight forwarder monitors gateway ports in a dashboard. When the /port-congestion endpoint labels a port as moderate or high, the system queries /disruptions filtered by that port to determine if weather will intensify delays. If risk rises above a threshold, it automatically calls /freight-rates with candidate inland ZIPs and recommends prebooking an FTL move. This reduces dwell-based detention fees and improves ETA reliability.

2) Fuel-surcharge calculator embedded in TMS workflows

A 3PL integrates /fuel-prices with /historical (30d and 90d) to compute weekly surcharges. It normalizes volatility by mixing national_average with 30d_avg and applies regional multipliers for west_coast or gulf_coast where appropriate. When a customer requests a quote, the TMS instantly calculates surcharges using the same model used across all ops teams, eliminating spreadsheet drift and inconsistent pricing.

3) Carrier vetting gate before dispatch

Before assigning a drayage job, a dispatcher’s console calls /carriers with the DOT number to verify status and safety rating. If status is not active or safety_rating violates policy, the console suggests alternates and triggers new /freight-rates requests. This reduces compliance risk and failed pickups that would otherwise inflate TEU dwell at the terminal.

4) Port trend reporting for leadership

A supply chain analytics team builds trend charts by calling /historical with metric port_congestion:<portid> for major lanes (Shanghai–LA/LB, Singapore–Rotterdam). They correlate ratio_vs_baseline to actual container dwell from WMS/TMS timestamps and show confidence intervals for next week’s dwell risk. This justifies pre-emptive routing decisions and improves weekly planning cadence.

5) Automated disruption routing guardrails

A SaaS shipment tracker uses /disruptions with port-based filters to flag high-severity events within 300km. If containers are scheduled to discharge during the event window, the app raises alerts in the customer portal and suggests contingency moves (earlier pickup or alternate inland routing). Users see a unified picture without switching between weather, seismic, and port feeds.

Detailed Endpoint Walkthroughs with Complete JSON

/port-congestion — multiple-port filtering example 

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": "Los Angeles-Long Beach",
"locode": "US LAX",
"country": "United States",
"congestion": "high",
"as_of": "2026-08-14",
"metrics": {
"recent_avg_portcalls_per_day": 7.9,
"baseline_avg_portcalls_per_day": 10.5,
"ratio_vs_baseline": 0.75
}
},
{
"port": "New York-New Jersey",
"locode": "US NYC",
"country": "United States",
"congestion": "high",
"as_of": "2026-08-14",
"metrics": {
"recent_avg_portcalls_per_day": 11.1,
"baseline_avg_portcalls_per_day": 14.2,
"ratio_vs_baseline": 0.78
}
}
]
}
}

Interpretation:

/disruptions — type and severity filtering 

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

{
"success": true,
"data": {
"results": [
{
"id": "noaa:SW:2026-08-21:CA-SoCal",
"type": "severe_weather",
"severity": "moderate",
"title": "Coastal Wind Advisory - Southern California",
"country": "United States",
"starts_at": "2026-08-21T00:00:00+00:00",
"source": "NOAA/NWS"
},
{
"id": "noaa:SW:2026-08-22:TX-Gulf",
"type": "severe_weather",
"severity": "moderate",
"title": "Thunderstorm Risk - Upper Texas Coast",
"country": "United States",
"starts_at": "2026-08-22T06:00:00+00:00",
"source": "NOAA/NWS"
}
]
}
}

Interpretation:

/freight-rates — minimal vs. enriched requests 

# Minimal trucking request (required zips)
curl -s -H "X-API-Key: YOUR_API_KEY" \
"https://freightpulsehq.com/api/v1/freight-rates?mode=trucking&origin_zip=11232&destination_zip=07030"

# Enriched trucking request with weight and pickup date
curl -s -H "X-API-Key: YOUR_API_KEY" \
"https://freightpulsehq.com/api/v1/freight-rates?mode=trucking&origin_zip=11232&destination_zip=07030&pickup_date=2026-08-25&qty=1&total_weight_lb=36000"

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

Interpretation:

/fuel-prices — augmenting surcharge stability 

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
}
}
}
}
}

Interpretation:

/carriers — ocean vs trucking lookups 

# Ocean NVOCC/OTI by name
curl -s -H "X-API-Key: YOUR_API_KEY" \
"https://freightpulsehq.com/api/v1/carriers?q=expeditors&type=ocean"

{
"success": true,
"data": {
"type": "ocean",
"query": "expeditors",
"results": [
{
"org_number": "XXXXXXX",
"legal_name": "EXPEDITORS INTERNATIONAL OF WASHINGTON, INC.",
"status": "active",
"address": {
"city": "Seattle",
"state": "WA",
"country": "US"
}
}
]
}
}

Interpretation:

/historical — port congestion trend series 

# Example: 90-day congestion series for Los Angeles-Long Beach
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.98 },
{ "date": "2026-06-08", "value": 0.94 },
{ "date": "2026-06-15", "value": 0.91 },
{ "date": "2026-06-22", "value": 0.89 },
{ "date": "2026-06-29", "value": 0.87 }
]
}
}

Interpretation:

Modeling TEU Dwell Reduction with FreightPulse Signals

Let’s translate the combined signals into a simple decision framework that your orchestration service can run hourly:

  1. Signal collection: Pull latest /port-congestion for active gateway ports; fetch /historical to fit a linear trend; query /disruptions by port at moderate+ severity.
  2. Risk synthesis: Convert congestion band to a base score; add a boost for event density near the port. Fit an expected_delay_days from your historical mapping.
  3. Cost crossover: Compute expected detention and storage charges from your tariff matrix. Compare against /freight-rates for candidate inland legs.
  4. Execution: If crossover occurs (dwell cost ≥ threshold of lane price), pre-book FTL; else, reassess in the next cycle. Verify carriers via /carriers before final dispatch.
  5. Communication: Update ETA and risk banners in customer portals; attach supporting data points (as_of, ratio_vs_baseline, event titles).

This disciplined loop turns port and disruption signals into an operational control system for containers—precisely the lever you need to cut TEU turnaround times.

Performance Tuning and Implementation Tips

FAQ

How often do FreightPulse fuel prices update?

Fuel prices reflect EIA benchmarks with national and regional coverage, along with rolling 30/90-day averages. Use national_average for fast updates and pair with 30d_avg to dampen weekly noise in surcharge formulas.

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

Yes. Use GET /carriers with type=ocean for NVOCC/OTI lookups from FMC directories, and the default trucking mode for FMCSA SAFER data. For air, the endpoint returns available:false to indicate lookup is not supported.

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

No. Port congestion is a lagged approximation, typically 6–7 days stale, reporting a 7-day average of port calls versus a 90-day baseline. Use it as a strong directional signal for capacity pressure and dwell risk—not for minute-by-minute queue tracking.

How can I reduce false positives in disruption alerts?

Anchor alerts to ports with the port parameter and set a severity threshold. Combine disruption counts with congestion bands to prioritize true risks where hazards coincide with already-stressed terminals.

What’s the fastest way to build a congestion dashboard for leadership?

Start with GET /port-congestion for current bands and GET /historical with metric port_congestion:<portid> for trend lines. Add nearby /disruptions for context and overlay diesel 30d_avg from /fuel-prices to frame the cost backdrop for drayage decisions.

Conclusion + CTA

Reducing TEU turnaround time is ultimately a data coordination problem across ports, hazards, carriers, trucks, and cost drivers. With FreightPulse, you unify these signals behind one consistent API and wire them directly into your TMS, dashboards, and automation workflows. That turns a chaotic blend of congestion anecdotes and weather headlines into a predictable system that buys capacity when it matters and eliminates unnecessary dwell.

If you need to move faster—standing up a congestion-aware drayage planner, a fuel-surcharge service, or a carrier vetting gate—start by instrumenting the endpoints covered here. You will have a measurable path to fewer days in terminal, fewer detention bills, and happier shippers.

Build smarter transportation systems today with FreightPulse. Explore the endpoints, prototype your first dashboard, and get to production without juggling five separate feeds. Try FreightPulse for free and turn port and disruption signals into action that cuts TEU dwell, starting this week.