Home → Blog

Incentive programs for carriers and contracted fleets only work if they are fair, transparent, and grounded in shared reality. If your scorecards ignore fuel volatility, weather and cyclone impacts, port slowdowns, or lane-by-lane market rates, even your best partners will disengage. The result is a familiar loop: spreadsheets filled with unverifiable metrics, arguments about what’s “in their control,” and underwhelming performance because nobody trusts the scoreboard.

This post shows how to create a data-driven carrier incentive and gamification program using real-time and near-real-time signals from FreightPulse. With one REST API, you can pull EIA fuel prices, live US FTL freight rate quotes, IMF PortWatch congestion approximations, FMCSA/FMC carrier verifications, and natural-disruption alerts—consolidating what would otherwise be five different integrations. We’ll walk through how to capture these signals, normalize them into events your platform can score, and turn the results into league tables, bonuses, and nudges that actually improve on-time performance, cost per mile, and customer satisfaction.

I’ll take a developer-first approach: concrete endpoints, example requests and JSON responses, data modeling tips, and production-grade practices for retries, backoff, and observability. By the end, you’ll have everything you need to stand up a credible, automated carrier scorecard with gamification that both operations and carriers respect.

Why FreightPulse

When you need to fuse market context with operational accountability, context matters as much as outcomes. FreightPulse delivers that context in one place:

The net effect is faster time-to-production with fewer blind spots. Your carriers can see how market context influences targets and bonuses, and your operators can trust that every exception has a source and timestamp.

Quick Start

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

Below is a first request to pull the latest national diesel price signal—useful for normalizing scorecards and calculating fuel-surcharge-adjusted performance. This example demonstrates a simple GET to the fuel prices endpoint and a compact JSON envelope that you can ingest directly into a scoring job. 

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

Example JSON 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 to use them:

Core Endpoints for Incentives and Gamification

To transform raw operations into fair, motivating scores, we’ll combine fuel context, benchmark rates, congestion approximations, carrier vetting, disruption exceptions, and trend history. The following endpoints are the backbone of that program.

1) GET /fuel-prices — Normalize cost signals

Path: /fuel-prices

Purpose: Retrieve national and regional diesel/gasoline price signals with week-over-week deltas and short/long historical averages. Use these as the basis for fuel-indexed scoring and to detect when rising fuel should relax tight CPM targets temporarily.

Request (no required params): 

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

Representative response (complete): 

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

2) GET /freight-rates — Benchmark against market quotes

Path: /freight-rates

Purpose: Live FTL quotes (via Warp) give you a benchmark to compare what you actually paid vs a contemporaneous market signal. If a carrier consistently invoices 15% over market on the same lanes without quality offsets, you can encode negative points; if they beat market while maintaining on-time performance, bonus them.

Key params (trucking mode): mode=trucking (default), origin_zip, destination_zip, optional pickup_date, qty, total_weight_lb.

Request: 

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

Field meanings and gamification tips:

3) GET /port-congestion — Context for ocean legs and inbound flow

Path: /port-congestion

Purpose: Pull a 7-day average of port calls vs a 90-day baseline, approximated from IMF PortWatch AIS data. This is not real-time and is typically lagged ~6–7 days. For gamification, use it to gate exceptions on port-linked delays or to calibrate receiving/dwell KPIs when congestion is elevated.

Key params: port (name or LOCODE, e.g., USLAX), country (name or ISO3), region (continent). Optional filter: congestion=low|moderate|high.

Request: 

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

How to apply:

4) GET /carriers — Vet before you score

Path: /carriers

Purpose: Verify carriers using FMCSA SAFER (trucking) or FMC NVOCC/OTI (ocean). Use this during onboarding and ongoing audits. In a gamified context, only accredited, active carriers should be eligible for leaderboards or bonuses.

Key params: q (required), type=trucking|ocean|air (air currently returns available:false). For trucking, q can be DOT number or name. For ocean, FMC org number or name.

Request (trucking by DOT): 

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

Field meanings:

5) GET /disruptions — Objective exceptions for fairness

Path: /disruptions

Purpose: Consolidate natural-hazard events (GDACS, USGS, NOAA/NWS). This excludes geopolitics, strikes, or administrative closures. Use it to programmatically approve exceptions when severe events occur near a route, customer DC, or port.

Key params: type (cyclone|earthquake|flood|volcano|drought|wildfire|severe_weather), severity (low|moderate|high), country, port (filters by distance: 300km, 100km for US weather).

Request (filter by a port with severity): 

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:

6) GET /historical — Build trend-aware targets

Path: /historical

Purpose: Pull weekly national fuel price series or daily port-congestion series (for curated major ports). Ideal for trend dashboards, seasonality-aware targets, and “beat your rolling average” challenges.

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

Request (30d diesel history): 

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

Practical applications:

Modeling the Incentive Engine: Events, Scores, and Badges

A robust gamification program treats real-world signals as events, normalizes them, and computes scores with transparent formulas. Below is a reference model for building an explainable leaderboard using FreightPulse data:

This model centers fairness. Scores never ignore context; they codify it—making your program both motivating and defensible.

End-to-End Example: Computing a Weekly Composite Score

Let’s outline a weekly job that calculates composite scores for each carrier, incorporating FreightPulse events:

  1. Fetch the weekly diesel index and 30d average via /fuel-prices and /historical (fuel) to compute a Fuel Adjustment Factor (FAF).
  2. For each lane serviced by the carrier this week, call /freight-rates to anchor a benchmark price and expected transit days.
  3. If the shipment includes an ocean leg, query /port-congestion for the relevant port(s) and capture congestion ratio and label (low/moderate/high).
  4. During the shipment’s timeline, poll /disruptions with port or country filters to detect any severe events overlapping the pickup-to-delivery window.
  5. Compute subscores:
    • Cost Efficiency = clamp( (Market - Invoice) / Market, -0.2, +0.2 ) weighted by FAF.
    • Timeliness = on-time ratio weighted by expected transit and exceptions from disruptions and congestion.
    • Compliance Gate = 1 if /carriers.status is active and safety_rating meets policy; else 0.
  6. Composite Score = (0.5 * Cost Efficiency) + (0.4 * Timeliness) + (0.1 * Exception Quality), where Exception Quality reflects appropriate use of pre-approved alternate routing when disruptions are present.

Your leaderboard service then publishes rankings, badges, and drill-downs linking to the underlying FreightPulse events for trust and auditability.

Code Walkthroughs: From Polling to Scoring

cURL: Multisource data capture for one lane 

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

# 2) Market benchmark for a specific lane (NY 10001 to CA 90210)
curl -s -H "X-API-Key: YOUR_API_KEY" \
"https://freightpulsehq.com/api/v1/freight-rates?mode=trucking&origin_zip=10001&destination_zip=90210"

# 3) Congestion approximation for LA/LB
curl -s -H "X-API-Key: YOUR_API_KEY" \
"https://freightpulsehq.com/api/v1/port-congestion?port=USLAX"

# 4) Disruption scan near a port with severity filter
curl -s -H "X-API-Key: YOUR_API_KEY" \
"https://freightpulsehq.com/api/v1/disruptions?port=USLAX&severity=high"

Python: Compose a composite score for a shipment 

import requests
from datetime import datetime

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

def get_fuel():
r = requests.get(f"{BASE}/fuel-prices", headers=HEADERS, timeout=10)
r.raise_for_status()
p = r.json()["data"]["data"]["diesel"]
return p["national_average"], p["historical"]["30d_avg"]

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=10)
r.raise_for_status()
return r.json()["data"]

def get_congestion(port_code):
r = requests.get(f"{BASE}/port-congestion", params={"port": port_code}, headers=HEADERS, timeout=10)
r.raise_for_status()
data = r.json()["data"]["results"]
return data[0] if data else None

def get_disruptions(port_code):
r = requests.get(f"{BASE}/disruptions", params={"port": port_code}, headers=HEADERS, timeout=10)
r.raise_for_status()
return r.json()["data"]["results"]

def score_shipment(invoice_usd, origin_zip, dest_zip, maybe_port):
diesel_now, diesel_30d = get_fuel()
faf = diesel_now / max(diesel_30d, 0.0001)

rate = get_rate(origin_zip, dest_zip)
market = rate["price_usd"]
transit_days = rate["transit_days"]

