Get Commodity Details

Get detailed information about a specific commodity: catalog metadata, the latest price, and per-source publication/collection cadence.

Endpoint

GET /v1/commodities/{code}

Parameters

Parameter	Type	Required	Description
`code`	string	Yes	The commodity code (e.g., `WTI_USD`, `BRENT_CRUDE_USD`)

Headers

Header	Value	Required
`Authorization`	`Token YOUR_API_KEY`	Yes
`Content-Type`	`application/json`	Yes

Response

Success Response (200 OK)

{
  "status": "success",
  "data": {
    "code": "JET_FUEL_USD",
    "name": "Jet Fuel",
    "currency": "USD",
    "category": "refined_products",
    "description": "Kerosene-type jet fuel spot price",
    "unit": "gallon",
    "unit_description": "Price per gallon",
    "multiplier": 100,
    "validation": { "min": 1.5, "max": 8.0 },
    "price_change_threshold": 0.15,
    "update_frequency": "weekly",
    "status": "available",
    "has_data": true,
    "current_price": {
      "value": 3.37,
      "formatted": "$3.37",
      "currency": "USD",
      "last_updated": "2026-07-15T19:29:40.737Z"
    },
    "sources": [
      {
        "label": "Published market reporting",
        "role": "market_data",
        "publication": {
          "observation_frequency": "weekday",
          "cadence": "weekly_batch",
          "schedule": "Market-price observations are released in an EIA-hosted weekly batch, typically Wednesdays, covering trading days through the prior Monday.",
          "typical_lag_days": { "min": 2, "max": 8 },
          "revisions": "The source may revise previously published periods; revised values are updated in place."
        },
        "collection": {
          "frequency": "daily at 21:00 UTC",
          "backfills_missed_data": true,
          "captures_revisions": true,
          "ingestion_latency": "typically within 24 hours of source publication"
        }
      }
    ],
    "links": {
      "docs": "https://docs.oilpriceapi.com/api-reference/commodities/details",
      "publication_schedule": "https://docs.oilpriceapi.com/data/publication-schedules#jet_fuel_usd",
      "openapi": "https://api.oilpriceapi.com/.well-known/openapi.json",
      "latest": "https://api.oilpriceapi.com/v1/prices/latest?by_code=JET_FUEL_USD",
      "historical": "https://api.oilpriceapi.com/v1/prices/historical?by_code=JET_FUEL_USD"
    },
    "your_access": {
      "history_available_from": null,
      "note": "Your plan includes the full available price history for this commodity."
    }
  }
}

Response Fields

Field	Type	Description
`code`	string	Commodity code
`name`	string	Human-readable name
`currency`	string	Quote currency
`category`	string	Category slug (e.g. `refined_products`)
`description`	string	Description of the instrument
`unit` / `unit_description`	string	Unit of measure
`multiplier`, `validation`, `price_change_threshold`	—	Internal configuration (deprecated for client use)
`update_frequency`	string	Observation frequency of the series (e.g. `daily`, `weekly`, `weekday`, `realtime`). This is how often the source observes the market, not how often values are published — superseded by `sources[]` below
`status` / `has_data`	string / boolean	Availability of the code and whether it is backed by data
`current_price`	object \| null	Latest price: `value`, `formatted`, `currency`, `last_updated`
`sources`	array	Rolling out. Per-source cadence: what the publisher does (`publication`) and what OilPriceAPI does (`collection`) — see below
`links`	object	Rolling out. Absolute URLs for this commodity: `docs`, `publication_schedule` (with a per-code anchor), `openapi`, `latest`, `historical`
`your_access`	object	Rolling out. Historical depth included in your plan: `history_available_from` (ISO date, or `null` for the full archive) and a human-readable `note`
`instrument_disclosure`	object	Only on calendar-month average swap codes (`SINGAPORE_JET_KEROSENE_USD`, `SINGAPORE_MOGAS_92_USD`): states that `current_price` is a contract-month average, not a spot price. Same shape as on Latest Prices

