You need a reliable way to query transportation data to inform freight rate calculations without hard-coding prices or scraping unstable sources. By the end of this article, you’ll be able to call FreightPulse’s Freight Rates API with guest access, parse its envelope, understand the fields and data cadence, and wire the response into your transportation pricing or planning workflow—without treating any single response as a live spot quote.
What this API gives you for transportation pricing
The FreightPulse Freight Rates endpoint provides a structured, machine-readable envelope you can call for transportation analysis and pricing inputs. Requests are lane-aware via parameters for mode and postal codes, and responses include standardized fields for units, currency, timestamps, and data provenance so you can track what you’re using in your pipeline.
Use this to: enrich your trucking lane models with authoritative cost drivers, keep your enrichment steps consistent across regions, and align internal calculators on a shared source of truth without emitting “today’s price” fare claims.
Access and authentication
Authentication uses the X-API-Key header. If you don’t pass a key, you still get guest access at 100 requests per day per IP. This is sufficient to prototype, test CI jobs, or run low-frequency batch enrichment. For higher volume, add the header with your key after you register.
- Header name: X-API-Key
- Header value: YOUR_API_KEY
- Guest, no key: 100 requests/day per IP
Register to get a key: Register. See field-level docs: Documentation.
Request shape and envelope
All responses are wrapped in a top-level envelope with success and data. Treat the timestamp as an ISO 8601 string with timezone, the currency as a three-letter code, and unit as a human-readable unit name. Do not treat any freight lane request as a live spot quote; base currency is USD where provided, and units are explicit in the payload.
Copy-paste cURL example
The following call targets the documented FreightPulse endpoint with mode and ZIP parameters. You can include or omit the X-API-Key header; if omitted, you are limited to 100 requests/day per IP.
curl -H "X-API-Key: YOUR_API_KEY" "https://freightpulsehq.com/api/v1/freight-rates?mode=trucking&origin_zip=10001&destination_zip=90210"Official JSON response format
Below is the official response sample you should use to wire your parser. Pay attention to the envelope, timestamp, currency and unit fields, and the nested data and historical blocks.
{
"success": true,
"data": {
"timestamp": "2026-11-06T00:00:20+00:00",
"source": "EIA (U.S. Energy Information Administration)",
"currency": "USD",
"unit": "gallon",
"data": {
"diesel": {
"national_average": 6.292,
"change_week": -0.06,
"change_percent": -0.94,
"updated_at": "2026-11-02",
"regions": {
"east_coast": 6.025,
"midwest": 6.402,
"gulf_coast": 5.912,
"rocky_mountain": 6.445,
"west_coast": 7.272,
"california": 8.076
}
},
"gasoline": {
"national_average": 4.153,
"change_week": -0.116,
"change_percent": -2.72,
"updated_at": "2026-11-02",
"grades": {
"regular": 4.153,
"midgrade": 4.757,
"premium": 5.158
}
},
"bunker_fuel": {
"available": false,
"note": "No known free source (Rotterdam/Singapore/Houston) — requires a paid provider (e.g. Ship & Bunker, Argus)."
}
},
"historical": {
"diesel_30d_avg": 6.275,
"diesel_90d_avg": 6.033,
"diesel_yoy_change": 67.7,
"gasoline_30d_avg": 4.259,
"gasoline_90d_avg": 4.232,
"gasoline_yoy_change": 37.6
}
},
"meta": {
"request_id": "8dc4fb8c-1383-4022-b508-91a41a9ec62d"
}
}Field notes you will actually use:
- success: boolean guard for downstream logic.
- data.timestamp: ISO 8601 UTC time. Useful for cache keys and staleness checks.
- data.source: provenance string for audit trails.
- data.currency: base currency for numeric values (USD).
- data.unit: measurement unit for cost drivers (gallon).
- data.data.diesel.* and data.data.gasoline.*: aggregates, regional breakdowns, and week-over-week deltas you can fold into fuel-surcharge logic.
- data.historical.*: rolling averages and year-over-year change for smoothing and thresholds.
- meta.request_id: attach to logs to help support trace your call.
JavaScript example: call and parse
This Node.js snippet calls the same endpoint and extracts timestamp, currency, unit, and a few diesel metrics. Keep the header as shown; remove it to operate in guest mode (100 requests/day per IP).
import fetch from 'node-fetch';
const URL = 'https://freightpulsehq.com/api/v1/freight-rates?mode=trucking&origin_zip=10001&destination_zip=90210';
async function main() {
const res = await fetch(URL, {
headers: {
'X-API-Key': 'YOUR_API_KEY'
},
timeout: 15000
});
if (!res.ok) {
throw new Error(`HTTP ${res.status}`);
}
const body = await res.json();
if (!body || body.success !== true) {
throw new Error('API indicated failure');
}
const ts = body.data?.timestamp; // ISO 8601, UTC
const currency = body.data?.currency; // 'USD'
const unit = body.data?.unit; // 'gallon'
const diesel = body.data?.data?.diesel;
const natAvg = diesel?.national_average; // number
const westCoast = diesel?.regions?.west_coast; // number
const yoy = body.data?.historical?.diesel_yoy_change; // number
console.log({
timestamp: ts,
currency,
unit,
diesel_national_average: natAvg,
diesel_west_coast: westCoast,
diesel_yoy_change: yoy
});
}
main().catch(err => {
console.error(err);
process.exit(1);
});How to use these fields in transportation pricing
Freight programs often need a defensible fuel component rather than a fluctuating per-lane fare. Use the currency, unit, and diesel aggregates to calculate or update your fuel surcharge table. Because the response includes regional values, you can select a region that best matches your lane coverage or build a blended factor across multiple regions.
Do not present any single lane request as “today’s trucking price.” Instead, use this API to keep inputs current for an internal model that accounts for distance, accessorials, and your own carrier network contracts. The historical fields support smoothing and guardrails for automatic updates.
Port congestion data: interpretation and lag
If you incorporate port congestion into intermodal or drayage decisions, remember the congestion data source is IMF PortWatch. It is lagged by roughly 6–7 days and uses a 7‑day average versus a 90‑day baseline. It is not a live AIS wait time feed.
In practice: when projecting ocean-to-truck handoffs, apply the lag to buffers and do not treat congestion as real-time. For batch planning, the 7‑day average improves stability; for exception management, rely on your TMS events or carrier dispatch updates rather than assuming immediate changes at the port.
Practical notes that save time
- Units and currency: numeric values are in USD and gallon where specified by the unit field; persist both with the value.
- Timestamps: use data.timestamp as your freshness indicator; it is ISO 8601 with timezone (UTC). Store it alongside derived values.
- Caching: for server apps, cache on the combination of URL and the top-level timestamp. Where fuel data updates weekly, a TTL aligned to update cadence avoids unnecessary calls.
- Idempotency: the endpoint is safe to retry; add exponential backoff and respect guest limits.
- Pagination: this response shape is a single document; no pagination fields are present.
- Rate limits: guest usage is 100 requests/day per IP. Integrate a counter and short-circuit to cache when near the threshold.
- Error handling: check success === true, and log meta.request_id on errors for support traceability.
- Regional choices: when applying diesel regions to trucking lanes, pick a consistent policy (origin-based, destination-based, or weighted) and keep it documented in code.
Integration checklist
Minimum viable integration
- Call the endpoint with or without X-API-Key depending on your plan.
- Validate success and parse data.timestamp, currency, and unit.
- Extract diesel national_average and relevant regional values.
- Compute or update your internal fuel surcharge table without emitting a per-lane USD fare as a live price.
- Cache by timestamp with a TTL aligned to update cadence.
Operational hardening
- Add retries with jitter and a guest-mode request budget (100/day/IP).
- Record meta.request_id on both success and error paths.
- Expose source in your admin UI for auditability.
- Feature-flag your congestion adjustments given the 6–7 day lag.
FAQ
Can I use the API without a key?
Yes. Guest access allows 100 requests per day per IP without sending the X-API-Key header.
Is this a live spot quote for a trucking lane?
No. Do not treat the response as today’s lane price. Use the structured fields (currency, unit, aggregates, historicals) as inputs to your own pricing model.
What timezone is the timestamp?
The timestamp is ISO 8601 with timezone; treat it as UTC for caching and freshness windows.
How often do port congestion figures update?
They come from IMF PortWatch and are lagged by about 6–7 days, using a 7‑day average against a 90‑day baseline. They are not live AIS wait times.
Where do I find parameter and field references?
See the product docs for parameter and field lists: Documentation.
Ready to move from a prototype to production with an API key and higher throughput? Create your account now: Register.