金価格API：開発者のための完全ガイド

金価格APIで得られるもの

金価格APIは、金の現在価格と過去価格を構造化データとして返します。通常はHTTPS経由のJSONで提供されるため、ウェブページをスクレイピングしたり数値を手作業でコピーしたりしなくても、ソフトウェアから直接利用できます。MetalAPIでは、金のシンボルはXAUで、金1トロイオンスを表すISO 4217コードです。リアルタイム価格はスポット価格、つまりインターバンクのBidとAskの気配値の仲値です。

ほとんどの連携はトレーディングシステムではありません。代表的な用途は次のとおりです：

• 市場の動きに合わせて金製品の価格を改定するオンラインショップや宝石店。
• スクラップ金、カラット別のジュエリー、地金のプレミアムの計算ツール。
• 保有資産を現地通貨で評価するポートフォリオ管理ツールや家計管理アプリ。
• 在庫を日次の終値で再評価する会計システムやERPシステム。
• 過去1年分のチャートが必要なダッシュボード、ニュースレター、社内レポート。

同じAPIで、銀（XAG）、プラチナ（XPT）、パラジウム（XPD）、4種類の産業用金属、5種類のエネルギー契約、57通貨、13の暗号資産も扱えます。合計83シンボルで、すべてシンボルページに掲載されています。このガイドでは金を中心に説明しますが、内容はすべて他のシンボルにも当てはまります。

APIキーを取得する

無料アカウントを作成します。Freeプランはクレジットカード不要で、月100リクエストと毎日の価格更新が含まれており、連携の構築とテストには十分です。有料プランでは、より新しい価格、より多くのリクエスト、追加のエンドポイントを利用できます。後述のプラン表に概要をまとめています。

ダッシュボードでAPI keysを開き、キーを作成します。キーはmk_live_で始まります。保存されるのはキーのハッシュ値のみなので、完全なキーが表示されるのは一度だけです。すぐに環境変数かシークレットマネージャーに保存してください：

export METALAPI_KEY="mk_live_your_key_here"

APIはキーを3つの同等な方法で受け付けます。api_keyクエリパラメーター、Authorization: Bearerヘッダー、X-API-Keyヘッダーです。完全なURLはアクセスログ、プロキシ、エラートラッカーに残りやすいため、本番環境ではヘッダーの使用をおすすめします。ブラウザから呼び出すためのドメイン制限付きキーについては、API認証ガイドで説明しています。

# 1. クエリパラメーター
curl "https://metalapi.com/api/v1/latest?api_key=$METALAPI_KEY&currencies=XAU"

# 2. Authorizationヘッダー
curl "https://metalapi.com/api/v1/latest?currencies=XAU" \
  -H "Authorization: Bearer $METALAPI_KEY"

# 3. X-API-Keyヘッダー
curl "https://metalapi.com/api/v1/latest?currencies=XAU" \
  -H "X-API-Key: $METALAPI_KEY"

curl、JavaScript、Pythonで最初のリクエストを送る

すべてのエンドポイントはhttps://metalapi.com/api/v1/配下のシンプルなGETリクエストです。/latestエンドポイントは現在の価格を返します。baseは価格を表す通貨（デフォルトはUSD）を指定し、currenciesはレスポンスを必要なシンボルだけに絞り込みます。1回のリクエストで多数のシンボルを取得しても、カウントは1リクエストです。

curl "https://metalapi.com/api/v1/latest?base=USD&currencies=XAU,XAG" \
  -H "X-API-Key: $METALAPI_KEY"

成功すると、次のようなレスポンスが返されます。数値はMetalAPIのドキュメント全体で使われている例の値で、リアルタイムの価格ではありません：

{
  "success": true,
  "timestamp": 1792834892,
  "date": "2026-10-24",
  "base": "USD",
  "rates": {
    "XAU": 0.0002501319,
    "USDXAU": 3997.89,
    "XAG": 0.0185392857,
    "USDXAG": 53.94
  },
  "rate_limit": {
    "limit": 10000,
    "remaining": 9876,
    "reset": 1793491200,
    "used": 124,
    "plan": "Standard",
    "reset_date": "2026-11-01T00:00:00.000Z"
  }
}

同じ呼び出しを、fetchが組み込まれているNode.js 18以降から行う例です。トップレベルのawaitが使えるようにgold.mjsとして保存し、node gold.mjsで実行します：

const params = new URLSearchParams({ base: "USD", currencies: "XAU,XAG" });
const res = await fetch(`https://metalapi.com/api/v1/latest?${params}`, {
  headers: { Authorization: `Bearer ${process.env.METALAPI_KEY}` },
  signal: AbortSignal.timeout(10_000),
});
const data = await res.json();

