---
title: "Monthly average of EIA U.S. on-highway diesel, with month-to-date and surcharge effective month"
method: GET
path: "/v1/diesel-prices/monthly-average"
tags: ["Fuel Surcharge"]
---

# Monthly average of EIA U.S. on-highway diesel, with month-to-date and surcharge effective month

`GET /v1/diesel-prices/monthly-average`

## Request

- Base URL: `https://api.oilpriceapi.com`
- URL: `https://api.oilpriceapi.com/v1/diesel-prices/monthly-average`
- Auth: API key in header `Authorization`

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 monthly rail fuel-surcharge programs are keyed to.

Each month carries two separate figures. `eia_monthly_average` is the
value EIA publishes for the month, served as published (`kind:
published`). `weekly_mean` is OilPriceAPI's arithmetic mean of EIA's
weekly prints dated in the month, rounded half up to 3 decimals (`kind:
calculated`), with the weeks used and the week count. For the open
month `eia_monthly_average` is null, `weekly_mean` is the month-to-date
mean and `provisional` is true. When a weekly print EIA has already
published is not held, `weekly_mean.value` is null and `warning` says
why; nothing is interpolated.

`effective_month` is the basis month plus two calendar months. That
convention is listed in `surcharge_lag.verified_programs` only for the
programs whose public page states it; `surcharge_lag.exceptions` lists
a program that uses a different basis period. The applicable tariff or
contract governs.

With no parameters the response holds the current month and the two
before it, newest first. Available on every plan. EIA revises its
values; a revised value is served with `revised_at` and
`previous_value`. EIA's API carries no release timestamp, so
`first_seen_at` is when OilPriceAPI first read the value.

## Query parameters

- `month` string
- `start_month` string
- `end_month` string

## Response `200`

Requested months, newest first

- object
  - `status` string
  - `data` object
    - `months` DieselMonthlyAverageMonth[]
      - `basis_month` string
      - `effective_month` string: Basis month plus two calendar months. See `surcharge_lag` for the programs this was verified for.
      - `status` 'final' | 'provisional' | 'unavailable': `final`: EIA has published the month. `provisional`: only the weekly mean exists. `unavailable`: neither figure can be stated.
      - `provisional` boolean: True until EIA publishes the monthly average.
      - `eia_monthly_average` object, nullable: EIA's published monthly average. Null until EIA publishes it.
        - `value` number
        - `value_text` string: The value to EIA's 3 decimals.
        - `kind` 'published'
        - `units` string
        - `source` string
        - `series_id` string
        - `frequency` string
        - `period` string
        - `first_seen_at` string, date-time: When OilPriceAPI first read this period from EIA. Not EIA's release date.
        - `revised_at` string, date-time, nullable: When a changed EIA value for this period was last stored.
        - `previous_value` number, nullable
        - `revision_count` integer
      - `weekly_mean` object: OilPriceAPI's arithmetic on EIA's weekly prints for the month. Month-to-date while the month is open.
        - `value` number, nullable: Null when a weekly print EIA has already published is not held, or none exists yet.
        - `value_text` string, nullable
        - `unrounded` string, nullable
        - `kind` 'calculated'
        - `units` string
        - `method` string
        - `weeks_observed` integer
        - `weeks_in_month` integer: Mondays in the calendar month.
        - `complete` boolean: True when every Monday of the month has a print.
        - `month_to_date` boolean
        - `weeks` object[]
          - `period` string, date
          - `value` number
          - `series_id` string
          - `revised_at` string, date-time, nullable
        - `missing_weeks` string[]
        - `warning` 'weekly_prints_missing' | 'unexpected_weekly_period' | 'no_weekly_prints_yet' | 'null', nullable
        - `matches_eia_monthly` boolean, nullable: Whether the rounded weekly mean equals EIA's monthly value. Null unless both exist and the month is complete.
    - `series` object: The EIA series, its units and EIA's own pages for it.
    - `surcharge_lag` object: The basis-month-plus-2 rule, the programs it was verified for with their sources, and known exceptions.
    - `coverage` object
      - `earliest_month` string
      - `latest_published_month` string
      - `latest_weekly_period` string, date
    - `freshness` object
      - `last_successful_refresh_at` string, date-time, nullable: When both the weekly and monthly series were last read from EIA successfully.
      - `stale` boolean: True when EIA has not been read successfully in the last 36 hours. Stored values are still served.
      - `latest_weekly_period` string, date, nullable
      - `latest_published_month` string, nullable

## Other responses

- `400`: Malformed month, including an empty or whitespace-padded value (`INVALID_MONTH`), any `format` other than json (`INVALID_FORMAT`), a month that has not started (`MONTH_IN_FUTURE`), `month` combined with a range (`INVALID_MONTH_PARAMETERS`), a start after the end (`INVALID_MONTH_RANGE`) or more than 120 months (`MONTH_RANGE_TOO_LARGE`). The code is in `data.code`.
- `401`: Unauthorized - Invalid API key
- `404`: A month before the first month held (`MONTH_BEFORE_COVERAGE`, with `data.coverage`) or no data yet (`NO_DATA`).
- `500`: Unexpected server error. Retry transient failures with bounded backoff and retain the request ID when contacting support.

## Changes

- **2026-11-15** `ea22019fbf1b`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/oilpriceapi/apis/oil-price-api-v1/changes/v1/diesel-prices/monthly-average/get.md)

---

[API](https://skmtc.dev/oilpriceapi/apis/oil-price-api-v1.md) - [All operations](https://skmtc.dev/oilpriceapi/apis/oil-price-api-v1/llms.txt) - [OpenAPI document](https://skmtc.dev/oilpriceapi/apis/oil-price-api-v1/revisions/ea22019fbf1b?raw)
