Home → Blog

Logistics teams rely on truck telematics for GPS pings, engine hours, and duty-cycle data, yet a surprising amount of ETA risk still hides outside the cab: fuel price swings that force routing changes, upstream port slowdowns that starve DCs, and severe weather that shuts interstates. Without a way to fuse telematics with real-time market and disruption intelligence, planners end up firefighting with stale spreadsheets, while dispatchers chase exceptions shipment by shipment. The result: ETAs slip, detention compounds, and utilization inches down instead of up.

This post walks through how to integrate your truck telematics stack with FreightPulse, a single REST API that consolidates live US FTL quotes, EIA fuel prices, port congestion signals, FMCSA/FMC carrier lookups, and natural-disruption alerts. You will learn how to use these signals to make your ETA models more robust and to surface actionable utilization insights—in near real time—without wiring up five different data providers. We will cover the endpoints you need, show complete JSON responses, and detail how to stitch results with telematics data to drive better dispatch, routing, and procurement decisions.

We will treat this as a developer tutorial: start with the logistics problems, implement the data plumbing with practical code, and finish with production-minded patterns for monitoring, validation, and exception handling that your operations team will appreciate on Day 1.

Why FreightPulse

Developers and operators often assemble a patchwork of feeds: one for fuel, one for freight quotes, another for carrier compliance, an AIS-driven port dataset, and a handful of weather or hazard sources. The stitching alone—normalizing schemas, dealing with stale endpoints, and aligning timestamps—can eat sprints. FreightPulse compresses that problem to one REST surface with a consistent response shape and practical coverage across transportation realities that affect truck ETAs and fleet productivity.

Here are the core differentiators that matter when you are building ETA and utilization features:

In short, FreightPulse collapses multi-provider complexity into one developer-friendly interface so you can focus on logic: ETA recalculation, dispatch heuristics, and utilization uplift—not on plumbing.

Quick Start

Base URL:

https://freightpulsehq.com/api/v1

All responses share this structure: 

{
"success": true,
"data": {
"...": "endpoint-specific payload"
}
}

Let’s make a first request for national fuel prices. This gives you diesel and gasoline averages you can immediately wire into linehaul cost models or fuel-surcharge logic attached to your dispatch system. 

curl "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 and how to use them:

Core Endpoints

For truck telematics integration focused on real-time ETA accuracy and utilization insights, these FreightPulse endpoints form the backbone: /freight-rates for live cost and transit-day references, /disruptions for hazard-aware routing, /port-congestion for upstream flow shaping ETAs, /carriers for compliance and partner routing, /fuel-prices for cost-to-serve math, and /historical for timeseries modeling. Below, we cover each with parameters, cURL examples, complete JSON, and field-by-field guidance.

1) Live FTL Freight Rates — GET /freight-rates

What it solves: Where telematics tells you where the truck is, live FTL quotes tell you whether a lane is surging and what realistic transit duration looks like today. That matters for dispatchers committing to pickup windows and for planners adjusting ETAs after a mid-week tender.

Endpoint:

/freight-rates

Key params:

Example: 

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

Sample 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:

Notes:

2) Natural-Hazard Disruptions — GET /disruptions

What it solves: ETAs derail most often due to weather and seismic events. Your telematics app can ingest this feed, filter by corridor or port radius, and proactively reroute or resequence stops before trucks hit road closures or cyclone bands.

Endpoint:

/disruptions

Key params:

Example: 

curl "https://freightpulsehq.com/api/v1/disruptions?port=USLAX&severity=high"

Sample 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:

3) Port Congestion — GET /port-congestion

What it solves: Upstream port slowdowns shape truck ETAs days to weeks out—yard turns stretch, drayage arrivals compress, and long-haul pickups swing. You do not need expensive live AIS to get a reliable signal. FreightPulse provides a lagged approximation (~6–7 days) using a 7-day average of port calls vs. a 90-day baseline.

Endpoint:

/port-congestion

