Home → Blog

Supply chain leaders are under urgent pressure to quantify and reduce the carbon footprint of every shipment they procure. Whether you run a 3PL RFQ event, dispatch a last-minute truckload, or divert ocean freight around a congestion spike, stakeholders now ask a simple question with a complex answer: how much CO₂e did we just buy? The problem is not a lack of methodology—GHG Protocol and EN 16258 offer guidance—but a lack of unified, high-fidelity operational data to attribute carbon at shipment granularity in near real time.

In practice, carbon attribution demands more than a one-off emissions factor. It requires dynamic inputs that swing daily: lane-level truck rate quotes and expected transit (which imply routing and service type), current diesel prices (which correlate with fuel burn and surcharge behavior), port congestion (which affects berth wait times and voyage speeds), carrier verification (which determines equipment class and compliance), and active natural disruptions (which force detours and extended time-in-transit). Stitching these inputs from multiple sources slows teams down and yields inconsistent calculations across apps and regions. APIs that only answer one slice of the problem push complexity onto your developers and delay procurement’s sustainability commitments.

This post shows how to build shipment-level carbon attribution—end-to-end—using a single, developer-friendly REST API: FreightPulse. We will connect the data you need (fuel, rates, congestion, carrier facts, and natural-disruption alerts) with a pragmatic attribution model that fits procurement workflows. You will see concrete cURL and code examples, realistic JSON payloads, and implementation patterns that help you go from notebook prototype to production dashboards and automated sustainability reporting—fast.

Why FreightPulse

Most sustainability programs fail not at methodology but at data plumbing. FreightPulse consolidates the core operational signals required to estimate shipment emissions into one REST interface, helping you avoid five separate integrations and the reliability and reconciliation headaches that come with them.

The net effect: one API replaces scattered feeds and accelerates carbon attribution from weeks to days while increasing confidence in the numbers procurement teams share with finance, customers, and regulators.

Quick Start

The base URL for all endpoints is: 

https://freightpulsehq.com/api/v1

Let’s make a first request to fetch national and regional fuel prices. You can run this directly from a terminal: 

curl "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 for carbon attribution:

Core Endpoints for Shipment-Level Carbon Attribution

To build defensible, auditable carbon attribution per shipment, you will combine several FreightPulse endpoints. Below we walk through each, including parameters, example requests, realistic responses, and how each field contributes to an attribution pipeline.

1) Fuel Prices — GET /fuel-prices

Purpose: Anchor your trucking emissions factor and surcharge math with current diesel prices and historical context. While a pure CO₂e model may not “need” price, procurement workflows do; diesel price informs carrier behavior, routing choices, and surcharge pass-through—vital when estimating marginal emissions variation at the shipment level.

Request: 

curl "https://freightpulsehq.com/api/v1/fuel-prices"

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

How to use it:

2) Live Freight Rates — GET /freight-rates

Purpose: Shipment-level attribution hinges on lane selection, expected transit, and service type. Live US FTL quotes yield distance and service assumptions that drive per-mile factors and validate mode choices. Ocean and air modes are also supported for specific corridors, enabling cross-modal comparisons during procurement cycles.

Key params:

cURL example for a truckload quote: 

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

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 in attribution:

Note: If you pass incomplete parameters, the endpoint may return available=false semantics rather than a hard error. Guard on both success and core fields’ presence before computing carbon.

3) Port Congestion — GET /port-congestion

Purpose: Port congestion changes sailing speeds, berth wait times, and drayage idle periods—key drivers of additional CO₂e for ocean legs and near-port trucking. FreightPulse provides a lagged approximation using IMF PortWatch (AIS-derived) data: a 7-day average portcall rate benchmarked to a 90-day baseline with a typical 6–7 day data lag. Use it for planning and trend attribution, not as a substitute for real-time AIS.

Key params:

cURL: 

curl "https://freightpulsehq.com/api/v1/port-congestion?port=USLAX"

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 use it:

4) Carrier Verification — GET /carriers

Purpose: Emissions attribution accuracy improves when you know the operator. Trucking carriers vary by fleet age, equipment class, and safety posture. For ocean, NVOCC/OTI identity helps match to route archetypes. FreightPulse centralizes FMCSA SAFER data for trucking and FMC lookups for ocean, helping procurement teams vet carriers in-line with carbon models.

Key params:

cURL example lookup by DOT: 

curl "https://freightpulsehq.com/api/v1/carriers?q=54283"

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 hazards alter routes and dwell times, shaping shipment-level emissions. FreightPulse aggregates GDACS, USGS, and NOAA/NWS signals and lets you filter by hazard type, severity, and proximity to ports. Use these alerts to adjust emissions estimates when shipments are affected by cyclones, earthquakes, or severe weather—not geopolitical events or labor strikes.

Key params:

cURL example: 

curl "https://freightpulsehq.com/api/v1/disruptions?port=USLAX&severity=high"

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 Time Series — GET /historical

Purpose: Audit-ready carbon reporting needs trend context. FreightPulse exposes weekly national fuel-price series and daily port-congestion histories for curated major ports. Use these for time-based normalizations, trend charts in procurement dashboards, and backtesting your attribution factors.

