Home → Blog

Supply chain visibility is no longer just about tracking a truck on a map. Shippers and platforms need to blend satellite AIS-derived port activity, live truck events, fuel indices, carrier compliance, and natural-disruption intelligence into one reliable operational picture. Doing this from scratch—stitching EIA for fuel, FMCSA/FMC for carriers, Warp for FTL quotes, PortWatch-derived AIS for port congestion, and multiple hazard sources—creates an integration tax that slows teams down and makes every outage your problem. The result is siloed dashboards, brittle ETL, and delayed response to what matters most: keeping shipments moving.

In this post, we’ll build a unified multimodal visibility layer that combines satellite AIS-proxied port congestion, port-specific disruption risk, FTL truck quotes, and carrier verification using a single, developer-friendly surface: FreightPulse. Whether you’re a supply chain SaaS vendor, a 3PL building a control tower, or an enterprise team seeking better ETA governance, this post shows how to wire practical endpoints into your product with production-grade patterns—retries, health checks, field interpretation, and latency-aware routing strategies—so you can go from zero to meaningful visibility in days, not quarters.

We’ll be opinionated and hands-on: you’ll see actionable cURL, JavaScript, and Python examples; complete JSON payloads; and concrete design notes explaining how to interpret each field for analytics and operations. We will also be explicit where the data is lagged (e.g., port congestion derived from IMF PortWatch’s AIS aggregation has a ~6–7 day lag) versus live (e.g., FTL trucking quotes). The goal is to arm you with a realistic blueprint for a multimodal visibility layer you can ship today.

Why FreightPulse

FreightPulse consolidates the core datasets that most modern logistics products need—fuel prices, live FTL quotes, port congestion, carrier verification, and natural-disruption alerts—behind one REST interface. That means one schema, one set of error semantics, one observability strategy, and far less glue code. Here are the differentiators that matter for developers and operators:

By standardizing on FreightPulse, you avoid writing a fragile patchwork of integrations and get a coherent, unified visibility layer ready for production governance—retries/backoff, health checks, and circuit breakers—deployed once across all your logistics data sources rather than five times.

Quick Start

Base URL:

https://freightpulsehq.com/api/v1

Authentication is via an HTTP header (X-API-Key). Below is the smallest possible “hello world” to fetch national fuel prices. This gives you an immediately useful, production-safe payload—timestamped indices and regional breakdowns you can drop into a UI or surcharge calculator. 

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

Example 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 to know:

Core Endpoints You’ll Use to Build a Unified Multimodal Layer

Below we’ll focus on endpoints that let you build a practical, multimodal visibility layer: real-time US FTL quotes, port congestion derived from AIS via IMF PortWatch, disruption alerts near ports, carrier verification (trucking and ocean), and historical series for charting. Each example includes request parameters, a cURL example, and a realistic JSON response with guidance on how to interpret it in your UI or planner workflow.

1) Live US FTL Quotes: GET /freight-rates

Purpose: Get live pricing and lead-time estimates for US full-truckload shipments, with support for some ocean/air flows into the US. Embed this in a booking flow (rate shopping), a capacity planning widget, or an automated quoting system in your TMS.

Key params: 

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&total_weight_lb=36000"

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

Notes:

2) Port Congestion (AIS-derived): GET /port-congestion

Purpose: Gauge recent port activity relative to a 90-day baseline, proxied from IMF PortWatch’s aggregations of satellite AIS. This is a lagged indicator (~6–7 days), designed for planning, analytics, and early signals—not for minute-by-minute berth operations.

Key params: 

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:

3) Disruption Intelligence: GET /disruptions

Purpose: Track natural hazards—cyclones, earthquakes, floods, volcanoes, droughts, wildfires, severe weather—that could impact ocean and inland legs. Filter by proximity to a port to keep alerts relevant to shipments actually at risk.

Key params: 

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:

4) Carrier Verification: GET /carriers

Purpose: Verify US trucking carriers via FMCSA SAFER and ocean NVOCC/OTI entities via FMC. This helps you programmatically gate tendering, ensure regulatory compliance, and highlight safety considerations.

Key params: 

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 Prices + Historical: GET /fuel-prices and GET /historical

Purpose: Power surcharge calculations, weekly ops emails, dashboards, and market trend analysis. Combine “latest” indices with historical series to contextualize swings and reduce surprise in customer pricing.

Latest prices: 

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

Historical series: 

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

{
"success": true,
"data": {
"metric": "fuel_price_diesel_national",
"period": "90d",
"series": [
{ "date": "2026-06-01", "value": 3.79 },
{ "date": "2026-06-08", "value": 3.82 },
{ "date": "2026-06-15", "value": 3.85 },
{ "date": "2026-06-22", "value": 3.81 },
{ "date": "2026-06-29", "value": 3.83 },
{ "date": "2026-07-06", "value": 3.86 },
{ "date": "2026-07-13", "value": 3.88 },
{ "date": "2026-07-20", "value": 3.84 },
{ "date": "2026-07-27", "value": 3.85 },
{ "date": "2026-08-03", "value": 3.87 }
]
}
}

