Home → Blog

Carrier terms are ultimately about leverage. Procurement teams, 3PL providers, and enterprise supply chain groups negotiate best when they can quantify the market: What are US FTL spot rates right now for my lanes? How did diesel move week-over-week? Are the West Coast ports running soft or tight compared to their own 90‑day baseline? Are my slated pickup windows about to collide with a cyclone or severe weather system within 300km of a port? Without a single, consistent data surface, these answers live in disparate feeds, stale spreadsheets, and expensive point tools that take weeks to wire up.

This post shows how to embed logistics intelligence directly into your contracting workflows using the FreightPulse API. By bringing real-time and near-real-time signals—fuel indices, live US truckload quotes, port congestion, carrier verifications, and natural-disruption alerts—into the same negotiation screen, you replace guesswork with evidence. The outcome: faster cycles, fewer escalations, and terms that reflect today’s conditions rather than last quarter’s assumptions.

If you’re a developer supporting procurement or a product owner at a 3PL, the promise is pragmatic: one standardized JSON schema across the data you need most. That means faster prototypes, easier audits, and less time stitching together incompatible payloads. Below, we’ll walk through the endpoints, sample requests and responses, field-by-field interpretations, and concrete ways to use FreightPulse to secure better carrier terms.

Introduction

Procurement and 3PL teams increasingly face a two-sided squeeze. Carriers are faster and more sophisticated in surfacing constraints and risks—fuel spikes, weather disruptions, driver availability—while shippers demand stable capacity at predictable rates. Negotiations bog down or produce suboptimal outcomes when each party references different sources of truth. Meanwhile, developers are asked to “add context” to contract tools by connecting five separate data providers: fuel indices, FTL rate APIs, AIS-based port congestion monitors, US trucking and ocean carrier directories, and natural hazard systems. That is months of integration work and ongoing maintenance risk.

What teams need is one authenticated way to answer the core negotiation questions: What’s the fair FTL price for this lane next week? Should our fuel-surcharge peg change based on EIA’s latest weekly report? Are key ports (Los Angeles-Long Beach, Rotterdam, Shanghai) operating above or below normal activity levels? Is the counterparty a legitimate, active carrier with acceptable safety ratings? And is there any natural disruption likely to hit our lane, route, or port handoffs?

FreightPulse consolidates exactly those signals behind a single REST API. You don’t need to refactor your contracting tools to handle four data formats; you need consistent JSON, reliable timestamps, and predictable semantics so your procurement logic can evaluate apples-to-apples across endpoints. In this guide, we will: highlight the developer benefits; show a zero-to-first-call quick start; tour the core endpoints; and then demonstrate real-world implementation patterns—fuel-surcharge calculators, congestion dashboards, carrier vetting boards, and disruption-aware SLAs—that improve negotiating leverage right away.

Why FreightPulse

- One surface for diverse logistics signals. Instead of building brittle glue code across EIA feeds, a live truckload quoting provider, the IMF PortWatch AIS-derived dataset, FMCSA/FMC directories, and hazard alert systems, you get unified responses shaped as {"success": true/false, "data": {...}, "error": "..."} with consistent field naming. For developers, this means less defensive parsing and fewer edge cases. For operators, it means your dashboards align across metrics rather than contradict each other.

- Actionable negotiations with blended real-time and near-real-time data. FreightPulse pairs live US FTL quotes (via Warp) with EIA fuel series in the same typography of JSON. You can compute a lane-specific floor/ceiling informed by both market rate and input costs, then validate the counterparty with FMCSA SAFER or FMC directory lookups. Procurement stops switching tabs and starts defending numbers.

- Port risk awareness without an AIS headache. Port congestion metrics originate from IMF PortWatch, summarizing 7‑day average portcalls versus a 90‑day baseline. It is a lagged approximation (about 6–7 days), not live AIS, but it is excellent for trend-aware contracting: you’ll know if a port is running above/below normal. This informs buffer clauses, service-level commitments, and contingency rates—without you buying or decoding AIS streams.

- Disruption-aware planning built-in. The disruptions endpoint unifies GDACS, USGS, and NOAA/NWS natural-hazard alerts into one filterable surface. You can scope by country or port radius to detect cyclones, earthquakes, or severe weather likely to hit a shipment window, then encode risk-based surcharges or alternative routings into the negotiation itself.

Quick Start

Base URL: 

https://freightpulsehq.com/api/v1

First request: pull national diesel and gasoline indices to calibrate your fuel-surcharge peg before a rate review. This example requires no parameters. 

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

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

This one payload lets you build a surcharge table, validate carrier fuel line items, and standardize how your team references energy costs across contracts.

Core Endpoints

1) Fuel Prices — GET /fuel-prices

