銅・アルミニウム・亜鉛・原油の価格をAPIで取得する：開発者ガイド

産業用金属とエネルギーのシンボル

注目を集めるのは貴金属ですが、多くの企業にとってより重要なのは銅、アルミニウム、鋼、燃料です。これらは、ケーブルやモーター、缶や自動車の車体、建設用鋼材、そして物を運ぶすべてのトラックのコストを左右します。MetalAPIは、金や銀と並んで4種類の産業用金属と5種類のエネルギー契約の価格を、同じエンドポイント、同じレスポンス形式で提供しています。

シンボルページにはこれらがリアルタイム価格とともに掲載されており、GET /api/v1/symbols?details=1を呼び出すと、各シンボルのカテゴリと単位がJSONで返されます。この呼び出しは無料で、クォータにはカウントされません。

市場の取引単位とAPIの正規化

これらの市場にはそれぞれ独自の慣習があります。ニューヨークでは、銅は1ポンドあたり、アルミニウムと亜鉛は1メートルトンあたり、米国の鋼は1ショートトンあたり、原油は1バレルあたり、天然ガスは100万英国熱量単位（MMBtu）あたり、石油製品は1ガロンあたりで取引されます。これらを取り違えると、数値が1,000倍以上ずれてしまいます。

MetalAPIは金属の単位を正規化し、エネルギーは契約単位のまま提供します：

• 貴金属と産業用金属のすべての金属は、デフォルトでトロイオンスあたりの価格で提示されます。 これにより、すべての金属を直接比較でき、1つのパラメーターでどの金属でも換算できます。トロイオンスあたりの銅価格で取引する人はいないため、産業用金属ではほぼ常にunitを指定することになります。
• エネルギーは契約単位あたりの価格で提示されます。 WTIとBRENTはバレル、NATURALGASはMMBtu、GASOLINEとHEATINGOILは米ガロンです。unitパラメーターは、エネルギー、通貨、暗号資産には適用されません。

unitには、troy_oz（デフォルト）、gram、kilogram、ounce、pound、metric_ton、short_tonを指定できます。各金属をその市場で使われる単位で取得するには、次のようにします：

# 銅：1ポンドあたりUSD
curl "https://metalapi.com/api/v1/latest?currencies=XCU&unit=pound" \
  -H "Authorization: Bearer YOUR_API_KEY"

# アルミニウムと亜鉛：1メートルトンあたりUSD
curl "https://metalapi.com/api/v1/latest?currencies=ALU,ZNC&unit=metric_ton" \
  -H "Authorization: Bearer YOUR_API_KEY"

# 熱延コイル鋼：1ショートトンあたりUSD
curl "https://metalapi.com/api/v1/latest?currencies=HRC&unit=short_ton" \
  -H "Authorization: Bearer YOUR_API_KEY"

デフォルト以外の単位を使用すると、レスポンスのunitフィールドにそれが示されます。必要な価格は基準通貨を接頭辞に持つキー（USDXCU）で、接頭辞のないXCUキーはその逆数です。逆数のキーは旧来の連携との互換性のために残されています：

{
  "success": true,
  "timestamp": 1792834892,
  "date": "2026-10-24",
  "base": "USD",
  "unit": "pound",
  "rates": {
    "XCU": 0.2222222222,
    "USDXCU": 4.5
  }
}

先物ベースの価格と「期近」の意味

金のスポットは24時間店頭で取引されていますが、産業用金属とエネルギーの価格が最も透明性高く形成されるのは先物取引所です。MetalAPIは、これらの価格をCOMEXとNYMEX（いずれもCMEグループ傘下）およびICEから取得しています。先物契約とは、特定の限月に受け渡すことを前提に、決められた数量を決められた価格で売買する標準化された契約です。限月ごとに別々の契約があり、それぞれに価格が付きます。

期近とは、まだ取引されている中で最も近い受け渡し月のことです。期近の連続系列は、その契約が満期に近づくまで追跡し、その後は次の契約に切り替わります。これをロールと呼びます。開発者にとって重要な影響が3つあります：

• ロールによる段差。 ロール日には、市場が動いたからではなく、次の契約が異なる価格で取引されているために、系列が跳ねることがあります。期先の方が高い場合（コンタンゴ）は系列が上に、安い場合（バックワーデーション）は下に段差が生じます。満期前後の1日の変動でアラートを出す前に、この点を考慮してください。
• 1つの取引所が市場全体ではない。 COMEXの銅価格は米国の取引所の価格です。世界の銅、アルミニウム、亜鉛の現物の多くはロンドン金属取引所（LME）を基準に価格が決まり、現物の受け渡しには地域プレミアム、運賃、税金が加わります。取引所ごとの価格は互いに密接に連動しますが、完全には一致しません。供給契約でLMEの公式価格や公表されている価格評価など特定の参照価格が指定されている場合、請求書の基準になるのはその参照価格です。取引所の先物フィードは監視や見積もりに適したツールですが、契約上の指標の代わりにはなりません。
• 取引時間。 これらの契約は各取引所の取引時間に従います。ニューヨーク時間の日曜日夕方から金曜日午後までほぼ24時間取引され、毎日短い休止時間があります。週末の間、MetalAPIは最後の価格を返し続けます。

