現物価格系列API

米国の週次燃料小売価格、日次の原油・天然ガスのスポット価格、月次の商品指標価格を検索できます。

エンドポイントとリクエスト

REST エンドポイント

GET /v1/commodities/physical/series

契約リクエスト

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

MCPの使用 commodities_list_physical_seriesです。REST と MCP は、スキーマ、アカウントのクォータ、権限チェック、エラー形式を共有します。

パラメータ

名前	必須	種別	意味
`commodity`	いいえ	クエリ · 文字列	gasoline、diesel、copper、urea、rice、crude-oil、coffeeなどの商品で絞り込みます。系列検索で返されたcommodityの値を使用してください。
`category`	いいえ	クエリ · カテゴリー	対象カテゴリーはsofts、oils-oilseeds、metals、grains、energy、fertilizers、forestry、livestock-dairyです。燃料系列にはenergyを使用します。
`country`	いいえ	クエリ · 国コード	世界の指標価格にはWLD、欧州連合にはEUUを使用します。対象国コードはUSA、THA、JPN、AUS、ZAF、MYS、CMR、VNM、MEX、LKA、IND、KENです。米国の燃料にはUSAを使用します。
`price_type`	いいえ	クエリ · 価格種別	燃料はretail_averageを使用します。EIAの日次スポット系列とWorld Bankの系列はinternational_benchmarkを使用します。ただし、たばこはimport_unit_valueを使用します。
`currency`	いいえ	クエリ · 通貨コード	建値通貨で絞り込みます。現在、両方のソースでUSDを使用しています。
`limit`	いいえ	クエリ · 整数、1～500	1ページ当たりの最大件数。デフォルトは100です。
`cursor`	いいえ	クエリ · 文字列	前のページのnext_cursorを、同じフィルターとlimitで使用してください。nullは次のページがないことを示します。

ソース：米国エネルギー情報局。ソース：The World Bank: World Bank Commodity Price Data (The Pink Sheet), CC BY 4.0

レスポンス

契約例

{
  "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
}

フィールド	種別	必須	意味
`series`	配列	はい	commodity、product、country、area、価格基準basis、currency、unit、frequency、attribution、対象期間を含む系列。空の配列は、一致する系列がないことを示します。
`series[].series_id`	文字列	はい	系列検索で返される固定ID。
`series[].currency`	文字列	はい	建値通貨。米国の燃料系列と月次指標価格系列は、どちらもUSDを使用します。
`series[].unit / series[].unit_quantity`	文字列	はい	公表時の単位と価格の対象数量。燃料にはus_gallonを使用します。月次指標価格にはmetric_ton、kilogram、barrel、cubic_meter、troy_ounce、mmbtu、dry_metric_ton_unit、sheetのいずれかを使用します。数量は1ですが、合板のみ100枚当たりのUSD建てです。値の換算は行いません。
`series[].attribution`	文字列	はい	データとともにレスポンスの出典情報を保持してください。ソース：米国エネルギー情報局。ソース：The World Bank: World Bank Commodity Price Data (The Pink Sheet), CC BY 4.0
`series[].commodity / series[].category / series[].product`	文字列	はい	商品、カテゴリー、製品の定義。例：gasoline / energy / regular-gasoline、copper / metals / copper。系列検索で各系列の値を取得できます。
`series[].area`	文字列	いいえ	areaは地域範囲を示し、全国系列では省略されます。
`series[].country`	文字列	はい	WLDは世界の指標価格を表します。EUUは欧州連合を表します。国にはISO alpha-3コードを使用します。米国の燃料の全国平均にはUSAを使用します。
`series[].price_type`	文字列	はい	燃料はretail_averageを使用します。EIAの日次スポット系列と月次系列はinternational_benchmarkを使用します。ただし、たばこはimport_unit_valueを使用します。
`series[].basis`	文字列	いいえ	basisは価格の定義を示し、情報源に記載がない場合は省略されます。
`series[].frequency`	文字列	はい	EIAの石油・ガススポット価格は日次、米国の燃料は週次、World Bankの指標価格は月次です。
`series[].description`	文字列	はい	系列の定義。
`series[].coverage_start / series[].coverage_end`	日付	はい	最も古い観測値の初日と最新の観測値の末日で、両日を含みます。一部の系列は開始が遅い、または終了しています。この日付範囲は、欠損のない履歴を保証しません。
`next_cursor`	文字列または null	はい	内部構造の解釈を必要としない継続トークン。nullは最終ページを示します。

エラーとクォータ

400 invalid_query, コード、地域、日付範囲、limit、またはセレクターが無効です。
400 invalid_cursor, カーソルが無効か、リクエストのフィルターと一致しません。
401 invalid_api_key, Bearerキーが指定されていないか、拒否されました。
409 cursor_expired, 公開データが変更されました。カーソルを指定せずにページ取得をやり直してください。
429 rate_limit_exceeded または quota_exhausted, 共通の利用枠を使い切りました。
503 physical_reference_unavailable, 完全な公開データを利用できません。

拒否されたリクエストとサーバーエラーは月間クォータを消費しません。

カバレッジ

米国の週次小売燃料価格20系列。レギュラーガソリンと道路用No. 2ディーゼルを、それぞれ全米平均と9地域について提供します。単位は米ガロン当たりUSDです。全米平均の履歴は、ガソリンが1990年8月、ディーゼルが1994年3月からです。地域別系列の開始時期はそれより後です。毎週月曜日の調査後に履歴を追加します。出典：U.S.Energy Information Administration。EIAの日次スポット価格3系列は、クッシングのWTI原油、ブレント原油、ヘンリーハブ天然ガスを対象とし、単位はバレル当たりUSDまたは百万Btu当たりUSDです。月次データにはWorld Bankの70系列が含まれ、ソフトコモディティ、油脂・油糧種子、金属、穀物、エネルギー、肥料、林産物、畜産・乳製品を対象とします。履歴は1960年まで遡りますが、開始時期が遅い系列もあります。月次公表後に新しい月を追加しますが、系列によっては遅延や終了があります。大麦とソルガムは2020年8月、メキシコ産エビは2023年10月で終了しています。各系列のcoverage_endを確認してください。価格はすべてUSDで、公表された単位を使用します。出典：The World Bank: World Bank Commodity Price Data (The Pink Sheet)、CC BY 4.0

Narwhal APIキーで利用できます。