Home → Blog

You’re trying to build a real-time capacity marketplace that matches shippers, brokers, and carriers for instant spot contracts—but your data is scattered. You need live US truckload quotes to price capacity, diesel prices to compute surcharges, carrier verification to reduce fraud, disruption alerts to avoid bad lanes, and port congestion to anticipate capacity ripples. By the end of this post, you’ll have the building blocks—requests, responses, and glue logic—to stand up a production-grade spot matching workflow using a single transportation data API.

Introduction

Spot capacity only clears when pricing, risk, and operations see the same picture at the same time. In practice, developers wire up EIA fuel feeds for surcharges, a rate provider for spot quotes, FMCSA for carrier vetting, AIS for port congestion, and weather/quake feeds for risk. Each integration comes with a different schema, cadence, auth model, and failure mode. Your marketplace slows down or stalls when a single feed throttles or drifts.

The fastest way to unblock this is to collapse logistics intelligence into one transport-focused interface with consistent shapes, uptime, and semantics. That’s what the FreightPulse REST API delivers: live full-truckload quotes, national and PADD fuel prices, carrier lookups, disruption alerts, and port congestion in the same JSON schema. You get a single base URL, consistent authentication, and responses that are easy to cache and compare across endpoints.

In this tutorial, we’ll assemble a minimal but production-friendly capacity marketplace flow: quote a lane, compute a fuel surcharge, verify a carrier, screen for natural-hazard risk and port slowdowns, and return an instant contract decision. Every step uses one API, one schema, and transport-relevant endpoints.

Why FreightPulse

Quick Start

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

Authentication: Send X-API-Key: YOUR_API_KEY. If you omit it, unauthenticated requests are allowed up to a daily limit per IP. All responses share this shape: {"success": true/false, "data": {...}, "error": "message" // only if success=false}.

First request: fetch national diesel and gasoline prices (EIA) to fuel-index your spot quotes.

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 use: data.diesel.national_average (USD per gallon) for surcharge math, data.timestamp (UTC) for caching, and data.regions for regionalized indices. We recommend caching this response for the business day because EIA is weekly, though FreightPulse includes 30/90-day aggregates for quick trend references.

Core Endpoints

1) Live US FTL Freight Quotes: GET /freight-rates

Use this to price spot contracts instantly. For trucking mode, pass origin_zip and destination_zip. Base currency is USD.

Endpoint: /freight-rates

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&pickup_date=2026-08-24"

{
"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: data.price_usd is the headline you’ll present or combine with surcharges. data.transit_days supports ETA windows, and pickup_date/delivery_date simplify SLA validation. Handle the documented behavior where missing required params return HTTP 200 with an availability flag rather than an error—always check success and presence of pricing fields before rendering.

2) Carrier Verification: GET /carriers

Prevent fraud and ensure compliance by verifying US trucking carriers via FMCSA SAFER. Query by DOT number or name.

Endpoint: /carriers

Key params:

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

{
"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: status indicates operating status, safety_rating provides a quick safety signal, and drivers can be used as a proxy for scale. Always present the legal_name and DOT number on-screen when gathering consent and building digital contracts.

3) Natural Disruptions Near Ports or Lanes: GET /disruptions

Screen for cyclones, earthquakes, or severe weather that could jeopardize pickup, linehaul, or delivery. Filter by a port to pull relevant events near coastal gateways affecting domestic capacity.

Endpoint: /disruptions

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

Field notes: results[].type and severity are your gating signals; starts_at is an ISO 8601 timestamp in UTC. Use port-based filters to catch gateway-adjacent risk for imports that spill into your FTL lanes.

4) Port Congestion Context: GET /port-congestion

Estimate how tight downstream capacity might be when booking spot loads near major ports. This is not live AIS vessel wait time; the feed is a 7-day average of port calls compared against a 90-day baseline with a ~6–7 day lag.

Endpoint: /port-congestion

Key params:

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

Field notes: use congestion for a quick badge, and ratio_vs_baseline for trend-aware logic. Combine this with disruptions to flag heightened risk tolerance (e.g., allow only pre-vetted carriers when congestion is high).

5) Historical Series: GET /historical

Power your trend charts and index-based adjustments without building a data lake. Query weekly national fuel or daily port congestion for curated ports.

Endpoint: /historical

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

Field notes: series[].date is a date string (no timezone needed for weekly EIA), and value aligns to the same currency/unit as the live endpoint (USD per gallon).

End-to-End Flow: Matching for Instant Spot Contracts

Below is a minimal lane-pricing and risk-screening flow. It fetches a live FTL quote, computes a diesel surcharge using the current national index, validates a carrier by DOT number, and checks for nearby disruptions and port congestion for context.

Step 1 — Fetch live FTL rate and compute fuel surcharge

Units and currency: price_usd (USD), diesel price (USD per gallon). Apply your own FSC formula; for example, a cents-per-mile ladder based on data.diesel.national_average (not provided here—use your internal rate card). Cache fuel prices per business day; cache freight-rates only for seconds to minutes depending on your tolerance.

Step 2 — Verify carrier

Block unknown carriers or stale authorities by checking status and safety_rating. Present legal_name and dot_number in your digital contract to prevent identity mismatches.

