Home → Blog

Enterprise supply chain teams have a simple question that turns out to be technically hard: how do we compare carrier service-level performance across markets when the data that drives those comparisons is scattered across incompatible feeds, hidden behind separate dashboards, and updated on different cadences? Building a global view means normalizing fuel surcharges from EIA data, overlaying live FTL quotes for cost baselining, factoring in port congestion for ocean reliability, verifying carrier credentials, and tracking natural disruptions near relevant ports—ideally inside a single analytics surface. That’s the problem this guide solves.

In this post, we’ll walk through a practical, developer-first approach to benchmarking carrier SLA performance across markets using the consolidated logistics intelligence provided by FreightPulse. We’ll focus on normalizing critical cost and risk inputs, designing latency-aware KPIs, and building an apples-to-apples methodology your engineering, ops, and procurement stakeholders can trust. You’ll see how one REST API can serve as the data backbone for an SLA observability layer that works for trucking, ocean, and air scenarios.

You’ll learn how to correlate live US FTL quotes with fuel price trends to control for cost volatility, tap curated port congestion indices to contextualize on-time delivery, and enrich safety and compliance scoring with FMCSA/FMC lookups—all while integrating a real-time natural-disruption feed to anticipate the externalities that derail SLAs. The result is a consistent, defensible benchmark you can surface in your TMS, BI dashboards, or internal supply chain applications.

Why FreightPulse

Consolidation is the core value: FreightPulse replaces a patchwork of integrations (EIA, freight quote providers, AIS-derived port analytics, FMCSA/FMC registries, and hazard alert feeds) with a single REST surface and a unified response schema. Here’s why that matters to developers and operators building SLA observability:

The bottom line: build the SLA benchmarking layer once, feed it from one API, and keep your focus on decision support instead of data housekeeping.

Quick Start

Base URL: 

https://freightpulsehq.com/api/v1

All endpoints return JSON using a shared envelope. You can start exploring immediately. Below is a first call to retrieve national EIA diesel and gasoline prices and regional breakdowns. 

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

Example response: 

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

Core Endpoints for SLA Benchmarking

To benchmark carrier SLAs across markets, you’ll usually combine signals from at least three categories: cost baselines (fuel, rates), operational friction (port congestion), and compliance/risk (carrier registries, disruptions). Below are the most relevant endpoints and how to apply them.

1) Fuel Prices — GET /fuel-prices

Purpose: Normalize trucking cost performance across regions and time. When comparing carriers’ on-time delivery or price adherence, adjust by diesel trends so you don’t penalize (or over-credit) carriers for macro fuel swings.

Request: 

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

Response highlights: 

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

2) Freight Rates — GET /freight-rates

Purpose: Establish a lane-level, mode-aware cost baseline for benchmarking. For US FTL, you can pull live quotes to compare a carrier’s billed rate against contemporaneous market levels. For ocean/air (limited to Asian origins into US ZIPs), you can add a directional price signal into your SLA cost normalization.

Request (trucking): 

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

Example response: 

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

Request (ocean example, Asia origin into US): 

curl -H "X-API-Key: YOUR_API_KEY" \
"https://freightpulsehq.com/api/v1/freight-rates?mode=ocean&origin_country=CN&dest_zip=90744&container_size=40HC"

Interpretation tip: For ocean, align rate pulls with your sailing windows and pair with the port congestion endpoint below to avoid penalizing a carrier for systemic port delays.

3) Port Congestion — GET /port-congestion

Purpose: Contextualize ocean (and port-adjacent intermodal) SLA performance by normalizing for port conditions. The metric represents a 7-day average of port calls versus a 90-day baseline using AIS-derived signals (data lag ~6–7 days). This is not live vessel wait time; it is a curated approximation for trending and benchmarking.

Request by LOCODE: 

curl -H "X-API-Key: YOUR_API_KEY" \
"https://freightpulsehq.com/api/v1/port-congestion?port=USLAX"

Example response: 

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

4) Carrier Registry — GET /carriers

Purpose: Verify carriers before attributing SLA failures to operators that are inactive, poorly rated, or not suited for certain loads. For trucking, query FMCSA SAFER records by DOT number or name. For ocean NVOCC/OTI operators, query FMC records.

Request (trucking by DOT): 

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

Example response: 

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

5) Disruptions — GET /disruptions