Key params:

cURL example: 

curl "https://freightpulsehq.com/api/v1/historical?metric=fuel_price_diesel_national&period=30d"

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:

Designing a Shipment-Level Carbon Attribution Pipeline with FreightPulse

Let’s connect the dots. A defensible shipment-level carbon attribution model should be both operationally useful for procurement and rigor-aligned for sustainability teams. Here is a practical approach using FreightPulse’s endpoints as the data backbone:

  1. Ingest operational context:
    • For trucking: call /freight-rates with origin_zip, destination_zip, pickup_date, and weight. Persist service, transit_days, and price_usd with the shipment.
    • For ocean legs: determine port pairs; query /port-congestion for both load and discharge ports to derive a congestion multiplier; use /disruptions with port filters over the sailing window for hazard multipliers.
    • For carrier identity (trucking and ocean): query /carriers to retrieve legal_name, status, and safety_rating; attach to shipment for governance and emission factor customization.
  2. Establish dynamic emission factors:
    • Query /fuel-prices and/or /historical to get diesel baselines; compute a weighted factor by origin/destination PADD proxy if your network aligns with those regions.
    • Apply port_congestion ratio_vs_baseline to ocean leg dwell assumptions and drayage idle time.
    • Use disruption severity as a multiplier when alerts intersect the route window.
  3. Calculate shipment CO₂e:
    • Trucking: CO₂e = distance_miles × base_factor_per_mile(service) × diesel_adjustment × congestion_adjustment(if near-port drayage) × disruption_adjustment.
    • Ocean: CO₂e = TEU-days × base_factor_per_TEU_day(vessel archetype) × congestion_adjustment(load/discharge) × disruption_adjustment.
  4. Governance and auditability:
    • Log every external dependency: the exact /fuel-prices timestamp, the /port-congestion as_of, the disruption ids and sources, and the carrier verification snapshot at time of booking.
    • Store both raw JSON and normalized fields; this is invaluable when auditors question assumptions or when rerunning the model retroactively.

This architecture makes the procurement carbon number explainable: when a shipment spikes, the dashboard can show “Transit prolonged due to moderate congestion at USLAX (ratio 0.85 as_of 2026-08-14) and severe weather alert near port window” rather than a mysterious delta.

Code Patterns: Robust Calls, Retries, and Field Validation

You will likely integrate FreightPulse into a service that calculates CO₂e at quote time and again at dispatch or milestone events. Build durability with the following patterns:

Example: Minimal Python client to fetch core signals with retries and basic validation. 

import time
import requests

BASE = "https://freightpulsehq.com/api/v1"

def get_json(path, params=None, retries=2, timeout=4.0):
url = f"{BASE}{path}"
for attempt in range(retries + 1):
try:
r = requests.get(url, params=params, timeout=timeout)
r.raise_for_status()
js = r.json()
if js.get("success") is True:
return js["data"]
else:
raise RuntimeError(js.get("error", "Unknown API error"))
except Exception as e:
if attempt < retries:
time.sleep(0.5 * (2 ** attempt))
continue
raise

def fuel_baseline():
data = get_json("/fuel-prices")
diesel = data["data"]["diesel"]["national_average"]
ts = data["timestamp"]
return {"diesel_usd_gal": diesel, "timestamp": ts}

def trucking_quote(origin, dest):
params = {"mode": "trucking", "origin_zip": origin, "destination_zip": dest}
data = get_json("/freight-rates", params=params)
return {
"service": data.get("service"),
"transit_days": data.get("transit_days"),
"price_usd": data.get("price_usd")
}

def port_congestion(locode):
data = get_json("/port-congestion", params={"port": locode})
results = data.get("results", [])
if not results:
return None
r = results[0]
return {
"port": r["port"],
"ratio": r["metrics"]["ratio_vs_baseline"],
"as_of": r["as_of"],
"state": r["congestion"]
}

JavaScript example for a frontend procurement tool that displays a congestion badge when quoting: 

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 res = await fetch(url.toString(), { method: "GET" });
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const js = await res.json();
if (!js.success) throw new Error(js.error || "API error");
return js.data;
}

async function getCongestionBadge(locode) {
const data = await fpGet("/port-congestion", { port: locode });
const r = (data.results || [])[0];
if (!r) return { label: "N/A", color: "gray" };
const ratio = r.metrics.ratio_vs_baseline;
if (ratio >= 1.0) return { label: "Low", color: "green" };
if (ratio >= 0.85) return { label: "Moderate", color: "orange" };
return { label: "High", color: "red" };
}

Real-World Use Cases

Below are practical projects sustainability and procurement teams can ship this quarter using FreightPulse as the backbone.

End-to-End Example: Attributing CO₂e for a Bi-Coastal Truckload via LA Port Drayage

