Home → Blog

Carrier performance is the backbone of your transportation strategy, but most organizations still score carriers using stale KPIs and fragmented data. On-time pickup and delivery tell only part of the story. Volatile fuel costs distort effective rate performance. Weather and seismic events complicate root-cause analysis. Port slowdowns quietly extend cycle times. Without a consolidated, objective lens, you can’t separate carrier-driven variance from market-driven variance—and that means you can’t build trustworthy scorecards or align incentives that actually move the needle.

This post shows how to build end-to-end carrier performance scorecards and incentive programs backed by a single, developer-first API: FreightPulse. We will pull fuel prices, live US FTL rate quotes, port congestion signals, trucking and ocean carrier lookups, and natural-disruption alerts from one place. You’ll see how to calculate normalized cost performance (fuel-adjusted), resiliency factors (exposure to disruptions and congested ports), and compliance measures (safety and registration status). The result: auditable scorecards your executives will trust and your carriers will respect—because the inputs are objective and the math is transparent.

Whether you’re a 3PL benchmarking hundreds of carriers per quarter, an enterprise supply chain team designing KPI-linked incentives, or a supply chain SaaS platform embedding scorecards into your TMS, the approach below is pragmatic and production-ready. We’ll work through the core endpoints, show complete JSON examples, and discuss reliability patterns, governance, and observability so your scoring pipelines stay healthy even under peak tender volumes.

Why FreightPulse

Carrier performance programs collapse when the underlying data is scattered across EIA for fuel, FMCSA/FMC directories for verification, proprietary freight rate providers, AIS-powered port tools, and a blend of weather and disaster feeds. Stitching those together is slow and brittle. FreightPulse consolidates this into one REST surface so you can build faster and spend your time on analytics instead of integration glue.

Developer ergonomics matter, too. FreightPulse uses consistent response shapes across endpoints, supports straightforward pagination-free access for most queries, and pairs well with resilient client patterns like retries, circuit breakers, and health checks. You can instrument calls with metrics and structured logs to build audit trails for every score revision, making incentive negotiations equitable and data-backed.

Quick Start

Base URL for all endpoints:

https://freightpulsehq.com/api/v1

To get oriented, let’s fetch national fuel prices to power fuel-adjusted carrier cost metrics. The example below includes a header that your client can send; adapt as needed in your environment. 

curl -s -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 and how they feed scorecards:

With this single call, you can compute a fuel-normalized rate KPI for each carrier lane: normalized_rate = paid_rate - (fuel_index_factor × diesel.national_average). That makes your incentives fairer by isolating operational execution from volatile energy markets.

Core Endpoints for Carrier Scorecards and Audits

Below are the endpoints we’ll use most for building objective scorecards. We will cover every FreightPulse capability and connect each to practical KPIs and incentive logic.

1) Fuel Prices — GET /fuel-prices

Purpose: Provide national and regional diesel/gasoline prices with weekly change and historical averages. This is the cornerstone for fuel-adjusted cost metrics and budget variance analysis.

Key parameters: None required. 

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

Example response (abbreviated above; full structure repeated for clarity): 

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

How to use it:

2) Freight Rates — GET /freight-rates

Purpose: Fetch live FTL quotes for US trucking lanes (and limited ocean/air into US ZIPs). This is vital for benchmarking carrier bids or evaluating whether current routing guides remain market-competitive.

Key parameters (trucking mode): 

curl -s -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"
}
}

How to use it:

Note: If required parameters are missing, the API returns success with available=false (HTTP 200) rather than an error. Handle “available” checks in your benchmarking code.

3) Port Congestion — GET /port-congestion

Purpose: Provide a lagged, quantitative view of port activity: the 7-day average portcalls vs a 90-day baseline. Use this to avoid penalizing carriers for macro port slowdowns and to contextualize dwell.

Key parameters: 

curl -s -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
}
}
]
}
}

Important context:

4) Carriers — GET /carriers

Purpose: Verify trucking (FMCSA SAFER) and ocean (FMC NVOCC/OTI) carrier details for onboarding and compliance KPIs. Use these signals as eligibility gates and for safety-weighted incentive multipliers.

Key parameters: 

curl -s -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"
}
}
]
}
}

How to use it:

5) Disruptions — GET /disruptions

Purpose: Natural hazard monitoring from consolidated sources (GDACS, USGS, NOAA/NWS). Filter by port radius to preemptively excuse or de-risk lanes likely to be affected by cyclones, earthquakes, severe weather, and more.

Key parameters: 

curl -s -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"
}
]
}
}

How to use it:

6) Historical Series — GET /historical

Purpose: Pull weekly national fuel series or daily port-congestion series for curated ports. This powers trend charts on your carrier scorecard dashboards and supports seasonality adjustments.