これらのシンボルは先物から取得しているため単一の価格で配信され、BidやAskのサフィックスは利用できません。金属とエネルギーの日次履歴は2000年までさかのぼり、過去データガイドでは終値、期間指定、OHLCバーの照会方法を紹介しています。

単位と通貨の換算

複数の金属を異なる単位で取得したい場合、最も安上がりなのは、トロイオンス単位で1回リクエストし、換算は自分のコードで行う方法です。データリクエストは返されるシンボルの数に関係なく1回としてカウントされるため、3リクエストではなく1リクエストで済みます。以下の定数は、各単位の定義から導かれます：

// 各質量単位に含まれるトロイオンス数
const GRAMS_PER_TROY_OZ = 31.1034768;
const TROY_OZ_PER = {
  lb: 453.59237 / GRAMS_PER_TROY_OZ,        // 14.5833…
  short_ton: 907184.74 / GRAMS_PER_TROY_OZ, // 29,166.67…
  metric_ton: 1e6 / GRAMS_PER_TROY_OZ,      // 32,150.75…
};

const NATURAL_UNIT = { XCU: "lb", ALU: "metric_ton", ZNC: "metric_ton", HRC: "short_ton" };

const url = new URL("https://metalapi.com/api/v1/latest");
url.searchParams.set("currencies", Object.keys(NATURAL_UNIT).join(","));

const res = await fetch(url, { headers: { "X-API-Key": process.env.METALAPI_KEY } });
const data = await res.json();
if (!data.success) throw new Error(data.error.code + ": " + data.error.info);

for (const [symbol, unit] of Object.entries(NATURAL_UNIT)) {
  const perTroyOz = data.rates["USD" + symbol]; // 1トロイオンスあたりUSD
  if (perTroyOz === undefined) continue;
  console.log(symbol, (perTroyOz * TROY_OZ_PER[unit]).toFixed(2), "USD per", unit);
}

通貨の扱いは、金属でもエネルギーでも同じです。base=EUR、またはサポートされている57通貨のいずれかを指定すると、レスポンス内のすべての価格が、同じスナップショットから換算されたその通貨建てで返されます。数量の価値を直接求めるには、数量と単位を受け取る/convertを使います：

# 銅25メートルトンのユーロ建て価格
curl "https://metalapi.com/api/v1/convert?from=XCU&to=EUR&amount=25&unit=metric_ton" \
  -H "Authorization: Bearer YOUR_API_KEY"

エネルギーの換算は自分のコードで行います。役立つ標準的な換算係数は次のとおりです。1バレルは42米ガロン、約158.987リットル、1米ガロンは3.785411784リットル、1 MMBtuは約1.055ギガジュール、293.07 kWh、10サームです。原油のバレルからトンへの換算は油の密度によって変わるため、実際に購入する油種の係数を使用してください。

活用例：調達とコスト監視

調達チームは、取引所の価格を使って原材料コストの動向を把握し、サプライヤーの見積もりの妥当性を確認しています。代表的な構成要素は次のとおりです：

• 日次ダッシュボード：銅、アルミニウム、鋼、ディーゼルを、契約で使われている単位と通貨で表示します。
• 期間ごとの変動：/changeを使えば、1回のリクエストで各シンボルの2つの日付間の開始価格、終了価格、変動額、変動率を取得できます。
• しきい値アラート：有料プランでは、価格が一定の水準を超えたときや一定の割合で動いたときに、ダッシュボードの価格アラートからメールが届きます。Advancedプラン以上では署名付きWebhookも送信されます。予算の前提を見直すきっかけとして手軽に使えます。
• 見積もりのチェック：サプライヤーの価格に含まれる金属分を取引所の参照価格と比較すると、価格変動のうちどれだけが金属によるもので、どれだけがプレミアムや加工によるものかがわかります。

# 1メートルトンあたりの銅とアルミニウム：2026年9月の変動
curl "https://metalapi.com/api/v1/change?currencies=XCU,ALU&unit=metric_ton&start_date=2026-09-01&end_date=2026-09-30" \
  -H "Authorization: Bearer YOUR_API_KEY"

先ほどの注意点を忘れないでください。契約が特定の公表価格に連動している場合、請求書に記載するものについては、その指標と照合してください。

活用例：製造原価モデル

部品表（BOM）には通常、金属の含有量がキログラム単位で記載されています。unitはすべての金属でkilogramを受け付けるため、1回のリクエストで、すべての金属のキログラムあたりの価格をレポート用の通貨で取得できます：

import os
import requests

