Home → Blog

Enterprise supply chain teams live in a world of constant flux: diesel prices swing weekly, FTL rates can climb overnight on tight capacity, a tropical system spins up across the Pacific, and a handful of high-volume ports ebb and flow with congestion. The hard part is not acknowledging uncertainty—it’s simulating it, testing scenarios, and confidently answering “What happens to our network if fuel spikes 15% next month? What if Los Angeles-Long Beach slows to 80% of baseline? What if a severe weather system sits 100 km from our critical inland port?” Without the right data, your digital twin is just a pretty diagram.

This post shows how to design a digital twin of your freight network with a single, developer-friendly integration. Using FreightPulse, you can stitch together the five essential pillars of logistics intelligence—fuel prices, live truckload quotes, port congestion, carrier verification, and natural-disruption alerts—behind one consistent REST API. We’ll walk through how to wire each dataset into a test harness for scenario analysis and disruption simulation, so your planners, TMS, and control tower apps can move from reactive to predictive.

You’ll see concrete cURL and code examples, complete JSON responses, field-by-field explanations, and proven best practices for reliability, routing, and observability. By the end, you’ll have a blueprint for a production-grade digital twin that helps engineering, operations, and finance align around shared “what-if” models—and make confident decisions under uncertainty.

Why FreightPulse

Designing a digital twin is less about models and more about the data contracts that feed them. The biggest friction for developers is not visualization or math—it’s wrestling with multiple schemas and update cycles across different public agencies and commercial feeds. Here is why FreightPulse accelerates the journey from zero to a working supply chain twin:

Quick Start

All requests use the same base: 

Base URL: https://freightpulsehq.com/api/v1
Common response envelope:
{
"success": true | false,
"data": { ... },
"error": "message" // present only when success=false
}

Let’s start with a fuel-price pull. You’ll use this to parameterize your fuel-surcharge model in the twin. 

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

Core Endpoints for a Digital Twin

1) Fuel Prices — GET /fuel-prices

Purpose: Power surcharge calculators, sensitivity analysis, and forward-looking budget scenarios by anchoring your network’s variable cost inputs to current and historical diesel/gasoline data.

Key characteristics:

Example request: 

curl "https://freightpulsehq.com/api/v1/fuel-prices"

Interpretation tips:

2) Live Freight Rates — GET /freight-rates

Purpose: Inject current market rates into lane-level cost models for U.S. truckload movements, with limited support for ocean/air into U.S. ZIPs for Asia-origin legs. This turns your twin from a static bill-of-rates into a live-to-market simulator.

Core parameters:

Example (U.S. FTL 53’ dry van): 

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

Key fields:

Notes:

3) Port Congestion — GET /port-congestion

Purpose: Approximate port activity to detect slowdowns or throughput risk. The metric compares a rolling 7-day average portcalls against a 90-day baseline. It is intentionally lagged by several days and should not be interpreted as live vessel wait times. Use it to set “congestion regimes” in your twin that affect ocean-to-land transit assumptions, drayage capacity, and DC receiving schedules.

Core parameters:

Example request: 

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 model with these fields:

4) Carrier Verification — GET /carriers

Purpose: Validate carriers before tendering or modeling capacity. For U.S. trucking, you can pull DOT numbers, status, safety ratings, and driver counts; for ocean, you can look up NVOCC/OTI records. Use this in your twin to filter out non-compliant carriers and to weight capacity assumptions by size/safety.

Core parameters:

Example (U.S. 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 it:

5) Natural-Disruption Alerts — GET /disruptions

Purpose: Detect and simulate the impact of natural hazards near your critical nodes or ports before they affect live shipments. Use the port-radius filter to pre-qualify risk for the exact gateways in your network model.

Core parameters:

Example (high-severity disruptions near USLAX): 

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

Modeling guidance:

6) Historical Time Series — GET /historical

Purpose: Power trend-aware models, rolling baselines, and anomaly detection inside your twin. You can query diesel/gasoline series or port-congestion history for curated major ports to visualize seasonality and calibrate buffers.

Core parameters:

Example (30-day diesel time series): 

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

Modeling tips:

Building the Digital Twin: Architecture, Routing, and Reliability

Your digital twin needs more than raw data endpoints—it needs a resilient data pipeline and a clean contract with your simulation engine. Below are pragmatic guidelines for how to wire FreightPulse into a production-grade, enterprise-ready twin.

Recommended architecture

Per-request routing and performance best practices

Governance and controls

Observability and error handling

Example error response (to test your handlers): 

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

Implementation Walkthroughs with Code

cURL: Compose a scenario-ready snapshot

Fetch the key ingredients for a baseline run: fuel prices, an LA port congestion read, and a representative east-to-west FTL quote. Store them under a single scenario ID in your cache or DB. 

