Stack Overflow上の金価格API:開発者のトラブルシューティングに答える

連携がうまくいかなくなると、開発者はそのエラーをStack Overflowに貼り付ける。金価格APIについて出てくる質問は、ほぼ毎回同じ一握りに絞られる。認証拒否、不正な形式のシンボル、レート制限の壁、あるいはブラウザからのCORSエラーだ。本稿ではgoldprice.devを実例として、それぞれを直接解決していく。以下のコード片はすべてhttps://api.goldprice.devに対する、実際に動く呼び出しだ。

"401 Unauthorized": APIキーが拒否される

キーはベアラートークンとしてAuthorizationヘッダーに入れる。その際、Bearerという単語(末尾にスペース付き)が必ず必要だ。

curl https://api.goldprice.dev/v1/prices?symbol=XAU-USD-SPOT \  -H "Authorization: Bearer ga_live_YOUR_KEY"

実際に401を引き起こす原因は主に三つ。Bearer という接頭辞が抜けている、コピー&ペーストの際にキーへ余計な改行や引用符が紛れ込んでいる、あるいはキーが読み込まれていない環境変数から読み取られている、のいずれかだ。キーにはga_live_という接頭辞が付く。始めるだけなら厳密にはキーは不要で、匿名呼び出しも動作するが、IPごとに毎分30、毎時100、月1,000リクエストという上限がある。簡単なテストの範囲を超えるなら、認証しておくべきだ。

"400 invalid_symbol"：最初につまずく最も一般的なエラー

symbolパラメータは、金属コード単体ではない。BASE-QUOTE-CONTRACTという形式だ。symbol=XAUを渡すと400 invalid_symbolが返る。リアルタイムの金現物が欲しいなら、正しい値はXAU-USD-SPOTだ。

# 誤り、400 invalid_symbolcurl "https://api.goldprice.dev/v1/prices?symbol=XAU"# 正しいcurl "https://api.goldprice.dev/v1/prices?symbol=XAU-USD-SPOT"

銀の現物はXAG-USD-SPOT、銅の現物はHG-USD-SPOTだ。金・銀・銅の現物は全プランで使える。新プランに先物は含まれない。symbolを省略すると、プランで許可されたデフォルトの行が返る。

"429 Too Many Requests"：レート制限への対処

全レスポンスにX-RateLimit-Remainingが付く。ゼロになる前に読み取り、呼び出し頻度を下げよう。毎分の上限はFree 10、Basic 60、Plus 120、Pro 300リクエストだ。短いキャッシュで呼び出しを減らせる。

"CORSエラー"：ブラウザからAPIを呼び出す場合

自分のキーを使ってフロントエンドのJavaScriptから直接APIを呼び出してはいけない。理由は二つある。開発者ツールを開いた誰にでもga_live_...が見えてしまうこと、そしてブラウザのCORSがそれをブロックすることだ。呼び出しは自分のバックエンド経由でプロキシし、キーはサーバー側に留め、ブラウザには自分のエンドポイントを叩かせる。

// 自分のバックエンドのルート、キーはブラウザに届くことがないconst r = await fetch(  "https://api.goldprice.dev/v1/prices?symbol=XAU-USD-SPOT",  { headers: { Authorization: `Bearer ${process.env.GOLDPRICE_API_KEY}` } },);const data = await r.json();

JSONを処理するのではなく、単にリアルタイム価格を表示したいだけなら、無料の金価格ウィジェットを使うとよい。そのホスト型iframeはAPIキーを一切必要とせず、ブラウザのCORS問題そのものを完全に回避できる。

"どのフィールドが価格なのか?"：レスポンスの読み方

デフォルトにはprice、computed_at、is_staleが含まれる。bid/askは有料のみの任意項目で、整合した両側の気配値がある場合に返る。 より豊富な情報はすべて?include=によるオプトインだ。?include=sourcesはsources[]配列を追加し、?include=karatはカラット別のグラム単価内訳を追加し、?include=stats(認証必須)はopen_price、high_price、low_price、prev_close_price、変化率フィールド、そしてdivergence_bps/divergence_flagを追加する。?include=allは、自分の認証レベルで許可されているすべてを返す。正確さのために重要なフィールドが二つある。

• is_stale：値が想定される更新ウィンドウより古くなるとtrueになる。価格を表示する前に必ず確認すること。
• sources[](?include=sources使用時)：アップストリームごとに1行、それぞれ独自のpriceとtimestampを持つ。データソース間で食い違いがある場合、divergence_bps(?include=stats使用時)がその乖離幅を教えてくれるので、出所不明な単一の混合値を鵜呑みにするのではなく、自分で許容範囲を設定できる。

"過去データ/OHLCデータはどう取得するか?"

日次終値の履歴はGET /v1/prices/historyで取得でき、すべてのプランで利用できる。変わるのは、どこまで遡れるかだ。無料プランは直近30日分、Basicは直近1年分、PlusとProは全履歴を返す。したがって、履歴クエリの結果が想定より短い場合、それは自分のプランのウィンドウ制限によるものであり、認証エラーではない。

動く最短の呼び出し

キー不要、正しいシンボルを指定するだけ。

curl "https://api.goldprice.dev/v1/prices?symbol=XAU-USD-SPOT"

これで、陳旧度フラグ付きの15分遅延の金価格が返ってくる。寄与しているデータソースが欲しければ?include=sourcesを加える。完全なレスポンス形式とより高い上限が欲しくなったら、無料キーの取得は1分で終わる。特定言語向けの手順を見たいなら、Fetch live gold prices in JavaScriptがREST経路を端から端まで解説しており、Caching gold prices and staying inside rate limitsは大量アクセス時の扱い方をカバーしている。