Oil Price API Fuel Surcharge API

openapi: 3.2.0
info:
  title: Oil Price API V1 Fuel Surcharge API
  version: v1
  description: 'Source-aware oil and energy data API. Check each endpoint''s source timestamp,

    coverage, and freshness fields before using a response in a time-sensitive workflow. ## Authentication


    API-key endpoints use `Authorization: Token YOUR_API_KEY`. Operations that do

    not require an API key explicitly declare an empty security requirement. `/v1/demo/prices` is keyless. ## Rate Limiting


    - Free tier: 50 requests per day

    - Paid tiers have plan-specific monthly quotas. - `402` means the allowance is exhausted: a Free or post-trial caller

    must upgrade, and a paid plan has used its monthly allowance (the body

    carries `MONTHLY_QUOTA_EXCEEDED` and reset metadata, so do not retry before

    the reset). `429` means an active-trial allowance or a rolling rate limit

    (for example the hourly safety limit) is exceeded; retry `429` and transient

    `5xx` responses with bounded backoff. - Website login and signup (`POST /sessions` and `POST /users`) also enforce

    authentication-attempt limits independently of API plan quotas: 3 attempts

    per normalized email address in 5 minutes, and 3 attempts per minute per

    verified visitor IP. Requests without a verified proxy identity retain

    the existing 20 requests/minute IP ceiling. A `429` on these routes means

    wait for `Retry-After` before retrying; upgrading a plan does not remove

    authentication-attempt limits. Futures curves are never refused because a market is closed or a session has

    just reopened. The last available data is served with `metadata.freshness_status`,

    `metadata.stale`, `metadata.latest_data_at` and `metadata.stale_by_minutes`:

    `outside_market_hours` while the venue is closed (weekend, daily break,

    holiday); `awaiting_first_print` for the first 30 minutes of a new session

    while only a valid prior close exists; `degraded` when the market is open and

    the source is behind. None of these is a fresh trade; source timestamps remain

    unchanged. Data older than the 96-hour serving bound is refused with 503. Gasoil reports `metadata.freshness_status: no_recent_trades` when the

    benchmark contract has not traded within 30 minutes but our collector confirmed

    the quote within that window and the curve printed within 90 minutes. The last

    trade is served with its true `latest_data_at` and `stale_by_minutes`, plus

    `source_checked_at` and `curve_latest_trade_at`. Paid monthly-cap responses include `retry_guidance`: immediate retries cannot

    restore quota. When a representative sample supports it, `batching_opportunity`

    describes an estimated lower request rate; batching does not restore an already

    exhausted allowance. It may replace an unnecessary upgrade recommendation. ## Continuous futures coverage


    On `/v1/futures/continuous/brent`, `/v1/futures/continuous/wti` and their

    `/historical` routes, `metadata.history_available_from` is the earliest

    stored public continuous futures source date, falling back to collection

    date for older imports without a source timestamp. It is a date string or

    null when no public observations exist. Coverage metadata is cached for up

    to one hour and does not promise observations or volume on every later date. It describes the archive independently of the request''s date range; account

    depth limits remain in `metadata.history_window` on historical responses. Latest-response `metadata.total_historical_records` counts stored public

    snapshots, including revisions, rather than distinct source dates. Latest

    quotes and their prior-day comparisons exclude private organization rows

    and other price types. Repeated source timestamps select the later collected

    revision; the oldest metadata/response cache formats are no longer used. ## Spread and indicator query parameters


    Spread and indicator endpoints reject unrecognized query parameter names with

    HTTP 400 and `error.code: UNKNOWN_PARAMETERS`, after authentication and access

    checks. The error includes `unrecognized_parameters`, `allowed_parameters`,

    and a `suggestions` map for recognized date-name mistakes; values are not

    echoed.'
  contact:
    name: Oil Price API Support
    email: support@oilpriceapi.com
    url: https://oilpriceapi.com
  license:
    name: Commercial License
    url: https://oilpriceapi.com/terms
servers:
- url: https://api.oilpriceapi.com
  description: Production server
tags:
- name: Fuel Surcharge
  description: Published carrier fuel-surcharge schedules and history.
