Home → Blog

You need to turn messy, lagged, and real-time logistics signals into a product your sales team can stand behind: premium time-definite shipping with guaranteed transit windows. By the end of this tutorial, you’ll be able to compute a defensible pickup-to-delivery window that accounts for current truckload transit expectations, historical fuel impacts, port congestion drift, and natural-disruption risk—pulled from one place: FreightPulse.

Introduction

Any promise that includes “guaranteed by” is a technical commitment. If you run a 3PL, enterprise routing team, or a freight SaaS platform, you’ve likely stitched together multiple feeds—EIA for fuel, a market-rate widget for trucking quotes, an AIS feed just to eyeball port congestion, a weather alert bot, and a spreadsheet of risk buffers. The operational result is drift: buffers swell, quotes slip, and “guaranteed” becomes “aspirational.”

This post shows a pragmatic path to package time-definite products using FreightPulse latency signals. We’ll combine live FTL transit-day expectations, lagged-but-stable port congestion ratios, and port-proximate disruption alerts to produce a risk-adjusted delivery window you can expose to customers and enforce with SLAs. You’ll see concrete API calls and field-by-field logic you can ship this week.

Why FreightPulse

Quick Start

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

Authentication: Send X-API-Key: YOUR_API_KEY. Unauthenticated requests are allowed up to 100/day per IP (guest access).

First request: check the current national diesel price and regional breakdowns to size fuel surcharge buffers.

curl -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 you’ll actually use:

JavaScript example: read diesel prices and compute a simple surcharge basis

async function fetchDiesel() {
const resp = await fetch("https://freightpulsehq.com/api/v1/fuel-prices", {
headers: { "X-API-Key": "YOUR_API_KEY" }
});
const json = await resp.json();
if (!json.success) throw new Error(json.error);
const diesel = json.data.data.diesel;
// Example: surcharge basis = delta vs 90d average
const basis = diesel.national_average - diesel.historical["90d_avg"];
return { current: diesel.national_average, basis, timestamp: json.data.timestamp };
}

fetchDiesel().then(console.log).catch(console.error);

Core Endpoints

1) Live truckload transit expectations for your base window

Endpoint: GET /freight-rates

Purpose: Get a lane’s current price and transit_days. Use transit_days as the center of your time window before applying risk buffers.

Key params:

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

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

Use transit_days and delivery_date to define your base commitment. If your request is missing required parameters, the API returns HTTP 200 with an availability indicator instead of a hard error, so always validate inputs client-side.

2) Port congestion drift to modulate cross-border or dray buffers

Endpoint: GET /port-congestion

Purpose: Pull a lagged approximation of port activity—7-day average portcalls vs a 90-day baseline—to bias buffers up or down. This is not live AIS; the data lags ~6–7 days.

Key params (at least one):

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

Practical use: When ratio_vs_baseline is significantly below 1.0, treat as soft congestion signal and extend ocean-dray or transload buffers. as_of is your data currency and good for cache headers.

3) Disruption alerts near a port or lane

Endpoint: GET /disruptions

Purpose: Detect cyclones, earthquakes, and severe weather that could impact a leg. You can filter by port; the API uses a default search radius (300km; 100km for US weather) so you don’t have to manage geo-polygons.

Key params:

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

Use severity and type to adjust buffers asymmetrically. For example, raise the late-side buffer by 12–24 hours for high-severity cyclones near the receiving port. starts_at is in ISO 8601 with timezone.

4) Historical series for stability checks

Endpoint: GET /historical

Purpose: Pull a compact series for diesel or a curated set of major ports. Use it to compute trend multipliers or to show SLA-rationale charts in your UI.

Key params:

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

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

Each element in series is date (YYYY-MM-DD) and value. Cache daily; roll over at the same cadence as source updates.

Real-World Use Cases

1) Time-definite trucking with risk-adjusted windows

Use /freight-rates to get transit_days and delivery_date for the requested pickup_date, then adjust the late-side buffer when /disruptions returns high-severity events along the route or near the destination metro (proxy via destination port if applicable). Fuel volatility from /fuel-prices can be displayed as a separate surcharge or used to lock pricing for a limited time window.

2) Ocean-to-truck SLA with port drift buffers

For ocean legs that touch curated major ports, query /port-congestion for the destination port and interpret ratio_vs_baseline below 1.0 as soft congestion. If ratio is 0.85 and /disruptions shows active severe_weather nearby, extend the drayage/transload-to-FTL handoff window by 12–36 hours depending on severity. Use /historical for that port to avoid overreacting to a single lagged snapshot.

3) Fuel-inclusive guaranteed quote builder

Combine /freight-rates price_usd with a surcharge derived from /fuel-prices diesel national_average and your fleet MPG assumptions. If the 30d_avg is sharply below current, limit the quote validity window or raise the risk buffer. Show the surcharge math in your UI so sales can explain deltas to enterprise shippers.