Scenario: A shipment moves from a New York warehouse (10001) to a Los Angeles cross-dock (90210) with a final dray leg to a nearby port. We estimate emissions at quote time using live FTL context, diesel prices, LA-Long Beach congestion, and any active disruptions.

  1. Get diesel baseline: 
    curl "https://freightpulsehq.com/api/v1/fuel-prices"
    Parse data.data.diesel.national_average and the timestamp. Suppose diesel is 3.847 USD/gal.
  2. Get live trucking quote and transit: 
    curl "https://freightpulsehq.com/api/v1/freight-rates?mode=trucking&origin_zip=10001&destination_zip=90210"
    Use service = "FTL (53' dry van)" and transit_days = 4 to select a base per-mile factor and base idle time.
  3. Assess LA-Long Beach congestion: 
    curl "https://freightpulsehq.com/api/v1/port-congestion?port=USLAX"
    ratio_vs_baseline = 0.85, congestion = "moderate". Apply a moderate idling multiplier for the drayage portion.
  4. Check disruptions near the port window: 
    curl "https://freightpulsehq.com/api/v1/disruptions?port=USLAX&severity=high"
    If results exist, factor an incremental dwell/detour multiplier.
  5. (Optionally) confirm the carrier at dispatch: 
    curl "https://freightpulsehq.com/api/v1/carriers?q=54283"
    If the award goes to the returned carrier, tag the shipment with safety_rating and drivers for governance analytics.

Then compute CO₂e for the line-haul plus a short dray leg with multipliers for moderate port congestion. Store the raw JSON from each step along with your normalized fields and the resulting attribution number. Present a trace to procurement: “4-day FTL dry van quote; diesel baseline 3.847 USD/gal (EIA); LA-LB congestion moderate (0.85 ratio as_of 2026-08-14), no high-severity disruptions detected; carrier verified at dispatch.”

Interpreting Responses and Handling Errors

All responses share a simple shape that enables predictable parsing. Always check success and guard critical fields before using them in attribution math. Implement human-readable error propagation to your UI so buyers understand what needs to be retried or adjusted.

Common error scenarios:

Example error response: 

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

Best practices:

Performance, Reliability, and Governance Considerations

Sustainability claims must be reproducible, so your integration needs predictable performance, robust failure handling, and strong governance controls. Here is how to structure your FreightPulse consumption with production-grade patterns:

Comprehensive Endpoint Coverage and Field-by-Field Guidance

Let’s summarize all available endpoints and their business value in carbon attribution, along with key fields to extract:

Expanded Examples: JSON You Can Paste Into Tests

Use these complete, realistic responses to write robust parsers and unit tests for your carbon attribution service.

Fuel Prices Snapshot (EIA via FreightPulse) 

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

Live Truckload Quote (Warp via FreightPulse) 

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

Port Congestion (IMF PortWatch approximation) 

{
"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 Lookup (FMCSA) 

{
"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 Alert (GDACS/USGS/NOAA/NWS) 

{
"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 (Fuel or Port Congestion) 

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

FAQ

How often do FreightPulse fuel prices update?

FreightPulse reflects EIA updates for national and regional diesel and gasoline prices on the standard government publishing cadence. Each response includes a timestamp you should store with your shipment records to document the reference used for attribution.

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

Yes. The /carriers endpoint supports trucking lookups (FMCSA SAFER) and ocean NVOCC/OTI lookups (FMC directory) using the type parameter. Air is included for completeness but returns available:false, so plan your validation logic accordingly.

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

No. FreightPulse provides a lagged approximation based on IMF PortWatch with a 7-day average benchmarked to a 90-day baseline and a typical 6–7 day data lag. It is ideal for planning and attribution multipliers, not for minute-by-minute berth queues or live AIS tracking.

What hazards are included in the disruptions feed?

FreightPulse consolidates natural hazards only—cyclones, earthquakes, floods, volcanoes, droughts, wildfires, and severe weather—sourced from GDACS, USGS, and NOAA/NWS. Geopolitical events, strikes, and administrative closures are out of scope to keep the signal focused on natural events that impact routing and dwell emissions.

How should I handle partial or missing fields in API responses?

Always check success and verify the presence of key leaf fields before computing emissions. Implement retries with exponential backoff for transient network issues, and fall back to cached values for trend endpoints like /historical and /port-congestion when appropriate. Log missing fields and surface a clear “estimated” label in your UI to preserve trust.

Conclusion + CTA

Shipment-level carbon attribution fails when it is siloed from the operational signals procurement uses to make daily decisions. With FreightPulse, you can anchor your emissions math to live US FTL quotes, current EIA diesel benchmarks, port congestion trends, verified carrier identities, and natural-disruption alerts—without juggling multiple providers and schemas. The result is a faster, clearer, and more defensible sustainability footprint across every tender and award.

As a developer, your path from prototype to production is straightforward: call the endpoints above, cache intelligently, attach timestamps and evidence to your shipment records, and expose multipliers (congestion, disruption, diesel smoothing) as configurable policy in your app. Your procurement partners will see the why behind every CO₂e estimate, not just the number.

Build your first attribution today. Explore the endpoints, run the cURL commands, and wire them into your TMS, procurement UI, or analytics pipelines. Try FreightPulse for free and make shipment-level carbon attribution a reliable part of your sustainable procurement workflow.