if (!data.success) {
  throw new Error(`MetalAPI ${data.error.code} (${data.error.type}): ${data.error.info}`);
}

const gold = data.rates[`${data.base}XAU`];
const asOf = new Date(data.timestamp * 1000).toISOString();
console.log(`Gold: ${gold} ${data.base} per troy ounce (data from ${asOf})`);

Pythonではrequestsライブラリを使います：

import os

import requests

resp = requests.get(
    "https://metalapi.com/api/v1/latest",
    params={"base": "USD", "currencies": "XAU,XAG"},
    headers={"X-API-Key": os.environ["METALAPI_KEY"]},
    timeout=10,
)
data = resp.json()
if not data["success"]:
    err = data["error"]
    raise RuntimeError(f"MetalAPI {err['code']} ({err['type']}): {err['info']}")

base = data["base"]
print(f"Gold:   {data['rates'][base + 'XAU']} {base} per troy ounce")
print(f"Silver: {data['rates'][base + 'XAG']} {base} per troy ounce")

どちらのコードも、レートのキーをハードコードせずにdata.baseから組み立てています。この小さな習慣のおかげで、後から基準通貨を変更してもコードは正しく動作します。そしてこれが、このガイドで最も重要なポイントにつながります。

レートの形式を正しく読む

ratesにはすべてのシンボルが2回ずつ登場し、2つの数値は互いに逆数の関係にあります：

一般的なルールとして、rates.<BASE><SYMBOL>はシンボル1単位の基準通貨建て価格です。接頭辞のないrates.<SYMBOL>はその逆数で、基準通貨1単位あたりのシンボルの数量です。逆数の形式は、為替系APIや旧来のMetalAPI連携との互換性のために残されています。

旧来の連携で逆数の値をすでに保存している場合でも、再ダウンロードする必要はありません。価格＝1÷逆数です。上の例では、1÷0.0002501319で、丸めによる末尾の桁の差を除いて3997.89に戻ります。

通貨も同じルールに従います。基準通貨がUSDの場合、USDEURは1ユーロの米ドル建て価格で、EURは1米ドルあたりのユーロ額です。データ形式ガイドには、Standardプラン以上で利用できるBidとAskのキーを含め、さらに多くの例が掲載されています。

基準通貨と単位

金価格を別の通貨で取得するには、baseを変更します。それに合わせてレートのキーも変わり、base=EURではEURXAU、base=INRではINRXAUが返されます。クロスレートは同じスナップショットから計算されるため、ユーロ建ての金価格とユーロの米ドル建て価格は常に整合しています。

金属価格はデフォルトでトロイオンスあたりの価格です。unitパラメーターを使うと、別の重量単位あたりの価格を取得できます：

次のリクエストは、金と銀を1グラムあたりのユーロ建てで返します。unitがデフォルト以外の場合、レスポンスのトップレベルのunitフィールドにも同じ値が含まれます：

curl "https://metalapi.com/api/v1/latest?base=EUR&currencies=XAU,XAG&unit=gram" \
  -H "X-API-Key: $METALAPI_KEY"

unitが影響するのは貴金属と産業用金属だけです。エネルギー、通貨、暗号資産は変わりません。トロイオンス、グラム、トラ、丸めの詳細については、トロイオンス、グラム、キログラムをお読みください。ジュエリーを販売している場合は、カラット別の金価格の解説で22Kと18Kの価格や/caratエンドポイントを紹介しています。

金の過去価格

過去の価格も、同じパラメーターと同じレスポンス形式で取得できます。履歴は、金属とエネルギーが2000年、通貨が1999-01-04、暗号資産が2014年からです。ほとんどの用途は次の4つのエンドポイントでカバーできます：

• /YYYY-MM-DD（または/historical?date=YYYY-MM-DD、/yesterday）：1日分の終値。週末や祝日の場合は、直近の取引日の終値が返されます。
• /timeframe（エイリアス/timeseries）：start_dateからend_dateまでの日次終値。1リクエストあたり、Freeでは最大30日、有料プランでは最大365日です。
• /change：2つの日付間の開始レート、終了レート、変動額、変動率。
• /ohlc：1日分の始値、高値、安値、終値。

# 2024年1月15日終値の金と銀
curl "https://metalapi.com/api/v1/2024-01-15?currencies=XAU,XAG" \
  -H "X-API-Key: $METALAPI_KEY"

# 2026年9月の金の日次終値（ユーロ建て）
curl "https://metalapi.com/api/v1/timeframe?start_date=2026-09-01&end_date=2026-09-30&base=EUR&currencies=XAU" \
  -H "X-API-Key: $METALAPI_KEY"

