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
  • Futures

    • Futures API
    • ICE Brent Futures
    • ICE WTI Futures
    • ICE Gas Oil Futures
    • NYMEX Natural Gas Futures
  • Dark Data (Premium)

    • Dark Data API
    • Rig Counts
    • Oil Inventories
    • OPEC Production
    • Drilling Productivity
    • Forecasts (STEO)
  • Analytics

    • Analytics API
  • Account & Billing

    • Account API

Historical Prices

Status: ✅ Available | 📈 Time-Series | 🔄 Multiple Intervals

Access historical price data for oil and commodity markets with customizable time ranges and intervals.

Endpoints

MethodEndpointDescription
GET/v1/prices/past_dayHourly prices for past 24 hours
GET/v1/prices/past_weekDaily prices for past 7 days
GET/v1/prices/past_monthDaily prices for past 30 days
GET/v1/prices/past_yearWeekly prices for past 365 days

Authentication

See Authentication Guide for API key setup.

Parameters

ParameterTypeRequiredDescriptionDefaultExample
by_codestringNoCommodity code to retrieveBRENT_CRUDE_USDWTI_USD, NATURAL_GAS_USD
by_typestringNoPrice type to retrievespot_pricespot_price, daily_average_price
intervalstringNoTime interval for data aggregationrawraw, 1h, 1d, 1w, 1m
pageintegerNoPage number for pagination11, 2, 3
per_pageintegerNoNumber of results per page (max: 100)10010, 50, 100
formatstringNoResponse formatjsonjson, csv

Interval Parameter

The interval parameter controls time-based aggregation for historical data. When specified, prices are averaged within each time bucket, reducing data transfer and improving performance for charting and dashboard applications.

IntervalDescriptionAggregationUse Case
rawNo aggregation (default)Individual price pointsFull granularity, detailed analysis
1h, hourlyHourly aggregationAverage price per hourIntraday analysis, short-term trends
1d, dailyDaily aggregationAverage price per dayDaily charts, week-over-week comparison
1w, weeklyWeekly aggregationAverage price per weekMonthly/quarterly charts, medium-term trends
1m, monthlyMonthly aggregationAverage price per monthYearly charts, long-term trends

Benefits:

  • Reduced Data Transfer: Fewer data points for the same time range (e.g., 30 days = 30 daily averages vs. 43,200 minute-level points)
  • Lower Rate Limit Usage: Aggregated responses use the same rate limit as raw data
  • Optimized for Charting: Pre-aggregated data is ideal for time-series visualizations
  • Consistent Formatting: All prices rounded to 2 decimal places for currency consistency

Response

Success (200) - Raw Data

{
  "status": "success",
  "data": {
    "prices": [
      {
        "price": 78.45,
        "formatted": "$78.45",
        "currency": "USD",
        "code": "WTI_USD",
        "created_at": "2025-07-18T10:00:00.000Z",
        "type": "spot_price",
        "source": "oilprice.business_insider"
      }
    ]
  }
}

Success (200) - With Interval Aggregation

When using the interval parameter, responses include aggregated prices:

{
  "status": "success",
  "data": {
    "prices": [
      {
        "price": 78.46,
        "formatted": "$78.46",
        "currency": "USD",
        "code": "WTI_USD",
        "created_at": "2025-07-18T00:00:00.000Z",
        "type": "daily_average",
        "source": "aggregated"
      },
      {
        "price": 77.92,
        "formatted": "$77.92",
        "currency": "USD",
        "code": "WTI_USD",
        "created_at": "2025-07-17T00:00:00.000Z",
        "type": "daily_average",
        "source": "aggregated"
      }
    ]
  }
}

Response Fields

FieldTypeDescription
pricenumberPrice value (rounded to 2 decimal places)
formattedstringCurrency-formatted price with symbol
currencystringCurrency code (USD, EUR, GBP)
codestringCommodity code
created_atstringISO 8601 timestamp (UTC)
typestringPrice type: spot_price, daily_average, weekly_average, monthly_average, hourly_average
sourcestringData source: aggregated for interval data, or scraper source for raw data

Pagination

Historical endpoints return paginated results for performance:

HeaderDescriptionExample
X-TotalTotal number of records2016
X-Total-PagesTotal number of pages21
X-PageCurrent page number1
X-Per-PageRecords per page100
LinkRFC 5988 pagination links<...?page=2>; rel="next"

Examples

Basic Usage

# Get past 24 hours of raw WTI data (all individual price points)
curl "https://api.oilpriceapi.com/v1/prices/past_day?by_code=WTI_USD" \
  -H "Authorization: Token YOUR_API_KEY"

# Get past week with pagination
curl "https://api.oilpriceapi.com/v1/prices/past_week?by_code=WTI_USD&page=1&per_page=50" \
  -H "Authorization: Token YOUR_API_KEY"

