Alpha Vantage から Narwhal へ移行する

移行すべき人と、残るべき人

チームが乗り換える理由は、ライセンスとクォータです。Alpha Vantageは、書面で別途合意しない限り、無料キーと有料キーを個人の非商用利用に限定していますが、Narwhalはすべてのアカウントで商用アプリでの利用が含まれます。Alpha Vantageの無料キーは1日25リクエストまでですが、Narwhalはすべてのアカウントに最初の12か月間、毎月$10分の無料クレジットを付与します。Alpha Vantageの経済系列は米国のみですが、Narwhalは37か国の経済データを読み取れます。1つのNarwhalキーはMCPでも使えるため、エージェント向けのプロジェクトにも適しています。

テクニカル指標、オプション、ニュースセンチメントには Alpha Vantage を使い続けてください。Alpha Vantage は日次履歴を25年以上掲載しており、Narwhal は各系列の全履歴を返します。Narwhal の株式は42の取引所をカバーしますが、東京は含まれません。

各 function をエンドポイントに対応づける

以下の各パスは、2026年11月3日に有効なキーで呼び出しました。Narwhal の ID には XNYS:IBM のように取引所が含まれるため、まず /v1/equities/search で株式を検索してください。

Narwhal に対応するものがないもの

これらには、Alpha Vantage か別のデータソースを使い続けてください。

• テクニカル指標：SMA、RSI、MACD などの53個の function。
• オプション（リアルタイムと過去の両方）。
• NEWS_SENTIMENT と IPO_CALENDAR。
• 指数の幅：INDEX_DATA は200以上の指数を掲載しますが、Narwhal が価格を扱うのは18です。

3つの呼び出しを移行する

1. キーを設定する 無料キーを取得し、NARWHAL_API_KEY に保存します。Narwhal はキーを Authorization: Bearer ヘッダーから読むので、すべての URL から apikey を削除してください。
2. CPI 呼び出しを置き換える Narwhal のパスは国を指定し、最新値を返します。履歴が必要な場合は、start と end を付けて /observations を追加します。Alpha Vantage が一覧で返すのと同じ指数値が返ります。
   curl、CPI の移行前と移行後

   # Ran 2026-11-03: Alpha Vantage 200 OK with the demo key, Narwhal 200 OK both calls
   # Before: Alpha Vantage, CPI
   curl "https://www.alphavantage.co/query?function=CPI&interval=monthly&apikey=demo"
   
   # After: Narwhal, latest US CPI
   curl "https://api.narwhalapi.com/v1/economics/USA/cpi" \
     -H "Authorization: Bearer $NARWHAL_API_KEY"
   
   # After: Narwhal, CPI for July to September
   curl -G \
     --url "https://api.narwhalapi.com/v1/economics/USA/cpi/observations" \
     -d start=2026-07 -d end=2026-09 \
     -H "Authorization: Bearer $NARWHAL_API_KEY"

3. 株価と為替の呼び出しを置き換える Narwhal は株式を上場 ID で、為替レートを基準通貨で指定し、対象は currencies に入れます。
   curl、株価と為替の移行前と移行後

   # Ran 2026-11-03: Alpha Vantage quote 200 OK (demo key), Narwhal quote and FX 200 OK
   # Before: Alpha Vantage, last price for IBM
   curl "https://www.alphavantage.co/query?function=GLOBAL_QUOTE&symbol=IBM&apikey=demo"
   
   # After: Narwhal, same stock (ids look like XNYS:IBM)
   curl "https://api.narwhalapi.com/v1/equities/XNYS:IBM/price" \
     -H "Authorization: Bearer $NARWHAL_API_KEY"
   
   # Before: Alpha Vantage, USD to JPY (request taken from its documentation, not run)
   curl -G \
     --url "https://www.alphavantage.co/query" \
     -d function=CURRENCY_EXCHANGE_RATE -d from_currency=USD \
     -d to_currency=JPY -d apikey=YOUR_ALPHA_VANTAGE_KEY
   
   # After: Narwhal, USD to JPY
   curl "https://api.narwhalapi.com/v1/fx/rates/USD?currencies=JPY" \
     -H "Authorization: Bearer $NARWHAL_API_KEY"