Understanding `sources[]`: publication vs collection

Each entry in sources[] describes one source family feeding the commodity, in priority order:

publication — what the source does: observation_frequency (how often the market is observed), cadence (how often observations are released, e.g. weekly_batch vs continuous), a human-readable schedule, typical_lag_days (how far behind real time a release typically runs), and revisions.
collection — what OilPriceAPI does: sampling frequency, whether missed periods are backfilled, whether source revisions are captured, and typical ingestion_latency.

The two diverge for batch publishers: a weekday series published in weekly batches can be up to ~8 days behind real time just before a release and still be perfectly healthy. Before treating a series as stale, check its entry on the Data Publication & Collection Schedules page — links.publication_schedule deep-links straight to it. Sources that publish market price reporting appear with the generic label market_reporting; OilPriceAPI is not affiliated with, endorsed by, or a licensed distributor of any exchange or price-reporting agency.

Error Response (404 Not Found)

{
  "status": "fail",
  "error": {
    "code": "COMMODITY_NOT_FOUND",
    "message": "Commodity not found",
    "commodity_code": "INVALID_CODE"
  }
}

Code Examples

cURL

# Get WTI crude oil details
curl "https://api.oilpriceapi.com/v1/commodities/WTI_USD" \
  -H "Authorization: Token YOUR_API_KEY"

# Get Brent crude details
curl "https://api.oilpriceapi.com/v1/commodities/BRENT_CRUDE_USD" \
  -H "Authorization: Token YOUR_API_KEY"

# Get natural gas details
curl "https://api.oilpriceapi.com/v1/commodities/NATURAL_GAS_USD" \
  -H "Authorization: Token YOUR_API_KEY"

Python

import requests

api_key = "YOUR_API_KEY"
commodity_code = "JET_FUEL_USD"

response = requests.get(
    f"https://api.oilpriceapi.com/v1/commodities/{commodity_code}",
    headers={"Authorization": f"Token {api_key}"}
)

if response.status_code == 200:
    data = response.json()
    commodity = data['data']
    print(f"{commodity['name']}: {commodity['current_price']['formatted']}")
    # When is this series published? (sources[] is rolling out)
    for source in commodity.get('sources', []):
        print(f"  {source['label']}: {source['publication']['schedule']}")
else:
    print(f"Error: {response.status_code}")

JavaScript

const apiKey = "YOUR_API_KEY";
const commodityCode = "WTI_USD";

fetch(`https://api.oilpriceapi.com/v1/commodities/${commodityCode}`, {
  headers: {
    Authorization: `Token ${apiKey}`,
  },
})
  .then((response) => response.json())
  .then((data) => {
    if (data.status === "success") {
      const commodity = data.data;
      console.log(`${commodity.name}: ${commodity.current_price.formatted}`);
    }
  })
  .catch((error) => console.error("Error:", error));

Ruby

require 'net/http'
require 'json'

api_key = 'YOUR_API_KEY'
commodity_code = 'WTI_USD'

uri = URI("https://api.oilpriceapi.com/v1/commodities/#{commodity_code}")
request = Net::HTTP::Get.new(uri)
request['Authorization'] = "Token #{api_key}"

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

if response.code == '200'
  data = JSON.parse(response.body)
  commodity = data['data']
  puts "#{commodity['name']}: #{commodity['current_price']['formatted']}"
end

PHP

<?php
$apiKey = 'YOUR_API_KEY';
$commodityCode = 'WTI_USD';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.oilpriceapi.com/v1/commodities/{$commodityCode}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Token {$apiKey}"
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode === 200) {
    $data = json_decode($response, true);
    $commodity = $data['data'];
    echo "{$commodity['name']}: {$commodity['current_price']['formatted']}\n";
}
?>

Available Commodity Codes

The List Commodities endpoint returns the codes backed by data. Codes that are configured but not backed by data (never published, withheld, or discontinued) are omitted from that default listing even though some of them are still callable; pass ?include_unavailable=true to list every configured code with has_data and a reason.