Purpose: Incorporate exogenous risk (cyclones, earthquakes, severe weather) into SLA normalization and predictive ETAs. Filter events by port proximity to focus on disruptions relevant to your lanes.

Request (high-severity events within a port radius): 

curl -H "X-API-Key: YOUR_API_KEY" \
"https://freightpulsehq.com/api/v1/disruptions?port=USLAX&severity=high"

Example response: 

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

6) Historical Series — GET /historical

Purpose: Build trending dashboards and trailing-average normalizers for SLAs. Retrieve weekly national fuel price series or daily port congestion series for curated major ports.

Request (diesel national series, last 30 days): 

curl -H "X-API-Key: YOUR_API_KEY" \
"https://freightpulsehq.com/api/v1/historical?metric=fuel_price_diesel_national&period=30d"

Example response: 

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

Designing a Normalized SLA Benchmark Across Markets

A defensible, comparable SLA framework should separate what a carrier controls from market noise. Below is a recipe you can adapt for your lanes and modes:

An example KPI formula for on-time performance (OTP) adjustment:

The combination gives you an SLA score that respects operational reality while still rewarding executional excellence.

End-to-End Example: From Data Pull to SLA Dashboard

Let’s wire up a minimalist ingestion loop that powers your dashboard and alerting. We’ll sketch it in Python and JavaScript fetch for quick adoption.

Python (requests) example 

import os
import requests
from datetime import datetime

BASE = "https://freightpulsehq.com/api/v1"
HEADERS = {"X-API-Key": os.getenv("FP_API_KEY", "")}

def get_fuel():
r = requests.get(f"{BASE}/fuel-prices", headers=HEADERS, timeout=20)
j = r.json()
if not j.get("success"):
raise RuntimeError(j.get("error", "fuel error"))
return j["data"]["data"]["diesel"]

def get_rate(origin_zip, dest_zip):
r = requests.get(
f"{BASE}/freight-rates",
params={"mode": "trucking", "origin_zip": origin_zip, "destination_zip": dest_zip},
headers=HEADERS,
timeout=20,
)
j = r.json()
if not j.get("success"):
raise RuntimeError(j.get("error", "rate error"))
return j["data"]

def get_congestion(locode):
r = requests.get(f"{BASE}/port-congestion", params={"port": locode}, headers=HEADERS, timeout=20)
j = r.json()
if not j.get("success"):
raise RuntimeError(j.get("error", "congestion error"))
results = j["data"]["results"]
return results[0] if results else None

def get_disruptions(port):
r = requests.get(f"{BASE}/disruptions", params={"port": port}, headers=HEADERS, timeout=20)
j = r.json()
if not j.get("success"):
raise RuntimeError(j.get("error", "disruptions error"))
return j["data"]["results"]

def normalize_lane_sla(origin_zip, dest_zip, port_locode):
fuel = get_fuel()
rate = get_rate(origin_zip, dest_zip)
cong = get_congestion(port_locode)
haz = get_disruptions(port_locode)

diesel = fuel["national_average"]
live_quote = rate.get("price_usd")
cong_ratio = (cong or {}).get("metrics", {}).get("ratio_vs_baseline", 1.0)

# Basic normalization factors
congestion_factor = max(0.8, cong_ratio) # floor at 0.8 to avoid over-normalizing
disruption_factor = 1.0
for e in haz:
if e["severity"] == "high":
disruption_factor *= 0.9
elif e["severity"] == "moderate":
disruption_factor *= 0.95

# Example KPIs
to_market_index = None
if live_quote:
# Use diesel as a coarse input to weight quote comparisons
to_market_index = live_quote / max(1.0, diesel * 100) # for illustration

kpis = {
"diesel_usd_per_gallon": diesel,
"ftl_live_quote_usd": live_quote,
"congestion_ratio": cong_ratio,
"disruption_factor": disruption_factor,
"to_market_index": to_market_index,
"timestamp": datetime.utcnow().isoformat() + "Z"
}
return kpis

if __name__ == "__main__":
kpis = normalize_lane_sla("10001", "90210", "USLAX")
print(kpis)

Notes:

JavaScript (fetch) example 

const BASE = "https://freightpulsehq.com/api/v1";
const HEADERS = { "X-API-Key": "YOUR_API_KEY" };

