List Commodities

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

GET/v1/commodities

Request

Headers

HeaderRequiredDescription
AuthorizationYesToken YOUR_API_KEY
AcceptNoapplication/json (default)

Query Parameters

ParameterTypeRequiredDescriptionExample
categorystringNoFilter by commodity categoryoil, natural_gas, drilling_intelligence
activebooleanNoOnly show actively traded commoditiestrue, false
searchstringNoSearch commodities by name or codebrent, 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

CategoryDescriptionCountAccess TierExample Commodities
oilCrude oil benchmarks and refined products9PaidBRENT_CRUDE_USD, WTI_USD, GASOLINE_RBOB_USD
natural_gasNatural gas benchmarks3PaidNATURAL_GAS_USD, NATURAL_GAS_GBP, DUTCH_TTF_EUR
drilling_intelligenceUpstream activity data12Reservoir MasteryUS_RIG_COUNT, PERMIAN_FRAC_SPREADS
natural_gas_intelligenceGas storage data1Reservoir MasteryNATURAL_GAS_STORAGE
marine_fuelsBunker fuel prices4PaidVLSFO_USD, MGO_05S_USD
forexCurrency exchange rates2PaidGBP_USD, EUR_USD
otherCoal, metals, carbon, etc.5PaidCOAL_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);
}

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

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);
}

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