yahoo-finance2

yahoo-finance2

このスキルの用途

次のように、タスクで yahoo-finance2 を扱う場合にこのスキルを使用します。

• サーバーサイドの JavaScript／TypeScript アプリに Yahoo Finance の市場データを追加する。
• quote、chart、historical、quoteSummary、 fundamentalsTimeSeries、screener、options などのモジュールから選択する。
• パッケージの CLI または同梱の MCP サーバーを使用する。
• このリポジトリの Deno ソース、テスト、生成されたスキーマ、ドキュメント、または npm 出力ビルドを変更する。

これは非公式の Yahoo Finance クライアントです。Yahoo API としてサポートされていると説明したり、Yahoo のデータの可用性、鮮度、形式が保証されていると想定したりしないでください。

パッケージの使用

v3 のクラス API を優先してください。

import YahooFinance from "yahoo-finance2";

const yahooFinance = new YahooFinance();
const quote = await yahooFinance.quote("AAPL");
console.log(quote?.regularMarketPrice, quote?.currency);

yahooFinance.setGlobalConfig() のような古い v1／v2 のシングルトンパターンは使用しないでください。v3 では new YahooFinance(options) でインスタンスを作成します。

このパッケージはサーバーサイドのランタイム向けです。ブラウザー／クライアントのバンドルで Yahoo Finance を直接呼び出さないでください。Yahoo の CORS と Cookie の動作には、サーバー、サーバーレス、エッジ、Deno、Bun、または Node のコンテキストが必要です。

モジュールの選択

• シンボルが不明な場合は、まず search(query) を使用します。
• 現在またはほぼリアルタイムの気配値フィールドには quote(symbolOrSymbols) を使用します。1 つのシンボルまたは配列を指定できます。ペイロードを制限するには fields を使用し、キーを指定してアクセスするにはオブジェクトまたはマップ形式の戻り値をリクエストします。
• 複数の独立したコードパスで気配値データが必要な場合は quoteCombine(symbol) を使用します。複数の単一シンボル呼び出しをまとめ、より少ない quote() リクエストにします。
• 配当や株式分割などのイベントを含む、チャート向けの過去データには chart(symbol, { period1, period2, interval }) を使用します。return: "array" は反復処理が簡単で、return: "object" は Yahoo のネイティブ形式に対応しています。
• よりシンプルな OHLCV 履歴インターフェースには historical() を使用します。
• プロフィール、価格、サマリーの詳細、提出書類、所有者情報、推奨情報、その他の気配値サマリーモジュールには quoteSummary(symbol, { modules }) を使用します。必要なモジュールだけをリクエストしてください。
• 財務諸表には fundamentalsTimeSeries() を使用します。2024 年後半以降、incomeStatementHistory、balanceSheetHistory、cashflowStatementHistory などの気配値サマリーの財務諸表モジュールから得られるデータはごくわずかです。
• オプションチェーンには options(symbol) を使用します。
• 削除済み／非推奨の日次上昇銘柄または下落銘柄モジュールの代わりに screener() を使用します。よく使われる定義済みスクリーナーには day_gainers、day_losers、most_actives があります。
• 専用の Yahoo Finance エンドポイントには trendingSymbols(region)、recommendationsBySymbol()、insights() を使用します。

信頼性、検証、エラー

モジュールの呼び出しは try/catch で囲んでください。ネットワークエラー、Yahoo API エラー、上場廃止となったシンボル、データの欠落、検証の失敗は、想定される運用上の状況です。

デフォルトでは、返されるデータは検証され、既知の日付は Date オブジェクトに変換され、既知の結果形式は安全に扱えるように調整されます。検証に失敗した場合は、通常、検証を無効にするよりも、型付きインターフェースを修正してスキーマを再生成する方が適切です。

呼び出し元が unknown の出力を受け入れ、独自にチェックを行う場合に限り、{ validateResult: false } を使用してください。ライブラリがまだモデル化していない Yahoo のクエリパラメーターを試す場合に限り、{ validateOptions: false } を使用してください。

デフォルトのクライアントキューは、同時に実行される Yahoo リクエスト数を制限します。より厳格なレート制御が必要な場合は、コンストラクターまたは呼び出し単位の queue オプションを使用してください。