Key params:

Example: 

curl "https://freightpulsehq.com/api/v1/port-congestion?port=USLAX"

Sample 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:

4) Carrier Verification — GET /carriers

What it solves: When dispatching overflow or brokering a last-minute rescue, you need to vet motor carriers quickly. Pull status, safety rating, headcount, and location from an authoritative directory so you can automate acceptance rules and reduce on-hold time.

Endpoint:

/carriers

Key params:

Example (US trucking by DOT number): 

curl "https://freightpulsehq.com/api/v1/carriers?q=54283"

Sample 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:

5) Fuel Prices — GET /fuel-prices

What it solves: Accurate ETAs are half the battle—profitable ETAs are the other half. Weekly diesel indices drive surcharges and can influence route recommendations (e.g., a slightly longer route with cheaper PADD fuel may be optimal).

Endpoint:

/fuel-prices

Key params: None required.

Practical tips:

6) Historical Series — GET /historical

What it solves: ETAs and utilization improve when your models incorporate trends. Use diesel series for seasonal cost patterns and port-congestion series for medium-term arrival shaping across ocean-to-OTR handoffs.

Endpoint:

/historical

Key params:

Example (diesel series, 30 days): 

curl "https://freightpulsehq.com/api/v1/historical?metric=fuel_price_diesel_national&period=30d"

Sample 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:

Real-World Use Cases

1) Hazard-Aware ETA Adjustment for Live Fleets

Combine your telematics GPS pings and duty status with FreightPulse /disruptions. Every five minutes, query disruptions filtered to your destination corridor or port radius. If a severe_weather event intersects the route in the next 6 hours, extend ETA by a policy-based buffer (e.g., 15% plus fixed 30 minutes) and alert dispatch. Endpoints: /disruptions and /freight-rates (to re-benchmark transit_days when rebidding urgent tenders).

2) Drayage Arrival Smoothing with Port Congestion Trends

Inbound ocean shipments create bursts of drayage work. Use /port-congestion to classify target ports as low/moderate/high and /historical with port_congestion:<portid> to understand trend direction. Feed this into your yard and chassis scheduling; if congestion is high and rising, pre-book drivers earlier and spread arrivals across terminals to protect dwell KPIs. Endpoints: /port-congestion, /historical.

3) Lane Cost and Surcharge Planner

Before tendering overflow, query /freight-rates for an on-the-day price and transit_days. Pull /fuel-prices to compute a transparent surcharge, optionally smoothed with /historical for 30d averages. Present procurement with a “price-to-ETA” graph, letting them trade time sensitivity for cost while preserving utilization goals. Endpoints: /freight-rates, /fuel-prices, /historical.

4) Carrier Vetting Inside a TMS Tender Screen

When an operator types a DOT number in your tender form, auto-query /carriers to confirm status=s active and safety_rating within thresholds. Flag risky carriers and recommend alternatives that match geography and size. This shortens tender cycles and reduces rejects. Endpoints: /carriers.

5) Exception Management for Weather and Seismic Events

Build a control-tower widget that constantly polls /disruptions for cyclone and severe_weather near your high-volume corridors. When triggered, push tasks to dispatch to resequence stops, notify shippers, and, when necessary, reprice urgent tenders with /freight-rates. Endpoints: /disruptions, /freight-rates.

FAQ

How often do FreightPulse fuel prices update?

Fuel prices are sourced from the EIA and presented with a timestamp in the response. Use that timestamp for cache control and UI recency indicators. Pair the current value with the 30d and 90d averages to stabilize week-to-week fluctuations in your pricing logic.

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

Yes. The /carriers endpoint supports type=ocean for FMC directory lookups by name or organization number. For US trucking carriers, use the default type=trucking with DOT numbers or names for FMCSA SAFER data. Air queries return available: false.

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

No. Port congestion is a lagged approximation (~6–7 days) built from a 7-day average of port calls versus a 90-day baseline. It is designed for planning and trend analysis, not live berth or anchor wait times. Always use the as_of date to communicate recency to operators.