cost_eff = (market - invoice_usd) / max(market, 0.0001)
cost_eff = max(min(cost_eff, 0.2), -0.2) * faf

on_time_base = 1.0 # assume on-time; replace with TMS timestamps
timeliness = on_time_base

if maybe_port:
cg = get_congestion(maybe_port)
if cg and cg["congestion"] in ("moderate", "high"):
timeliness = min(1.0, timeliness + 0.05) # soft credit when congestion elevated

events = get_disruptions(maybe_port)
severe = any(e["severity"] == "high" for e in events)
if severe:
timeliness = min(1.0, timeliness + 0.1)

exception_quality = 0.05 if timeliness >= 1.0 and cost_eff >= 0 else 0

composite = (0.5 * cost_eff) + (0.4 * timeliness) + (0.1 * exception_quality)
return {
"diesel_now": diesel_now,
"diesel_30d": diesel_30d,
"faf": faf,
"market": market,
"transit_days": transit_days,
"cost_eff": cost_eff,
"timeliness": timeliness,
"exception_quality": exception_quality,
"composite": composite
}

print(score_shipment(invoice_usd=6900, origin_zip="10001", dest_zip="90210", maybe_port="USLAX"))

JavaScript: Fetch and display leaderboard-ready fields 

async function fpGet(path, params = {}) {
const url = new URL(`https://freightpulsehq.com/api/v1/${path}`);
Object.entries(params).forEach(([k,v]) => url.searchParams.set(k, v));
const r = await fetch(url.toString(), { headers: { "X-API-Key": "YOUR_API_KEY" } });
const j = await r.json();
if (!j.success) throw new Error(j.error || "Unknown error");
return j.data;
}

async function laneSnapshot(origin, dest) {
const prices = await fpGet("fuel-prices");
const diesel = prices.data.diesel.national_average;

const quote = await fpGet("freight-rates", { mode: "trucking", origin_zip: origin, destination_zip: dest });

return {
diesel,
market_usd: quote.price_usd,
transit_days: quote.transit_days,
pickup_date: quote.pickup_date,
delivery_date: quote.delivery_date
};
}

laneSnapshot("10001", "90210").then(console.log).catch(console.error);

Real-World Use Cases

1) Fuel-indexed scorecards that carriers trust

Operations teams frequently debate CPM fairness when fuel spikes. With /fuel-prices and /historical, you can publish a transparent formula that normalizes CPM by national or regional diesel averages and a rolling 30/90-day baseline. Carriers see how adjustments are computed, and your weekly “Efficiency Stars” badge becomes credible. Endpoints: /fuel-prices, /historical.

2) Lane-level value benchmarking with on-time targets

For each shipment, capture a market quote via /freight-rates and store price_usd and transit_days with the load. On settlement, compare invoice vs market and on-time performance vs expected transit. Award points for beating market while delivering on time; flag consistent over-market outliers for review. Endpoints: /freight-rates.

3) Ocean-inbound resilience challenges

When inbound containers flow through high-variability ports, use /port-congestion to set realistic dwell and drayage targets based on lagged congestion levels. Combine with /disruptions to auto-approve exceptions for cyclones or severe weather. Recognize carriers that maintain service quality through challenging conditions. Endpoints: /port-congestion, /disruptions.

4) Automated vetting gates for leaderboard eligibility

Before a carrier appears on any leaderboard, verify legal status and safety posture via /carriers. If status != active or safety rating falls below your threshold, exclude them and notify your procurement team. Endpoints: /carriers.

5) Trend-aware quarterly targets

Use /historical fuel and port congestion series to set seasonal targets and avoid whipsawing carriers between tight and loose goals. For example, loosen port-related dwell KPIs in periods where historical series shows sustained congestion. Endpoints: /historical, /port-congestion.

Interpreting Responses and Field-by-Field Guidance

All FreightPulse endpoints share a consistent envelope: {"success": true/false, "data": {...}, "error": "..."} when error. That uniformity simplifies error handling and logging in your scoring pipelines.

Error Handling, Retries, and Observability

Production-grade incentive engines need resilient data ingestion. Use structured handling aligned to the common response shape and documented HTTP status codes. Below is a compact reference to good practices:

Example of capturing and interpreting an error payload for auditing downstream: 