Key parameters: 

curl -s -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 }
]
}
}

How to use it:

End-to-End Architecture for Scorecards: Patterns, Reliability, and Governance

Your carrier scorecard pipeline should be as reliable and auditable as your TMS. Below are practical patterns that play nicely with FreightPulse endpoints and keep operators and developers confident during peak season.

Hands-On: Building KPIs that Drive Carrier Incentives

Let’s translate the endpoints into actionable KPIs. We’ll define a few canonical measures and show how to calculate them using FreightPulse.

Together, these KPIs produce a composite score: Score = Weight(FNLC) + Weight(MCI) + Weight(OTP) + Weight(Claims) + RA - Noncompliance Penalties. What’s different here is the objective context: fuel, market rates, port trends, and disruptions are all coming from one API, time-stamped, and stored for audit.

Code Examples: Fetch, Normalize, and Score

Below are minimal client snippets you can adapt for services and batch jobs that compute carrier KPIs.

JavaScript (Node.js) — Fetch fuel and rates, then compute FNLC and MCI 

import fetch from "node-fetch";

async function getFuel() {
const res = await fetch("https://freightpulsehq.com/api/v1/fuel-prices", {
headers: { "X-API-Key": process.env.FP_KEY }
});
const body = await res.json();
if (!body.success) throw new Error(body.error || "fuel error");
return body.data.data.diesel.national_average;
}

async function getRate(origin, dest) {
const url = `https://freightpulsehq.com/api/v1/freight-rates?mode=trucking&origin_zip=${origin}&destination_zip=${dest}`;
const res = await fetch(url, { headers: { "X-API-Key": process.env.FP_KEY } });
const body = await res.json();
if (!body.success) throw new Error(body.error || "rate error");
return body.data.price_usd;
}

async function computeKpis({ origin, dest, paidRate, fuelFactor }) {
const [diesel, liveRate] = await Promise.all([getFuel(), getRate(origin, dest)]);
const f n l c = paidRate - (fuelFactor * diesel); // Fuel-Normalized Lane Cost
const mci = (paidRate / liveRate) * 100; // Market Competitiveness Index (%)
return { diesel, liveRate, FNLC: f n l c, MCI: mci };
}

computeKpis({ origin: "10001", dest: "90210", paidRate: 7600, fuelFactor: 100 })
.then(console.log)
.catch(console.error);

Notes:

Python — Apply congestion and disruption adjustments 

import os
import requests

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

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

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

def resiliency_adjustment(locode):
adj = 0.0
pc = get_port_congestion(locode)
if pc:
ratio = pc["metrics"]["ratio_vs_baseline"]
if ratio < 0.9: adj += 0.05
if ratio < 0.8: adj += 0.05
haz = get_disruptions(locode, "high")
if haz:
adj += 0.05
return min(adj, 0.15)

if __name__ == "__main__":
ra = resiliency_adjustment("USLAX")
print({"resiliency_adjustment": ra})

Notes:

Error Handling and Troubleshooting

FreightPulse returns structured JSON with success and data keys for normal responses and includes an error message when success=false. Some endpoints return HTTP 200 with “available”: false (e.g., missing params on /freight-rates). Implement robust guards around both transport-level and application-level errors.

Error example: 

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

Best practices:

Real-World Use Cases

1) Fuel-Surcharge Aware Carrier Scorecards

A shipper’s transportation analytics team builds a weekly scorecard that deducts fuel volatility from the equation. They pull /fuel-prices to compute a lane-specific fuel component, compare paid rates against live /freight-rates for benchmark context, then roll up FNLC and MCI into a composite cost performance score. Disputes about “the market moved” are settled by referencing time-stamped fuel and live quote data from the same source.

2) Port-Conscious On-Time Performance Dashboard for a Freight Forwarder

A forwarder’s ocean control tower overlays /port-congestion readings on their ETA risk board. When Los Angeles-Long Beach drops to 0.85 ratio_vs_baseline, the dashboard automatically widens ETA tolerance bands and tags impacted shipments. Late-delivery penalties for carriers are paused or reduced during the affected window using the measured ratio and /historical trends to ensure fairness.

3) Carrier Vetting and Incentive Eligibility for a 3PL

A 3PL integrates /carriers to programmatically verify FMCSA active status and safety ratings for every carrier in its routing guide. Only carriers with status=active and acceptable safety_rating are eligible for quarterly incentive pools. During severe weather alerts detected via /disruptions around key ports, the 3PL exempts certain penalties but maintains the vetted roster, keeping quality and safety front-and-center.

4) Disruption-Aware Shipment Tracker with Automated Exceptions

