OilPriceAPI Documentation
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

Historical Prices

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

IntervalDescriptionAggregation
rawNo aggregation (default)Individual price points
1h, hourlyHourly aggregationOHLC data by hour
1d, dailyDaily aggregationOHLC data by day
1w, weeklyWeekly aggregationOHLC data by week
1m, monthlyMonthly aggregationOHLC data by month

Response

Success (200)

{
  "status": "success",
  "data": {
    "WTI": {
      "name": "West Texas Intermediate",
      "currency": "USD",
      "unit": "barrel",
      "prices": [
        {
          "timestamp": "2025-07-18T10:00:00Z",
          "price": 78.45,
          "volume": 125420,
          "open": 78.20,
          "high": 78.55,
          "low": 78.15,
          "close": 78.45
        }
      ],
      "summary": {
        "start": "2025-07-17T11:00:00Z",
        "end": "2025-07-18T10:00:00Z",
        "high": 79.20,
        "low": 77.50,
        "average": 78.35,
        "change": 0.82,
        "change_percent": 1.05
      }
    }
  },
  "meta": {
    "request_id": "req_hist123",
    "response_time_ms": 156,
    "data_points": 24,
    "interval": "1h"
  }
}

Response Fields

FieldTypeDescription
timestampstringISO 8601 timestamp
pricenumberPrice value
volumenumberTrading volume
opennumberOpening price
highnumberHighest price
lownumberLowest price
closenumberClosing price

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

# Get past 24 hours of WTI hourly data
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 aggregated daily data
curl "https://api.oilpriceapi.com/v1/prices/past_month?by_code=BRENT_CRUDE_USD&interval=1d" \
  -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"
// Get past week data
async function getWeeklyPrices() {
  const response = await fetch('https://api.oilpriceapi.com/v1/prices/past_week?by_code=WTI_USD', {
    headers: {
      'Authorization': 'Token YOUR_API_KEY'
    }
  });

  const data = await response.json();
  return data.data.WTI.prices;
}

// Handle pagination
async function getAllHistoricalData(endpoint = 'past_week') {
  let allData = [];
  let page = 1;
  let totalPages = 1;

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

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

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

    page++;
  }

  return allData;
}

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
Prev
Get Latest Prices