# 1) Fuel
curl "https://freightpulsehq.com/api/v1/fuel-prices"

# 2) Port congestion (Los Angeles-Long Beach)
curl "https://freightpulsehq.com/api/v1/port-congestion?port=USLAX"

# 3) FTL quote (NYC → Beverly Hills)
curl "https://freightpulsehq.com/api/v1/freight-rates?mode=trucking&origin_zip=10001&destination_zip=90210"

Python: Minimal client with retries and normalization 

import time
import requests

BASE = "https://freightpulsehq.com/api/v1"

def get(path, params=None, retries=3):
url = f"{BASE}{path}"
for attempt in range(retries):
try:
r = requests.get(url, params=params, timeout=5)
r.raise_for_status()
payload = r.json()
if not payload.get("success", False):
raise RuntimeError(payload.get("error", "Unknown error"))
return payload["data"]
except Exception as e:
if attempt == retries - 1:
raise
time.sleep(0.5 * (2 ** attempt))

def fuel_snapshot():
data = get("/fuel-prices")
d = data["data"]["diesel"]
return {
"as_of": data["timestamp"],
"unit": data["unit"],
"national": d["national_average"],
"regions": d["regions"],
"trend_30d": d["historical"]["30d_avg"],
"trend_90d": d["historical"]["90d_avg"]
}

def la_congestion():
data = get("/port-congestion", {"port": "USLAX"})
res = data["results"][0]
return {
"as_of": res["as_of"],
"ratio": res["metrics"]["ratio_vs_baseline"],
"label": res["congestion"]
}

def ftl_quote(o, d):
data = get("/freight-rates", {"mode": "trucking", "origin_zip": o, "destination_zip": d})
return {
"price": data["price_usd"],
"transit_days": data["transit_days"],
"pickup_date": data.get("pickup_date"),
"delivery_date": data.get("delivery_date")
}

if __name__ == "__main__":
fuel = fuel_snapshot()
la = la_congestion()
nyc_to_bh = ftl_quote("10001", "90210")
print({"fuel": fuel, "la_congestion": la, "nyc_to_bh": nyc_to_bh})

JavaScript: Browser or Node fetch with guardrails 

async function fpGet(path, params = {}) {
const url = new URL(`https://freightpulsehq.com/api/v1${path}`);
Object.entries(params).forEach(([k, v]) => url.searchParams.set(k, v));
const res = await fetch(url.toString(), { method: "GET" });
const body = await res.json();
if (!body.success) throw new Error(body.error || "Unknown error");
return body.data;
}

async function scenario() {
const [fuel, la, quote] = await Promise.all([
fpGet("/fuel-prices"),
fpGet("/port-congestion", { port: "USLAX" }),
fpGet("/freight-rates", { mode: "trucking", origin_zip: "10001", destination_zip: "90210" })
]);

const diesel = fuel.data.diesel.national_average;
const ratio = la.results[0].metrics.ratio_vs_baseline;
const price = quote.price_usd;

// Example derived KPIs for UI
return {
diesel,
la_ratio: ratio,
lane_price: price,
congestion_status: la.results[0].congestion,
as_of: {
fuel: fuel.timestamp,
port: la.results[0].as_of
}
};
}

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

Real-World Use Cases

1) Fuel-surcharge calculator with regional weighting

Operations and finance often need a defensible, transparent fuel-surcharge logic. Use GET /fuel-prices to compute a base surcharge from data.diesel.national_average and refine it by legs that traverse regions.*. Persist the surcharge curve for each week and expose it via your TMS UI. When modeling forward, pull /historical to project trends and test shock scenarios (+10%, +20%).

2) Port-congestion dashboard for import planning

A freight forwarder wants daily visibility into congestion regimes across a curated list of global ports that feed its clients’ DCs. Use GET /port-congestion with port or country filters to populate a dashboard showing congestion labels, ratio_vs_baseline, and as_of. When labels cross thresholds (e.g., moderate → high), trigger “what-if” re-routing runs to alternate gateways. Pair with GET /disruptions to surface hazard proximity around those same ports.

3) Carrier vetting and allocation in a 3PL tendering tool

Before a tender is released, the platform needs carrier validation and capacity hints. Use GET /carriers to check status, safety_rating, and drivers for candidates. Filter out non-active or low-safety carriers; weight allocations toward carriers with higher driver counts. Combine with GET /freight-rates to estimate cost and GET /fuel-prices to finalize the fuel-adjusted landed cost for each carrier candidate.

4) Disruption-aware shipment tracker with port radius filters

A supply chain SaaS provider enriches shipment ETAs with hazard awareness. Use GET /disruptions?port=USLAX (or any relevant node) and type/severity filters to surface cyclones, severe weather, or earthquakes near that gateway. If severity is high, add predicted delays to downstream legs and notify operators of a recommended re-route. Complement this with GET /port-congestion to show baseline vs. recent throughput context.

