Physical price series details API

Read the definition, units and coverage of one weekly fuel or monthly benchmark series.

Endpoint and request

REST endpoint

GET /v1/commodities/physical/series/{series_id}

Contract request

curl --request GET \
  --url "https://api.narwhalapi.com/v1/commodities/physical/series/fuel-eia-usa-regular-gasoline" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

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

Parameters

Name	Required	Type	Meaning
`series_id`	Yes	path · string	Use a stable ID returned by discovery, such as fuel-eia-usa-regular-gasoline or worldbank-cmo-copper.

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_id": "fuel-eia-usa-regular-gasoline",
  "commodity": "gasoline",
  "category": "energy",
  "product": "regular-gasoline",
  "market": "USA",
  "area": null,
  "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).",
  "publisher": "U.S. Energy Information Administration",
  "attribution": "Source: U.S. Energy Information Administration",
  "coverage_start": "2026-07-20",
  "coverage_end": "2026-10-05"
}

Field	Type	Required	Meaning
`series_id`	string	Yes	Stable ID returned by series discovery.
`currency`	string	Yes	Quote currency. Both US fuel and monthly benchmark series use USD.
`unit / 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.
`attribution`	string or null	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
`commodity / category / 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.
`market / area`	string / string or null	Yes	Priced market and optional regional scope. WLD means a world benchmark, EUU means the European Union, and country markets use ISO alpha-3 codes. US fuel uses USA, with a null area for the national average.
`price_type / basis`	string / string or null	Yes	Fuel uses retail_average. Monthly series use international_benchmark, except tobacco, which uses import_unit_value. The basis describes the price definition when available.
`frequency`	string	Yes	weekly for US fuel and monthly for World Bank benchmarks.
`description / publisher`	strings	Yes	Series definition and publishing institution.
`coverage_start / 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.

Errors and quota

400 invalid_query, a code, area, date range, limit, or selector is invalid.
401 invalid_api_key, the Bearer key is missing or rejected.
404 physical_series_not_found, no complete approved data matches the request.
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. History starts on 20 July 2026 and grows each week after the Monday survey. Source: U.S. Energy Information Administration. 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. The latest available month is September 2026, 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.