async function fp(path, params = {}) {
const url = new URL(`${BASE}/${path}`);
Object.entries(params).forEach(([k, v]) => url.searchParams.set(k, v));
const res = await fetch(url.toString(), { headers: HEADERS });
const j = await res.json();
if (!j.success) throw new Error(j.error || `Request failed: ${path}`);
return j.data;
}

async function example() {
const fuel = await fp("fuel-prices");
const diesel = fuel.data.diesel.national_average;

const rate = await fp("freight-rates", {
mode: "trucking",
origin_zip: "73301",
destination_zip: "33101"
});

const cong = await fp("port-congestion", { port: "USLAX" });
const entry = cong.results[0];
const ratio = entry ? entry.metrics.ratio_vs_baseline : 1.0;

console.log({
diesel,
quoteUSD: rate.price_usd,
congestionRatio: ratio
});
}

example().catch(console.error);

This snippet shows how simple it is to join the core building blocks—fuel, rates, congestion—into a unified view you can chart in any dashboarding layer.

Real-World Use Cases

1) Fuel-Surcharge Calculator and Cost Normalization

Teams build surcharge calculators that adjust contracted FTL linehaul by current EIA diesel levels, generate a weekly delta, and then score carriers by “to-market” performance. Use GET /fuel-prices for current benchmarks and GET /historical for trailing averages. Combine with GET /freight-rates for a real-time competitive baseline so you can flag invoices that drift too far above market.

2) Port-Congestion Dashboard for Ocean Reliability

Freight forwarders deploy an ocean dashboard that tracks daily congestion ratios across curated global ports and annotates charts with active disruptions near each port. Use GET /port-congestion and GET /historical (port_congestion:<portid>) for trend series. Layer in GET /disruptions with the port filter to contextualize spikes. Your SLA module reads the ratio_vs_baseline to adjust expected dwell and on-time windows.

3) Carrier Vetting and Compliance Scoring for a 3PL

Before awarding lanes, a 3PL checks carrier status and safety rating, segments by capacity (drivers), and enforces a minimum compliance score. Use GET /carriers for FMCSA lookups (trucking) and FMC checks (ocean). Feed the results into your procurement UI and link to an SLA forecast view that blends in historical rate and congestion context to set realistic performance expectations.

4) Disruption-Aware Shipment Tracker

A shipment tracking tool listens for high-severity events near origin/destination ports and posts exceptions proactively, adjusting ETA tolerances during the active window. Use GET /disruptions with the port parameter and severity filter, and refresh frequently. The tracker shows a “disruption-adjusted OTP” side-by-side with raw OTP so analysts can distinguish execution issues from environmental risk.

5) Enterprise SLA Scorecard Across Regions

An enterprise team rolls up carrier performance by region, normalizing each lane for diesel trends, live rate benchmarks, congestion ratios, and local hazards. Use GET /fuel-prices and GET /freight-rates to create a cost-normalized baseline, GET /port-congestion for throughput normalization, GET /disruptions for risk overlays, and GET /carriers for eligibility filters. The resulting scorecard is defensible in quarterly reviews with carriers and internal finance stakeholders.

Implementation Tips and Best Practices

Endpoint Catalog with Detailed Examples

GET /fuel-prices — National and Regional EIA Fuel Data

Purpose: Normalize trucking cost and build surcharge logic. No parameters required.

Example cURL: 

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

Representative response (fields explained inline comments style in prose below): 

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

GET /freight-rates — Live Quotes for Benchmarking

Purpose: Compare carrier-billed rates against contemporaneous market rates; estimate transit windows.

Key parameters:

Example cURL (FTL): 

curl -H "X-API-Key: YOUR_API_KEY" \
"https://freightpulsehq.com/api/v1/freight-rates?mode=trucking&origin_zip=60601&destination_zip=98101&pickup_date=2026-09-01"

Interpreting response fields:

GET /port-congestion — Throughput Approximation (Lagged)

Purpose: A lagged approximation of port activity using a 7-day average vs 90-day baseline. Data lag is typically ~6–7 days; not a live AIS view. Best used for trend-based normalization of ETAs and SLA expectations.

Key parameters: port (name or LOCODE like USLAX), country (ISO3 or name), region (continent), congestion filter (low|moderate|high).

Example cURL: 

curl -H "X-API-Key: YOUR_API_KEY" \
"https://freightpulsehq.com/api/v1/port-congestion?country=USA&congestion=high"