Step 3 — Screen for disruptions and congestion

Call /disruptions with a port key (e.g., USLAX) or country filter. If any high-severity events match, escalate to manual review or offer longer ETAs. For context, call /port-congestion to decide whether to open the lane to a wider pool of carriers or keep it limited.

Code: Quote a Lane and Read Key Fields

cURL (FTL quote):

curl -H "X-API-Key: YOUR_API_KEY" \
"https://freightpulsehq.com/api/v1/freight-rates?mode=trucking&origin_zip=30301&destination_zip=85001&pickup_date=2026-08-24"

JavaScript (Node.js/Fetch) example that pairs the live quote with fuel and carrier verification:

async function buildSpotOffer() {
const api = "https://freightpulsehq.com/api/v1";
const headers = { "X-API-Key": "YOUR_API_KEY" };

// 1) Live FTL quote
const rateUrl = `${api}/freight-rates?mode=trucking&origin_zip=30301&destination_zip=85001&pickup_date=2026-08-24`;
const rateRes = await fetch(rateUrl, { headers });
const rateJson = await rateRes.json();
if (!rateJson.success || !rateJson.data || typeof rateJson.data.price_usd !== "number") {
throw new Error("No rate available for requested lane.");
}

// 2) Fuel index (national diesel)
const fuelRes = await fetch(`${api}/fuel-prices`, { headers });
const fuelJson = await fuelRes.json();
if (!fuelJson.success) throw new Error("Fuel index unavailable.");
const diesel = fuelJson.data.data.diesel.national_average; // USD/gal

// Example: simple FSC using your internal method; replace with your business logic
function computeFSC(dieselUsdPerGal) {
// Placeholder logic: return a flat 5% if diesel >= $4.00, else 3%
return dieselUsdPerGal >= 4.0 ? 0.05 : 0.03;
}
const fscPct = computeFSC(diesel);
const base = rateJson.data.price_usd;
const allIn = Math.round((base * (1 + fscPct)) * 100) / 100;

// 3) Verify carrier by DOT number
const carrierRes = await fetch(`${api}/carriers?q=54283`, { headers });
const carrierJson = await carrierRes.json();
const carrierOk = carrierJson.success && carrierJson.data.results.length > 0
&& carrierJson.data.results[0].status === "active";

// 4) Disruption screen near USLAX (Los Angeles/Long Beach)
const disRes = await fetch(`${api}/disruptions?port=USLAX&severity=high`, { headers });
const disJson = await disRes.json();
const riskEvents = disJson.success ? disJson.data.results : [];

// 5) Optional congestion context
const congRes = await fetch(`${api}/port-congestion?port=USLAX`, { headers });
const congJson = await congRes.json();
const congestion = congJson.success ? congJson.data.results[0]?.congestion : "unknown";

return {
lane: "30301 -> 85001",
base_price_usd: base,
fuel_index_usd_per_gal: diesel,
fuel_surcharge_percent: fscPct,
all_in_price_usd: allIn,
carrier_active: carrierOk,
disruption_count: riskEvents.length,
congestion
};
}

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

This example reads exactly the fields you need to render a spot offer. Store timestamps (like fuel-prices data.timestamp) to drive cache invalidation and support audit logs for contract disputes.

Real-World Use Cases

Operational Notes That Save Time

Putting It Together: Sample Responses to Integrate

Fuel baseline for FSC:

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

Live FTL quote (illustrative values):

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

Carrier verification (US trucking):

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

Disruption screen near a port:

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

Port congestion context (lagged, 7-day avg vs 90-day baseline):

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

FAQ

How often do FreightPulse fuel prices update?

The EIA fuel prices are weekly. FreightPulse returns a UTC timestamp so you can cache for a business day and display when the index was captured. For quick context, 30/90-day averages are included in the same payload.

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

Yes. The /carriers endpoint supports trucking (FMCSA SAFER) and ocean (FMC NVOCC/OTI) lookups via the type parameter. Air returns available:false by design.

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

No. The /port-congestion endpoint approximates congestion from IMF PortWatch AIS as a 7-day average against a 90-day baseline with a ~6–7 day data lag. It’s intended for planning and context, not live berth-wait ETAs.

Can I try the API without an API key?

Yes. Guest access allows a limited number of unauthenticated requests per IP so you can explore endpoints. For production, add the X-API-Key header to your requests.

What error handling should I implement?

Check HTTP status and the success flag. Handle 401 (invalid/missing key), 403 (inactive subscription), 422 (missing required parameter), and 429 (quota or rate limit). For /freight-rates, also check for availability if required params are missing.

Conclusion + CTA

Real-time capacity marketplaces live or die on integration friction. By consolidating live US FTL quotes, diesel indices, carrier verification, disruption alerts, and port congestion into one consistent API, you can quote and clear spot contracts faster while reducing fraud and operational risk.

You now have copy-pasteable calls, JSON field references, and an end-to-end flow that your team can ship this week. Start with a single lane, wire in surcharge math, and add risk screening as a gating step before you publish an instant contract to your shipper or broker UI.

Try FreightPulse for free to explore the endpoints used here, or visit FreightPulse to learn more.