A price request for a code that does not exist returns 400 invalid_code with near-miss suggestions and a described did_you_mean[] (code, name, description, available, and unavailable_reason when available is false) — see Latest Prices › Errors. A suggested code with available: false is callable; it is simply absent from the default listing.

Common Codes

Crude Oil: WTI_USD, BRENT_CRUDE_USD, DUBAI_CRUDE_USD
Natural Gas: NATURAL_GAS_USD, NATURAL_GAS_GBP, DUTCH_TTF_EUR
Refined Products: GASOLINE_RBOB_USD, ULSD_DIESEL_USD, HEATING_OIL_USD
Marine Fuels: MGO_05S_USD, VLSFO_USD, HFO_380_USD

Rate Limits

This endpoint counts against your monthly API request limit. Check the response headers for current usage:

X-RateLimit-Limit: Your monthly limit
X-RateLimit-Remaining: Requests remaining this month
X-RateLimit-Reset: When the limit resets (Unix timestamp)

Notes

Update cadence varies by source: see each commodity's sources[] block and its entry on the Data Publication & Collection Schedules page. Batch-published series (e.g. EIA weekly batches) can be several days behind real time by design
Historical data retention varies by commodity and by plan — see your_access in the response
Some commodities may have limited metadata depending on the source
Marine fuel prices include IMO 2020 compliance information

Commodity-Specific Examples

WTI USD

West Texas Intermediate - The primary US crude oil benchmark

curl "https://api.oilpriceapi.com/v1/commodities/WTI_USD" \
  -H "Authorization: Token YOUR_API_KEY"

# Get latest WTI price
curl "https://api.oilpriceapi.com/v1/prices/latest?by_code=WTI_USD" \
  -H "Authorization: Token YOUR_API_KEY"

BRENT CRUDE USD

Brent Crude - The global crude oil benchmark

curl "https://api.oilpriceapi.com/v1/commodities/BRENT_CRUDE_USD" \
  -H "Authorization: Token YOUR_API_KEY"

# Get latest Brent price
curl "https://api.oilpriceapi.com/v1/prices/latest?by_code=BRENT_CRUDE_USD" \
  -H "Authorization: Token YOUR_API_KEY"

NATURAL GAS USD

Henry Hub Natural Gas - US natural gas benchmark

curl "https://api.oilpriceapi.com/v1/commodities/NATURAL_GAS_USD" \
  -H "Authorization: Token YOUR_API_KEY"

# Get past week of natural gas prices
curl "https://api.oilpriceapi.com/v1/prices/past_week?by_code=NATURAL_GAS_USD" \
  -H "Authorization: Token YOUR_API_KEY"

GASOLINE RBOB USD

RBOB Gasoline - Reformulated Blendstock for Oxygenate Blending

curl "https://api.oilpriceapi.com/v1/commodities/GASOLINE_RBOB_USD" \
  -H "Authorization: Token YOUR_API_KEY"

# Compare with diesel
curl "https://api.oilpriceapi.com/v1/prices/latest?by_code=GASOLINE_RBOB_USD,ULSD_DIESEL_USD" \
  -H "Authorization: Token YOUR_API_KEY"

ULSD DIESEL USD

Ultra-Low Sulfur Diesel - Highway diesel fuel standard

curl "https://api.oilpriceapi.com/v1/commodities/ULSD_DIESEL_USD" \
  -H "Authorization: Token YOUR_API_KEY"

JET FUEL USD

Jet Fuel - Aviation turbine fuel

curl "https://api.oilpriceapi.com/v1/commodities/JET_FUEL_USD" \
  -H "Authorization: Token YOUR_API_KEY"

Publication: Market-price observations arrive through an EIA-hosted weekly batch, typically Wednesdays, covering trading days through the prior Monday — so the latest observation can be ~2–8 days behind real time and still be current. Schedule

HEATING OIL USD

Heating Oil - Residential and commercial heating fuel