paths:
  /v1/fuel-surcharge:
    get:
      summary: List current LTL carrier fuel surcharges
      operationId: getV1FuelSurcharge
      tags:
      - Fuel Surcharge
      description: 'Returns the latest stored published fuel-surcharge percentage for every

        covered LTL carrier that currently has data. Each row preserves the

        carrier''s effective date, retrieval timestamp, and published source URL.'
      security:
      - ApiKeyAuth: []
      responses:
        '200':
          description: Current LTL carrier fuel surcharges
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FuelSurchargeListResponse'
        '401':
          description: Unauthorized - Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/fuel-surcharge/{carrier}/latest:
    get:
      summary: Get the current LTL fuel surcharge for one carrier
      operationId: getV1FuelSurchargeCarrierLatest
      tags:
      - Fuel Surcharge
      description: 'Returns the latest stored published fuel-surcharge percentage for one

        LTL carrier. An unknown carrier or a carrier with no ingested data

        returns 404; the API never fabricates a current value.'
      parameters:
      - $ref: '#/components/parameters/FuelSurchargeCarrier'
      security:
      - ApiKeyAuth: []
      responses:
        '200':
          description: Current LTL carrier fuel surcharge
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FuelSurchargeRateResponse'
        '401':
          description: Unauthorized - Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Carrier is unknown or has no retrieved data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/fuel-surcharge/{carrier}/history:
    get:
      summary: Get LTL fuel-surcharge history for one carrier
      operationId: getV1FuelSurchargeCarrierHistory
      tags:
      - Fuel Surcharge
      description: 'Returns stored weekly published fuel-surcharge rows newest first. Each

        row retains its original effective date and retrieval timestamp.'
      parameters:
      - $ref: '#/components/parameters/FuelSurchargeCarrier'
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/FuelSurchargePerPage'
      security:
      - ApiKeyAuth: []
      responses:
        '200':
          description: Paginated LTL carrier fuel-surcharge history
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FuelSurchargeHistoryResponse'
        '401':
          description: Unauthorized - Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Carrier is unknown or has no retrieved data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/fuel-surcharge/calculate:
    get:
      summary: Calculate your fuel surcharge from the EIA weekly diesel index
      operationId: getV1FuelSurchargeCalculate
      tags:
      - Fuel Surcharge
      description: 'Applies your own surcharge schedule to the stored EIA (DOE) weekly

        retail on-highway diesel series and returns the result for the latest

        week plus a weekly table, newest first. Two methods: `percent`

        (surcharge % = completed increments over base x percent per increment)

        and `per_mile` ((diesel - base) / mpg, USD per mile). Diesel at or

        below the base price is a 0 surcharge. Each week carries its EIA week

        date and retrieval time. A region with no stored week returns 404.'
      parameters:
      - name: base_price
        in: query
        required: true
        description: Diesel price (USD/gallon) already built into your base rate.
        schema:
          type: number
          example: 1.25
      - name: method
        in: query
        required: false
        description: '`percent` returns `surcharge_percent` per week; `per_mile` returns `surcharge_per_mile` in USD per mile. Case-insensitive; defaults to `percent`.'
        schema:
          type: string
          enum:
          - percent
          - per_mile
          default: percent
          example: percent
      - name: increment
        in: query
        required: false
        description: Required for `percent`. Diesel price step (USD/gallon) per surcharge step, at least 0.001. Plain decimals only.
        schema:
          type: number
          example: 0.05
      - name: percent_per_increment
        in: query
        required: false
        description: Required for `percent`. Surcharge percentage points added per step.
        schema:
          type: number
          example: 1
      - name: rounding
        in: query
        required: false
        description: '`floor` counts completed steps only; `ceil` counts a partial step; `exact` applies no banding.'
        schema:
          type: string
          enum:
          - floor
          - ceil
          - exact
          default: floor
          example: floor
      - name: mpg
        in: query
        required: false
        description: Required for `per_mile`. Fleet fuel economy in miles per gallon, at least 1.
        schema:
          type: number
          example: 6.5
      - name: region
        in: query
        required: false
        description: EIA weekly retail diesel region. `national` is the U.S. average (DIESEL_RETAIL_USD); the others are the EIA PADD regions plus California. Case-insensitive; defaults to `national`.
        schema:
          type: string
          enum:
          - national
          - east-coast
          - midwest
          - gulf-coast
          - rocky-mountain
          - west-coast
          - california
          default: national
          example: national
      - name: weeks
        in: query
        required: false
        description: Number of most recent EIA weeks in the `weeks` table, newest first, 1 to 52. Defaults to 4.
        schema:
          type: integer
          minimum: 1
          maximum: 52
          default: 4
          example: 4
      security:
      - ApiKeyAuth: []
      responses:
        '200':
          description: Surcharge for the latest EIA week and the weekly table
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  data:
                    type: object
                    properties:
                      region:
                        type: string
                      commodity_code:
                        type: string
                        example: DIESEL_RETAIL_USD
                      index:
                        type: string
                      as_of:
                        type: string
                        format: date
                        description: EIA week of the latest stored diesel price.
                      stale:
                        type: boolean
                        description: True when the latest EIA week is more than 9 days old (ingestion behind).
                      stale_reason:
                        type:
                        - string
                        - 'null'
                      inputs:
                        type: object
                        additionalProperties: true
                      current:
                        $ref: '#/components/schemas/FuelSurchargeCalculationWeek'
                      weeks:
                        type: array
                        items:
                          $ref: '#/components/schemas/FuelSurchargeCalculationWeek'
        '400':
          description: Missing or invalid parameters; every problem is listed in `data.errors`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: No EIA weekly diesel price stored for the region
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/fuel-surcharge/parcel:
    get:
      summary: List current parcel carrier fuel surcharges
      operationId: getV1FuelSurchargeParcel
      tags:
      - Fuel Surcharge
      description: 'Returns current published parcel fuel surcharges grouped by carrier and

        service level, with effective dates and retrieval timestamps.'
      security:
      - ApiKeyAuth: []
      responses:
        '200':
          description: Current parcel fuel surcharges by carrier and service level
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParcelFuelSurchargeListResponse'
        '401':
          description: Unauthorized - Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/fuel-surcharge/parcel/{carrier}/latest:
    get:
      summary: Get current parcel fuel surcharges for one carrier
      operationId: getV1FuelSurchargeParcelCarrierLatest
      tags:
      - Fuel Surcharge
      description: 'Returns all current service-level surcharges for a parcel carrier, or a

        single rate when `service_level` is provided.'
      parameters:
      - $ref: '#/components/parameters/ParcelFuelSurchargeCarrier'
      - $ref: '#/components/parameters/FuelSurchargeServiceLevel'
      security:
      - ApiKeyAuth: []
      responses:
        '200':
          description: Current parcel carrier surcharge data
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/FuelSurchargeRateResponse'
                - $ref: '#/components/schemas/ParcelFuelSurchargeCarrierResponse'
        '401':
          description: Unauthorized - Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Carrier, service level, or retrieved data is unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/fuel-surcharge/parcel/{carrier}/history:
    get:
      summary: Get parcel fuel-surcharge history for one service level
      operationId: getV1FuelSurchargeParcelCarrierHistory
      tags:
      - Fuel Surcharge
      description: 'Returns stored published parcel fuel-surcharge rows newest first for one

        carrier and required service level.'
      parameters:
      - $ref: '#/components/parameters/ParcelFuelSurchargeCarrier'
      - name: service_level
        in: query
        required: true
        description: Carrier service-level identifier returned by the parcel list endpoint
        schema:
          type: string
          example: ground
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/FuelSurchargePerPage'
      security:
      - ApiKeyAuth: []
      responses:
        '200':
          description: Paginated parcel fuel-surcharge history
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FuelSurchargeHistoryResponse'
        '400':
          description: service_level is missing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Carrier, service level, or retrieved data is unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  parameters:
    ParcelFuelSurchargeCarrier:
      name: carrier
      in: path
      required: true
      description: Covered parcel carrier slug returned by the parcel list endpoint
      schema:
        type: string
        example: ups
    FuelSurchargeCarrier:
      name: carrier
      in: path
      required: true
      description: Covered LTL carrier slug returned by the list endpoint
      schema:
        type: string
        example: odfl
    FuelSurchargeServiceLevel:
      name: service_level
      in: query
      required: false
      description: Optional carrier service-level identifier, such as `ground`
      schema:
        type: string
        example: ground
    Page:
      name: page
      in: query
      required: false
      description: One-indexed result page
      schema:
        type: integer
        minimum: 1
        default: 1
    FuelSurchargePerPage:
      name: per_page
      in: query
      required: false
      description: Results per page, capped at 100
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 100
  schemas:
    ParcelFuelSurchargeListResponse:
      type: object
      required:
      - status
      - data
      properties:
        status:
          type: string
          enum:
          - success
        data:
          type: object
          required:
          - carriers
          properties:
            carriers:
              type: array
              items:
                $ref: '#/components/schemas/ParcelFuelSurchargeCarrier'
    FuelSurchargeHistoryMeta:
      type: object
      required:
      - page
      - per_page
      - total_count
      - total_pages
      properties:
        page:
          type: integer
          minimum: 1
        per_page:
          type: integer
          minimum: 1
          maximum: 100
        total_count:
          type: integer
          minimum: 0
        total_pages:
          type: integer
          minimum: 0
    ParcelFuelSurchargeCarrierResponse:
      type: object
      required:
      - status
      - data
      properties:
        status:
          type: string
          enum:
          - success
        data:
          $ref: '#/components/schemas/ParcelFuelSurchargeCarrier'
    FuelSurchargeListResponse:
      type: object
      required:
      - status
      - data
      properties:
        status:
          type: string
          enum:
          - success
        data:
          type: object
          required:
          - carriers
          properties:
            carriers:
              type: array
              items:
                $ref: '#/components/schemas/FuelSurchargeRate'
    FuelSurchargeHistoryResponse:
      type: object
      required:
      - status
      - data
      properties:
        status:
          type: string
          enum:
          - success
        data:
          type: object
          required:
          - history
          - meta
          properties:
            history:
              type: array
              items:
                $ref: '#/components/schemas/FuelSurchargeRate'
            meta:
              $ref: '#/components/schemas/FuelSurchargeHistoryMeta'
    FuelSurchargeCalculationWeek:
      type: object
      properties:
        week_of:
          type: string
          format: date
          description: EIA week the diesel price was observed for.
        diesel_price:
          type: number
          description: EIA weekly retail on-highway diesel, USD/gallon.
        diesel_change:
          type:
          - number
          - 'null'
          description: Change from the prior EIA week, USD/gallon.
        retrieved_at:
          type: string
          format: date-time
        surcharge_percent:
          type: number
          description: Present for method=percent.
        surcharge_per_mile:
          type: number
          description: Present for method=per_mile, USD per mile.
    FuelSurchargeRateResponse:
      type: object
      required:
      - status
      - data
      properties:
        status:
          type: string
          enum:
          - success
        data:
          $ref: '#/components/schemas/FuelSurchargeRate'
    ParcelFuelSurchargeCarrier:
      type: object
      required:
      - carrier
      - carrier_name
      - mode
      - service_levels
      properties:
        carrier:
          type: string
          example: ups
        carrier_name:
          type: string
          example: UPS
        mode:
          type: string
          enum:
          - parcel
        service_levels:
          type: array
          items:
            $ref: '#/components/schemas/FuelSurchargeRate'
    FuelSurchargeRate:
      type: object
      required:
      - carrier
      - carrier_name
      - mode
      - surcharge_percent
      - effective_date
      - doe_diesel_price
      - diesel_band
      - source
      - retrieved_at
      properties:
        carrier:
          type: string
          example: odfl
        carrier_name:
          type: string
          example: Old Dominion Freight Line
        mode:
          type: string
          enum:
          - ltl
          - parcel
        service_level:
          type: string
          description: Present for parcel rates
          example: ground
        surcharge_percent:
          type: number
          format: float
          example: 25.5
        effective_date:
          type: string
          format: date
        doe_diesel_price:
          type:
          - number
          - 'null'
          format: float
        diesel_band:
          type:
          - object
          - 'null'
          required:
          - min
          - max
          properties:
            min:
              type:
              - number
              - 'null'
              format: float
            max:
              type:
              - number
              - 'null'
              format: float
        source:
          type: string
          format: uri
          description: Carrier-published schedule URL
        retrieved_at:
          type: string
          format: date-time
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Machine-readable error code (e.g. UNAUTHORIZED, NOT_FOUND, INVALID_PARAMETER).
              example: UNAUTHORIZED
            message:
              type: string
              example: 'Missing or invalid API key. Include header: Authorization: Token YOUR_API_KEY'
            status:
              type: integer
              example: 401
            request_id:
              type: string
              example: fa0e389f-ca86-47b2-b167-2b4645a2fb8b
            docs:
              type: string
              example: https://docs.oilpriceapi.com#UNAUTHORIZED
            signup_url:
              type:
              - string
              - 'null'
              example: https://www.oilpriceapi.com/auth/signup
            demo_endpoint:
              type:
              - string
              - 'null'
              example: /v1/demo/prices
  responses:
    InternalServerError:
      description: Unexpected server error. Retry transient failures with bounded backoff and retain the request ID when contacting support.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'API key as: Authorization: Token YOUR_API_KEY'
externalDocs:
  description: OilPriceAPI developer documentation
  url: https://docs.oilpriceapi.com