OilPriceAPI Docs
Quick Start
API Reference
  • SDKs and languages
  • Tutorials
  • Articles
  • Documentation directory
  • Quick reference
  • API explorer
  • FAQ
  • Changelog
  • Status
  • Dashboard
GitHub
Quick Start
API Reference
  • SDKs and languages
  • Tutorials
  • Articles
  • Documentation directory
  • Quick reference
  • API explorer
  • FAQ
  • Changelog
  • Status
  • Dashboard
GitHub
  • Interactive Explorer

    • Interactive API Explorer
  • Price Data

    • API Reference
    • Get Latest Prices
    • Historical Prices
    • Batch Prices
    • Excel Latest Price Gateway
    • Price Widget Endpoints
    • Price Utility Endpoints
    • Demo API (No Authentication)
    • Natural Gas Intelligence
    • Energy News Feed
  • Commodities

    • List Commodities
    • Get Commodity Details
    • Denmark diesel list prices (OK Danmark)
    • Data Publication & Collection Schedules
  • AI Agents (MCP)

    • Get Market Brief
    • Subscriptions / Watches
    • Agent Subscriptions with MCP
  • Marine Fuels

    • Marine Fuel API
    • List Marine Fuel Ports
    • Get Port Details with Prices
    • Bunker Fuels
    • Maritime Fuels
  • Fuel Surcharges

    • Fuel Surcharge API
  • Premium Endpoints

    • All Prices API - One Call, All Commodities
    • Cushing Oil Storage Intelligence API
    • Drilling Intelligence API
    • Marine Fuels API
    • ICE Brent Futures API
    • Aviation Fuel Pilot
  • Spreads & Margins

    • Spreads & Margins
    • Crack Spreads
    • European Gasoil Crack
    • Basis Spreads
    • Refining Margins
    • Curve Structure
    • Physical Premiums
  • Market Indicators

    • Market Indicators
    • Fuel Switching
    • Price Context
    • Storage Analytics
    • CFTC Positioning
    • Market Annotations
  • Futures

    • Futures API
    • ICE Brent Futures
    • WTI Futures
    • Continuous Futures (Brent, WTI)
    • ICE Gas Oil Futures
    • NYMEX Natural Gas Futures
    • ICE EUA Carbon Futures
    • EU Carbon Futures
    • TTF Gas Futures
    • LNG JKM Futures
    • UK Carbon Futures
  • Dark Data (Premium)

    • Energy Intelligence API
    • Rig Counts
    • Well Permits
    • Well Production Beta
    • Drilling Intelligence (Public)
    • Oil Inventories
    • OPEC Production
    • Drilling Productivity
    • Forecasts (STEO)
  • Well Production (Beta)

    • Well Production Data
    • Well Production API Reference
  • Analytics

    • Analytics API
  • Webhooks API

    • Webhooks API Reference
    • Webhook Endpoint Reference
  • Alerts

    • Price Alerts API
  • Scheduled Deliveries

    • Scheduled Deliveries API
  • Account & Billing

    • Account API
    • API Keys
    • Subscriptions
    • Organizations

Fuel Surcharge API

Use these endpoints to retrieve carrier-published fuel surcharge percentages for LTL freight and parcel shipping. Responses preserve the carrier's effective_date, the OilPriceAPI retrieved_at timestamp, and the carrier schedule source URL so you can decide whether a rate is current enough for billing, quoting, or audit workflows.

Newly launched

The fuel-surcharge endpoints are newly launched. Coverage and response fields may expand - check the changelog for updates.

Plan required: available to all authenticated plans. Standard quota and rate limits apply.

Endpoints

MethodEndpointDescription
GET/v1/fuel-surchargeLatest LTL surcharge for every covered carrier with data
GET/v1/fuel-surcharge/{carrier}/latestLatest LTL surcharge for one carrier
GET/v1/fuel-surcharge/{carrier}/historyHistorical LTL surcharge rows for one carrier
GET/v1/fuel-surcharge/parcelLatest parcel surcharges grouped by carrier and service level
GET/v1/fuel-surcharge/parcel/{carrier}/latestLatest parcel surcharge for one carrier, optionally one service level
GET/v1/fuel-surcharge/parcel/{carrier}/historyHistorical parcel surcharge rows for one carrier and service level
GET/v1/diesel-prices/monthly-averageMonthly average of the EIA U.S. on-highway diesel price, month-to-date, and surcharge effective month. See Diesel monthly average

Authentication

Authorization: Token YOUR_API_KEY

Carrier Slugs

LTL

Covered LTL carriers:

odfl, saia, estes, xpo, abf, tforce, averitt, southeastern-freight

