You need to programmatically look up lane-level freight rates with strict authentication, predictable envelopes, and zero guesswork about data provenance. By the end of this guide you will be able to authenticate with FreightPulse, call the freight-rates lookup, parse the response envelope reliably, and safely present results without misrepresenting prices as “today’s live fare.”
What you will build and why this flow is auth-first
The goal is a small, production-ready lookup that requests a trucking rate for a single lane and renders normalized cost context without inventing or implying live spot quotes. The flow is auth-first because:
- FreightPulse requires a header key: X-API-Key: YOUR_API_KEY. Guests without a key are limited to 100 requests/day per IP, which is not sufficient for most workloads.
- A consistent response envelope lets you safely parse the payload even as data providers change.
- Port congestion metrics are lagged (IMF PortWatch ~6–7 days; 7-day average vs 90-day baseline), so your UI must avoid implying live AIS wait times.
You will ship a copy-pasteable curl, a working script (Python and JavaScript), and JSON parsing that respects base currency, units, and timestamps.
Authentication and request envelope
All requests include the API key in a header:
- Header: X-API-Key: YOUR_API_KEY
- Guest mode without a key: 100 requests/day per IP
Responses use a predictable wrapper to help you branch logic and surface errors centrally:
- Envelope: {"success": true, "data": {...}} plus optional "meta"
Always check the boolean success flag before reading data. Cache responsibly on your side if your render path fan-outs across many pages or widgets.
Endpoint, parameters, and a copy-pasteable curl
The documented freight lookup you will call is the trucking mode lane request:
- Endpoint: https://freightpulsehq.com/api/v1/freight-rates
- Method: GET
- Parameters (query): mode=trucking, origin_zip=10001, destination_zip=90210
Here is the exact, copy-pasteable curl request using the required auth header:
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 sample and field notes
Below is the official sample response. Use it to implement your envelope parsing and field extraction. Do not treat any embedded value as a live quote; do not present a USD fare as today’s price.
{
"success": true,
"data": {
"timestamp": "2026-11-20T00:00:30+00:00",
"source": "EIA (U.S. Energy Information Administration)",
"currency": "USD",
"unit": "gallon",
"data": {
"diesel": {
"national_average": 5.937,
"change_week": -0.19,
"change_percent": -3.1,
"updated_at": "2026-11-16",
"regions": {
"east_coast": 5.782,
"midwest": 5.967,
"gulf_coast": 5.547,
"rocky_mountain": 6.011,
"west_coast": 6.948,
"california": 7.733
}
},
"gasoline": {
"national_average": 3.805,
"change_week": -0.19,
"change_percent": -4.76,
"updated_at": "2026-11-16",
"grades": {
"regular": 3.805,
"midgrade": 4.435,
"premium": 4.834
}
},
"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.177,
"diesel_90d_avg": 6.137,
"diesel_yoy_change": 53.5,
"gasoline_30d_avg": 4.056,
"gasoline_90d_avg": 4.213,
"gasoline_yoy_change": 24.3
}
},
"meta": {
"request_id": "465e02a3-9dce-4e63-a5bd-243730948bcc"
}
}
Fields you will commonly use:
- success: boolean gate to branch logic and retries.
- data.timestamp: ISO 8601 with timezone (+00:00). Use this to display data recency.
- data.source: provenance you can attribute in your UI.
- data.currency: base currency (USD). Do not convert unless you clearly label transformations.
- data.unit: unit context for cost factors (gallon in this sample).
- data.data.diesel / gasoline: nested aggregates by product; includes national averages and regional breakdowns that may feed your lane cost model.
- historical.*: moving averages and year-over-year context for trend-aware UX (sparklines, tooltips).
- meta.request_id: attach to logs for reproducible support tickets.
Three complete sample responses you can test against
Use these identical samples in your automated tests to assert consistent envelope parsing, currency handling, and timestamp formatting. Keep values as-is to avoid flaky tests tied to changing feeds.
Sample response A
{
"success": true,
"data": {
"timestamp": "2026-11-20T00:00:30+00:00",
"source": "EIA (U.S. Energy Information Administration)",
"currency": "USD",
"unit": "gallon",
"data": {
"diesel": {
"national_average": 5.937,
"change_week": -0.19,
"change_percent": -3.1,
"updated_at": "2026-11-16",
"regions": {
"east_coast": 5.782,
"midwest": 5.967,
"gulf_coast": 5.547,
"rocky_mountain": 6.011,
"west_coast": 6.948,
"california": 7.733
}
},
"gasoline": {
"national_average": 3.805,
"change_week": -0.19,
"change_percent": -4.76,
"updated_at": "2026-11-16",
"grades": {
"regular": 3.805,
"midgrade": 4.435,
"premium": 4.834
}
},
"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.177,
"diesel_90d_avg": 6.137,
"diesel_yoy_change": 53.5,
"gasoline_30d_avg": 4.056,
"gasoline_90d_avg": 4.213,
"gasoline_yoy_change": 24.3
}
},
"meta": {
"request_id": "465e02a3-9dce-4e63-a5bd-243730948bcc"
}
}
Sample response B
{
"success": true,
"data": {
"timestamp": "2026-11-20T00:00:30+00:00",
"source": "EIA (U.S. Energy Information Administration)",
"currency": "USD",
"unit": "gallon",
"data": {
"diesel": {
"national_average": 5.937,
"change_week": -0.19,
"change_percent": -3.1,
"updated_at": "2026-11-16",
"regions": {
"east_coast": 5.782,
"midwest": 5.967,
"gulf_coast": 5.547,
"rocky_mountain": 6.011,
"west_coast": 6.948,
"california": 7.733
}
},
"gasoline": {
"national_average": 3.805,
"change_week": -0.19,
"change_percent": -4.76,
"updated_at": "2026-11-16",
"grades": {
"regular": 3.805,
"midgrade": 4.435,
"premium": 4.834
}
},
"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.177,
"diesel_90d_avg": 6.137,
"diesel_yoy_change": 53.5,
"gasoline_30d_avg": 4.056,
"gasoline_90d_avg": 4.213,
"gasoline_yoy_change": 24.3
}
},
"meta": {
"request_id": "465e02a3-9dce-4e63-a5bd-243730948bcc"
}
}
Sample response C
{
"success": true,
"data": {
"timestamp": "2026-11-20T00:00:30+00:00",
"source": "EIA (U.S. Energy Information Administration)",
"currency": "USD",
"unit": "gallon",
"data": {
"diesel": {
"national_average": 5.937,
"change_week": -0.19,
"change_percent": -3.1,
"updated_at": "2026-11-16",
"regions": {
"east_coast": 5.782,
"midwest": 5.967,
"gulf_coast": 5.547,
"rocky_mountain": 6.011,
"west_coast": 6.948,
"california": 7.733
}
},
"gasoline": {
"national_average": 3.805,
"change_week": -0.19,
"change_percent": -4.76,
"updated_at": "2026-11-16",
"grades": {
"regular": 3.805,
"midgrade": 4.435,
"premium": 4.834
}
},
"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.177,
"diesel_90d_avg": 6.137,
"diesel_yoy_change": 53.5,
"gasoline_30d_avg": 4.056,
"gasoline_90d_avg": 4.213,
"gasoline_yoy_change": 24.3
}
},
"meta": {
"request_id": "465e02a3-9dce-4e63-a5bd-243730948bcc"
}
}
Parsing the freight-rates response in Python
This Python example performs the same request and safely reads the fields you actually need for a backend or CLI integration. It also demonstrates basic guardrails around envelope parsing and the timestamp, currency, and units.
import os
import sys
import json
import time
import urllib.parse
import requests
from datetime import datetime, timezone
API_BASE = "https://freightpulsehq.com/api/v1/freight-rates"
API_KEY = os.environ.get("FREIGHTPULSE_API_KEY", "YOUR_API_KEY")
def fetch_lane(mode: str, origin_zip: str, destination_zip: str) -> dict:
params = {
"mode": mode,
"origin_zip": origin_zip,
"destination_zip": destination_zip,
}
url = f"{API_BASE}?{urllib.parse.urlencode(params)}"
headers = {
"X-API-Key": API_KEY
}
resp = requests.get(url, headers=headers, timeout=20)
resp.raise_for_status()
payload = resp.json()
if not isinstance(payload, dict) or not payload.get("success", False):
raise RuntimeError(f"FreightPulse lookup failed: {json.dumps(payload)[:500]}")
return payload
def summarize(payload: dict) -> str:
data = payload.get("data", {})
ts = data.get("timestamp")
src = data.get("source")
currency = data.get("currency")
unit = data.get("unit")
# Optional nested aggregates
fuel = data.get("data", {})
diesel = fuel.get("diesel", {})
gasoline = fuel.get("gasoline", {})
historical = data.get("historical", {})
lines = []
lines.append(f"Data timestamp: {ts} (ISO-8601, timezone-aware)")
lines.append(f"Source: {src}")
lines.append(f"Base currency: {currency}")
lines.append(f"Unit: {unit}")
if diesel:
lines.append(f"Diesel national avg: {diesel.get('national_average')} {currency} per {unit}")
regions = diesel.get("regions", {})
if regions:
lines.append(f"Diesel regions: east_coast={regions.get('east_coast')}, midwest={regions.get('midwest')}, west_coast={regions.get('west_coast')}")
if gasoline:
lines.append(f"Gasoline national avg: {gasoline.get('national_average')} {currency} per {unit}")
if historical:
lines.append(f"Diesel 30d avg: {historical.get('diesel_30d_avg')} | Diesel 90d avg: {historical.get('diesel_90d_avg')}")
meta = payload.get("meta", {})
if meta.get("request_id"):
lines.append(f"Request ID: {meta['request_id']}")
return "\n".join(lines)
if __name__ == "__main__":
try:
payload = fetch_lane("trucking", "10001", "90210")
print(summarize(payload))
# Business rule: never present a USD freight fare as "today's price".
# Instead, label outputs as historical/contextual cost factors and trends.
except Exception as e:
print(f"Error: {e}", file=sys.stderr)
sys.exit(1)
Parsing the freight-rates response in JavaScript
If you prefer a browser or Node setup, this example shows the exact same request and safe envelope parsing. In a browser, do not expose a production key; proxy calls through your server.
const API_URL = "https://freightpulsehq.com/api/v1/freight-rates?mode=trucking&origin_zip=10001&destination_zip=90210";
const API_KEY = "YOUR_API_KEY";
async function fetchLane() {
const res = await fetch(API_URL, {
headers: {
"X-API-Key": API_KEY
}
});
if (!res.ok) {
throw new Error(`HTTP ${res.status}`);
}
const payload = await res.json();
if (!payload || payload.success !== true) {
throw new Error("FreightPulse lookup failed or success=false");
}
return payload;
}
function renderSummary(payload) {
const d = payload.data || {};
const ts = d.timestamp;
const src = d.source;
const currency = d.currency;
const unit = d.unit;
const agg = (d.data) || {};
const diesel = agg.diesel || {};
const gasoline = agg.gasoline || {};
const hist = d.historical || {};
const meta = payload.meta || {};
return [
`Data timestamp: ${ts}`,
`Source: ${src}`,
`Base currency: ${currency}`,
`Unit: ${unit}`,
diesel.national_average != null ? `Diesel national avg: ${diesel.national_average} ${currency} per ${unit}` : null,
gasoline.national_average != null ? `Gasoline national avg: ${gasoline.national_average} ${currency} per ${unit}` : null,
hist.diesel_30d_avg != null ? `Diesel 30d avg: ${hist.diesel_30d_avg}` : null,
meta.request_id ? `Request ID: ${meta.request_id}` : null
].filter(Boolean).join("\n");
}
fetchLane()
.then(payload => {
const summary = renderSummary(payload);
console.log(summary);
// Business rule: do not render any USD value as a live spot fare.
})
.catch(err => {
console.error(err);
});
How to present results without implying a live USD fare
To ensure clarity and compliance:
- Label outputs with their update timestamp (ISO 8601 with timezone) and data source.
- Display currency explicitly (USD) alongside units (e.g., “per gallon”).
- Do not quote a freight-rates USD fare as today’s price. Treat aggregates as contextual cost drivers rather than bookable quotes.
- If you show port congestion in your UI, note it is IMF PortWatch-based, lagged ~6–7 days and computed as a 7-day average versus a 90-day baseline. It is not live AIS wait times.
Implementation details that will save you time
- Timestamps and timezone: Fields like data.timestamp use an explicit offset (+00:00). Parse as timezone-aware to avoid accidental local-time shifts.
- Base currency and units: The response includes currency=USD and unit=gallon. Keep these attached to any derived metric. If you convert currency client-side, label conversions clearly.
- Caching: Because guests are limited to 100 requests/day per IP, cache at your edge or server for commonly queried lanes. Revalidate when the timestamp meaningfully changes for your use case.
- Pagination: Not applicable to this lookup flow; treat the payload as a single envelope.
- Error handling: Check HTTP status first, then success in the JSON envelope. Log meta.request_id for traceability.
- Security: Use the X-API-Key header from server-side code. Do not embed YOUR_API_KEY in client-side apps without a proxy.
Putting it together: UI and backend checklist
- Backend:
- Send X-API-Key: YOUR_API_KEY.
- Call /api/v1/freight-rates with mode=trucking, origin_zip, destination_zip.
- Parse success, then fields under data.* and historical.*.
- Log meta.request_id.
- Apply caching keyed by the full URL and header profile.
- Frontend:
- Show timestamp and source badge.
- Render currency and unit near each numeric value.
- Never label any USD amount as a live bookable fare.
- For congestion visuals, annotate lagged methodology (IMF PortWatch, 7-day vs 90-day baseline).
- Ops:
- Set alerts on rising error rates or sudden changes in update cadence.
- Rotate and store API keys securely; avoid client bundling.
End-to-end example: from request to rendered context
Below is a concise operational flow you can replicate:
- Server receives lane request (e.g., GET /lane?origin=10001&dest=90210).
- Server calls FreightPulse using the header key and the trucking mode parameters.
- Server checks HTTP status and payload.success, rejects otherwise with a retry or cached fallback.
- Server normalizes units (keep USD and gallon), extracts timestamp, source, and regional aggregates needed.
- Server returns a minimal JSON to the frontend with labels like “Updated: 2026-11-20T00:00:30+00:00 (EIA).”
- Frontend renders context and tooltips; it explicitly avoids labeling any number as a bookable, live USD fare.
Where to go next
If you need a deeper field-by-field description, review the official docs. For production usage that surpasses guest limits, register for an API key and move to a server-side integration.
FAQ
Can I call the endpoint without an API key?
Yes, but guests are limited to 100 requests/day per IP. For anything beyond quick tests, use X-API-Key: YOUR_API_KEY from a server-side environment.
Are the congestion metrics live AIS wait times?
No. FreightPulse port congestion uses IMF PortWatch, lagged ~6–7 days and shown as a 7-day average vs a 90-day baseline.
Can I show a USD freight price as today’s bookable rate?
No. Do not quote a freight-rates USD fare as today’s price. Treat the returned values as contextual cost drivers and historical aggregates.
What currency and units should I display?
Display the base currency from the payload (USD) and the unit (gallon in the sample). Keep them attached to any derived metrics.
How do I debug production issues?
Log the envelope’s meta.request_id and the HTTP status. On failures, surface a cached result with its timestamp and retry in the background.
Set up your authenticated lookup now so your team can programmatically fetch contextual cost signals for lanes without mislabeling them as live quotes. Get your API key in minutes: Register.