curl "https://api.oilpriceapi.com/v1/commodities/HEATING_OIL_USD" \
  -H "Authorization: Token YOUR_API_KEY"

NATURAL GAS GBP

UK Natural Gas (NBP) - UK natural gas benchmark (priced in pence/therm)

curl "https://api.oilpriceapi.com/v1/commodities/NATURAL_GAS_GBP" \
  -H "Authorization: Token YOUR_API_KEY"

DUTCH TTF EUR

Dutch TTF Natural Gas - European natural gas benchmark

curl "https://api.oilpriceapi.com/v1/commodities/DUTCH_TTF_EUR" \
  -H "Authorization: Token YOUR_API_KEY"

COAL USD

Newcastle Coal (Legacy) - Thermal coal benchmark price. Note: For comprehensive coal coverage, see the 8 dedicated coal endpoints below.

curl "https://api.oilpriceapi.com/v1/commodities/COAL_USD" \
  -H "Authorization: Token YOUR_API_KEY"

CAPP COAL USD

Central Appalachian Coal - US thermal coal spot price from Central Appalachian region

curl "https://api.oilpriceapi.com/v1/commodities/CAPP_COAL_USD" \
  -H "Authorization: Token YOUR_API_KEY"

# Get latest price
curl "https://api.oilpriceapi.com/v1/prices/latest?by_code=CAPP_COAL_USD" \
  -H "Authorization: Token YOUR_API_KEY"

# Get past month of data
curl "https://api.oilpriceapi.com/v1/prices/past_month?by_code=CAPP_COAL_USD" \
  -H "Authorization: Token YOUR_API_KEY"

Publication: Published by EIA weekly, covering the prior week's coal spot assessments. Collected weekly (Tuesdays 02:00 UTC). ScheduleUnit: USD per short ton

PRB COAL USD

Powder River Basin Coal - US thermal coal spot price from Wyoming's PRB region

curl "https://api.oilpriceapi.com/v1/commodities/PRB_COAL_USD" \
  -H "Authorization: Token YOUR_API_KEY"

# Get latest price
curl "https://api.oilpriceapi.com/v1/prices/latest?by_code=PRB_COAL_USD" \
  -H "Authorization: Token YOUR_API_KEY"

Publication: Published by EIA weekly, covering the prior week's coal spot assessments. Collected weekly (Tuesdays 02:00 UTC). ScheduleUnit: USD per short ton

ILLINOIS COAL USD

Illinois Basin Coal - US thermal coal spot price from Illinois Basin region

curl "https://api.oilpriceapi.com/v1/commodities/ILLINOIS_COAL_USD" \
  -H "Authorization: Token YOUR_API_KEY"

# Get latest price
curl "https://api.oilpriceapi.com/v1/prices/latest?by_code=ILLINOIS_COAL_USD" \
  -H "Authorization: Token YOUR_API_KEY"

Publication: Published by EIA weekly, covering the prior week's coal spot assessments. Collected weekly (Tuesdays 02:00 UTC). ScheduleUnit: USD per short ton

NEWCASTLE COAL USD

Newcastle Coal (API6) - Asian thermal coal benchmark (CIF ARA)

curl "https://api.oilpriceapi.com/v1/commodities/NEWCASTLE_COAL_USD" \
  -H "Authorization: Token YOUR_API_KEY"

# Get latest price
curl "https://api.oilpriceapi.com/v1/prices/latest?by_code=NEWCASTLE_COAL_USD" \
  -H "Authorization: Token YOUR_API_KEY"

# Get today's samples
curl "https://api.oilpriceapi.com/v1/prices/past_day?by_code=NEWCASTLE_COAL_USD" \
  -H "Authorization: Token YOUR_API_KEY"

Publication: Prices are published by market sources throughout the trading day; sampled multiple times per hour on trading days. ScheduleUnit: USD per metric ton

COKING COAL USD

Coking Coal - Metallurgical coal for steel production

curl "https://api.oilpriceapi.com/v1/commodities/COKING_COAL_USD" \
  -H "Authorization: Token YOUR_API_KEY"