Reserved but not yet covered LTL slugs return 404 with the current covered list. Reserved slugs include fedex-freight and rl-carriers.

Parcel

Covered parcel carriers:

ups, fedex, dhl

Parcel responses are grouped by service_level. Service levels are carrier-specific and can change; call the carrier's latest endpoint without service_level to discover current values.

Common examples include ground, air, international_air_export, international_air_import, and international_ground.

Parameters

LTL History

GET /v1/fuel-surcharge/odfl/history?per_page=12&page=1
ParameterTypeRequiredDefaultDescription
pageintegerNo1Page number
per_pageintegerNo100Rows per page, max 100

Parcel Latest and History

GET /v1/fuel-surcharge/parcel/ups/latest?service_level=ground
GET /v1/fuel-surcharge/parcel/ups/history?service_level=ground&per_page=12
ParameterTypeRequiredDescription
service_levelstringLatest: no. History: yes.Parcel service level, for example ground or international_air_export
pageintegerNoHistory page number
per_pageintegerNoHistory rows per page, max 100

Response Fields

FieldTypeDescription
carrierstringPublic carrier slug
carrier_namestringCarrier display name
modestringltl or parcel
service_levelstringParcel service level. Only present on parcel rate rows.
surcharge_percentnumberFuel surcharge percentage
effective_datedateDate the carrier says the surcharge applies
doe_diesel_pricenumber or nullDOE diesel benchmark used for LTL surcharge tables, when available
diesel_bandobject or nullLTL diesel-price band with min and max, when the carrier publishes a banded schedule
sourcestringCarrier schedule URL used for the stored row
retrieved_atdatetimeUTC timestamp when OilPriceAPI retrieved the carrier schedule

Examples

Latest LTL Surcharge

curl "https://api.oilpriceapi.com/v1/fuel-surcharge/odfl/latest" \
  -H "Authorization: Token YOUR_API_KEY"
{
  "status": "success",
  "data": {
    "carrier": "odfl",
    "carrier_name": "Old Dominion Freight Line",
    "mode": "ltl",
    "surcharge_percent": 38.32,
    "effective_date": "2026-07-14",
    "doe_diesel_price": 3.72,
    "diesel_band": {
      "min": 3.7,
      "max": 3.75
    },
    "source": "https://www.odfl.com/us/en/resources/fuel-surcharge.html",
    "retrieved_at": "2026-07-14T05:00:00Z"
  }
}

Latest Parcel Surcharges for a Carrier

curl "https://api.oilpriceapi.com/v1/fuel-surcharge/parcel/ups/latest" \
  -H "Authorization: Token YOUR_API_KEY"
{
  "status": "success",
  "data": {
    "carrier": "ups",
    "carrier_name": "UPS",
    "mode": "parcel",
    "service_levels": [
      {
        "carrier": "ups",
        "carrier_name": "UPS",
        "mode": "parcel",
        "service_level": "ground",
        "surcharge_percent": 25.25,
        "effective_date": "2026-07-20",
        "doe_diesel_price": null,
        "diesel_band": null,
        "source": "https://www.ups.com/us/en/support/shipping-support/shipping-costs-rates/fuel-surcharges",
        "retrieved_at": "2026-07-17T12:00:00Z"
      }
    ]
  }
}

One Parcel Service Level

curl "https://api.oilpriceapi.com/v1/fuel-surcharge/parcel/ups/latest?service_level=ground" \
  -H "Authorization: Token YOUR_API_KEY"
{
  "status": "success",
  "data": {
    "carrier": "ups",
    "carrier_name": "UPS",
    "mode": "parcel",
    "service_level": "ground",
    "surcharge_percent": 25.25,
    "effective_date": "2026-07-20",
    "doe_diesel_price": null,
    "diesel_band": null,
    "source": "https://www.ups.com/us/en/support/shipping-support/shipping-costs-rates/fuel-surcharges",
    "retrieved_at": "2026-07-17T12:00:00Z"
  }
}

Parcel History

curl "https://api.oilpriceapi.com/v1/fuel-surcharge/parcel/ups/history?service_level=ground&per_page=2" \
  -H "Authorization: Token YOUR_API_KEY"
{
  "status": "success",
  "data": {
    "history": [
      {
        "carrier": "ups",
        "carrier_name": "UPS",
        "mode": "parcel",
        "service_level": "ground",
        "surcharge_percent": 25.25,
        "effective_date": "2026-07-20",
        "doe_diesel_price": null,
        "diesel_band": null,
        "source": "https://www.ups.com/us/en/support/shipping-support/shipping-costs-rates/fuel-surcharges",
        "retrieved_at": "2026-07-17T12:00:00Z"
      }
    ],
    "meta": {
      "page": 1,
      "per_page": 2,
      "total_count": 13,
      "total_pages": 7
    }
  }
}