5) End-to-end digital twin scenario engine

An enterprise supply chain team builds a scenario engine that toggles fuel costs, congestion ratios, and live rates to compute total network cost, on-time probability, and service-level risk. For each scenario: pull /fuel-prices, /port-congestion for the relevant gateways, /freight-rates for top lanes, and /carriers for compliance filters. Use /historical to backtest the model’s predictions against prior periods and calibrate how aggressively to react to weekly swings.

End-to-End Field Explanations and Practical Usage

Fuel fields you should persist

Freight rate fields to model

Port congestion interpretation

Carrier vetting essentials

Disruption alert handling

Performance Tips and Caching Strategies

Developer Patterns for Scenario Testing

Additional Complete Examples

Compute a region-weighted fuel surcharge 

# Pseudocode
diesel = GET /fuel-prices
regions = diesel.data.diesel.regions
legs = [
{ miles: 850, region: "gulf_coast" },
{ miles: 300, region: "west_coast" }
]
base_mpg = 6.5
surcharge_per_mile = sum( (leg.miles / base_mpg) * regions[leg.region] ) / sum(leg.miles)

Map congestion ratio to dwell multiplier 

# Example heuristic
ratio = GET /port-congestion (USLAX).data.results[0].metrics.ratio_vs_baseline
if (ratio >= 0.95) dwell_multiplier = 1.0
else if (ratio >= 0.85) dwell_multiplier = 1.1
else if (ratio >= 0.75) dwell_multiplier = 1.25
else dwell_multiplier = 1.5

Composite JSON: Scenario bundle you might store 

{
"scenario_id": "S-2026Q3-LAX-ALT",
"created_at": "2026-08-20T10:22:00Z",
"inputs": {
"fuel_multiplier": 1.12,
"override_ports": {
"USLAX": { "ratio_override": 0.82 }
},
"allowed_carrier_safety": ["S"]
},
"snapshots": {
"fuel": { "diesel_usd_per_gal": 3.847, "as_of": "2026-07-30T12:00:00Z" },
"port": { "USLAX": { "ratio": 0.85, "as_of": "2026-08-14" } },
"rates": {
"10001-90210": { "price_usd": 7207.92, "transit_days": 4 }
}
},
"derived": {
"applied_port_ratio_USLAX": 0.82,
"ftl_price_adjusted": 7420.00,
"estimated_dwell_days": 2.6
}
}

FAQ

How often do FreightPulse fuel prices update?

Fuel data reflects weekly national and regional updates with historical context. Treat the timestamp in the response as the single source of truth for your surcharge tables and cache accordingly for stability.

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

Yes. The carrier lookup supports trucking by DOT or name and ocean NVOCC/OTI by organization identifiers or names. Air lookups return available: false so you can handle that case gracefully in your UI.

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

No. The congestion signal is a lagged approximation that compares a recent 7-day average to a 90-day baseline. Use it for trend and regime analysis, not minute-by-minute dispatch or live queue lengths.

How should I model disruption severity in my ETA calculations?

Map severity tiers to discrete delay multipliers by node type. For example, a high-severity cyclone near a major port could add multi-day delays across ocean arrival and drayage. Always bound the multipliers to avoid runaway estimates and override them when on-the-ground intel arrives.

What’s the best way to cache different FreightPulse signals?

Cache lagged or weekly signals (fuel, historical, congestion) for longer windows, and refresh on a schedule. Treat live FTL quotes as ephemeral—fetch on demand or expire quickly for batch simulations. For disruptions, poll more frequently around critical nodes and during known peak seasons.

Conclusion + Call to Action

A digital twin is only as good as its inputs. Freight networks operate on signals: prices, rates, activity, carrier quality, and disruptions. If you can’t ingest, normalize, and simulate those signals quickly, your twin will lag reality and your decisions will lag the market. With a single, consistent API, you can build a scenario engine that speaks the language of planners and the interface that engineers love—simple methods, clear JSON, and predictable semantics.

Whether you are a developer wiring up a microservice, a 3PL operations lead pushing for proactive routing, or an enterprise planning team under quarter-end pressure, a unified data surface is the fastest path from zero to a working simulation. Start by pulling fuel prices, add live FTL quotes for your top lanes, stitch in port congestion for gateways, enforce carrier vetting, and overlay disruption proximity. Then iterate: codify your delay multipliers, backtest against history, and publish explainable recommendations into your TMS or control tower.

Build a more resilient network model today. Explore the endpoints, run your first scenario, and put your digital twin to work: FreightPulse. Ready to experiment right now? Try FreightPulse for free.