Home → Blog

Dynamic pricing in freight forwarding has always been a juggling act. Spot truckload markets can swing by double-digit percentages week to week, diesel prices yo-yo with geopolitical shocks, and a thunderstorm aimed at a specific port can blow up your carefully modeled ETAs and margins. Many teams try to tame this with spreadsheets, stale CSVs, and a patchwork of one-off integrations—leading to brittle tooling that fails when you need it most.

This post shows how to build a production-grade dynamic pricing engine—one that continuously optimizes quotes in real time—using a single, developer-friendly API: FreightPulse. Instead of stringing together separate feeds for EIA fuel prices, FTL lane quotes, AIS-derived port congestion, FMCSA/FMC carrier lookups, and natural-disruption alerts, you can pull all of this intelligence from one REST surface with consistent schemas. We’ll walk through the key endpoints, practical data interpretation, error handling, and implementation patterns for reliable, low-latency pricing pipelines.

By the end, you’ll have a blueprint for calculating fuel surcharges from current diesel, benchmarking FTL quotes against congestion or disruption risk, validating carriers before tender, and surfacing port congestion trends to your margin model—all behind the same base URL. We’ll include end-to-end cURL and code examples, complete JSON responses, and concrete field-by-field breakdowns so you can ship faster with fewer moving parts.

Why FreightPulse

A dynamic pricing engine only works if it sees the market as it moves. FreightPulse consolidates the core signals your model needs—fuel, rates, congestion, carriers, and disruptions—so you can trade spreadsheet wrangling for clean, consistent JSON. Here are the key reasons teams ship with it:

Beyond data consolidation, FreightPulse is built for developers: consistent JSON envelopes, friendly defaults, and straightforward filtering. It’s the fastest path from idea to production—without wrestling five third-party contracts or reconciling disjointed schemas.

Quick Start

Base URL: 


https://freightpulsehq.com/api/v1

Authentication uses an HTTP header (X-API-Key). Requests without a key are also supported for exploration. Here is a first request that fetches national and regional fuel prices from EIA data: 


curl -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 for pricing:

With an anchor like national diesel at your fingertips, we can now layer in lane-specific FTL quotes, port congestion signals, and disruption risk scores—all in a consistent request pattern.

Core Endpoints for Real-Time Rate Optimization

A dynamic pricing engine benefits most from a few core signals: current fuel costs, live freight quotes, congestion context, carrier verification, disruption risk, and supporting historical series. FreightPulse provides dedicated endpoints for each. In this section, we’ll cover all available endpoints, demonstrate usage, and explain the response fields you’ll integrate directly into your pricing logic.

1) Fuel Prices: GET /fuel-prices

Purpose: Provide current national and regional diesel/gasoline benchmarks from the EIA, plus historical averages for model stabilization and trend analysis.

Key parameters: None (straightforward fetch). 


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

Representative response and field breakdown: 

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

Implementation best practices:

2) Freight Rates: GET /freight-rates

Purpose: Get live FTL rates for US ZIP-to-ZIP lanes (via Warp), with optional pickup dates and weight/quantity parameters. This is your main lane-price signal.

Key parameters: 


curl -H "X-API-Key: YOUR_API_KEY" \
"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"
}
}

Practical considerations:

3) Port Congestion: GET /port-congestion

Purpose: Provide an actionable congestion indicator for major global ports derived from IMF PortWatch (AIS-based) data. This is a lagged approximation of activity, not live queue/wait time. For pricing, treat it as a probability-of-delay proxy rather than a guarantee of real-time slowness.

Key parameters: 


curl -H "X-API-Key: YOUR_API_KEY" \
"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
}
}
]
}
}

Usage tips:

4) Carrier Verification: GET /carriers

Purpose: Validate US trucking carriers (FMCSA SAFER) and ocean NVOCC/OTI entities (FMC directories). Avoid quoting or tendering with carriers that are inactive or lack required credentials. Air is supported as a type but returns available:false at the moment.

Key parameters: 


curl -H "X-API-Key: YOUR_API_KEY" \
"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"
}
}
]
}
}

Implementation tips:

