Oil Price API Documentation - Quick Start in 5 Minutes | REST API
GitHub
GitHub
  • Interactive Explorer

    • Interactive API Explorer
  • Price Data

    • API Reference
    • Get Latest Prices
    • Historical Prices
  • Commodities

    • List Commodities
    • Get Commodity Details
  • Marine Fuels

    • List Marine Fuel Ports
    • Get Port Details with Prices
  • Premium Endpoints

    • All Prices API - One Call, All Commodities
    • Cushing Oil Storage Intelligence API
    • Drilling Intelligence API
    • Marine Fuels API
    • ICE Brent Futures API

Diesel Fuel Prices

Access Ultra-Low Sulfur Diesel (ULSD) spot prices from two major US trading hubs.


Available Diesel Codes

CodeNameRegionDescription
DIESEL_USDDiesel (Gulf Coast)US Gulf CoastULSD No 2 Diesel spot price FOB Gulf Coast
ULSD_DIESEL_USDULSD Diesel (NY Harbor)New York HarborULSD No 2 Diesel spot price FOB NY Harbor

Data Source: U.S. Energy Information Administration (EIA) Update Frequency: Daily (business days) Unit: USD per gallon


Gulf Coast Diesel (DIESEL_USD)

The Gulf Coast is the largest refining hub in the United States, making it the primary benchmark for wholesale diesel prices in the Americas.

Get Latest Price

GET/v1/prices/latest?by_code=DIESEL_USD
curl "https://api.oilpriceapi.com/v1/prices/latest?by_code=DIESEL_USD" \
  -H "Authorization: Token YOUR_API_KEY"

Response

{
  "status": "success",
  "data": {
    "price": 2.15,
    "formatted": "$2.15",
    "currency": "USD",
    "code": "DIESEL_USD",
    "created_at": "2025-12-10T14:30:00.000Z",
    "type": "spot_price",
    "source": "eia_api",
    "metadata": {
      "source": "eia_api",
      "source_description": "U.S. Gulf Coast Ultra-Low Sulfur No 2 Diesel Spot Price"
    }
  }
}

NY Harbor Diesel (ULSD_DIESEL_USD)

New York Harbor is the primary trading hub for the US East Coast and serves as the delivery point for NYMEX heating oil futures. NY Harbor prices typically trade at a premium to Gulf Coast due to transportation costs.

Get Latest Price

GET/v1/prices/latest?by_code=ULSD_DIESEL_USD
curl "https://api.oilpriceapi.com/v1/prices/latest?by_code=ULSD_DIESEL_USD" \
  -H "Authorization: Token YOUR_API_KEY"

Response

{
  "status": "success",
  "data": {
    "price": 2.22,
    "formatted": "$2.22",
    "currency": "USD",
    "code": "ULSD_DIESEL_USD",
    "created_at": "2025-12-10T14:30:00.000Z",
    "type": "spot_price",
    "source": "eia_api",
    "metadata": {
      "source": "eia_api",
      "source_description": "New York Harbor Ultra-Low Sulfur No 2 Diesel Spot Price"
    }
  }
}

Compare Both Hubs

Get both diesel prices in a single request to compare the spread:

curl "https://api.oilpriceapi.com/v1/prices/latest?by_code=DIESEL_USD,ULSD_DIESEL_USD" \
  -H "Authorization: Token YOUR_API_KEY"

Historical Data

Get historical diesel prices:

# Gulf Coast diesel - past week
curl "https://api.oilpriceapi.com/v1/prices/past_week?by_code=DIESEL_USD" \
  -H "Authorization: Token YOUR_API_KEY"

# NY Harbor diesel - past month
curl "https://api.oilpriceapi.com/v1/prices/past_month?by_code=ULSD_DIESEL_USD" \
  -H "Authorization: Token YOUR_API_KEY"

# Custom date range
curl "https://api.oilpriceapi.com/v1/prices/historical?by_code=DIESEL_USD&start_date=2025-01-01&end_date=2025-01-31" \
  -H "Authorization: Token YOUR_API_KEY"

Code Examples

Python

import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.oilpriceapi.com/v1"

def get_diesel_prices():
    """Get both Gulf Coast and NY Harbor diesel prices."""
    headers = {"Authorization": f"Token {API_KEY}"}
    params = {"by_code": "DIESEL_USD,ULSD_DIESEL_USD"}

    response = requests.get(
        f"{BASE_URL}/prices/latest",
        headers=headers,
        params=params
    )

    return response.json()