Can I use these endpoints to trigger hazard-aware routing for my trucks?

Yes. Filter /disruptions by type and port or country, join with telematics GPS and planned routes, and apply policy-based ETA buffers or alternate corridors. This is especially effective when combined with /freight-rates to re-benchmark delivery commitments.

How should I combine telematics speed data with FreightPulse transit_days?

Use transit_days as a prior, then apply real-time corrections from telematics (average speed by road class, driver HOS, dwell) and any active disruptions. Over time, fit lane-specific bias adjustments so your model learns where transit_days consistently runs hot or cold relative to your fleet performance.

Conclusion + CTA

Telematics alone describes what your trucks are doing. To predict what they will do next—reliably and profitably—you need external context: dynamic rates, shifting port throughput, severe weather, and validated carrier partners. FreightPulse brings those inputs into one developer-friendly API so you can build hazard-aware ETAs, smoother drayage handoffs, smarter tendering, and higher utilization—all without maintaining a web of provider integrations.

Start small: wire /disruptions into your dispatch exceptions. Then add /freight-rates for mid-tender replans and /fuel-prices to ground your surcharge math. As you harden the workflow, layer /port-congestion and /historical for horizon-level forecasts and dashboards your operators will trust. The result is fewer surprises on the road, tighter arrival windows, and better asset productivity.

Ready to see these building blocks in action inside your telematics or TMS stack? Try FreightPulse for free and ship a working prototype today.

Implementation Notes, Examples, and Best Practices

Below are additional patterns and code snippets to help you get from proof-of-concept to production-grade integration.

Joining telematics pings with disruption alerts

Assume you have a stream of GPS pings with longitude, latitude, and planned route segments. Poll /disruptions by relevant port or country, then intersect the disruption bounding area with your next 200 miles of corridor. When an overlap is detected at severity=high, apply a buffer to the ETA and notify dispatch. 

// JavaScript (Node.js) - minimal example
import fetch from "node-fetch";

async function getDisruptionsNearPort(locode) {
const url = `https://freightpulsehq.com/api/v1/disruptions?port=${encodeURIComponent(locode)}&severity=high`;
const res = await fetch(url);
const json = await res.json();
if (!json.success) throw new Error(json.error || "Unknown error");
return json.data.results || [];
}

async function adjustEtaForHazards(currentEtaMinutes, nextCorridorPort) {
const hazards = await getDisruptionsNearPort(nextCorridorPort);
const hasSevere = hazards.some(h => ["severe_weather", "cyclone", "wildfire"].includes(h.type));
if (hasSevere) {
// Example policy: +15% and +30 minutes hard buffer
return Math.round(currentEtaMinutes * 1.15 + 30);
}
return currentEtaMinutes;
}

adjustEtaForHazards(420, "USLAX").then(console.log).catch(console.error);

Using live FTL quotes to replan time-sensitive pickups 

# Python - replanning an urgent tender
import requests
from datetime import date

def get_quote(origin_zip, destination_zip):
params = {
"mode": "trucking",
"origin_zip": origin_zip,
"destination_zip": destination_zip,
"pickup_date": str(date.today())
}
r = requests.get("https://freightpulsehq.com/api/v1/freight-rates", params=params, timeout=15)
data = r.json()
if not data.get("success"):
raise RuntimeError(data.get("error", "quote failed"))
return data["data"]

quote = get_quote("77001", "33101")
print(f"Price: ${quote['price_usd']:.2f}, Transit: {quote['transit_days']} days, Delivers: {quote['delivery_date']}")

Building a port-congestion trendline for dray planning

To support staffing and chassis allocation around LA/LB, query a daily series with /historical for port_congestion:USLAX and plot the ratio_vs_baseline if provided via a separate series endpoint. When working with /port-congestion alone, combine recent_avg_portcalls_per_day and baseline_avg_portcalls_per_day for a derived ratio. 