過去の日の終値は変わらないため、繰り返しリクエストするのではなく一度保存してください。APIで金・銀の過去価格を取得するでは、25年分のデータを分割して取得し、ローカルに保存してチャートにする方法を順を追って説明しています。過去データガイドには、長い期間を扱うためのJavaScriptのヘルパーが掲載されています。

エラー、クォータ、プランの制限

失敗したリクエストは、HTTPエラーステータスとsuccess: falseを含む本文を返します。errorオブジェクトには、数値のcode、機械判読用のtype、人が読むためのinfoが含まれます。分岐にはcodeまたはtypeを使い、infoのテキストは使わないでください。レート制限（104）、クォータ（105）、プラン制限（106）、期間（207）のエラーにはupgrade_urlも含まれます：

{
  "success": false,
  "error": {
    "code": 106,
    "type": "plan_restriction",
    "info": "The carat endpoint requires a paid subscription plan",
    "upgrade_url": "https://metalapi.com/dashboard/billing"
  }
}

よく遭遇するエラーコードは次のとおりです：

認証済みのすべてのレスポンスで、クォータの状況がX-RateLimit-*ヘッダーと本文のrate_limitオブジェクトの両方で返されます。/usageと/symbolsはクォータにカウントされないため、監視ツールから自由に呼び出せます。104、106、107、またはサーバーエラーで拒否されたリクエストは課金されませんが、バリデーションエラーは課金されます。エラーハンドリングガイドには、すべてのエラーコードとリトライ用のヘルパーが掲載されています。

プランの主な違いは、リクエスト数と価格の鮮度です：

年払いにすると最大25%お得になります。最新の詳細は常に料金ページでご確認ください。

キャッシュと本番運用のヒント

プランの更新間隔より頻繁に/latestをリクエストしても同じ数値が返され、クォータを無駄に消費するだけです。最新価格は少なくともプランの更新間隔の間はキャッシュし、過去の日のデータは永続的にキャッシュしてください。次のPythonヘルパーは最新価格をキャッシュし、APIに到達できない場合は最後に取得できたレスポンスを返し続けます：

import os
import time

import requests

TTL_SECONDS = 600  # Standardプラン：価格は10分ごとに更新
session = requests.Session()
session.headers["X-API-Key"] = os.environ["METALAPI_KEY"]
_cache = {"at": 0.0, "data": None}


def latest_prices():
    now = time.monotonic()
    if _cache["data"] and now - _cache["at"] < TTL_SECONDS:
        return _cache["data"]
    try:
        r = session.get(
            "https://metalapi.com/api/v1/latest",
            params={"currencies": "XAU,XAG,XPT,XPD"},
            timeout=10,
        )
        data = r.json()
    except (requests.RequestException, ValueError):
        data = None
    if data and data.get("success"):
        _cache.update(at=now, data=data)
        return data
    if _cache["data"]:
        return _cache["data"]  # 最後に取得できた価格。そのタイムスタンプを表示する
    raise RuntimeError(data["error"] if data else "MetalAPI unreachable")

連携を低コストで安定させるための習慣を、さらにいくつか紹介します：

• すべてのシンボルを1回の呼び出しで取得する。 currencies=XAU,XAG,XPT,XPDなら1リクエストで済みますが、4回に分けると4リクエストかかります。
• キーはサーバー上に置く。 ブラウザからAPIを呼び出す必要がある場合は、ドメイン制限付きキーを使用してください。コードを書かずにウェブサイトに価格を表示するなら、埋め込みウィジェットを使えばページにキーを一切含めずに済みます。
• タイムスタンプを表示する。 timestampはリクエストの時刻ではなく、データの時刻です。特にキャッシュした値を返す場合や、週末で市場が閉まっている場合は、価格の横に表示してください。
• ポーリングの予算を立てる。 10分ごとのポーリングで月に約4,500リクエスト、1分ごとでは約45,000リクエストを消費します。Proプラン以上ではポーリングの代わりにリアルタイムストリームを、Advanced以上ではWebhookによる価格アラートを利用できます。
• タイムアウトを設定し、再試行は選択的に行う。 タイムアウトは10秒程度に設定し、104はRetry-Afterの後に、5xxエラーはバックオフを挟んで再試行してください。バリデーションエラーは決して再試行しないでください。
• シンボルを事前に検証する。 起動時に/symbolsを一度読み込み（無料です）、不明なコードはリクエストを消費する前に弾いてください。

AIアシスタントを使っている場合は、https://metalapi.com/mcpのMetalAPI MCPサーバーが同じデータをツールとして公開しているため、Claude、ChatGPT、Cursor、VS Codeからご契約のプランで金価格や履歴を調べられます。詳しくはAI・MCPをご覧ください。すべてのエンドポイントとパラメーターについては、APIドキュメントがリファレンスです。