jquants-cli-usage

name: jquants-cli-usage description: > J-Quants CLI (jquants) で日本株式市場データを取得するコマンドを構築・実行する。 株価・四本値・分足・ティック、信用取引残高・空売り比率、先物・オプション、 財務諸表・配当金、TOPIX・指数データの取得に対応。 プランごとの API 利用可否・取得可能データ期間（Free/Light/Standard/Premium）の確認にも対応。 トリガー: jquants, J-Quants, 株価, 株価データ, 銘柄, 四本値, 分足, OHLCV, JPX, 東証, TOPIX, 日経225, 先物, オプション, デリバティブ, 空売り, 信用取引, 配当, 財務諸表, 決算, PER, PBR, ROE, 指数, バルクダウンロード, 日本株, Japanese stock, stock price, market data, financial statements, プラン, サブスクリプション, subscription, plan, Free, Light, Standard, Premium, 取得可能期間, データ範囲, data range, API availability, 更新時刻, データ更新, 更新タイミング, データが古い, 最新データ, いつ更新, data freshness, update schedule, update time, when is data updated, latest data

J-Quants CLI 使用スキル

Role & Decision Flow

jquants コマンドを構築するときは、以下の順序で判断する:

1. データ種別を決める — 株式(eq)・市場(mkt)・デリバティブ(deriv)・財務(fins)・指数(idx)
2. プラン制限を確認する — ユーザーのプランで利用可能か確認する（下記「Subscription Plans & API Availability」参照）。プランが不明な場合は、コマンドを提示しつつ必要プランを明記する
3. フィールド名を確認する — -f で絞り込む前に jquants schema <endpoint> で正確な名前を調べる（推測しない）
4. 個別API vs バルクを選ぶ — 「全銘柄」「1ヶ月以上」「大量」のいずれかに該当 → バルク（references/commands-bulk.md 参照）。個別APIを大量に繰り返すとレートリミットに抵触するため（下記 Rate Limits 参照）。Free プランは CSV/バルク不可（mkt calendar を除く）
5. コマンドを組み立てる — グローバルオプション（--output, --save, -f）をサブコマンドの前に置く
6. パイプを考慮する — パイプ先がある場合は --output を省略するだけで自動的に CSV が流れる

Prerequisites

推奨: jquants login でブラウザログイン（API キーを自動取得・保存）

jquants login   # ブラウザが開き、Cognito OAuth2 PKCE でログイン
                # → ~/.config/jquants/credentials.json に API キーを自動保存

フォールバック: 環境変数で直接指定

export JQUANTS_API_KEY="your-api-key"
# または .env ファイルに記載

認証優先順位: ~/.config/jquants/credentials.json の api_key → JQUANTS_API_KEY 環境変数 → エラー（jquants login を促す）

**jquants schema は認証不要。**ログイン前でもフィールド名の確認に使える。

Command Syntax Rules

グローバルオプション (--output, --save, -f) はサブコマンドの前に置く:

# ✅ 正しい
jquants --output csv --save out.csv eq daily --code 86970

# ❌ 誤り（サブコマンド後は無効）
jquants eq daily --code 86970 --output csv

なぜ: clap の設計上、サブコマンド以降のフラグはサブコマンド自身のオプションとして解析される。サブコマンドの後に置くと「不明なフラグ」エラーになる。

パイプ時の自動CSV切替:

stdout が TTY でない場合（パイプ先がある場合）、--output table（デフォルト）は自動的にCSV形式で出力される。

# パイプすると自動でCSVが流れる
jquants eq daily --code 86970 | head -5

# 明示的にJSONをパイプしたい場合は指定が必要
jquants --output json eq daily --code 86970 | jq '.[] | .AdjustmentClose'

フィールド選択 (--fields / -f) でカラムを絞り込む:

# 日付・コード・調整済終値だけを取得
jquants -f Date,Code,AdjustmentClose eq daily --code 86970

# 不正なフィールド名を指定するとエラーで利用可能フィールド一覧が表示される

Schema-First: フィールド名の確認

--fields でカラムを絞り込む前に、jquants schema <endpoint> で正確なフィールド名を確認する。フィールド名を推測しない（PascalCase が多いが一致しないことがある）。

jquants schema                  # 全エンドポイント一覧（キー・説明・フィールド数）
jquants schema eq.daily         # eq.daily の全フィールド（名前・型・説明）
jquants --output json schema    # JSON 形式で出力

エンドポイントキーは カテゴリ.コマンド 形式（例: eq.daily, fins.summary, mkt.short-ratio）。

手順:

1. jquants schema eq.daily でフィールド一覧を取得
2. 必要なフィールド名をコピーして -f に指定
3. 不正なフィールド名はエラーで拒否される（利用可能フィールド一覧が表示される）

Quick Reference

認証 & ユーティリティ

株式データ（eq）

市場データ（mkt）

デリバティブ（deriv）

財務データ（fins）

指数データ（idx）

適時開示（td）※ TDnet/適時開示情報アドオン必要

Category Reference Files

各カテゴリの詳細なコマンド構文・フラグ・例はリファレンスファイルに記載されている。Quick Reference の情報で十分な場合はリファレンスを読む必要はない。

