OilPriceAPI Documentation

# List Commodities

Get a comprehensive list of all available commodities with their details, categories, and trading information.

GET /v1/commodities

# Request

# Headers

Header Required Description
Authorization Yes Token YOUR_API_KEY
Accept No application/json (default)

# Query Parameters

Parameter Type Required Description Example
category string No Filter by commodity category oil, natural_gas, drilling_intelligence
active boolean No Only show actively traded commodities true, false
search string No Search commodities by name or code brent, gold

# Response

# Success Response (200 OK)

# Code Examples

# Access Tiers & Pricing

All standard commodities available on Hobby, Starter, Professional, Business, and Enterprise plans.

Categories included:

  • Oil Products (9 codes)
  • Natural Gas (3 codes)
  • Marine Fuels (4 codes)
  • Forex (2 codes)
  • Other Commodities (5 codes)

# Reservoir Mastery ($129/month) - 13 additional commodities

Premium upstream intelligence data exclusively for Reservoir Mastery subscribers.

Additional categories:

  • Drilling Intelligence (12 codes)
  • Natural Gas Intelligence (1 code)

# Commodity Categories

Category Description Count Access Tier Example Commodities
oil Crude oil benchmarks and refined products 9 Paid BRENT_CRUDE_USD, WTI_USD, GASOLINE_RBOB_USD
natural_gas Natural gas benchmarks 3 Paid NATURAL_GAS_USD, NATURAL_GAS_GBP, DUTCH_TTF_EUR
drilling_intelligence Upstream activity data 12 Reservoir Mastery US_RIG_COUNT, PERMIAN_FRAC_SPREADS
natural_gas_intelligence Gas storage data 1 Reservoir Mastery NATURAL_GAS_STORAGE
marine_fuels Bunker fuel prices 4 Paid VLSFO_USD, MGO_05S_USD
forex Currency exchange rates 2 Paid GBP_USD, EUR_USD
other Coal, metals, carbon, etc. 5 Paid COAL_USD, GOLD_USD, ETHANOL_USD

# Use Cases

# 1. Dynamic Price Dashboard

// Build a customizable dashboard
async function initializeDashboard() {
  // Get available commodities based on user's plan
  const response = await fetch('/v1/commodities', {
    headers: { 'Authorization': 'Token YOUR_API_KEY' }
  });
  
  const { data } = await response.json();
  
  // Filter by access tier if needed
  const accessibleCommodities = data.commodities.filter(c => 
    c.access_tier !== 'reservoir_mastery' || userHasReservoirMastery
  );
  
  // Let user select commodities to track
  const selectedCodes = await showCommodityPicker(accessibleCommodities);
  
  // Start fetching prices for selected commodities
  startPriceUpdates(selectedCodes);
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

# 2. Validate User Input

def validate_commodity_request(requested_codes, user_plan):
    """Validate commodity codes and access permissions"""
    
    # Get valid commodities
    response = requests.get(
        'https://api.oilpriceapi.com/v1/commodities',
        headers={'Authorization': 'Token YOUR_API_KEY'}
    )
    
    commodities = response.json()['data']['commodities']
    commodity_map = {c['code']: c for c in commodities}
    
    # Check requested codes
    invalid_codes = []
    access_denied = []
    
    for code in requested_codes:
        if code not in commodity_map:
            invalid_codes.append(code)
        elif (commodity_map[code].get('access_tier') == 'reservoir_mastery' 
              and user_plan != 'reservoir_mastery'):
            access_denied.append(code)
    
    if invalid_codes:
        raise ValueError(f"Invalid commodity codes: {', '.join(invalid_codes)}")
    
    if access_denied:
        raise PermissionError(f"Reservoir Mastery required for: {', '.join(access_denied)}")
    
    return True
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

# 3. Category-Based Analysis

// Analyze commodities by category
async function analyzeByCateory(category) {
  const response = await fetch(
    `https://api.oilpriceapi.com/v1/commodities?category=${category}`,
    { headers: { 'Authorization': 'Token YOUR_API_KEY' } }
  );
  
  const { data } = await response.json();
  const commodityCodes = data.commodities.map(c => c.code);
  
  // Fetch prices for all commodities in category
  const prices = await Promise.all(
    commodityCodes.map(async (code) => {
      const priceResponse = await fetch(
        `/v1/prices/latest?by_code=${code}`,
        { headers: { 'Authorization': 'Token YOUR_API_KEY' } }
      );
      return priceResponse.json();
    })
  );
  
  // Calculate category statistics
  return calculateCategoryStats(prices);
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

# Best Practices

  1. Cache commodity list - Commodity details rarely change, cache for 24 hours
  2. Validate before requesting - Always check valid codes before making price requests
  3. Use categories - Organize commodities logically for users
  4. Implement search - Help users find commodities quickly
  5. Show access tiers - Clearly indicate which features require upgrades
  6. Handle permissions - Gracefully handle premium feature access denials

← Get Commodity Details →