Purpose: Rapidly compute or validate fuel surcharges and insert time-relevant context into contracts. Weekly changes and historical baselines support both short-term adjustments and longer-term peg renegotiations.

Parameters: None.

cURL: 

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

Response (complete, realistic): 

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

Field notes and negotiation uses:

2) Live Freight Rates — GET /freight-rates

Purpose: Pull live FTL quotes for US lanes to anchor negotiation floors and ceilings. Combine with the fuel price endpoint to separate base linehaul from fuel components.

Key parameters:

cURL (FTL example): 

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

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

Field notes:

If required parameters are missing, this endpoint returns HTTP 200 with available: false in the payload rather than an error. Your UI can safely prompt for missing fields without exception handling interrupting the flow.

3) Port Congestion — GET /port-congestion

Purpose: Bring trend-aware port activity into contract language for ocean or intermodal shipments. This helps you set buffer days, choose alternative routings, or consider peak-season surcharges. Important: this is a lagged approximation—FreightPulse uses IMF PortWatch based on AIS data; figures are a 7‑day average vs a 90‑day baseline and typically lag by 6–7 days. It is not live AIS vessel tracking.

Key parameters:

cURL: 

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

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

Field notes:

4) Carrier Lookups — GET /carriers

Purpose: Verify counterparties quickly. For US trucking, confirm DOT, status, safety rating, and driver count to differentiate asset-light brokers from asset-heavy carriers. For ocean NVOCC/OTI, validate organizations in the FMC directory.

Key parameters:

cURL (trucking example): 

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

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

Field notes:

5) Disruption Alerts — GET /disruptions

Purpose: Detect cyclones, earthquakes, floods, severe weather, and other natural hazards that may impact pick-ups, port handoffs, or last-mile operations. Bake dynamic risk language directly into contracts—e.g., force majeure carve‑outs gated by an objective hazard feed.

Key parameters:

cURL: 

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

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

Field notes:

6) Historical Series — GET /historical

Purpose: Backtest your surcharge banding or congestion buffers. For example, pull weekly national diesel over the last 90 days to calibrate thresholds or pull a daily port congestion series for a curated list of major global ports to build trend dashboards embedded in RFP tools.

Key parameters:

cURL: 

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

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

Field notes:

Real-World Use Cases

1) Fuel-Surcharge Calculator for Annual and Quarterly Refreshes

Use GET /fuel-prices for current indices and GET /historical for banding thresholds. Your calculator can:

Endpoints used: /fuel-prices, /historical.

2) Port-Congestion Dashboard for a Freight Forwarder’s RFP Tool

Build a side panel in your RFP screen showing congestion for LA/LB, Savannah, Rotterdam, and Shanghai using GET /port-congestion. Add a trend chart using GET /historical with metric=port_congestion:<portid>. Present the congestion tag (low/moderate/high), as_of date, and ratio_vs_baseline; then offer “buffer days” toggles buyers can add to terms. You’re providing context-driven knobs at negotiation time rather than retroactive excuses post-award.

Endpoints used: /port-congestion, /historical.

3) Carrier Vetting Panel for 3PL Onboarding and Award Decisions

In your tendering UI, add a “Verify Carrier” button that calls GET /carriers. Display legal_name, status, safety_rating, and drivers. On the procurement side, maintain internal policy rules (e.g., no awards to carriers with non‑satisfactory ratings or with missing status). During negotiations, cite this panel to justify non-awards or to require subcontractor disclosure.

Endpoints used: /carriers.

4) Disruption-Aware Contract Clauses for Ocean-Inland Handoffs

When negotiating for a lane that includes LA/LB or NY/NJ port calls, query GET /disruptions with port=USLAX (or port=USNYC) and desired severity filters. If hazards exist or are forecasted for the expected service window, automatically propose clauses for rescheduling windows or alternative routings at pre-agreed rates. This moves the debate from anecdotes to objective hazard flags.

Endpoints used: /disruptions.

5) Live FTL Sanity Checks Embedded in Procurement Scorecards

In a lane-by-lane scorecard, show GET /freight-rates price_usd alongside the carrier’s proposed base linehaul. Flag deltas greater than a threshold (e.g., ±12%) for manual review. Combine with /fuel-prices to highlight the implied base vs fuel portion of the proposal. This helps you counter inflated base linehaul when fuel increases are already accounted for.

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

End-to-End Example: Building a Negotiation Context Service

Let’s wire up a small service that retrieves fuel indices, a live FTL quote for a lane, and port congestion for LA/LB—then emits a JSON bundle you can mount in your procurement UI. Example shown in JavaScript (Node.js) and Python. The idea is to standardize a context payload for every negotiation session.

JavaScript (Node.js) 

import fetch from 'node-fetch';

const BASE = 'https://freightpulsehq.com/api/v1';