4. パーサーを書き直す フィールド名から番号が消え、系列は配列になります。このスクリプトは Narwhal の3つの呼び出しをすべて実行します。
   Python、Narwhal での3つの呼び出し

   # Ran 2026-11-03: 200 OK for all three calls
   import os
   import requests
   
   session = requests.Session()
   session.headers["Authorization"] = f"Bearer {os.environ['NARWHAL_API_KEY']}"
   
   
   def get(path, **params):
       r = session.get("https://api.narwhalapi.com" + path, params=params, timeout=10)
       r.raise_for_status()
       return r.json()
   
   
   cpi = get("/v1/economics/USA/cpi")  # was function=CPI
   print(cpi["period"], cpi["value"])
   
   ibm = get("/v1/equities/search", q="IBM", country="USA")["results"][0]["id"]
   print(ibm, get(f"/v1/equities/{ibm}/price")["price"])  # was GLOBAL_QUOTE
   
   fx = get("/v1/fx/rates/USD", currencies="JPY")["rates"][0]  # was CURRENCY_EXCHANGE_RATE
   print(fx["currency"], fx["rate"])

5. 出力を比較する 同じ入力で両方のプロバイダーを実行します。2026-09 の米国 CPI は両方とも 336.940、11月2日の IBM の終値は両方とも 252.51 です。

レスポンスの違い

Alpha Vantage は為替レートを Realtime Currency Exchange Rate の下に番号付きキーで入れ子にします。Narwhal は通貨ごとに1つのオブジェクトを持つ rates 配列を返します。

{
  "name": "Consumer Price Index for all Urban Consumers",
  "interval": "monthly",
  "unit": "index 1982-1984=100",
  "data": [
    { "date": "2026-09-01", "value": "336.940" },
    { "date": "2026-08-01", "value": "334.980" }
  ]
}

{
  "country": "USA",
  "period": "2026-09",
  "value": "336.940",
  "index_base": "1982-84=100",
  "released_on": "2026-10-14"
}

{
  "Global Quote": {
    "01. symbol": "IBM",
    "05. price": "252.5100",
    "07. latest trading day": "2026-11-02",
    "08. previous close": "257.8100",
    "10. change percent": "-2.0558%"
  }
}

{
  "id": "XNYS:IBM",
  "symbol": "IBM",
  "currency": "USD",
  "price": "252.51",
  "previous_close": "257.81",
  "change_percent": "-2.06",
  "market_session": "closed",
  "timestamp": "2026-11-02T21:00:00Z",
  "stale": false
}

レート制限に対処する

Alpha Vantage の無料キーは1日25リクエストまでです。有料プランは月額$49.99から、1分あたり75〜1,200リクエストで、1日の上限はありません。Narwhal は無料クレジットでは1分50リクエスト、有料クレジットがあれば1分500リクエストまで許可し、呼び出しは1,000回あたり$2〜$10です。

Alpha Vantage は 200 のレスポンス内で問題を報告するため、ステータスコードだけの確認では見逃します。例にない呼び出しでは、デモキーが Information の通知を返しました。Narwhal は送信が速すぎると 429 rate_limit_exceeded を返すので、Retry-After ヘッダーの時間だけ待って再試行してください。残高を使い切ると 402 insufficient_credits を返すので、クレジットを追加してください。どちらも課金されません。成功したレスポンスには X-RateLimit-Remaining と X-RateLimit-Reset が付きます。キャッシュについては、レスポンスのキャッシュと 429 エラーの処理を参照してください。

# 200 OK on both test calls; the 402 and 429 branches follow the documented codes
import os
import time
import requests

session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['NARWHAL_API_KEY']}"


def get(path, **params):
    for attempt in range(4):
        r = session.get("https://api.narwhalapi.com" + path, params=params, timeout=10)
        if r.status_code == 402:
            raise RuntimeError("Out of credit; add credit in the dashboard.")
        if r.status_code == 429:
            time.sleep(float(r.headers.get("Retry-After", 2)))
            continue
        r.raise_for_status()
        return r.json()
    raise RuntimeError(f"Gave up on {path}")

株式の ID はどう調べますか？

/v1/equities/search?q=IBM&country=USA を呼び出します。各結果には、価格とバーに使う XNYS:IBM のような id と、財務データに使う usa:0000051143 のような company_id が入っています。

残りの部分には Alpha Vantage を使い続けられますか？

はい。プロバイダーごとにキーと請求が別なので、表にあるファミリーだけを移し、指標、オプション、センチメントは今の場所に残してください。そのほかの違いはNarwhalとAlpha Vantageの比較にまとめています。

移行チェックリスト

• コードが呼び出す function をすべて洗い出し、表と照らして印を付けます。
• 株式のシンボルを上場 ID に一度だけ解決し、ID を保存します。
• キーを Bearer ヘッダーに移し、ログに残る URL から取り除きます。
• パーサーを、シンプルな名前、古い順の配列、文字列の数値に合わせて書き直します。
• Information の確認を、ステータスと code の確認に置き換えます。
• 数値を比較する前に、GDP と FF 金利の定義を確認します。
• Retry-After に従って再試行し、insufficient_credits では停止します。
• 切り替える前に、両方のプロバイダーを並行して動かし、値を比較します。