以下の場合にリファレンスを参照する:

Output, Fields, and Save

# 出力形式: table（デフォルト）、json、csv、parquet
jquants --output json eq master
jquants --output csv eq master
jquants --output parquet --save master.parquet eq master   # Parquet は --save 必須

# ファイル保存（--save は --output table と併用不可）
jquants --output csv --save master.csv eq master
jquants --output json --save daily.json eq daily --code 86970

# フィールド選択: -f でカラムを絞り込み（全形式で有効）
jquants -f Date,Code,AdjustmentClose eq daily --code 86970
jquants --output csv -f Date,Code,AdjustmentClose --save daily.csv eq daily --code 86970

# パイプでデータを加工
jquants eq daily --code 86970 | head -5                         # 自動CSV
jquants --output json eq daily --code 86970 | jq '.[0]'        # JSON明示

Workflow Recipes

特定銘柄の株価トレンド分析

# 1. 銘柄コードを確認
jquants eq master --code 72030

# 2. フィールド名を確認
jquants schema eq.daily

# 3. 過去3ヶ月の日次データを CSV で保存
jquants --output csv --save toyota.csv \
  -f Date,AdjustmentClose,Volume \
  eq daily --code 72030 --from 2026-01-01 --to 2026-03-31

全銘柄の月次データ取得（バルク）

# 個別APIでループしない。全銘柄は bulk を使う。
jquants bulk get --endpoint /equities/bars/daily --date 2026-03 --download

# 解凍して CSV として利用
gunzip *.gz

財務情報の取得

# 配当情報（期間指定）
jquants --output csv --save div.csv fins dividend --from 2026-01-01 --to 2026-03-31

# 財務サマリー（銘柄指定、JSON推奨）
jquants --output json fins summary --code 86970

# 財務諸表の完全データ（FS フィールドは JSON 必須）
jquants --output json fins details --code 86970

Special Behaviors

eq trades はバルク API を内部的に使用する

eq trades は他の eq コマンドと異なり、内部で /equities/trades のバルク API を呼び出す。そのため:

• --code フラグは使用不可
• --date YYYY-MM 形式の月指定が可能（個別 API の YYYY-MM-DD とは異なる）
• --download フラグでファイルをカレントディレクトリに保存する

jquants eq trades --date 2025-12             # URL取得のみ
jquants eq trades --date 2025-12 --download  # ファイルダウンロード

fins details の FS フィールド

fins details の FS（Financial Statement）フィールドはネストされた JSON オブジェクト。テーブル表示では "N items" と省略される。完全なデータを取得するには --output json を使う。

deriv の --contract-flag

--contract-flag 1 は中心限月（最も取引が活発な限月）のみを取得する。省略すると全限月のデータが返る。deriv futures と deriv options の両方で使用可能。

Rate Limits

J-Quants API はプランごとに1分あたりのリクエスト上限が設定されている。上限を意識してコマンドを設計することで、不要な遮断を避けられる。

プラン別上限（リクエスト/分）

アドオン別上限（プランとは独立して適用）

制限超過時の挙動

• HTTP 429 Too Many Requests が返される
• 大幅超過が続くと約5分間アクセスが完全遮断される（即時リトライは逆効果）

回避のポイント

• 全銘柄 × 全日付の個別ループは使わない — bulk get で1リクエスト・全銘柄を一括取得する
• 429 を受けたら即時リトライしない — しばらく待機（数十秒〜数分）してから再試行する
• クエリパラメータで絞り込む — 不要なフィールドや日付範囲を減らし、1リクエストで必要なデータを取り切る

Subscription Plans & API Availability

各 API はプランによってアクセス可否と取得可能期間が異なる。コマンドを提案する前にプランの制限を確認する。プランが不明な場合は、コマンドを提示しつつ必要プランを明記する。

最低必要プラン早見表

プラン階層: Free < Light < Standard < Premium（上位プランは下位の全 API を含む）

Free プランの制限: CSV/バルクダウンロード不可（mkt calendar を除く）。API アクセスのみ。データは「12週間前〜2年12週間前」のウィンドウに限定（最新12週と2年超の過去データは取得不可）。

詳細な取得可能期間・データ範囲は references/plans.md を参照。

Data Freshness（更新タイミング）

J-Quants API のデータは市場イベント後に順次更新される。現在時刻と更新時刻の関係によって取得できるデータの鮮度が変わる。

時間帯別更新サマリー（JST）

エージェント判断の指針

• 更新時刻前に当日データを聞かれた場合: 「○○:○○頃に当日分が反映されます。現時点では前営業日のデータが最新です」と伝える
• 週次データ（信用週末残高・投資部門別）: 信用残は火曜16:30、投資部門別は木曜18:00が更新目安。それ以外の曜日は前週分が最新
• デリバティブは27:00（翌日3:00 AM）更新: 翌営業日の早朝にならないと前日分が揃わない
• 「データが古い」と言われたとき: 更新時刻・週次サイクル・休祝日・プランの期間制限を順に確認する

詳細な判断フローとシナリオ例は references/data-update-schedule.md を参照。

Common Pitfalls