curl "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 guidance:

Error handling and response shape

All endpoints share a consistent envelope. When a call fails, the API provides a machine-friendly structure: 

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

Production tips:

End-to-end flow: Telemetrics-driven ETA with FreightPulse context

Below is a reference flow you can adapt:

  1. Telematics pings update position and HOS every 60 seconds. Your ETA engine forecasts arrival using historical segment speeds and driver duty windows.
  2. FreightPulse /disruptions polled every 5 minutes. If a relevant event is detected within a 100–300km buffer around destination or along the corridor, your engine adds policy-based delay.
  3. If the run is an inbound port dray, /port-congestion supplies context for gate wait risk; if moderate/high, keep a bigger buffer and adjust yard staffing.
  4. For urgent replans or rescue loads, /freight-rates posts a live transit_days and price_usd. You weigh the replan vs. the driver’s remaining HOS to decide on a handoff or team run.
  5. /fuel-prices and /historical update surcharge logic weekly, ensuring your utilization KPI reflects both time and cost performance.
  6. /carriers validates partner carriers when overflow capacity is needed, enforcing safety and status gates automatically in your tender workflow.

This architecture pairs what’s happening on the road with what’s happening in the world, closing the loop between ETA, cost, and compliance—without a maintenance burden of multiple provider SDKs.

Additional complete JSON examples

Fuel prices (already shown above) are ideal for cost modeling. Here are extra full responses you can use for tests or mocks.

Disruptions filtered by severe weather: 

{
"success": true,
"data": {
"results": [
{
"id": "nws:SW:US:2026-08-19-CA-001",
"type": "severe_weather",
"severity": "high",
"title": "Severe Thunderstorm Warning - Ventura County",
"country": "United States",
"starts_at": "2026-08-19T18:30:00+00:00",
"source": "NOAA/NWS"
},
{
"id": "usgs:EQ:2026-08-19-BAJA-4.8",
"type": "earthquake",
"severity": "moderate",
"title": "M4.8 - Baja California",
"country": "Mexico",
"starts_at": "2026-08-19T16:12:00+00:00",
"source": "USGS"
}
]
}
}

Freight rates with missing params behavior (availability response): 

{
"success": true,
"data": {
"available": false,
"reason": "Missing required parameters: origin_zip, destination_zip"
}
}

Carrier lookup by name (trucking): 

{
"success": true,
"data": {
"type": "trucking",
"query": "Acme Logistics",
"results": [
{
"dot_number": 1234567,
"legal_name": "ACME LOGISTICS LLC",
"status": "active",
"safety_rating": "S",
"drivers": 114,
"address": {
"city": "Dallas",
"state": "TX",
"country": "US"
}
},
{
"dot_number": 7654321,
"legal_name": "ACME LOGISTICS HOLDINGS INC",
"status": "inactive",
"safety_rating": "N",
"drivers": 0,
"address": {
"city": "Fort Worth",
"state": "TX",
"country": "US"
}
}
]
}
}

Port congestion for a region filter: 

{
"success": true,
"data": {
"results": [
{
"port": "Rotterdam",
"locode": "NL RTM",
"country": "Netherlands",
"congestion": "low",
"as_of": "2026-08-12",
"metrics": {
"recent_avg_portcalls_per_day": 24.1,
"baseline_avg_portcalls_per_day": 23.8,
"ratio_vs_baseline": 1.01
}
},
{
"port": "Antwerp-Bruges",
"locode": "BE ANR",
"country": "Belgium",
"congestion": "moderate",
"as_of": "2026-08-12",
"metrics": {
"recent_avg_portcalls_per_day": 18.3,
"baseline_avg_portcalls_per_day": 20.0,
"ratio_vs_baseline": 0.92
}
}
]
}
}

Field-by-field mapping to ETA and utilization logic

Performance and resiliency tips

When these practices are in place, your integration stays reliable even under peak operations while providing operators with trustworthy context for decisions.