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

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

Query Parameters

Parameter	Type	Description
`include_unavailable`	boolean	Also list codes that are not backed by data, each with `has_data: false` and a reason (optional)

There are no server-side category, search, or active filters — to narrow the results, filter the returned array client-side. See Filtering client-side below.

Field	Type	Description
`code`	string	Commodity code used in price requests (e.g. `WTI_USD`)
`name`	string	Human-readable name
`currency`	string	Quote currency (USD, EUR, GBP, ...)
`category`	string	Category slug (e.g. `crude_oil`, `natural_gas`)
`description`	string	Longer description of the instrument
`unit`	string	Unit of measure (e.g. `barrel`, `mmbtu`)
`unit_description`	string	Human-readable unit description
`multiplier`	number	Internal storage multiplier (deprecated for client use)
`validation`	object	Internal sanity bounds (deprecated for client use): `{ "min": number, "max": number }`
`price_change_threshold`	number	Internal anomaly-flag threshold (deprecated for client use)
`data_source`	string \| null	Underlying source, when set
`update_frequency`	string	Observation frequency of the series (e.g. `daily`, `weekly`, `weekday`, `realtime`, `monthly`). This is how often the source observes the market, not how often new values are published — superseded by `sources[]` and the publication schedules
`status`	string	Availability status for the code (e.g. `available`)
`has_data`	boolean	Whether the code is backed by data you can actually fetch
`sources`	array	Rolling out. Compact per-source cadence summary: `label`, `role`, `publication.cadence`, `collection.frequency`. Full publication/collection blocks live on `GET /v1/commodities/{code}`; human-readable schedules on the publication schedules page

update_frequency alone can mislead: a weekday series can still be published in weekly batches (EIA spot series are — typically Wednesdays, covering trading days through the prior Monday). Use the sources[] summary and the Data Publication & Collection Schedules page to see each source's publication cadence, typical lag, and how often we collect it.

Filtering client-side

The API returns the full catalog on every call. Filter data.commodities 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();
const commodities = data.commodities;

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

// Search by name or code (case-insensitive)
const query = "gas";
const matches = commodities.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.commodities.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" },
  });

  // The commodity array lives at data.commodities
  const { data } = await response.json();
  const commodities = data.commodities;

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

  // 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']['commodities']
    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.commodities
    .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

Cache commodity list - Commodity details rarely change, cache for 24 hours
Validate before requesting - Always check valid codes before making price requests
Filter client-side - The API returns the full list; filter data.commodities by category, name, or code in your own code
Build a code map - Key the array by code for fast lookups
Check publication cadence - Before alerting on "stale" data, check the code's publication schedule: batch-published series are days behind real time by design

GET /v1/prices/latest - Get current prices using these commodity codes
GET /v1/commodities/{code} - Full per-source publication/collection metadata for one commodity
Data Publication & Collection Schedules - When each source publishes and how often we collect
GET /v1/drilling-intelligence/summary - Drilling intelligence overview
GET /v1/marine-ports - Marine fuel port data