async function fp(path) {
const res = await fetch(`${BASE}${path}`);
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const body = await res.json();
if (!body.success) throw new Error(body.error || 'FreightPulse error');
return body.data;
}

async function buildContext({ originZip, destinationZip, pickupDate, port }) {
const [fuel, rates, congestion] = await Promise.all([
fp('/fuel-prices'),
fp(`/freight-rates?mode=trucking&origin_zip=${originZip}&destination_zip=${destinationZip}&pickup_date=${pickupDate}`),
fp(`/port-congestion?port=${port}`)
]);

const diesel = fuel.data.diesel.national_average;
const fuel30 = fuel.data.diesel.historical['30d_avg'];
const rate = rates.price_usd;
const transit = rates.transit_days;
const portStats = congestion.results?.[0];

return {
inputs: { originZip, destinationZip, pickupDate, port },
fuel: {
diesel_now: diesel,
diesel_30d_avg: fuel30
},
ftl_quote: {
price_usd: rate,
transit_days: transit,
pickup_date: rates.pickup_date,
delivery_date: rates.delivery_date
},
port_congestion: portStats ? {
port: portStats.port,
congestion: portStats.congestion,
as_of: portStats.as_of,
ratio_vs_baseline: portStats.metrics.ratio_vs_baseline
} : null
};
}

buildContext({
originZip: '10001',
destinationZip: '90210',
pickupDate: '2026-08-24',
port: 'USLAX'
}).then(ctx => {
console.log(JSON.stringify(ctx, null, 2));
}).catch(err => {
console.error('Context build failed:', err.message);
});

Python 

import json
import requests

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

def fp(path: str):
r = requests.get(f"{BASE}{path}", timeout=20)
r.raise_for_status()
body = r.json()
if not body.get("success"):
raise RuntimeError(body.get("error", "FreightPulse error"))
return body["data"]

def build_context(origin_zip: str, destination_zip: str, pickup_date: str, port: str):
fuel = fp("/fuel-prices")
rates = fp(f"/freight-rates?mode=trucking&origin_zip={origin_zip}&destination_zip={destination_zip}&pickup_date={pickup_date}")
congestion = fp(f"/port-congestion?port={port}")

diesel_now = fuel["data"]["diesel"]["national_average"]
diesel_30d = fuel["data"]["diesel"]["historical"]["30d_avg"]

port_res = congestion["results"][0] if congestion.get("results") else None

return {
"inputs": {
"origin_zip": origin_zip,
"destination_zip": destination_zip,
"pickup_date": pickup_date,
"port": port
},
"fuel": {
"diesel_now": diesel_now,
"diesel_30d_avg": diesel_30d
},
"ftl_quote": {
"price_usd": rates.get("price_usd"),
"transit_days": rates.get("transit_days"),
"pickup_date": rates.get("pickup_date"),
"delivery_date": rates.get("delivery_date")
},
"port_congestion": {
"port": port_res["port"],
"congestion": port_res["congestion"],
"as_of": port_res["as_of"],
"ratio_vs_baseline": port_res["metrics"]["ratio_vs_baseline"]
} if port_res else None
}

if __name__ == "__main__":
ctx = build_context("10001", "90210", "2026-08-24", "USLAX")
print(json.dumps(ctx, indent=2))

This pattern lets your procurement UI consistently present fuel snapshots, spot checks for base linehaul, and congestion context in a single payload. For many teams, this is all that’s needed to move from “opinion vs opinion” to “opinion vs data.”

Advanced Implementation Tips and Best Practices

- Normalize units and timestamps everywhere. Fuel prices come with unit: gallon and a timestamp in UTC. Store both alongside your computed surcharges so that future auditors and finance can reconcile figures exactly. If you export CSVs for carrier counter-signatures, include the timestamp and source fields explicitly.

- Decouple your negotiation scoring from any one endpoint’s cadence. Port congestion is lagged by ~1 week and based on a 7‑day average vs 90‑day baseline. Don’t mix it with minute-by-minute signals; instead, treat congestion as a trend weight in your contract risk score, not a day-of scheduling signal.

- Prefer defensive parsing with the shared response shape. Every endpoint returns {"success": true/false, "data": {...}, "error": "..."} if not success. Check success before dereferencing data to avoid noisy crashes in your contracting UI. For /freight-rates with missing inputs, handle the available: false result and prompt for more details.

- Build explainability into your UI. For each figure (e.g., diesel national average, FTL spot, ratio_vs_baseline), display a tooltip that explains the field and its provenance. Negotiations move faster when the counterparty can see where numbers came from.

- Cache what’s cacheable. Fuel prices update on a weekly cadence with weekly change indicators, while disruptions are more dynamic. Your UI can cache the former for a session and poll the latter more frequently. Store historical series locally to accelerate chart renders during live RFPs.

