List Commodities

Status: ✅ Available | 📋 Catalog

Get the full list of commodity codes available to your account with their details. Catalog availability can vary by dataset and plan.

GET/v1/commodities

Request

Headers

HeaderRequiredDescription
AuthorizationYesToken YOUR_API_KEY
AcceptNoapplication/json (default)

Query Parameters

This endpoint takes no query parameters — it always returns the complete list. To narrow the results (by category, name, or code), filter the returned array client-side. See Filtering client-side below.

Response

Success Response (200 OK)

data is a flat array of commodity objects (not nested under commodities, and there is no categories or meta block).

{
  "status": "success",
  "data": [
    {
      "code": "WTI_USD",
      "name": "West Texas Intermediate",
      "currency": "USD",
      "category": "crude_oil",
      "description": "West Texas Intermediate crude oil spot price",
      "unit": "barrel",
      "unit_description": "Price per barrel",
      "multiplier": 1,
      "validation": { "min": 0, "max": 500 },
      "price_change_threshold": 5.0,
      "data_source": null,
      "update_frequency": "5min"
    },
    {
      "code": "BRENT_CRUDE_USD",
      "name": "Brent Crude Oil",
      "currency": "USD",
      "category": "crude_oil",
      "description": "North Sea Brent crude oil spot price",
      "unit": "barrel",
      "unit_description": "Price per barrel",
      "multiplier": 1,
      "validation": { "min": 0, "max": 500 },
      "price_change_threshold": 5.0,
      "data_source": null,
      "update_frequency": "5min"
    },
    {
      "code": "NATURAL_GAS_USD",
      "name": "Henry Hub Natural Gas",
      "currency": "USD",
      "category": "natural_gas",
      "description": "Henry Hub natural gas spot price",
      "unit": "mmbtu",
      "unit_description": "Price per MMBtu",
      "multiplier": 1,
      "validation": { "min": 0, "max": 100 },
      "price_change_threshold": 5.0,
      "data_source": null,
      "update_frequency": "5min"
    }
  ]
}

Response Fields

Each item in the data array has the following fields:

FieldTypeDescription
codestringCommodity code used in price requests (e.g. WTI_USD)
namestringHuman-readable name
currencystringQuote currency (USD, EUR, GBP, ...)
categorystringCategory slug (e.g. crude_oil, natural_gas)
descriptionstringLonger description of the instrument
unitstringUnit of measure (e.g. barrel, mmbtu)
unit_descriptionstringHuman-readable unit description
multipliernumberPrice multiplier applied to raw values
validationobjectSanity bounds for prices: { "min": number, "max": number }
price_change_thresholdnumberPercent move that flags an anomalous update
data_sourcestring | nullUnderlying source, when set
update_frequencystringHow often the code is refreshed (e.g. 5min)

Filtering client-side

The API returns the full catalog on every call. There are no server-side category, search, or active filters — filter the returned array in your own code:

const res = await fetch("https://api.oilpriceapi.com/v1/commodities", {
  headers: { Authorization: "Token YOUR_API_KEY" },
});
const { data } = await res.json();

// Filter by category
const crudeOil = data.filter((c) => c.category === "crude_oil");

// Search by name or code (case-insensitive)
const query = "gas";
const matches = data.filter(
  (c) =>
    c.name.toLowerCase().includes(query) ||
    c.code.toLowerCase().includes(query),
);

Code Examples

Commodity Categories

Every item carries a category slug you can group or filter on. The catalog spans crude oil benchmarks, refined products, natural gas and LNG, coal, marine fuels, forex, metals, carbon, and upstream drilling intelligence. Common slugs include crude_oil and natural_gas. Because the API returns the full list, the simplest way to see the categories currently in use is to collect the distinct category values from the response:

const categories = [...new Set(data.map((c) => c.category))].sort();

Use Cases

1. Dynamic Price Dashboard

// Build a customizable dashboard
async function initializeDashboard() {
  const response = await fetch("https://api.oilpriceapi.com/v1/commodities", {
    headers: { Authorization: "Token YOUR_API_KEY" },
  });

  // `data` is a flat array of commodity objects
  const { data } = await response.json();

  // Let user select commodities to track
  const selectedCodes = await showCommodityPicker(data);

  // Start fetching prices for selected commodities
  startPriceUpdates(selectedCodes);
}

2. Validate User Input

def validate_commodity_request(requested_codes):
    """Validate commodity codes against the catalog."""

    response = requests.get(
        'https://api.oilpriceapi.com/v1/commodities',
        headers={'Authorization': 'Token YOUR_API_KEY'}
    )

    commodities = response.json()['data']  # flat list
    valid_codes = {c['code'] for c in commodities}

    invalid_codes = [code for code in requested_codes if code not in valid_codes]
    if invalid_codes:
        raise ValueError(f"Invalid commodity codes: {', '.join(invalid_codes)}")

    return True

3. Category-Based Analysis

// Analyze commodities by category (filter the full list client-side)
async function analyzeByCategory(category) {
  const response = await fetch("https://api.oilpriceapi.com/v1/commodities", {
    headers: { Authorization: "Token YOUR_API_KEY" },
  });

  const { data } = await response.json();
  const commodityCodes = data
    .filter((c) => c.category === category)
    .map((c) => c.code);

  // Fetch prices for all commodities in category
  const prices = await Promise.all(
    commodityCodes.map(async (code) => {
      const priceResponse = await fetch(
        `https://api.oilpriceapi.com/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. Filter client-side - The API returns the full list; filter by category, name, or code in your own code
  4. Build a code map - Key the array by code for fast lookups
Last Updated: