現物価格履歴API

週次燃料価格または月次商品価格の履歴を、期間、公表時の単位、改訂情報とともに取得します。

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

REST エンドポイント

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

契約リクエスト

curl --request GET \
  --url "https://api.narwhalapi.com/v1/commodities/physical/series/worldbank-cmo-copper/observations?start=2026-07-01&end=2026-10-01&limit=100" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

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

パラメータ

名前	必須	種別	意味
`series_id`	はい	パス · 文字列	fuel-eia-usa-regular-gasolineやworldbank-cmo-copperなど、系列検索で返される固定IDを使用してください。
`start`	いいえ	クエリ · YYYY-MM-DD	開始日を含みます。startとendは両方指定するか、両方省略してください。
`end`	いいえ	クエリ · YYYY-MM-DD	終了日は含まず、startより後の日付を指定します。指定した日付範囲と重なる観測値を返します。
`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_id": "worldbank-cmo-copper",
  "currency": "USD",
  "unit": "metric_ton",
  "unit_quantity": "1",
  "attribution": "The World Bank: World Bank Commodity Price Data (The Pink Sheet)",
  "observations": [
    {
      "period_start": "2026-07-01",
      "period_end": "2026-07-31",
      "price": "13543",
      "published_on": null,
      "revision": 1
    },
    {
      "period_start": "2026-08-01",
      "period_end": "2026-08-31",
      "price": "14326",
      "published_on": null,
      "revision": 1
    },
    {
      "period_start": "2026-09-01",
      "period_end": "2026-09-30",
      "price": "14474",
      "published_on": null,
      "revision": 1
    }
  ],
  "next_cursor": null
}

フィールド	種別	必須	意味
`series_id`	文字列	はい	系列検索で返される固定ID。
`currency`	文字列	はい	建値通貨。米国の燃料系列と月次指標価格系列は、どちらもUSDを使用します。
`unit / unit_quantity`	文字列	はい	公表時の単位と価格の対象数量。燃料にはus_gallonを使用します。月次指標価格にはmetric_ton、kilogram、barrel、cubic_meter、troy_ounce、mmbtu、dry_metric_ton_unit、sheetのいずれかを使用します。数量は1ですが、合板のみ100枚当たりのUSD建てです。値の換算は行いません。
`attribution`	文字列または null	はい	データとともにレスポンスの出典情報を保持してください。ソース：米国エネルギー情報局。ソース：The World Bank: World Bank Commodity Price Data (The Pink Sheet), CC BY 4.0
`observations`	配列	はい	古い順に並んだ観測値。各観測値にはperiod_start、period_end、小数文字列のprice、nullを許容するpublished_on、revisionが含まれます。
`observations[].period_start / observations[].period_end`	日付	はい	開始日と終了日を含む観測日。燃料では両方に月曜日の調査日を使用します。月次観測値は、2026-09-01から2026-09-30のように、その月全体を対象とします。
`observations[].price`	小数文字列	はい	unit_quantity単位当たりの、系列の通貨で公表された価格。系列の価格種別とbasisを併せて確認してください。
`observations[].published_on`	日付またはnull	はい	利用可能な場合の公表日。不明な場合はnullを保持します。
`observations[].revision`	整数	はい	1から始まり、後続の公表でその期間の値が変更されると増加します。
`next_cursor`	文字列または null	はい	内部構造の解釈を必要としない継続トークン。nullは最終ページを示します。

エラーとクォータ

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

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

カバレッジ

米国の燃料小売価格の週次系列20件を提供します。レギュラーガソリンと道路用2号ディーゼル燃料について、それぞれ全米平均と9地域を対象とします。価格は米ガロン当たりのUSD建てです。履歴は2026年7月20日から始まり、月曜日の調査後に毎週追加されます。ソース：米国エネルギー情報局。月次データには、ソフトコモディティ、油脂・油糧種子、金属、穀物、エネルギー、肥料、林産物、畜産物・乳製品にわたる世界銀行の70系列が含まれます。履歴は1960年まで遡りますが、一部の系列はそれ以降に始まります。利用可能な最新月は2026年9月ですが、系列によっては遅れや終了があります。大麦とソルガムは2020年8月、メキシコ産エビは2023年10月で終了しています。各系列のcoverage_endを確認してください。すべての価格はUSD建てで、公表時の単位を使用します。ソース：The World Bank: World Bank Commodity Price Data (The Pink Sheet), CC BY 4.0

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