Home → Blog

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:

Illustration: Look Up Freight Rates

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:

Responses use a predictable wrapper to help you branch logic and surface errors centrally:

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:

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:

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:

Implementation details that will save you time

Putting it together: UI and backend checklist

End-to-end example: from request to rendered context

Below is a concise operational flow you can replicate:

  1. Server receives lane request (e.g., GET /lane?origin=10001&dest=90210).
  2. Server calls FreightPulse using the header key and the trucking mode parameters.
  3. Server checks HTTP status and payload.success, rejects otherwise with a retry or cached fallback.
  4. Server normalizes units (keep USD and gallon), extracts timestamp, source, and regional aggregates needed.
  5. Server returns a minimal JSON to the frontend with labels like “Updated: 2026-11-20T00:00:30+00:00 (EIA).”
  6. 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.