5) Disruption Alerts: GET /disruptions

Purpose: Identify active natural hazards from GDACS, USGS, and NOAA/NWS. Use these alerts to re-price risk on affected lanes, increase buffer times, or suggest alternate routes. Note: This feed covers natural hazards only—no labor actions or geopolitical events.

Key parameters: 


curl -H "X-API-Key: YOUR_API_KEY" \
"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"
}
]
}
}

Pricing heuristics:

6) Historical Series: GET /historical

Purpose: Pull weekly national fuel series (diesel/gasoline) and daily port congestion series for curated major ports. This is valuable for smoothing, forecasting, and comparing a live signal to its typical range.

Key parameters: 


curl -H "X-API-Key: YOUR_API_KEY" \
"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 }
]
}
}

Best practices:

Error Handling and Response Envelope

All FreightPulse responses share a consistent top-level shape. Successful calls include success: true and a data object. Errors return success: false with a human-readable error message. Incorporate this pattern to simplify your client handling and observability. 

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

Implementation tips:

End-to-End Implementation: From Data Signals to Price Output

Let’s wire these endpoints into a robust, production-ready pipeline that can ingest signals, apply business logic, and output optimized quotes with transparent justifications and audit trails.

High-Level Flow

Example: JavaScript (Node.js) Orchestration 


// Pseudocode-level example: orchestrate a price for NY 10001 to CA 90210

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

async function getJson(url) {
const res = await fetch(url, { headers: HEADERS });
const body = await res.json();
if (!body.success) throw new Error(body.error || "Unknown API error");
return body.data;
}

async function priceLane(originZip, destZip) {
// 1) Fuel anchor
const fuel = await getJson(`${BASE}/fuel-prices`);

// 2) Live rate
const rate = await getJson(`${BASE}/freight-rates?mode=trucking&origin_zip=${originZip}&destination_zip=${destZip}`);

// 3) Optional port context (if lane involves LA/LB drayage heuristics)
const port = await getJson(`${BASE}/port-congestion?port=USLAX`);

// 4) Disruptions near LA/LB
const disruptions = await getJson(`${BASE}/disruptions?port=USLAX&severity=high`);

// 5) Carrier vetting (example DOT)
const carriers = await getJson(`${BASE}/carriers?q=54283`);

// Combine signals into a price
const diesel = fuel.data.diesel.national_average;
const congestionRatio = port.results?.[0]?.metrics?.ratio_vs_baseline ?? 1.0;

let base = rate.price_usd;

// Example surcharge logic
const fuelSurcharge = Math.max(0, (diesel - 3.00) * 0.15 * 100); // illustrative only
const congestionAdj = congestionRatio < 0.9 ? (1 + (0.9 - congestionRatio)) : 1.0;
const disruptionAdj = disruptions.results?.length ? 1.05 : 1.0;

const finalPrice = Math.round(base * congestionAdj * disruptionAdj + fuelSurcharge);

return {
requested_lane: { originZip, destZip },
base,
adjustments: {
fuelSurcharge,
congestionAdj,
disruptionAdj
},
finalPrice,
evidence: {
fuelTimestamp: fuel.timestamp,
ratePickup: rate.pickup_date,
portAsOf: port.results?.[0]?.as_of,
carrierExample: carriers.results?.[0]?.dot_number
}
};
}

This orchestration demonstrates a few principles:

Expanded Endpoint Coverage with Complete Examples

Below are additional cURL and JSON examples for each endpoint, with deeper interpretation so you can drop data directly into a model or UI component.

Fuel Prices: Diesel and Gasoline Anchors

Use case: Weekly recalibration of surcharge tables and daily variance alerts to ops teams. 


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

Expanded field usage:

Freight Rates: Lane-Specific Quotes

Use case: Render an instant quote in your TMS UI and pre-compute several alternates (different pickup dates, weights) to surface tradeoffs. 


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

Interpreting outcomes:

Port Congestion: Activity Ratio and Severity

Use case: Inform pricing and ETA buffers for drayage legs and ocean-involved intermodal shipments. 


