jquants-cli-usage

J-Quants CLI 使用スキル

Role & Decision Flow

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

1. データ種別を決める — 株式(eq)・市場(mkt)・デリバティブ(deriv)・EDINET書類(edinet)・財務(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

認証 & ユーティリティ

やりたいこと	コマンド
ログイン（初回セットアップ）	jquants login
ログアウト	jquants logout
API フィールド一覧を確認	jquants schema
特定エンドポイントのフィールド詳細	jquants schema eq.daily

株式データ（eq）

やりたいこと	コマンド	更新時刻
全銘柄マスタ	jquants eq master	日次 17:30頃
株価四本値	jquants eq daily	日次 16:30頃
バリュエーション指標	jquants eq valuation	日次 16:30頃
前場四本値	jquants eq am	日次 12:00頃
分足データ	jquants eq minute	日次 16:30頃
投資部門別売買状況	jquants eq investor-types	週次(木) 18:00頃
決算発表予定日	jquants eq earnings-calendar	不定期 19:00頃
株価ティック	jquants eq trades	日次 16:30頃

市場データ（mkt）

やりたいこと	コマンド	更新時刻
売買内訳	jquants mkt breakdown	日次 18:00頃
日々公表信用残	jquants mkt margin-alert	日次 16:30頃
信用取引残高	jquants mkt margin-interest	日次 16:00頃
取引カレンダー	jquants mkt calendar	不定期
業種別空売り比率	jquants mkt short-ratio	日次 16:30頃
空売り残高報告	jquants mkt short-sale-report	日次 17:30頃

デリバティブ（deriv）

やりたいこと	コマンド	更新時刻
先物四本値	jquants deriv futures	日次 27:00頃
オプション四本値	jquants deriv options	日次 27:00頃
日経225オプション	jquants deriv options-225	日次 27:00頃

EDINET書類由来データ（edinet）※ Standard プラン以上

やりたいこと	コマンド	更新時刻
大株主状況（有報）	jquants edinet major-shareholders	随時（平日 8:00〜17:59）
政策保有株式（有報）	jquants edinet cross-shareholdings	随時（平日 8:00〜17:59）
大量保有報告書	jquants edinet large-volume-shareholders	随時（平日 8:00〜17:59）

財務データ（fins）

やりたいこと	コマンド	更新時刻
財務諸表	jquants fins details	日次 18:00頃(速報) / 24:30頃(確報)
配当金情報	jquants fins dividend	日次 12〜19時頃
決算発表予定日	jquants fins earnings-date	日次 10:05頃
財務情報サマリー	jquants fins summary	日次 18:00頃(速報) / 24:30頃(確報)

指数データ（idx）

やりたいこと	コマンド	更新時刻
TOPIX指数四本値	jquants idx daily-topix	日次 16:30頃
指数四本値	jquants idx daily	日次 16:30頃

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

やりたいこと	コマンド	更新時刻
適時開示インデックス一覧	jquants td list	随時更新
適時開示ファイルURL取得	jquants td files	随時更新
適時開示一括ダウンロードURL取得	jquants td bulk	日次 26:00頃

Category Reference Files

各类别的详细命令语法、标志和示例均记载于参考文件中。如果 Quick Reference 中的信息已足够，则无需阅读参考文件。

在以下情况下参阅参考文件：

类别	参考文件	应参阅的情况
eq	references/commands-eq.md	股票代码、日期、期间筛选，eq trades 的特殊行为
mkt	references/commands-mkt.md	--s33、--disc-date/--calc-date 等特殊标志
deriv	references/commands-deriv.md	--category、--contract-flag 的用法
edinet	references/commands-edinet.md	嵌套项的处理、edinet_code/code 的互斥关系、3 个命令的具体规范
fins	references/commands-fins.md	fins details 的 FS 字段（必须使用 JSON 输出）、fins earnings-date 的互斥查询
idx	references/commands-idx.md	指数代码指定、TOPIX
bulk	references/commands-bulk.md	批量下载的判断标准、工作流、端点列表
td	references/commands-td.md	使用 --cursor 进行实时轮询、--download 的用法、文件名规则
plans	references/plans.md	各套餐的 API 可用性、可获取期间、附加组件信息
schedule	references/data-update-schedule.md	需要判断数据新鲜度、了解更新时间的详细信息、查看不同场景的判断示例时

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 命令不同，eq trades 会在内部调用 /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 会按套餐设置每分钟的请求上限。合理设计命令以避免触及上限，可避免不必要的访问限制。

各套餐的上限（请求/分钟）

套餐	上限
Free	5
Light	60
Standard	120
Premium	500

各附加组件的上限（独立于套餐适用）

附加组件	上限
股价分钟线・逐笔数据	60
TDnet/及时披露信息	100

超出限制时的行为

• 会返回 HTTP 429 Too Many Requests
• 持续大幅超限时，访问会被完全阻断约 5 分钟（立即重试会适得其反）

避免超限的要点

• 不要对所有股票 × 所有日期进行逐项循环 — 使用 bulk get，通过 1 次请求批量获取所有股票的数据
• 收到 429 后不要立即重试 — 等待一段时间（数十秒至数分钟）后再试
• 使用查询参数筛选 — 减少不需要的字段或日期范围，以便通过 1 次请求获取所需数据

Subscription Plans & API Availability

不同套餐的 API 访问权限和可获取期间各不相同。提出命令前，请先确认套餐限制。如果套餐不明确，请提供命令并注明所需套餐。

最低所需套餐速查表

最低所需套餐	CLI 命令
Free	eq master, eq daily, eq valuation, eq earnings-calendar, fins summary, fins earnings-date, mkt calendar
Light	eq investor-types, idx daily-topix
Standard	mkt margin-interest, mkt short-ratio, mkt short-sale-report, mkt margin-alert, idx daily, deriv options-225, edinet major-shareholders, edinet cross-shareholdings, edinet large-volume-shareholders
Premium	eq am, fins details, fins dividend, mkt breakdown, deriv futures, deriv options
Add-on	eq minute, eq trades（需要订购分钟线・逐笔数据专用附加组件）
Add-on	td list, td files, td bulk（需要订购 TDnet/及时披露信息附加组件）

**套餐层级：**Free < Light < Standard < Premium（高级套餐包含所有低级套餐的 API）

**Free 套餐的限制：**无法下载 CSV/批量数据（mkt calendar 除外）。仅限 API 访问。数据仅限于「12 周前至 2 年 12 周前」的时间窗口（无法获取最近 12 周和 2 年以前的历史数据）。

可获取期间和数据范围的详细信息请参阅 references/plans.md。

Data Freshness（更新时间）

J-Quants API 的数据会在市场事件发生后陆续更新。当前时间与更新时间的关系会影响可获取数据的新鲜度。

按时段划分的更新摘要（JST）

预计更新时间	更新的数据
〜10:05	财报发布日期（fins earnings-date）更新为当天已公布的数据
〜12:00	当天前场四本值（eq am）更新
〜16:30	当天股价四本值、分钟线、逐笔数据、指数、卖空比例、融资余额（日次）更新
〜17:30	股票主数据、卖空余额报告更新
〜18:00	交易明细、投资部门分类（周次）、财务信息（速报）更新
〜19:00	财报发布日期（仅 3 月和 9 月期，eq earnings-calendar）更新（不定期，与 JPX 联动）
随时	EDINET 文件来源的数据（edinet 系列）在披露发生后立即反映（工作日 8:00〜17:59）
〜24:30	财务信息（定报）、财务报表（定报）更新
〜27:00	衍生品（期货、期权）当天的数据更新（27:00 = 次日 3:00 AM）

エージェント判断の指針

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

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

Common Pitfalls

誤り	正しい書き方	なぜ
eq daily --code X --output csv	--output csv eq daily --code X	clap がサブコマンド後のフラグをサブコマンドのオプションとして解析するため
--save out.csv eq daily（output 未指定）	--output csv --save out.csv eq daily	table 形式は --save 非対応。保存には csv/json/parquet を明示する
mkt short-ratio --code 0050	mkt short-ratio --s33 0050	short-ratio は銘柄ではなく33業種分類でフィルタする API 設計のため
mkt short-sale-report --date 2024-08-01	--disc-date または --calc-date を使う	公表日と計算日は別概念。--date フラグは存在しない
eq daily --date 2026-03（月のみ）	--date は YYYY-MM-DD 形式	月指定は bulk 系のみ対応。個別 API は日単位
全銘柄ループで eq daily --code X を繰り返す	bulk get --endpoint /equities/bars/daily --date YYYY-MM --download	API rate limit 回避 & 効率。1ファイルで全銘柄取得可能
--output parquet eq daily（--save 未指定）	--output parquet --save out.parquet eq daily	Parquet はストリーミング出力できないため、ファイル保存が必須
-f date,code（小文字のフィールド名）	-f Date,Code（jquants schema <endpoint> で確認）	API フィールド名は PascalCase。大文字小文字を区別する
fins details でテーブル表示すると FS が "N items" になる	--output json fins details を使う	FS フィールドはネストされた JSON オブジェクト。テーブル表示では要約される
429 を受けてすぐリトライする	数十秒〜数分待機してから再試行する	大幅超過が続くと約5分間遮断される。即時リトライは遮断を長引かせる
Free プランで bulk get や --output csv を使う	個別 API（eq daily --code X）を使う、または上位プランへアップグレードを促す	Free プランは CSV/バルクダウンロード非対応（mkt calendar を除く）。API のみ利用可能
Light プランで idx daily や deriv options-225 を使う	Standard プランが必要である旨を伝える	Standard 以上が必要な API。プランとコマンドの対応は references/plans.md を参照
16:00に eq daily で「今日の株価」を取得して最新と思い込む	「16:30頃に当日分が反映されます。現時点では前営業日のデータです」と伝える	株価四本値は16:30頃に当日分が更新される。更新前は前営業日のデータが最新
mkt margin-interest --published-date X --date Y のように公表日と申込日付を同時指定する	--published-date 単独（--code との併用は可）にする	公表日と申込日付（--date/--from/--to）は排他。2026-09-25 申込分以降は毎営業日 16:00頃に前営業日分が反映される日次データ。2026-09-24 以前は週末時点のデータのみで、PubDate と金額 6 項目は null