const yahooFinance = new YahooFinance({
  queue: { concurrency: 2, interval: 250 },
});

CLI と MCP

シェルから手早く使用する場合：

npx yahoo-finance2 search AMZN
npx yahoo-finance2 quote AAPL
npx yahoo-finance2 quoteSummary NVDA '{"modules":["assetProfile","secFilings"]}'

JSON のように見える位置引数は JSON として解析されます。パイプ出力が成功した場合は、JSON として安全に扱えます。

MCP クライアント向けに、このパッケージには読み取り専用の Yahoo Finance MCP サーバーが含まれています。

npx -y -p yahoo-finance2 yahoo-finance-mcp

stdio、HTTP、埋め込みハンドラー、クライアント登録の詳細については、docs/mcp.md を参照してください。

このリポジトリへのコントリビュート

まず AGENTS.md と CONTRIBUTING.md を読んでください。このリポジトリは Deno を優先する TypeScript プロジェクトで、npm の出力は生成物です。

生成された出力を明示的に求められている場合を除き、npm/ の生成ファイルではなく、src/ 内のソースファイルを編集してください。ローカルの .ts インポート拡張子はそのままにしてください。

公開モジュールファイルは通常、次のパターンに従います。

• 型付きのクエリ／結果インターフェースを信頼できる情報源とします。
• @yf-schema が付いたファイルでは、生成された .schema.json をインポートします。
• モジュール関数は、クエリのデフォルト値、ランタイムパラメーター、任意の変換、結果変換、スキーマキー、モジュールオプションを指定して this._moduleExec() を呼び出します。
• オーバーロードでは、検証済みの結果と、{ validateResult: false } の場合に返される unknown を区別します。

@yf-schema が付いたファイルでエクスポート済みインターフェースを変更した場合は、次を実行してください。

deno task schema

モジュールを追加する場合は、src/modules/index.ts、deno.json のエクスポート、ドキュメント／README のリンク、該当する場合は README のモジュール一覧、テストに組み込みます。また、そのモジュールをユーザー向けに公開する場合に限り、CLI／MCP への公開にも組み込んでください。

テストとフィクスチャ

すべてのテストを実行するには、次を実行してください。

deno task test

対象を絞ってテストを実行するには、次を実行してください。

deno task test src/modules/quote.test.ts

デバッグ時や Yahoo へのリクエストの同時実行数を制限する場合は、deno task test:serial src/modules/quote.test.ts を使用してください。

Yahoo の HTTP レスポンスを扱うテストでは、tests/common.ts の setupCache() を呼び出してください。既存のパターンを使用してください。

const YahooFinance = createTestYahooFinance({ modules: { quote } });
const yf = new YahooFinance();

describe("quote", () => {
  setupCache();

  it("passes validation", async (t, onFinish) => {
    await yf.quote("AAPL", {}, {
      devel: { id: "quote-AAPL", t, onFinish },
    });
  });
});

モジュールとシナリオに対応するフィクスチャ ID を使用してください。FETCH_DEVEL=nocache はネットワークへのライブリクエストを強制します。FETCH_DEVEL=recache は失敗したテストのキャッシュファイルを更新します。.static.json または .fake.json で終わるフィクスチャは、意図的に安定したもの、または合成されたものなので、キャッシュを更新しないでください。

検証エラーを修正する場合は、検証エラーのパスとキャッシュされた Yahoo のレスポンスを確認し、まず TypeScript インターフェースを更新してから、スキーマ生成を実行し、最後に対象を絞ったテストを実行してください。

ビルド、リント、リリース対象

必要に応じて、次のチェックを実行してください。

deno fmt
deno lint
deno task test
deno task build:npm

scripts/build_npm.ts は、生成される npm パッケージのメタデータ、バイナリ、依存関係、コピーするファイル、パッケージキーワードを管理します。npm/ を明示的に再生成する場合を除き、npm パッケージの変更はここで行ってください。

コミットメッセージには、fix(quote): handle missing extended market fields のように、スコープ付きの Conventional Commits を使用してください。

エージェントスキルのインストール

正式なスキルは skills/yahoo-finance2/SKILL.md にあります。Skills CLI 経由でインストールし、skills.sh のテレメトリーに表示されるようにするには、次を使用してください。

npx skills add gadicc/yahoo-finance2