curl -H "X-API-Key: YOUR_API_KEY" \
"https://freightpulsehq.com/api/v1/port-congestion?country=United%20States&congestion=high"

This query narrows down US ports at high congestion levels. In a UI, you could:

Carriers: FMCSA and FMC Lookups

Use case: Auto-vetting carriers before rate confirmation; implementing must-pass rules (active status, acceptable safety rating). 


curl -H "X-API-Key: YOUR_API_KEY" \
"https://freightpulsehq.com/api/v1/carriers?type=ocean&q=Evergreen"

Interpret results:

Disruptions: Natural Hazards at Scale

Use case: Early reroute suggestions or dynamic pricing protection when severe weather targets a customer’s origin or destination. 


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

Operationalization:

Historical: Time Series for Stabilization

Use case: Price smoothing and anomaly detection for both fuel and port activity. 


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

Practical usage:

Reliability, Performance, and Governance Best Practices

Building a pricing engine is as much about reliability and observability as it is about fetching data. Here are platform-agnostic best practices—adapt them to your stack so your FreightPulse integration is robust and governed.

Resilience Patterns

Latency and Routing

Observability and Audits

Governance Controls

Python and JavaScript Client Examples

Below are concise examples of calling FreightPulse endpoints from Python and JavaScript. Use these as building blocks for your orchestrators.

Python: Fetch and Combine Fuel + FTL Quote 


import os, requests, math

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

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

def dynamic_price(origin_zip, dest_zip):
fuel = get("/fuel-prices")
rate = get("/freight-rates", { "mode": "trucking", "origin_zip": origin_zip, "destination_zip": dest_zip })

diesel = fuel["data"]["diesel"]["national_average"]
base = rate["price_usd"]

fuel_surcharge = max(0.0, (diesel - 3.00) * 0.15 * 100.0)
final = math.ceil(base + fuel_surcharge)

return {
"base_rate": base,
"fuel_surcharge": fuel_surcharge,
"final_quote": final,
"fuel_timestamp": fuel["timestamp"],
"pickup": rate.get("pickup_date"),
"delivery": rate.get("delivery_date")
}

print(dynamic_price("10001", "90210"))

JavaScript: Risk-Adjusted Pricing with Port and Disruption Signals 


async function riskAdjustedPrice(origin, dest, portLocode) {
const BASE = "https://freightpulsehq.com/api/v1";
const headers = { "X-API-Key": process.env.FP_KEY };

const get = async (url) => {
const r = await fetch(url, { headers });
const b = await r.json();
if (!b.success) throw new Error(b.error || "Upstream error");
return b.data;
};

const fuel = await get(`${BASE}/fuel-prices`);
const rate = await get(`${BASE}/freight-rates?mode=trucking&origin_zip=${origin}&destination_zip=${dest}`);
const port = await get(`${BASE}/port-congestion?port=${portLocode}`);
const dis = await get(`${BASE}/disruptions?port=${portLocode}&severity=high`);

const diesel = fuel.data.diesel.national_average;
const base = rate.price_usd;

const congestionRatio = port.results?.[0]?.metrics?.ratio_vs_baseline ?? 1.0;
const congestionAdj = congestionRatio < 0.95 ? (1 + (0.95 - congestionRatio) * 0.5) : 1;
const disruptionAdj = dis.results?.length ? 1.03 : 1;

const fuelSurcharge = Math.max(0, (diesel - 3.2) * 0.14 * 100);
const final = Math.round(base * congestionAdj * disruptionAdj + fuelSurcharge);

return { base, fuelSurcharge, congestionAdj, disruptionAdj, final };
}

Real-World Use Cases You Can Ship This Week

1) Fuel Surcharge Calculator for a 3PL

Pull the latest diesel from /fuel-prices and compare to a 30/90-day baseline from /historical. Compute surcharges dynamically by lane and display them alongside live quotes from /freight-rates. Operators can toggle between a “current” surcharge and a “stabilized” surcharge to reduce customer whiplash.

Endpoints used: /fuel-prices, /freight-rates, /historical.

2) Port-Congestion-Aware Pricing for a Freight Forwarder

