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`

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

For a complete list of available commodity codes, see the List Commodities endpoint.

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"