# Get latest price
curl "https://api.oilpriceapi.com/v1/prices/latest?by_code=COKING_COAL_USD" \
  -H "Authorization: Token YOUR_API_KEY"

# Compare with thermal coal
curl "https://api.oilpriceapi.com/v1/prices/latest?by_code=COKING_COAL_USD,NEWCASTLE_COAL_USD" \
  -H "Authorization: Token YOUR_API_KEY"

Publication: Prices are published by market sources throughout the trading day; sampled multiple times per hour on trading days. ScheduleUnit: USD per metric ton

CME COAL USD

CME Coal Futures - CME Group coal futures contract

curl "https://api.oilpriceapi.com/v1/commodities/CME_COAL_USD" \
  -H "Authorization: Token YOUR_API_KEY"

# Get latest price
curl "https://api.oilpriceapi.com/v1/prices/latest?by_code=CME_COAL_USD" \
  -H "Authorization: Token YOUR_API_KEY"

Publication: See this code's entry on the publication schedules pageUnit: USD per short ton

NYMEX APPALACHIAN USD

NYMEX Central Appalachian Coal - Historical NYMEX contract (discontinued 2016)

curl "https://api.oilpriceapi.com/v1/commodities/NYMEX_APPALACHIAN_USD" \
  -H "Authorization: Token YOUR_API_KEY"

# Get historical data (2004-2016)
curl "https://api.oilpriceapi.com/v1/prices/past_year?by_code=NYMEX_APPALACHIAN_USD" \
  -H "Authorization: Token YOUR_API_KEY"

Data Available: 2004-2016 (3,262 records) Status: Contract discontinued/delisted Unit: USD per short ton

NYMEX WESTERN RAIL USD

NYMEX Powder River Basin Coal - Historical NYMEX contract (discontinued 2017)

curl "https://api.oilpriceapi.com/v1/commodities/NYMEX_WESTERN_RAIL_USD" \
  -H "Authorization: Token YOUR_API_KEY"

# Get historical data (2009-2017)
curl "https://api.oilpriceapi.com/v1/prices/past_year?by_code=NYMEX_WESTERN_RAIL_USD" \
  -H "Authorization: Token YOUR_API_KEY"

Data Available: 2009-2017 (2,043 records) Status: Contract discontinued/delisted Unit: USD per short ton

EU CARBON EUR

EU Carbon Allowances - EU Emissions Trading System

curl "https://api.oilpriceapi.com/v1/commodities/EU_CARBON_EUR" \
  -H "Authorization: Token YOUR_API_KEY"

URANIUM USD

Uranium U3O8 - Nuclear fuel commodity

curl "https://api.oilpriceapi.com/v1/commodities/URANIUM_USD" \
  -H "Authorization: Token YOUR_API_KEY"

ETHANOL USD

Ethanol - Biofuel additive

curl "https://api.oilpriceapi.com/v1/commodities/ETHANOL_USD" \
  -H "Authorization: Token YOUR_API_KEY"

DUBAI CRUDE USD

Dubai Crude - Middle East crude oil benchmark

curl "https://api.oilpriceapi.com/v1/commodities/DUBAI_CRUDE_USD" \
  -H "Authorization: Token YOUR_API_KEY"

URALS CRUDE USD

Urals Crude - Russian crude oil benchmark

curl "https://api.oilpriceapi.com/v1/commodities/URALS_CRUDE_USD" \
  -H "Authorization: Token YOUR_API_KEY"

WCS CRUDE USD

Western Canadian Select - Canadian heavy crude oil

curl "https://api.oilpriceapi.com/v1/commodities/WCS_CRUDE_USD" \
  -H "Authorization: Token YOUR_API_KEY"

JKM LNG USD

Japan Korea Marker - Asian LNG benchmark

curl "https://api.oilpriceapi.com/v1/commodities/JKM_LNG_USD" \
  -H "Authorization: Token YOUR_API_KEY"