Field interpretation:

From Satellite AIS to Truck Events: Building a Unified Visibility Layer

A single shipment might touch two oceans and three networks: ocean leg departing Asia, discharge and dwell at a West Coast terminal, transload to a domestic DC, and final-mile trucking. Planners need to understand how a cyclone forming near Japan could ripple into berthing delays in LA/Long Beach a week later and, by extension, how your FTL rates and ETAs into Phoenix or Dallas might be impacted. With FreightPulse, you can model this chain with a consistent API:

Because each endpoint returns a consistent envelope with “success” and “data,” it becomes straightforward to standardize client-side error handling, retries, and circuit breakers. Your platform benefits from fewer integration seams and better stability.

Complete JSON Walkthrough: Putting It Together

Let’s simulate a control tower widget that, for a given ocean arrival into USLAX and a downstream truckload into 85001 (Phoenix), shows port status, disruption risk, projected FTL quote, and a compliance check. Below are stitched calls (pseudocode style) and payloads you can reuse.

JavaScript (Node) Example 

import fetch from "node-fetch";

const BASE = "https://freightpulsehq.com/api/v1";
const headers = { "X-API-Key": process.env.FP_KEY };

async function getPortSignal(locode) {
const url = `${BASE}/port-congestion?port=${encodeURIComponent(locode)}`;
const r = await fetch(url, { headers, timeout: 8000 });
return r.json();
}

async function getDisruptionsNearPort(locode) {
const url = `${BASE}/disruptions?port=${encodeURIComponent(locode)}&severity=high`;
const r = await fetch(url, { headers, timeout: 8000 });
return r.json();
}

async function getFTLQuote(originZip, destZip, pickupDate) {
const url = `${BASE}/freight-rates?mode=trucking&origin_zip=${originZip}&destination_zip=${destZip}&pickup_date=${pickupDate}`;
const r = await fetch(url, { headers, timeout: 8000 });
return r.json();
}

async function verifyCarrier(dot) {
const url = `${BASE}/carriers?q=${dot}`;
const r = await fetch(url, { headers, timeout: 8000 });
return r.json();
}

(async () => {
try {
const [port, hazards, quote, carrier] = await Promise.all([
getPortSignal("USLAX"),
getDisruptionsNearPort("USLAX"),
getFTLQuote("90001", "85001", "2026-08-24"),
verifyCarrier("54283")
]);

console.log(JSON.stringify({ port, hazards, quote, carrier }, null, 2));
} catch (err) {
// Fallback strategy: show cached port metrics and stale quotes
console.error("Control tower aggregation failed:", err.message);
}
})();

Design notes:

Python Example (Requests + Backoff) 

import os, time, requests
BASE = "https://freightpulsehq.com/api/v1"
HEADERS = { "X-API-Key": os.environ.get("FP_KEY", "") }

def get_json(path, params=None, retries=3):
for attempt in range(retries):
try:
r = requests.get(f"{BASE}{path}", headers=HEADERS, params=params, timeout=8)
r.raise_for_status()
payload = r.json()
if not payload.get("success", False):
# Return the error shape for caller interpretation
return payload
return payload
except (requests.Timeout, requests.ConnectionError) as e:
if attempt == retries - 1:
raise
time.sleep(0.5 * (2 ** attempt))

# Usage
fuel = get_json("/fuel-prices")
port = get_json("/port-congestion", params={"port": "USLAX"})
hist = get_json("/historical", params={"metric": "port_congestion:USLAX", "period": "30d"})
print(fuel)
print(port)
print(hist)

The function centralizes retry/backoff and returns either a successful payload or the standardized error envelope, simplifying higher-level controller logic.

Error Handling, Health Checks, and Circuit Breakers

All FreightPulse responses share a common envelope: 

{
"success": true | false,
"data": { ... }, // present if success=true
"error": "message" // present if success=false
}

HTTP status codes to anticipate:

Best practices:

Performance and Observability Patterns for Multimodal Data

A unified visibility layer only works if it’s reliably fast and explainable. When integrating FreightPulse:

These patterns keep your control tower responsive under load while ensuring that an upstream hiccup never collapses the operator experience.

End-to-End Example: Unifying AIS-Derived Port Signals with Truck Quotes and Fuel

Let’s build a practical endpoint on your server that answers, in one shot, “What’s the current operational picture for an LA arrival feeding a Phoenix truck leg?” We’ll combine /port-congestion, /disruptions, /freight-rates, and /fuel-prices and produce a concise JSON ready for your UI.

Aggregation Service (Pseudo-Response) 

