Historical Prices
Status: ✅ Available | 📈 Time-Series | 🔄 Multiple Intervals
Access historical price data for oil and commodity markets with customizable time ranges and intervals.
Endpoints
| Method | Endpoint | Description |
|---|---|---|
| GET | /v1/prices/past_day | Hourly prices for past 24 hours |
| GET | /v1/prices/past_week | Daily prices for past 7 days |
| GET | /v1/prices/past_month | Daily prices for past 30 days |
| GET | /v1/prices/past_year | Weekly prices for past 365 days |
Authentication
See Authentication Guide for API key setup.
Parameters
| Parameter | Type | Required | Description | Default | Example |
|---|---|---|---|---|---|
by_code | string | No | Commodity code to retrieve | BRENT_CRUDE_USD | WTI_USD, NATURAL_GAS_USD |
by_type | string | No | Price type to retrieve | spot_price | spot_price, daily_average_price |
interval | string | No | Time interval for data aggregation | raw | raw, 1h, 1d, 1w, 1m |
page | integer | No | Page number for pagination | 1 | 1, 2, 3 |
per_page | integer | No | Number of results per page (max: 100) | 100 | 10, 50, 100 |
format | string | No | Response format | json | json, 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.
| Interval | Description | Aggregation | Use Case |
|---|---|---|---|
raw | No aggregation (default) | Individual price points | Full granularity, detailed analysis |
1h, hourly | Hourly aggregation | Average price per hour | Intraday analysis, short-term trends |
1d, daily | Daily aggregation | Average price per day | Daily charts, week-over-week comparison |
1w, weekly | Weekly aggregation | Average price per week | Monthly/quarterly charts, medium-term trends |
1m, monthly | Monthly aggregation | Average price per month | Yearly 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
| Field | Type | Description |
|---|---|---|
price | number | Price value (rounded to 2 decimal places) |
formatted | string | Currency-formatted price with symbol |
currency | string | Currency code (USD, EUR, GBP) |
code | string | Commodity code |
created_at | string | ISO 8601 timestamp (UTC) |
type | string | Price type: spot_price, daily_average, weekly_average, monthly_average, hourly_average |
source | string | Data source: aggregated for interval data, or scraper source for raw data |
Pagination
Historical endpoints return paginated results for performance:
| Header | Description | Example |
|---|---|---|
X-Total | Total number of records | 2016 |
X-Total-Pages | Total number of pages | 21 |
X-Page | Current page number | 1 |
X-Per-Page | Records per page | 100 |
Link | RFC 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
| Code | Status | Description |
|---|---|---|
INVALID_COMMODITY | 400 | Invalid commodity code provided |
INVALID_INTERVAL | 400 | Invalid interval parameter |
INVALID_API_KEY | 401 | Missing or invalid API key |
RATE_LIMIT_EXCEEDED | 429 | Rate limit exceeded |
Rate Limits
| Plan | past_day | past_week | past_month | past_year |
|---|---|---|---|---|
| Free | 10/hour | 5/hour | 2/hour | 1/hour |
| Hobby | 100/hour | 50/hour | 20/hour | 10/hour |
| Professional | 1000/hour | 500/hour | 200/hour | 100/hour |
| Enterprise | Unlimited | Unlimited | Unlimited | Unlimited |
Related Endpoints
- Latest Prices - Current market prices
- Commodities List - Available commodity codes
- WebSocket Streaming - Real-time updates