# 製品1単位あたりの金属含有量（kg、例示）
BOM = {"XCU": 1.20, "ALU": 0.85, "ZNC": 0.05}

resp = requests.get(
    "https://metalapi.com/api/v1/latest",
    params={"currencies": ",".join(BOM), "unit": "kilogram", "base": "EUR"},
    headers={"X-API-Key": os.environ["METALAPI_KEY"]},
    timeout=10,
)
data = resp.json()
if not data.get("success"):
    raise RuntimeError(data["error"])

total = 0.0
for symbol, kg in BOM.items():
    eur_per_kg = data["rates"]["EUR" + symbol]
    cost = kg * eur_per_kg
    total += cost
    print(f"{symbol}: {kg} kg x {eur_per_kg:.4f} EUR/kg = {cost:.2f} EUR")

print(f"Metal content per unit: {total:.2f} EUR (prices of {data['date']})")

このようなモデルをより有用にする工夫が2つあります。1つ目は、各原価計算で使用した価格、単位、タイムスタンプを一緒に保存しておくことです。そうすれば、後から原価が変わった理由を説明できます。2つ目は、最新の価格1つではなく、一定期間の平均を使うことを検討することです。日々のノイズやロールによる段差を平滑化できます。/timeframeは、有料プランでは1リクエストあたり最大365日分（Freeでは30日分）の日次終値を返すため、月次や四半期の平均なら1回の呼び出しで十分です。

活用例：物流と燃料コスト

多くの運送会社にとって燃料は最大の変動費であり、燃料サーチャージは週次や月次で再計算されることがよくあります。HEATINGOILはNYハーバーの超低硫黄ディーゼル（ULSD）契約で、ディーゼルの卸売価格の指標として広く注目されています。GASOLINE（RBOB）はガソリンについて同じ役割を果たし、WTIとBRENTは原油をカバーします。

卸売の先物価格とスタンドの店頭価格は別物です。小売価格には流通コスト、利益、税金が加わり、先物価格に遅れて動きます。多くのサーチャージ表は公表されている小売価格の平均を参照しており、自社の表がそうであれば、使うべき数値はその平均です。それでも先物データは、社内のコスト追跡や、川上の動きを早めに把握するのに役立ちます。

次の例では、ディーゼル契約の先週の日次終値を平均し、その結果を1ガロンあたりUSDから1リットルあたりEURに換算します：

const LITRES_PER_GALLON = 3.785411784;

const url = new URL("https://metalapi.com/api/v1/timeframe");
url.searchParams.set("currencies", "HEATINGOIL");
url.searchParams.set("base", "EUR");
url.searchParams.set("start_date", "2026-10-19");
url.searchParams.set("end_date", "2026-10-23");

const res = await fetch(url, { headers: { "X-API-Key": process.env.METALAPI_KEY } });
const data = await res.json();
if (!data.success) throw new Error(data.error.code + ": " + data.error.info);

// ratesは日付がキー。終値のない日（週末、祝日）は含まれない
const closes = Object.values(data.rates).map((day) => day.EURHEATINGOIL);
const avgPerGallon = closes.reduce((sum, p) => sum + p, 0) / closes.length;

console.log("Average:", (avgPerGallon / LITRES_PER_GALLON).toFixed(4), "EUR per litre");

実践的なヒント

• ポーリングはプランの更新間隔に合わせ、それより頻繁にしない。 Freeは毎日、Liteは30分ごと、Standardは10分ごと、AdvancedとProは1分ごと、UltraとBusinessは15秒ごと、Enterpriseは5秒ごとに価格が更新されます。その間のリクエストは同じスナップショットを返しますが、カウントはされます。Pro以上では、ポーリングの代わりにリアルタイムストリームを使えます。
• シンボルをまとめてリクエストする。 1回のリクエストで産業用金属とエネルギーの9シンボルすべてを取得でき、コストは1シンボルのリクエストと同じです。
• 取得したデータを保存する。 各価格をシンボル、単位、基準通貨、timestampとともに保存してください。後から換算するのは簡単ですが、古い数値の単位を推測するのは困難です。
• 履歴には欠落があると想定する。 日次の系列には週末や取引所の休場日が含まれないため、暦日ごとに1件のエントリがあるとは想定しないでください。
• 長い期間は分割する。 1回の/timeframeリクエストでカバーできるのは有料プランで最大365日なので、2000年までさかのぼる長い履歴は1年ずつループで取得してください。
• 送信前に検証する。 無効な日付、シンボル、単位で拒否されたリクエストもクォータにカウントされるため、先にコードで確認してください。レート制限による拒否とサーバーエラーは課金されません。

まずは登録して無料のキーを取得し、シンボルページで産業用金属とエネルギーのリアルタイム価格を確認してください。すべてのエンドポイントとパラメーターはAPIドキュメントに記載されています。各プランの更新間隔とクォータは料金ページでご確認いただけます。