Response key fields:

GET /carriers — FMCSA/FMC Lookups

Purpose: Vet carriers and maintain a qualified panel. The endpoint supports trucking (FMCSA SAFER) and ocean (FMC NVOCC/OTI). Air returns available:false.

Key parameter: q (name, DOT number for trucking, org number/name for ocean), optional type override.

Example cURL (ocean): 

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

Response highlights:

GET /disruptions — Natural-Hazard Feed

Purpose: Anticipate risk and adjust expectations. Sources include GDACS, USGS, and NOAA/NWS; filter by port-radius for maritime sensitivity.

Key parameters: type (cyclone|earthquake|flood|volcano|drought|wildfire|severe_weather), severity, country, port.

Example cURL: 

curl -H "X-API-Key: YOUR_API_KEY" \
"https://freightpulsehq.com/api/v1/disruptions?type=severe_weather&country=US"

Field usage:

GET /historical — Time Series for Trends

Purpose: Build trend visualizations and trailing-average models for both fuel prices and port congestion per curated port.

Key parameters: metric (fuel_price_diesel_national | fuel_price_gasoline_national | port_congestion:<portid>), period (30d|90d|1y).

Example cURL (port series): 

curl -H "X-API-Key: YOUR_API_KEY" \
"https://freightpulsehq.com/api/v1/historical?metric=port_congestion:USLAX&period=90d"

Use the returned series for moving averages, trend direction, and variance analysis that feeds enterprise scorecards.

Error Handling and Resilience

Every response follows the envelope {"success": true/false, "data": {...}, "error": "..."} so you can centralize error parsing. When {"success": false}, log error and inputs, then trigger retry/backoff logic as appropriate. For validation misses (e.g., missing q on /carriers), treat as correctable and surface an actionable message to the caller. For transient throttling or network hiccups, apply exponential backoff and jitter. Circuit breakers prevent cascading failures downstream.

Example of a non-success payload: 

{
"success": false,
"error": "Missing required parameter: q"
}

Best practices:

FAQ

How often do FreightPulse fuel prices update?

Fuel data reflects EIA updates, delivered in a normalized JSON shape with historical aggregates for 30-day, 90-day, and YoY comparisons. Use the timestamp field to align your surcharge calculations and SLA normalization to the correct effective date.

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

Yes. The /carriers endpoint supports trucking (FMCSA SAFER) and ocean NVOCC/OTI (FMC) lookups. Pass q to search by DOT number or name (trucking) or by org number/name (ocean), and use type to specify the mode when needed.

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

No. Port congestion is a lagged approximation based on a 7-day average versus a 90-day baseline, with data typically lagging ~6–7 days. It’s designed for trend analysis and SLA normalization, not minute-by-minute operational dispatch.

How should I combine live FTL quotes with diesel prices in benchmarking?

Use live quotes from /freight-rates as your contemporaneous baseline and weight comparisons with diesel levels from /fuel-prices or /historical to adjust for macro fuel swings. This produces a “to-market” index that isolates carrier performance from broader cost changes.

Can I filter disruption alerts to only those near a specific port?

Yes. Use the port parameter on /disruptions to filter events by proximity to a specific port. This helps apply precise, location-aware risk adjustments to ETAs and on-time metrics.

Conclusion + CTA

Benchmarking carrier SLAs across markets is ultimately a data integration problem wrapped in an analytics one. You need fuel benchmarks to normalize costs, live FTL quotes to ground lane-level pricing, lag-aware congestion indices to explain throughput, authoritative carrier registries to gate eligibility, and a clean feed of natural-hazard events to anticipate service risk. Trying to stitch all of that together from disparate providers slows teams down and increases the odds of data drift. That’s precisely why developers, operators, and analysts reach for a single, consistent API surface.

With FreightPulse, you can plug these pillars into your TMS, control tower, procurement workflows, or BI dashboards within days—not months. Start with fuel and rates for cost normalization, add port congestion and disruptions for risk-aware SLAs, and enforce carrier vetting with registry lookups. The consistent schema, predictable responses, and focused endpoint set make it the fastest path from zero to production-grade SLA observability.

If you’re ready to unify your logistics intelligence and build a defensible, apples-to-apples SLA benchmark across your network, Try FreightPulse for free. Explore the endpoints, wire up your first dashboard, and put normalization where it belongs: in your platform, not on your backlog.