- Alerting and circuit breakers. For automated scorecards, set thresholds for anomalies (e.g., diesel moves more than a certain percent week-over-week) and pause auto-approvals to require human review. For endpoint failures or unexpected shapes, implement basic circuit breakers (e.g., fallback to last-known-good series or show a degraded badge).

Error Handling and Troubleshooting

Every FreightPulse response follows the same envelope: 

{
"success": true/false,
"data": { ... },
"error": "Human-readable message" // present only if success=false
}

Common edge scenarios:

Example of a structured error: 

{
"success": false,
"error": "Missing required parameter: q"
}

Tips:

Field-by-Field Deep Dive and Practical Interpretation

Fuel Prices

Freight Rates

Port Congestion

Carriers

Disruptions

Historical

Putting It Together: A Negotiation-Ready JSON Bundle

Here’s an example of a synthesized bundle you might hand to your contracting UI or store alongside each lane’s negotiation transcript. It merges fuel indices, an FTL quote, congestion context, and a disruptions snapshot into one document. 

{
"lane": {
"origin_zip": "10001",
"destination_zip": "90210",
"pickup_date": "2026-08-24"
},
"fuel_context": {
"timestamp": "2026-07-30T12:00:00Z",
"diesel_now": 3.847,
"diesel_30d_avg": 3.82,
"diesel_90d_avg": 3.75,
"weekly_change_percent": -0.6
},
"market_quote": {
"mode": "trucking",
"service": "FTL (53' dry van)",
"price_usd": 7207.92,
"transit_days": 4,
"pickup_date": "2026-08-24",
"delivery_date": "2026-08-28"
},
"port_context": {
"port": "Los Angeles-Long Beach",
"locode": "US LAX",
"as_of": "2026-08-14",
"congestion": "moderate",
"ratio_vs_baseline": 0.85
},
"risk_snapshot": {
"port": "USLAX",
"active_disruptions": [
{
"id": "gdacs:TC:1001305",
"type": "cyclone",
"severity": "moderate",
"country": "Japan",
"starts_at": "2026-08-18T12:00:00+00:00"
}
]
}
}

This “single panel of truth” is exactly what negotiators need: a live spot anchor, fuel peg, lagged but reliable port activity view, and any relevant natural hazards—pulled from the same API, stored with consistent timestamps, and ready for audits.

cURL Recipes for Your Playbook

- National fuel snapshot for surcharge pegs: 

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

- Lane sanity-check quote: 

curl "https://freightpulsehq.com/api/v1/freight-rates?mode=trucking&origin_zip=30301&destination_zip=97204&pickup_date=2026-09-01"

- Congestion check for USLAX: 

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

- Verify a US trucking carrier by DOT: 

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

- Disruptions near a port with high severity filter: 

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

- 90-day diesel trend: 

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

FAQ

How often do FreightPulse fuel prices update?

Fuel prices follow the cadence of EIA’s weekly releases and include week-over-week change indicators plus 30/90-day averages. For negotiations, snapshot the timestamp in your contract packet so both parties reference the same update.

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

Yes. The same /carriers endpoint supports ocean NVOCC/OTI lookups in addition to US trucking (FMCSA SAFER) via the type parameter. Use it to validate counterparties across modes without juggling separate directories.

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

No. Port congestion in FreightPulse is derived from IMF PortWatch and represents a 7‑day average of portcalls versus a 90‑day baseline, typically lagging by 6–7 days. It’s excellent for trend-aware contracting, but not a substitute for live AIS tracking.

Can I filter natural-disruption alerts to those that matter for a specific port?

Yes. Use the port parameter on /disruptions to filter by proximity (300km radius for general hazards; 100km for US weather). This keeps alerts focused on operations you actually care about.

What happens if I omit required parameters on /freight-rates?

You’ll receive an HTTP 200 response with availability information indicating missing data rather than a hard error. Your application can prompt users to provide the missing fields without interrupting the negotiation flow.

Conclusion + CTA

Carrier contracts should reflect today’s logistics reality, not assumptions glued together from disconnected sources. With FreightPulse, procurement, 3PL, and enterprise supply chain teams can bring fuel indices, live US FTL quotes, port activity trends, carrier verifications, and disruption alerts into the same contract pane—under one REST API and a unified JSON schema. That means less integration overhead, more reliable evidence, and faster, fairer outcomes.

As a developer or product owner, your advantage is speed: go from an empty screen to a negotiation-ready dashboard by composing a few endpoints and standardizing the response shapes. Build explainable scorecards, attach objective data to every clause, and automate the mundane parts of due diligence so humans can focus on strategy.

Start embedding this context into your workflows today with FreightPulse. If you’re ready to see these endpoints in action in your contracting UI, lanes board, or RFP tool, Try FreightPulse for free and turn negotiations into data-driven decisions.