Docs
Commodities API reference
Physical commodity prices, series discovery and history. Includes weekly US retail fuel prices and monthly World Bank benchmarks.
Base URL
This page covers physical palm oil, US fuel prices and monthly commodity benchmarks. Spot prices for all four metals have their own spot metals reference. Futures references remain unavailable until their product is released.
https://api.narwhalapi.com/v1/commodities- Every request uses the same Narwhal Bearer key and shared account quota.
- REST and MCP use the same input and output schemas.
Physical price operations
| Operation | REST path | MCP tool |
|---|---|---|
| Discover Palmoil physical series | /v1/commodities/palmoil/physical | commodities_list_palmoil_physical_series |
| Get latest Palmoil physical price | /v1/commodities/palmoil/physical/{series_id} | commodities_get_palmoil_physical_price |
| Get Palmoil physical history | /v1/commodities/palmoil/physical/{series_id}/observations | commodities_get_palmoil_physical_observations |
| Discover physical price series | /v1/commodities/physical/series | commodities_list_physical_series |
| Get physical price series details | /v1/commodities/physical/series/{series_id} | commodities_get_physical_series |
| Get the latest physical price | /v1/commodities/physical/series/{series_id}/latest | commodities_get_physical_latest |
| Get physical price history | /v1/commodities/physical/series/{series_id}/observations | commodities_get_physical_observations |
Shared behavior
- Physical-series discovery returns only complete, rights-approved series.
- CPO and Malaysian FFB return one scalar price. Indonesian FFB returns the complete tree-age schedule.
- Prices remain decimal strings in their native currency and unit.
- History is oldest-first and uses opaque filter-bound cursors.
- Missing, overlapping, ambiguous, or mixed-rights schedules fail closed.
- Rejected or unavailable requests do not consume monthly quota.
Coverage
Commodity prices today · Historical gas prices · Diesel price history
US fuel coverage includes 20 weekly series for regular gasoline and No. 2 on-highway diesel. Each product covers the US average and nine regions, in USD per US gallon. US average history starts in August 1990 for gasoline and March 1994 for diesel. Regional series start later. History grows each week after the Monday survey. Source: U.S. Energy Information Administration
Three daily spot series are available: WTI crude oil at Cushing from 2 January 1986 and Brent crude oil from 20 May 1987, both in USD per barrel; and Henry Hub natural gas from 7 January 1997, in USD per MMBtu. Source: U.S. Energy Information Administration
Explore the US fuel prices API
Monthly benchmarks cover 70 series across softs, oils and oilseeds, metals, grains, energy, fertilizers, forestry, and livestock and dairy. History reaches back to 1960. Some series start later or have ended. Prices use USD and units as published. Source: The World Bank: World Bank Commodity Price Data (The Pink Sheet), CC BY 4.0
Explore the historical commodity prices API
The release covers Indonesian CPO government reference prices, Indonesian FFB purchase schedules, Malaysian CPO local-delivered market averages and Malaysian FFB regional references. These are separate series with different meanings and native units.
History starts at different dates and contains documented source gaps. FCPO futures are not included. Read Commodities coverage and the methodology for the exact limits.
Available with a Narwhal API key.