Physical price series API

Discover weekly US retail fuel prices, daily oil and gas spot prices, and monthly commodity benchmarks.

Endpoint and request

REST endpoint

GET /v1/commodities/physical/series

Contract request

curl --request GET \
  --url "https://api.narwhalapi.com/v1/commodities/physical/series?commodity=gasoline" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

MCP uses commodities_list_physical_series. REST and MCP share the same schema, account quota, rights check, and problem shape.

Parameters

Name	Required	Type	Meaning
`commodity`	No	query · string	Filter by commodity, such as gasoline, diesel, copper, urea, rice, crude-oil or coffee. Use the commodity value returned by discovery.
`category`	No	query · category	Covered categories are softs, oils-oilseeds, metals, grains, energy, fertilizers, forestry and livestock-dairy. Fuel series use energy.
`country`	No	query · country code	Use WLD for world benchmarks or EUU for the European Union. Covered country codes are USA, THA, JPN, AUS, ZAF, MYS, CMR, VNM, MEX, LKA, IND and KEN. US fuel uses USA.
`price_type`	No	query · price type	Fuel uses retail_average. Daily EIA spot and World Bank series use international_benchmark, except tobacco, which uses import_unit_value.
`currency`	No	query · currency code	Filter by quote currency. Both sources currently use USD.
`limit`	No	query · integer, 1–500	Maximum items per page. Defaults to 100.
`cursor`	No	query · string	Use next_cursor from the previous page with the same filters and limit. Null means there are no more pages.

Source: U.S. Energy Information Administration. Source: The World Bank: World Bank Commodity Price Data (The Pink Sheet), CC BY 4.0

Response

Contract example

{
  "series": [
    {
      "series_id": "fuel-eia-usa-regular-gasoline",
      "commodity": "gasoline",
      "category": "energy",
      "product": "regular-gasoline",
      "country": "USA",
      "price_type": "retail_average",
      "basis": "cash self-serve pump price incl. all taxes, 8:00 a.m. Monday",
      "currency": "USD",
      "unit": "us_gallon",
      "unit_quantity": "1",
      "frequency": "weekly",
      "description": "United States: regular gasoline (all formulations), weekly average retail price in dollars per gallon from EIA's Monday survey (series EMM_EPMR_PTE_NUS_DPG.W).",
      "attribution": "Source: U.S. Energy Information Administration",
      "coverage_start": "1990-08-20",
      "coverage_end": "2026-10-19"
    }
  ],
  "next_cursor": null
}

Field	Type	Required	Meaning
`series`	array	Yes	Series with commodity, product, country, area, price basis, currency, unit, frequency, attribution and coverage dates. An empty array means no series matches.
`series[].series_id`	string	Yes	Stable ID returned by series discovery.
`series[].currency`	string	Yes	Quote currency. Both US fuel and monthly benchmark series use USD.
`series[].unit / series[].unit_quantity`	strings	Yes	Published unit and the quantity priced. Fuel uses us_gallon. Monthly benchmarks use metric_ton, kilogram, barrel, cubic_meter, troy_ounce, mmbtu, dry_metric_ton_unit or sheet. The quantity is 1 except for plywood, which uses USD per 100 sheets. Values are not converted.
`series[].attribution`	string	Yes	Keep the response attribution with the data. Source: U.S. Energy Information Administration. Source: The World Bank: World Bank Commodity Price Data (The Pink Sheet), CC BY 4.0
`series[].commodity / series[].category / series[].product`	strings	Yes	Commodity, category and product definition. Examples include gasoline / energy / regular-gasoline and copper / metals / copper. Discovery returns the values for each series.
`series[].area`	string	No	area gives the regional scope and is omitted for national series.
`series[].country`	string	Yes	WLD means a world benchmark. EUU means the European Union. Countries use ISO alpha-3 codes. US fuel uses USA for the national average.
`series[].price_type`	string	Yes	Fuel uses retail_average. Daily EIA spot and monthly series use international_benchmark, except tobacco, which uses import_unit_value.
`series[].basis`	string	No	The basis describes the price definition and is omitted when the source gives none.
`series[].frequency`	string	Yes	daily for EIA oil and gas spot prices, weekly for US fuel and monthly for World Bank benchmarks.
`series[].description`	string	Yes	Series definition.
`series[].coverage_start / series[].coverage_end`	dates	Yes	First day of the earliest observation and last day of the latest, both inclusive. Some series start later or have ended. Date bounds do not guarantee uninterrupted history.
`next_cursor`	string or null	Yes	Opaque continuation token. Null marks the final page.

Errors and quota

400 invalid_query, a code, area, date range, limit, or selector is invalid.
400 invalid_cursor, the cursor is invalid or does not match the request filters.
401 invalid_api_key, the Bearer key is missing or rejected.
409 cursor_expired, the publication changed. Restart pagination without a cursor.
429 rate_limit_exceeded or quota_exhausted, the shared allowance is exhausted.
503 physical_reference_unavailable, a complete publication is unavailable.

Rejected requests and server errors do not consume monthly quota.

Coverage

20 weekly US retail fuel series: regular gasoline and No. 2 on-highway diesel, each for the US average and nine regions. Prices use 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 EIA spot series cover WTI crude oil at Cushing, Brent crude oil and Henry Hub natural gas, in USD per barrel or per million Btu. Monthly coverage includes 70 World Bank series across softs, oils and oilseeds, metals, grains, energy, fertilizers, forestry, and livestock and dairy. History reaches back to 1960, with later starts for some series. A new month is added after each monthly publication, but individual series can lag or have ended. Barley and sorghum end in August 2020; Mexican shrimp ends in October 2023. Check coverage_end for each series. All prices use USD and units as published. Source: The World Bank: World Bank Commodity Price Data (The Pink Sheet), CC BY 4.0

Available with a Narwhal API key.