{
"success": true,
"data": {
"port": {
"locode": "USLAX",
"congestion": "moderate",
"ratio_vs_baseline": 0.85,
"as_of": "2026-08-14"
},
"hazards": [
{
"id": "gdacs:TC:1001305",
"type": "cyclone",
"severity": "moderate",
"title": "Tropical Cyclone SAUDEL-26",
"region_affinity": "NW Pacific",
"starts_at": "2026-08-18T12:00:00+00:00"
}
],
"ftl_quote": {
"lane": "90001 -> 85001",
"price_usd": 7207.92,
"transit_days": 4,
"pickup_date": "2026-08-24",
"delivery_date": "2026-08-28"
},
"fuel": {
"diesel_national": 3.847,
"week_over_week_pct": -0.6
},
"advice": {
"eta_buffer_hours": 24,
"risk_level": "elevated",
"notes": [
"Moderate congestion vs 90-day baseline; add 24h buffer to LA/LB discharge.",
"Cyclone activity observed; monitor forecast updates for trans-Pacific sailings.",
"FTL rate acceptable; reprice if >10% rise or if diesel moves +5% WoW."
]
}
}
}

How to use:

Real-World Use Cases You Can Ship This Quarter

Field-by-Field Reference and Practical Tips

/fuel-prices

/freight-rates

/port-congestion

/disruptions

/carriers

/historical

Additional End-to-End Examples with Complete JSON

Example: Ocean-to-Truck Handoff Planning (LA to Dallas) 

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

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

{
"success": true,
"data": {
"results": [
{
"id": "usgs:EQ:2026-08-13:CA:112233",
"type": "earthquake",
"severity": "moderate",
"title": "M4.9 near Southern California",
"country": "United States",
"starts_at": "2026-08-13T07:22:00+00:00",
"source": "USGS"
}
]
}
}

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

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

Interpretation: With ratio_vs_baseline at 0.85 (moderate congestion) and a moderate local seismic event, add a 24–48 hour buffer to discharge-transload timing. The Dallas FTL quote and transit_days give you a concrete downstream plan; surface all three insights in one control card.

Example: Carrier Vetting Before Tender 

curl -s -H "X-API-Key: YOUR_API_KEY" \
"https://freightpulsehq.com/api/v1/carriers?q=ACME%20TRUCKING&type=trucking"

{
"success": true,
"data": {
"type": "trucking",
"query": "ACME TRUCKING",
"results": [
{
"dot_number": 1234567,
"legal_name": "ACME TRUCKING LLC",
"status": "active",
"safety_rating": "S",
"drivers": 87,
"address": {
"city": "Grapevine",
"state": "TX",
"country": "US"
}
}
]
}
}

Interpretation: status=active and safety_rating=S clears automated tendering. If you have a policy requiring minimum driver count for specific lanes, use drivers to enforce it.

Example: Fuel Market Newsletter 

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

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

Interpretation: Compute WoW and YoY deltas; chart the 4-week and 12-week moving averages; include a one-liner on port signals for LA/LB and Rotterdam from /port-congestion to enrich your commentary.

Developer Implementation Guidance and Best Practices

FAQ

How often do FreightPulse fuel prices update?

Fuel prices reflect official EIA data cadence and include timestamped payloads for freshness. Use the timestamp to drive cache invalidation and clearly annotate your UI with “As of …” so operators trust the figures they see.

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

Yes. The /carriers endpoint supports type=ocean for FMC NVOCC/OTI directory lookups, and the default type=trucking covers FMCSA SAFER data. Air queries return available:false, so you can handle that gracefully in your UI.

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

No. Port congestion in FreightPulse is a lagged approximation derived from IMF PortWatch’s AIS-based aggregations. It represents a 7-day average versus a 90-day baseline with a data lag of roughly 6–7 days—ideal for planning and trend analysis, not live berth operations.

Can I filter natural-disruption alerts to only those that matter for my port?

Yes. Include the port parameter when querying /disruptions to retrieve events within a defined proximity to that port (300km globally and 100km radius for US weather). This keeps alerts relevant to shipments in-flight and reduces noise.

What’s the best way to combine FTL quotes with fuel indices and port signals?

Fetch /freight-rates for lane-level quotes, use /fuel-prices for surcharge context, and pull /port-congestion for port activity normalization. Apply a risk-aware ETA buffer if congestion is moderate/high or if /disruptions flags high-severity events near the relevant port.

Conclusion + CTA

A credible multimodal visibility layer doesn’t have to mean five vendor contracts, five schemas, and five different operational failure modes. By consolidating satellite AIS-proxied port activity, live truck quotes, fuel indices, carrier verification, and natural-disruption intelligence behind one API, your team can move faster, reduce brittle integration code, and deliver clearer operational guidance to customers. You get planning signals where they matter and live quotes where timing is critical—all in one consistent JSON envelope that’s easy to observe and govern.

If you’re building a control tower, a data-driven TMS, or a market analytics product, the path to value is short: start with port congestion and disruptions to orient your ocean leg, layer on FTL quotes for inland routing, and anchor your price narrative with fuel indices. With a handful of endpoints, your product can surface actionable insight across modes without claiming “real-time AIS” where you don’t need it—and without the fragility that comes from stitching together disparate feeds.

Ready to ship a unified multimodal visibility layer? Explore the endpoints and examples above and bring them into your stack today. Visit FreightPulse to learn more, or jump in and Try FreightPulse for free.