def get_diesel_spread():
    """Calculate the NY Harbor premium over Gulf Coast."""
    data = get_diesel_prices()

    # Parse prices from response
    prices = data["data"]
    gulf_coast = None
    ny_harbor = None

    # Handle both single and multiple price responses
    if isinstance(prices, list):
        for p in prices:
            if p["code"] == "DIESEL_USD":
                gulf_coast = p["price"]
            elif p["code"] == "ULSD_DIESEL_USD":
                ny_harbor = p["price"]
    else:
        # Single price response
        if prices["code"] == "DIESEL_USD":
            gulf_coast = prices["price"]
        elif prices["code"] == "ULSD_DIESEL_USD":
            ny_harbor = prices["price"]

    if gulf_coast and ny_harbor:
        spread = ny_harbor - gulf_coast
        spread_percent = (spread / gulf_coast) * 100

        print(f"Gulf Coast: ${gulf_coast:.3f}/gal")
        print(f"NY Harbor:  ${ny_harbor:.3f}/gal")
        print(f"Spread:     ${spread:.3f}/gal ({spread_percent:.1f}%)")

        return spread

    return None

# Usage
spread = get_diesel_spread()

JavaScript/Node.js

const API_KEY = 'YOUR_API_KEY';
const BASE_URL = 'https://api.oilpriceapi.com/v1';

async function getDieselPrices() {
  const response = await fetch(
    `${BASE_URL}/prices/latest?by_code=DIESEL_USD,ULSD_DIESEL_USD`,
    {
      headers: {
        'Authorization': `Token ${API_KEY}`
      }
    }
  );

  return response.json();
}

async function calculateDieselSpread() {
  const data = await getDieselPrices();
  const prices = data.data;

  let gulfCoast, nyHarbor;

  if (Array.isArray(prices)) {
    prices.forEach(p => {
      if (p.code === 'DIESEL_USD') gulfCoast = p.price;
      if (p.code === 'ULSD_DIESEL_USD') nyHarbor = p.price;
    });
  }

  if (gulfCoast && nyHarbor) {
    const spread = nyHarbor - gulfCoast;
    const spreadPercent = (spread / gulfCoast) * 100;

    console.log(`Gulf Coast: $${gulfCoast.toFixed(3)}/gal`);
    console.log(`NY Harbor:  $${nyHarbor.toFixed(3)}/gal`);
    console.log(`Spread:     $${spread.toFixed(3)}/gal (${spreadPercent.toFixed(1)}%)`);

    return spread;
  }

  return null;
}

// Usage
calculateDieselSpread();

Ruby

require 'net/http'
require 'json'
require 'uri'

API_KEY = 'YOUR_API_KEY'
BASE_URL = 'https://api.oilpriceapi.com/v1'

def get_diesel_prices
  uri = URI("#{BASE_URL}/prices/latest?by_code=DIESEL_USD,ULSD_DIESEL_USD")

  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true

  request = Net::HTTP::Get.new(uri)
  request['Authorization'] = "Token #{API_KEY}"

  response = http.request(request)
  JSON.parse(response.body)
end

def calculate_diesel_spread
  data = get_diesel_prices
  prices = data['data']

  gulf_coast = nil
  ny_harbor = nil

  if prices.is_a?(Array)
    prices.each do |p|
      gulf_coast = p['price'] if p['code'] == 'DIESEL_USD'
      ny_harbor = p['price'] if p['code'] == 'ULSD_DIESEL_USD'
    end
  end

  if gulf_coast && ny_harbor
    spread = ny_harbor - gulf_coast
    spread_percent = (spread / gulf_coast) * 100

    puts "Gulf Coast: $#{format('%.3f', gulf_coast)}/gal"
    puts "NY Harbor:  $#{format('%.3f', ny_harbor)}/gal"
    puts "Spread:     $#{format('%.3f', spread)}/gal (#{format('%.1f', spread_percent)}%)"

    return spread
  end

  nil
end

# Usage
calculate_diesel_spread

Use Cases

Fleet Fuel Cost Management

Monitor diesel prices to optimize fuel purchasing:

def check_diesel_price_threshold(threshold_price=2.50):
    """Alert when diesel drops below threshold."""
    data = get_diesel_prices()

    for price_data in data.get('data', []):
        if price_data['price'] < threshold_price:
            print(f"Low price alert: {price_data['code']} at ${price_data['price']}/gal")
            # Trigger purchase order or notification

Diesel Crack Spread Analysis

Compare diesel to crude oil for refinery margin analysis:

# Get both crude and diesel
curl "https://api.oilpriceapi.com/v1/prices/latest?by_code=WTI_USD,DIESEL_USD" \
  -H "Authorization: Token YOUR_API_KEY"

Regional Arbitrage

Monitor the spread between Gulf Coast and NY Harbor for trading opportunities.


Data Specifications

SpecificationDetails
SourceEIA (U.S. Energy Information Administration)
Update TimeDaily, typically after 4:00 PM ET
HistoryAvailable from 2010 to present
Precision3 decimal places (USD per gallon)
Days CoveredBusiness days (Mon-Fri, excluding US holidays)

Related Commodities

  • Gasoline USD - US Gulf Coast gasoline
  • Gasoline RBOB - NYMEX RBOB futures
  • Heating Oil - NY Harbor heating oil
  • Jet Fuel - Kerosene-type jet fuel

Related Endpoints

  • Latest Prices - Get current prices
  • Historical Data - Past price data
  • All Commodities - Complete list
Last Updated: 12/10/25, 12:11 PM