OilPriceAPI Documentation

# 📖 API Reference

Complete reference documentation for all OilPriceAPI endpoints.

# 🔐 Authentication

All API requests require authentication using your API key.

Authorization: Bearer YOUR_API_KEY
1

TIP

Get your API key from the dashboard (opens new window) after signing up.

# 🌐 Base URL

https://api.oilpriceapi.com/v1
1

# 📊 Response Format

All responses follow this structure:

{
  "status": "success|error",
  "data": { ... },
  "meta": {
    "request_id": "req_abc123",
    "response_time_ms": 42,
    "timestamp": "2025-07-18T10:30:00Z"
  }
}
1
2
3
4
5
6
7
8
9

# 🚦 Rate Limits

Plan Requests/Month Rate Limit
Free 1,000 10/minute
Hobby 10,000 100/minute
Starter 50,000 500/minute
Professional 100,000 1,000/minute
Business 200,000 2,000/minute
Reservoir Mastery 250,000 2,500/minute

Rate limit information is included in response headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1736784000
1
2
3

# 🎯 Available Endpoints

# Price Endpoints

GET /v1/prices/latest

Get latest commodity prices

View Details →
GET /v1/prices/past_day

Get hourly prices for past 24 hours

View Details →
GET /v1/prices/past_week

Get daily prices for past 7 days

View Details →
GET /v1/prices/past_month

Get daily prices for past 30 days

View Details →

# Commodity Endpoints

GET /v1/commodities

List all available commodities

View Details →
GET /v1/commodities/:code

Get commodity details

View Details →
GET /v1/commodities/categories

Get commodity categories

View Details →

# Marine Fuel Endpoints

GET /v1/prices/marine-fuels

Get marine fuel prices by port

View Details →
GET /v1/marine-ports

List all marine ports

View Details →

# Alert Endpoints

POST /v1/alerts

Create price alert

View Details →
GET /v1/alerts

List your alerts

View Details →
DELETE /v1/alerts/:id

Delete an alert

View Details →

# Premium Endpoints (Reservoir Mastery)

GET /v1/drilling-intelligence

Comprehensive drilling data

View Details →
GET /v1/rig-counts/latest

Latest rig count data (simplified)

View Details →
WS wss://api.oilpriceapi.com/cable

Real-time price streaming

View Details →

# 🔍 Common Parameters

# Filtering

Most endpoints support these common parameters:

Parameter Type Description Example
commodities string Comma-separated commodity codes WTI,BRENT
currency string Convert prices to currency EUR, GBP
fields string Specific fields to return price,timestamp
page integer Page number for pagination 2
per_page integer Items per page (max 100) 50

# Date Filtering

For historical endpoints:

Parameter Type Description Example
start_date string Start date (ISO 8601) 2025-01-01
end_date string End date (ISO 8601) 2025-07-18
interval string Data interval 1h, 1d, 1w
timezone string Timezone for timestamps America/New_York

# 🚨 Error Codes

Code Status Description
INVALID_API_KEY 401 Invalid or missing API key
RATE_LIMIT_EXCEEDED 429 Too many requests
INVALID_COMMODITY 400 Unknown commodity code
INVALID_PARAMETER 400 Invalid request parameter
INSUFFICIENT_PLAN 403 Feature not available on your plan
SERVER_ERROR 500 Internal server error

# Error Response Example

{
  "status": "error",
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded",
    "details": {
      "limit": 1000,
      "remaining": 0,
      "reset_at": "2025-07-18T11:00:00Z"
    }
  }
}
1
2
3
4
5
6
7
8
9
10
11
12

# 🌍 Supported Currencies

Convert prices to any of these currencies:

Major Currencies

  • USD - US Dollar (default)
  • EUR - Euro
  • GBP - British Pound
  • JPY - Japanese Yen
  • CNY - Chinese Yuan

Americas

  • CAD - Canadian Dollar
  • MXN - Mexican Peso
  • BRL - Brazilian Real

Europe

  • CHF - Swiss Franc
  • SEK - Swedish Krona
  • NOK - Norwegian Krone
  • DKK - Danish Krone

Asia-Pacific

  • AUD - Australian Dollar
  • SGD - Singapore Dollar
  • HKD - Hong Kong Dollar
  • KRW - South Korean Won

# 📚 SDK Support

Official SDKs are available for:

Community SDKs:

Get Latest Prices →