Home → Blog

You’re building a self-service integration portal so partner developers can onboard to your supply chain SaaS quickly—without back-and-forth emails, PDF specs, or one-off data contracts. By the end of this post, you’ll be able to stand up an API-first onboarding experience that gives partners live freight quotes, EIA fuel prices, port congestion trends, carrier lookups, and natural-disruption alerts from a single API, complete with copy-pasteable requests, testable responses, and usage guardrails.

Introduction

Most logistics platforms struggle to onboard partners because the data they need lives in five different feeds, each with its own auth model, schema, and SLAs. Your team ends up writing glue code around EIA for fuel, a freight marketplace for quotes, a vessel data source for congestion, FMCSA/FMC for carrier compliance, and separate hazard feeds—only to hand partners a brittle checklist of integrations.

FreightPulse consolidates these essentials behind one REST API. That means your onboarding portal can focus on developer experience: a single base URL, one auth header, consistent response shapes, and copyable examples that partners can run immediately—even without an API key via guest access. In practice, this is the fastest path from “Hello, World” to real logistics intelligence embedded in production workflows.

This guide shows how to design that portal: what to expose first, which endpoints to highlight, how to present cURL and code samples, and how to set expectations (e.g., port congestion is a lagged approximation, not live AIS). We’ll also provide realistic responses you can paste directly into your docs or API explorer.

Why FreightPulse

Quick Start

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

Authentication: X-API-Key header (e.g., X-API-Key: fp_live_...). Unauthenticated requests are allowed up to 100/day per IP, so your portal can let users try queries without creating an account.

Shared response shape: {"success": true|false, "data": {...}, "error": "message" // only if success=false}

First request: national fuel prices

This is a zero-parameter, high-signal endpoint—perfect for a “Run” button in your docs.

curl -H "X-API-Key: YOUR_API_KEY" "https://freightpulsehq.com/api/v1/fuel-prices"

Illustrative JSON response (values as provided by the API example):

{
"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 your portal should call out:

JavaScript example (fetch + basic rendering)

async function loadFuel() {
const res = await fetch("https://freightpulsehq.com/api/v1/fuel-prices", {
headers: { "X-API-Key": "YOUR_API_KEY" }
});
const json = await res.json();
if (!json.success) {
console.error(json.error);
return;
}
const diesel = json.data.data.diesel;
const ts = json.data.timestamp; // UTC
console.log("Diesel national avg (USD/gal):", diesel.national_average);
console.log("Updated:", ts);
// Example: update your portal DOM
// document.querySelector("#diesel").textContent = diesel.national_average.toFixed(3);
}
loadFuel().catch(console.error);

Tip: Cache stable endpoints (like weekly EIA updates) for a few minutes in your portal to keep pages snappy. For endpoints that can return different results per query (e.g., freight rates), prefer client-triggered fetches.

Core Endpoints

Below are four endpoints that power most onboarding portals. Each includes the path, notable parameters, a cURL you can paste into your docs, and a sample response with field notes.

1) Live freight rates

Path: GET /freight-rates

Mode: trucking (default), ocean, or air. For trucking you must pass origin_zip and destination_zip.

curl -H "X-API-Key: YOUR_API_KEY" "https://freightpulsehq.com/api/v1/freight-rates?mode=trucking&origin_zip=10001&destination_zip=90210"

{
"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: price_usd is what most portals highlight; transit_days and dates are vital for capacity planning views. Always display the mode and service in the UI to avoid ambiguity if you add ocean/air later.

2) Port congestion (lagged approximation)

Path: GET /port-congestion

This endpoint surfaces a 7-day average of port calls versus a 90-day baseline. Expect a ~6–7 day lag; this is not a live AIS queue length or berth wait time. Use it for trend charts, not ETA-critical calculations.

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 as_of to annotate charts; ratio_vs_baseline powers a simple traffic-light UI (e.g., under 0.8 = high congestion). Clarify in your portal that numbers are derived from historical AIS aggregates and are not “live vessel counts.”

3) Carrier lookups (compliance and vetting)

Path: GET /carriers

Look up US trucking carriers (FMCSA SAFER) by DOT number or name, and ocean NVOCC/OTI carriers (FMC) by org number or name. Air returns available:false.

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 and safety_rating are the critical compliance fields your portal should surface immediately. Present drivers and address as supporting context. If the user changes type to ocean, align labels accordingly.

4) Natural-disruption alerts (filter by port)

Path: GET /disruptions

Consolidates natural-hazard alerts (GDACS, USGS, NOAA/NWS). Use this to let partners subscribe to threats near critical ports or lanes. Geopolitical or labor events are out of scope.

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: id is stable for de-duplication. type and severity power your filters; starts_at is ISO-8601. If a partner wants lane-aware alerts, combine this with your shipment’s nearest-port metadata.

Real-World Use Cases

FAQ

How often do FreightPulse fuel prices update?

Fuel prices are sourced from EIA and are provided in USD per gallon with national and PADD-region breakdowns. The API includes a UTC timestamp you can display or use for cache headers in your portal.

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

Yes. Use GET /carriers with type=ocean to query NVOCC/OTI entities from the FMC directory. For US trucking, keep the default type=trucking and search by DOT number or legal name.

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

No. Port congestion is a 7-day average of port calls compared to a 90-day baseline and is typically lagged by about 6–7 days. Use it for trend insight and planning, not for minute-by-minute ETAs.

Can partners try the API without creating an account?

Yes. Unauthenticated requests are allowed up to 100/day per IP. This is ideal for your self-serve portal: provide cURL and one-click “Run” buttons that work out of the box, then encourage users to add an API key for higher limits.

What does an error look like, and which status codes should I handle?

All errors share {"success": false, "error": "message"}. Common HTTP codes: 401 (invalid/missing X-API-Key), 403 (no active subscription), 422 (missing required parameter such as q on /carriers), and 429 (quota or rate limit exceeded). Your portal should display the human-readable error and suggest the next step (add a missing param, wait and retry, or add a key).

Conclusion + CTA

A scalable developer-onboarding portal doesn’t just list endpoints—it gives partners a working path from idea to production. With FreightPulse, you can offer fuel prices, live US FTL quotes, port congestion trends, carrier verification, and natural-disruption alerts from a single, consistent API with guest access for zero-friction trials.

Use the examples in this post as drop-in modules for your portal: a Quick Start fuel widget, a lane-quote form, a congestion explorer, a carrier checker, and a disruption banner. Keep the expectations clear (e.g., congestion is lagged), highlight units and timestamps, and surface the same headers and response shape across every sample to reduce cognitive load.

Try FreightPulse for free and ship your self-service integration portal today—so partners can copy, paste, and build without waiting on your team.