A supply chain SaaS platform ingests /disruptions and associates alerts to planned port calls. The platform uses alert severity to tag shipments with “exception_exempt” flags so that its customer-facing scorecards don’t penalize carriers for events outside their control, while still recording exactly why a shipment missed its original ETA.

5) KPI-Linked Carrier Incentive Program for an Enterprise Shipper

An enterprise shipper establishes quarterly bonuses tied to normalized cost, OTP, and claims—then offsets penalties when /port-congestion or /disruptions show objective headwinds. They include /historical series in the executive dashboard to justify seasonal adjustments. Because every external input is fetched from FreightPulse and logged, carrier negotiations stay fact-based.

Deep Dive: Field-by-Field Interpretation and Practical Use

The value of a scorecard rests on field semantics. Below is a targeted breakdown of critical fields and how to operationalize them.

Comprehensive JSON Examples for Auditable Pipelines

Below are several complete responses you can copy into your fixtures for unit tests and ETL validations.

Fuel, Rates, and Congestion Fixture 

{
"fuel": {
"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
}
}
}
}
},
"rate": {
"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"
}
},
"congestion": {
"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
}
}
]
}
}
}

Carrier Verification Fixture 

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

Disruption Fixture 

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

Historical Series Fixture 

{
"success": true,
"data": {
"metric": "port_congestion:USLAX",
"period": "90d",
"series": [
{ "date": "2026-06-01", "value": 0.96 },
{ "date": "2026-06-15", "value": 0.93 },
{ "date": "2026-07-01", "value": 0.91 },
{ "date": "2026-07-15", "value": 0.88 },
{ "date": "2026-08-01", "value": 0.86 }
]
}
}

Production Tips: Data Modeling, Caching, and Versioning

To keep your scorecards fast and reproducible, treat external facts as slowly changing dimensions with explicit versioning:

Store fp_payload_hash (a checksum of the raw JSON) to ensure you can verify integrity if results are challenged months later. Keep a pointer from every shipment score to the exact dimensions used so you can reconstruct historical scores and defend incentive calculations.

Caching guidance:

Security, Governance, and Auditing Controls

Carrier incentives affect real money. Put governance guardrails around both data and formulas:

Additional cURL Recipes

Live trucking quote with shipment attributes 

curl -s -H "X-API-Key: YOUR_API_KEY" \
"https://freightpulsehq.com/api/v1/freight-rates?mode=trucking&origin_zip=60601&destination_zip=77001&pickup_date=2026-08-24&qty=24&total_weight_lb=36000"

Ocean carrier lookup 

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

Remember: For air queries, the endpoint returns available:false. Use that to gracefully disable UI elements for unsupported modes.

FAQ

How often do FreightPulse fuel prices update?

Fuel prices reflect EIA updates and include weekly changes and historical averages. For most scorecards, a daily refresh is sufficient; store the timestamp and apply it consistently across all shipments in the evaluated period.

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

Yes. Use GET /carriers with type=ocean to query FMC NVOCC/OTI records by organization number or name. The same endpoint with type=trucking returns FMCSA SAFER details for US trucking carriers.

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

No. Port congestion is a lagged approximation: a 7-day average compared to a 90-day baseline, with about a 6–7 day lag. It’s ideal for fairness adjustments in scorecards but is not a live AIS tracker.

What hazards are covered by the disruptions feed?

Cyclones, earthquakes, floods, volcanoes, droughts, wildfires, and severe weather are consolidated from GDACS, USGS, and NOAA/NWS. Filter by type, severity, country, or by proximity to a port to drive exception logic.

How should I handle missing parameters or unavailable results?

Validate inputs on the client before requesting. Some endpoints may return success with available:false when parameters are incomplete; handle that case distinctly from errors with success=false and an error message. Log both for observability and user feedback.

Conclusion and Call to Action

Carrier scorecards become contentious when they’re built on subjective inputs and stitched-together feeds. With FreightPulse, you can consolidate verified carrier identity and safety data, live US FTL rate benchmarks, objective fuel indices, disruption alerts, and quantitative port congestion into one pipeline. That lets you measure what matters, excuse what’s outside anyone’s control, and pay for sustained performance, not luck or market noise.

If you’re a developer, you’ll appreciate the unified JSON shape, straightforward endpoints, and how quickly you can stand up a production-grade enrichment service with proper retries, caching, and audits. If you’re an operator or analyst, you’ll value the consistency and defensibility when bringing carriers to the table with data that everyone can agree on.

Build your next scorecard and incentive program on a solid, objective foundation. Explore the endpoints, wire them into your scoring engine, and start shipping fair, auditable KPIs this quarter. Visit FreightPulse and Try FreightPulse for free to get started.