Putting it together: from signals to guaranteed windows

Here’s a practical algorithm you can implement today to produce a time-definite delivery window:

  1. Base transit: Call /freight-rates for the lane to get transit_days and delivery_date. Treat delivery_date as the center (or the right edge if you promise “by end of day”).
  2. Disruption bias: Call /disruptions for the nearest port or the destination country/region. For high-severity cyclones or severe_weather, add +24h late-side buffer; for moderate, +12h. If none, +0h.
  3. Port drift (if ocean leg involved): From /port-congestion, map ratio_vs_baseline to buffer adjustment, e.g., ratio <= 0.85 → +12h, 0.85–1.0 → +6h, > 1.0 → 0h. Note the as_of lag in your contract language.
  4. Price stability note: If diesel from /fuel-prices is ≥10% above its 90d_avg, shorten the quote validity period and pre-allocate capacity earlier in your TMS.

The outcome is a deterministic SLA window and a small set of inputs you can show to customers and operations: transit_days, disruption severity near the destination, and port activity signal.

Operational details that save an hour

Example: end-to-end fetch and window computation (concept)

This example shows the control flow you’ll write in your service. Values are illustrative; wire in your business thresholds.

async function computeGuaranteedWindow({ origin_zip, destination_zip, pickup_date }) {
// 1) Base transit from live trucking rates
const rateResp = await fetch(`https://freightpulsehq.com/api/v1/freight-rates?mode=trucking&origin_zip=${origin_zip}&destination_zip=${destination_zip}&pickup_date=${pickup_date}`, {
headers: { "X-API-Key": "YOUR_API_KEY" }
}).then(r => r.json());
if (!rateResp.success) throw new Error(rateResp.error);
const base = rateResp.data; // has transit_days and delivery_date

// 2) Disruption bias near destination port or region (use a known port if ocean leg exists)
const disResp = await fetch("https://freightpulsehq.com/api/v1/disruptions?port=USLAX&severity=high", {
headers: { "X-API-Key": "YOUR_API_KEY" }
}).then(r => r.json());
let lateBiasHours = 0;
if (disResp.success && disResp.data.results.length > 0) {
lateBiasHours = 24; // example: high-severity bias
}

// 3) Optional port drift bias
const pcResp = await fetch("https://freightpulsehq.com/api/v1/port-congestion?port=USLAX", {
headers: { "X-API-Key": "YOUR_API_KEY" }
}).then(r => r.json());
if (pcResp.success && pcResp.data.results.length) {
const ratio = pcResp.data.results[0].metrics.ratio_vs_baseline;
if (ratio <= 0.85) lateBiasHours += 12;
else if (ratio < 1.0) lateBiasHours += 6;
}

// 4) Compute window
const deliveryDate = new Date(base.delivery_date + "T17:00:00"); // assume EOD local; adjust per ops policy
const start = new Date(deliveryDate.getTime() - 12 * 3600 * 1000); // -12h early window
const end = new Date(deliveryDate.getTime() + lateBiasHours * 3600 * 1000);
return { start: start.toISOString(), end: end.toISOString(), transit_days: base.transit_days, price_usd: base.price_usd };
}

FAQ

How often do FreightPulse fuel prices update?

The fuel price endpoint reflects EIA data and includes a timestamp field you can treat as authoritative for caching. You also get 30d/90d historical averages to stabilize your surcharge math when week-to-week changes are noisy.

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

No. Port congestion is an approximation from IMF PortWatch AIS data: a 7-day average of portcalls versus a 90-day baseline, with a ~6–7 day lag. Use it to bias buffers, not to micro-time live ETAs.

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

Yes. The /carriers endpoint supports US trucking (FMCSA SAFER) and ocean NVOCC/OTI (FMC directory). Set type to trucking or ocean and pass q (DOT number, org number, or name). Air returns available:false.

How do I monitor natural hazards near a specific port without managing geofences?

Use /disruptions with the port parameter (e.g., USLAX). The API filters by distance to that port (300km default radius; 100km for US weather), returning relevant cyclones, earthquakes, floods, wildfires, and severe weather.

What happens if I exceed my request quota?

You’ll receive HTTP 429 with a JSON error message. Handle it by backing off, caching static fields by their timestamp/as_of dates, and consolidating queries where possible.

Conclusion + CTA

Time-definite shipping doesn’t require a patchwork of feeds or a data engineering backlog. With live truckload transit expectations, lag-aware port activity, nearby hazard alerts, and stable fuel context—all in one API—you can compute a delivery window that your team can support operationally and explain to customers clearly.

Build and ship your first guaranteed window today. Explore endpoints with guest access or wire them into your pricing and planning services. Try FreightPulse for free and turn latency signals into dependable SLAs for enterprise shippers and 3PLs.