{
"success": false,
"error": "Human-readable message."
}

In code, always check success. Log the "error" string with structured context, and avoid partially-applied score updates when a dependency fails.

Performance and Platform Best Practices

Putting It Together: A Sample Event Envelope and Score Explanation

Here is a minimal event envelope you can standardize across your services to explain any score to a carrier or internal stakeholder: 

{
"shipment_id": "SHP-2026-00812",
"carrier_dot": 54283,
"lane": { "origin_zip": "10001", "destination_zip": "90210" },
"events": [
{
"type": "FuelPriceUpdated",
"source": "FreightPulse",
"timestamp": "2026-07-30T12:00:00Z",
"payload": {
"diesel_national": 3.847,
"diesel_30d_avg": 3.82,
"region": "east_coast"
}
},
{
"type": "LaneQuoteBenchmarked",
"source": "FreightPulse",
"timestamp": "2026-08-24T00:00:00Z",
"payload": {
"price_usd": 7207.92,
"transit_days": 4
}
},
{
"type": "PortCongestionSnapshot",
"source": "FreightPulse",
"timestamp": "2026-08-14T00:00:00Z",
"payload": {
"port": "US LAX",
"congestion": "moderate",
"ratio_vs_baseline": 0.85,
"as_of": "2026-08-14"
}
},
{
"type": "DisruptionObserved",
"source": "FreightPulse",
"timestamp": "2026-08-18T12:00:00Z",
"payload": {
"id": "gdacs:TC:1001305",
"severity": "moderate",
"event_type": "cyclone"
}
}
],
"scores": {
"cost_efficiency": 0.08,
"timeliness": 0.95,
"exception_quality": 0.05,
"composite": 0.546
},
"explanation": [
"Cost efficiency +0.08: invoice 6% below market (per FreightPulse /freight-rates), adjusted by diesel FAF.",
"Timeliness 0.95: delivered on time vs expected transit (FreightPulse /freight-rates), minor credit applied for moderate congestion near US LAX.",
"Exception quality +0.05: maintained service during moderate cyclone window (FreightPulse /disruptions)."
]
}

This level of detail is how you defuse disputes and sustain engagement. Every point on the board maps to a timestamped event with provenance.

FAQ

How often do FreightPulse fuel prices update?

Fuel prices reflect EIA data and include weekly changes plus short and long historical averages. Use the timestamp field in the response to anchor your scoring windows and avoid double-counting updates.

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

Yes. The /carriers endpoint supports trucking (FMCSA SAFER) and ocean NVOCC/OTI (FMC directory) via the type parameter. Air returns available:false, so plan your onboarding flows accordingly.

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

No. Port congestion is a lagged approximation based on a 7-day average vs a 90-day baseline and typically reflects data that’s ~6–7 days old. Use it for trend-aware KPIs and fair exceptions, not for minute-level ETA promises.

What kinds of disruptions are included?

FreightPulse consolidates natural-hazard events like cyclones, earthquakes, floods, droughts, wildfires, volcanoes, and severe weather from sources such as GDACS, USGS, and NOAA/NWS. It does not include geopolitical events, strikes, or administrative port closures.

How should I benchmark rates for fair comparisons across time?

For each shipment, capture a contemporaneous market quote via /freight-rates and store price_usd and transit_days. Avoid comparing invoices to stale or mismatched quotes; align comparisons by similar pickup dates, lane ZIPs, and load characteristics.

Conclusion + CTA

Carrier incentives and gamification work when they’re anchored in data both sides recognize as fair. With FreightPulse, you can unify fuel context, live FTL rate benchmarks, port-congestion approximations, objective disruption exceptions, and carrier registry checks in a single pipeline. The result is a trustworthy scoreboard—one that motivates, rather than antagonizes, your partners.

The fastest path from zero to a production-grade incentive engine is to ship a thin slice: start with /fuel-prices and /freight-rates for cost-efficiency scoring, then layer in /disruptions and /port-congestion to make timeliness fair, and /carriers to safeguard eligibility. Keep your formulas explainable, store raw payloads for audits, and publish clear badge criteria that map directly to event fields.

Ready to build a leaderboard carriers actually want to climb? Explore the endpoints and start wiring your first scores today. Try FreightPulse for free.