# Get CSV format
curl "https://api.oilpriceapi.com/v1/prices/past_year?by_code=WTI_USD&format=csv" \
  -H "Authorization: Token YOUR_API_KEY"

Using Interval Aggregation

# Get past month as daily averages (30 data points instead of ~43,200)
curl "https://api.oilpriceapi.com/v1/prices/past_month?by_code=BRENT_CRUDE_USD&interval=1d" \
  -H "Authorization: Token YOUR_API_KEY"

# Get past year as weekly averages for long-term trending
curl "https://api.oilpriceapi.com/v1/prices/past_year?by_code=WTI_USD&interval=1w" \
  -H "Authorization: Token YOUR_API_KEY"

# Get past week as hourly averages for intraday analysis
curl "https://api.oilpriceapi.com/v1/prices/past_week?by_code=NATURAL_GAS_USD&interval=1h" \
  -H "Authorization: Token YOUR_API_KEY"

# Get past year as monthly averages for annual trends
curl "https://api.oilpriceapi.com/v1/prices/past_year?by_code=BRENT_CRUDE_USD&interval=1m" \
  -H "Authorization: Token YOUR_API_KEY"

JavaScript/TypeScript

// Get past week with daily aggregation
async function getWeeklyPrices() {
  const response = await fetch(
    'https://api.oilpriceapi.com/v1/prices/past_week?by_code=WTI_USD&interval=1d',
    {
      headers: {
        'Authorization': 'Token YOUR_API_KEY'
      }
    }
  );

  const data = await response.json();
  return data.data.prices; // Returns ~7 daily averages
}

// Get optimized data for charting (monthly averages for past year)
async function getChartData(commodityCode = 'WTI_USD') {
  const response = await fetch(
    `https://api.oilpriceapi.com/v1/prices/past_year?by_code=${commodityCode}&interval=1m`,
    {
      headers: { 'Authorization': 'Token YOUR_API_KEY' }
    }
  );

  const data = await response.json();

  // Format for chart libraries (e.g., Chart.js, Recharts)
  return data.data.prices.map(price => ({
    date: new Date(price.created_at),
    value: price.price,
    formatted: price.formatted
  }));
}

// Handle pagination for raw (non-aggregated) data
async function getAllRawData(endpoint = 'past_week', commodityCode = 'WTI_USD') {
  let allData = [];
  let page = 1;
  let totalPages = 1;

  while (page <= totalPages) {
    const response = await fetch(
      `https://api.oilpriceapi.com/v1/prices/${endpoint}?by_code=${commodityCode}&page=${page}`,
      {
        headers: { 'Authorization': 'Token YOUR_API_KEY' }
      }
    );

    totalPages = parseInt(response.headers.get('X-Total-Pages'));
    const data = await response.json();

    if (data.data?.prices) {
      allData.push(...data.data.prices);
    }

    page++;
  }

  return allData;
}

Python

import requests
from datetime import datetime

# Get past month as daily averages
def get_monthly_averages(commodity_code='WTI_USD'):
    url = 'https://api.oilpriceapi.com/v1/prices/past_month'
    headers = {'Authorization': 'Token YOUR_API_KEY'}
    params = {
        'by_code': commodity_code,
        'interval': '1d'  # Daily aggregation
    }

    response = requests.get(url, headers=headers, params=params)
    data = response.json()

    return data['data']['prices']

# Get past year with weekly aggregation for trending
def get_yearly_trend(commodity_code='BRENT_CRUDE_USD'):
    url = 'https://api.oilpriceapi.com/v1/prices/past_year'
    headers = {'Authorization': 'Token YOUR_API_KEY'}
    params = {
        'by_code': commodity_code,
        'interval': '1w'  # Weekly aggregation
    }

    response = requests.get(url, headers=headers, params=params)
    data = response.json()

    # Format for data analysis
    prices = []
    for price in data['data']['prices']:
        prices.append({
            'date': datetime.fromisoformat(price['created_at'].replace('Z', '+00:00')),
            'price': price['price'],
            'type': price['type']
        })

    return prices

Errors

CodeStatusDescription
INVALID_COMMODITY400Invalid commodity code provided
INVALID_INTERVAL400Invalid interval parameter
INVALID_API_KEY401Missing or invalid API key
RATE_LIMIT_EXCEEDED429Rate limit exceeded

Rate Limits

Planpast_daypast_weekpast_monthpast_year
Free10/hour5/hour2/hour1/hour
Hobby100/hour50/hour20/hour10/hour
Professional1000/hour500/hour200/hour100/hour
EnterpriseUnlimitedUnlimitedUnlimitedUnlimited

Related Endpoints

  • Latest Prices - Current market prices
  • Commodities List - Available commodity codes
  • WebSocket Streaming - Real-time updates
Last Updated: 12/28/25, 12:24 AM
Prev
Get Latest Prices