Diesel monthly average

GET /v1/diesel-prices/monthly-average returns the calendar-month average of the EIA U.S. on-highway diesel price (series EMD_EPD2D_PTE_NUS_DPG, "Diesel (On-Highway) - All Types", USD per gallon), the index that monthly rail fuel surcharges are keyed to. It is available on every authenticated plan, including Free, for every month held. Standard quota and rate limits apply. It serves JSON only.

ParameterDescription
monthOne month as YYYY-MM. Cannot be combined with start_month or end_month
start_monthFirst month of a range as YYYY-MM
end_monthLast month of a range as YYYY-MM. Defaults to the current month

With no parameters you get the current month and the two before it. A range can span at most 120 months. Months are returned newest first. The current month is the month in New York time.

curl "https://api.oilpriceapi.com/v1/diesel-prices/monthly-average?month=2026-10" \
  -H "Authorization: Token YOUR_API_KEY"

Each entry in data.months carries two figures that are never merged:

FieldMeaning
basis_monthThe month the diesel prices were observed
effective_monthbasis_month plus two calendar months (October average, December surcharge)
statusfinal (EIA has published the month), provisional (only the weekly mean exists) or unavailable
provisionaltrue until EIA publishes its monthly value
eia_monthly_averageEIA's own published monthly value (kind: "published"), served as published, or null before EIA publishes it. Includes first_seen_at, revised_at, previous_value and revision_count
weekly_meanOilPriceAPI's arithmetic mean of EIA's weekly prints dated in the month, rounded half up to 3 decimals (kind: "calculated"). Lists the weeks used, weeks_observed, weeks_in_month, complete, month_to_date, missing_weeks, warning and matches_eia_monthly

For the open month, eia_monthly_average is null and weekly_mean is the month-to-date mean with month_to_date: true. If a weekly print EIA has already published is not held, weekly_mean.value is null and warning is weekly_prints_missing; nothing is interpolated. matches_eia_monthly is null until the month has both a complete set of weekly prints and EIA's value.

first_seen_at is when OilPriceAPI first read the value from EIA. EIA's API carries no release timestamp. When EIA revises a value, the response shows the new value with revised_at and previous_value.

The response also carries:

  • series: the EIA series id, name, units and EIA's own pages for it.
  • surcharge_lag: the basis-month-plus-2 rule, the railroad programs whose public pages state it (Union Pacific, Norfolk Southern and CN, as read on 2026-11-13), CPKC as an exception that uses half-month periods, and BNSF and CSX as not verified. The applicable tariff or contract governs.
  • coverage: earliest_month, latest_published_month and latest_weekly_period.
  • freshness: last_successful_refresh_at and stale, which is true when EIA has not been read successfully in the last 36 hours. Stored values are still served while stale is true.

Refusals return {"status": "fail", "data": {"error": "...", "code": "..."}}:

StatuscodeWhen
400INVALID_MONTHA month value that is not exactly YYYY-MM, including an empty or space-padded value
400INVALID_MONTH_PARAMETERSmonth sent together with start_month or end_month
400INVALID_MONTH_RANGEstart_month is after end_month
400MONTH_RANGE_TOO_LARGEMore than 120 months
400MONTH_IN_FUTUREA month that has not started; the body includes current_month
400INVALID_FORMATAny format other than json
404MONTH_BEFORE_COVERAGEA month before the first one held; the body includes coverage
404NO_DATANo EIA on-highway diesel data is held yet

Error Cases

StatusWhenRecovery
400Parcel history request omits service_levelCall latest without service_level to list available service levels, then retry history
401Missing or invalid API keySend Authorization: Token YOUR_API_KEY
404Unknown carrier, reserved carrier, or covered carrier with no retrieved data yetUse the covered carrier list returned in the error body
402Free-tier daily quota exhausted (PAYMENT_REQUIRED), or a paid plan's monthly quota exhausted (MONTHLY_QUOTA_EXCEEDED)Check reset.date or plan; do not retry immediately
429Per-minute rate limit exceededBack off and retry after the 60-second window resets

MCP Tool

The OilPriceAPI MCP server v2.6.0 exposes these endpoints through opa_get_fuel_surcharge.

Example agent prompts:

What is the current UPS ground fuel surcharge?
Show me ODFL fuel surcharge history.
List parcel fuel surcharge service levels for FedEx.

Related

  • Logistics Fuel Cost API
  • Diesel Price Data
  • Authentication Guide
Last Updated: 11/15/26, 8:08 PM