When quoting shipments involving Los Angeles-Long Beach, call /port-congestion with port=USLAX and fetch /historical for trend context. If ratio_vs_baseline is below 0.9, apply a moderate congestion factor and extend lead time disclosures in your UI. Tie the “as_of” field to a tooltip explaining the 6–7 day lag so customers understand the nature of the signal.

Endpoints used: /port-congestion, /historical.

3) Carrier Vetting Widget Inside a TMS

Before confirming a quote, the TMS runs /carriers?q=DOT_NUMBER and displays legal_name, status, safety_rating, and drivers. If status != active or safety_rating is unacceptable, the system blocks progression or suggests alternatives. This reduces compliance risk and protects margins from preventable failure-to-perform events.

Endpoints used: /carriers.

4) Disruption-Aware Repricing Bot

A background worker polls /disruptions filtered by port and severity, then re-prices affected quotes by adding a small risk buffer. When a cyclone near a key Asian port escalates, the bot posts an alert to Slack with impacted quotes and a suggested repricing action for operator review.

Endpoints used: /disruptions, optionally /freight-rates for rechecks.

5) Market Intelligence Dashboard for Analysts

Analysts combine /historical diesel series with /historical port congestion curves for major ports to visualize correlations between fuel shocks and port activity. Overlay /freight-rates snapshots to test elasticity hypotheses and adjust strategic pricing guidelines.

Endpoints used: /historical, /fuel-prices, /freight-rates, /port-congestion.

FAQ

How often do FreightPulse fuel prices update?

Fuel prices reflect EIA updates and include national and regional breakdowns. You’ll also get 30/90-day averages for context, so your engine can stabilize surcharges even when the weekly refresh moves sharply.

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

Yes. The /carriers endpoint supports both trucking (FMCSA SAFER) and ocean NVOCC/OTI lookups (FMC). Use type=trucking or type=ocean with q set to a DOT number, org number, or name.

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

No. Port congestion is a lagged approximation derived from AIS-based activity (7-day average vs a 90-day baseline), with data typically lagging by ~6–7 days. It’s a practical indicator for pricing and planning—not a live queue length or real-time wait time metric.

Can I get disruption alerts near a specific port?

Yes. Use /disruptions with the port parameter to filter alerts by proximity (300 km globally, 100 km for US weather). Combine this with severity filtering to target only impactful events.

What happens if I miss a required parameter on a request?

For most endpoints you’ll receive an error object with success=false and a descriptive message. For /freight-rates, missing required parameters may return a 200 status with available=false—treat this as a soft validation failure and correct your inputs.

Deep Dive: Field-by-Field JSON Reference with Practical Uses

To make integration as frictionless as possible, here is an expanded, end-to-end set of complete JSON examples spanning multiple endpoints along with practical uses per field. Keep these handy when implementing your models and UI layers.

Fuel Prices Example (Complete) 

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

Freight Rates Example (Complete) 

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

Port Congestion Example (Complete) 

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

Disruptions Example (Complete) 

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

Carriers Example (Complete) 

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

Historical Example (Complete) 

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

Designing the Pricing Formula: Putting Signals to Work

Your pricing formula should be transparent, testable, and easy to iterate. Here’s a blueprint pattern:

To keep this process resilient:

Troubleshooting and Performance Tips

Conclusion + CTA

Modern freight pricing demands current market rates, fuel context, operational risk signals, and compliance checks—delivered in a cohesive, reliable workflow. With FreightPulse, you can collapse five separate data sources into a single, developer-friendly API and ship dynamic pricing engines that are faster to build, easier to govern, and more transparent to operate.

From pulling live US FTL quotes and EIA diesel benchmarks to tracking lagged port congestion and natural-disruption alerts near critical nodes, the platform equips your models with the signals that matter. You get consistent JSON responses, straightforward filtering, and an integration path that scales from a proof of concept to production in days—not months.

Build your dynamic pricing engine today. Explore the endpoints, plug in the examples from this guide, and iterate confidently with clean, auditable inputs. Try FreightPulse for free and turn fragmented logistics data into real-time pricing intelligence your customers can trust.