Role & Decision Flow
When building a jquants command, decide in the following order:
- Determine the data type — stocks (eq), market (mkt), derivatives (deriv), EDINET documents (edinet), financials (fins), indices (idx)
- Check plan restrictions — Check whether it is available on the user's plan (see "Subscription Plans & API Availability" below). If the plan is unknown, present the command while clearly stating the required plan
- Check field names —
-fbefore narrowing down withjquants schema <endpoint>look up the exact names with - Choose individual API vs bulk — If any of "all issues", "one month or more", or "large volume" applies → bulk (see references/commands-bulk.md). Repeatedly calling individual APIs in large numbers will hit rate limits (see Rate Limits below).The Free plan cannot use CSV/bulk（
mkt calendarexcept) - Assemble the command — Place global options (
--output,--save,-f) before the subcommand - Consider pipes — If there is a pipe destination, simply omit
--outputand CSV will flow automatically
Prerequisites
Recommended: jquants login browser login (automatically obtains and saves the API key)
jquants login # ブラウザが開き、Cognito OAuth2 PKCE でログイン
# → ~/.config/jquants/credentials.json に API キーを自動保存
Fallback: specify directly via environment variable
export JQUANTS_API_KEY="your-api-key"
# または .env ファイルに記載
Authentication priority: ~/.config/jquants/credentials.json の api_key → JQUANTS_API_KEY environment variable → error (jquants login prompt)
**
jquants schemadoes not require authentication. **It can be used to check field names even before logging in.
Command Syntax Rules
Global options (--output, --save, -f) are placed before the subcommand:
# ✅ 正しい
jquants --output csv --save out.csv eq daily --code 86970
# ❌ 誤り（サブコマンド後は無効）
jquants eq daily --code 86970 --output csv
Why: Due to clap's design, flags after the subcommand are parsed as the subcommand's own options. If placed after the subcommand, it results in an "unknown flag" error.
Automatic CSV switching when piping:
If stdout is not a TTY (if there is a pipe destination),--output table(default) is automatically output in CSV format.
# パイプすると自動でCSVが流れる
jquants eq daily --code 86970 | head -5
# 明示的にJSONをパイプしたい場合は指定が必要
jquants --output json eq daily --code 86970 | jq '.[] | .AdjustmentClose'
Narrow down columns with field selection (--fields / -f):
# 日付・コード・調整済終値だけを取得
jquants -f Date,Code,AdjustmentClose eq daily --code 86970
# 不正なフィールド名を指定するとエラーで利用可能フィールド一覧が表示される
Schema-First: Checking field names
--fields Before narrowing down columns withjquants schema <endpoint> check the exact field names with
jquants schema # 全エンドポイント一覧（キー・説明・フィールド数）
jquants schema eq.daily # eq.daily の全フィールド（名前・型・説明）
jquants --output json schema # JSON 形式で出力
Endpoint keys are in the カテゴリ.コマンド format (e.g., eq.daily, fins.summary, mkt.short-ratio）。
Steps:
jquants schema eq.dailyGet the field list with- Copy the required field names and specify them in
-fspecify in -f - Invalid field names are rejected with an error (a list of available fields is displayed)
Quick Reference
Authentication & Utilities
| What you want to do | Command |
|---|---|
| Login (initial setup) | jquants login |
| Logout | jquants logout |
| Check the list of API fields | jquants schema |
| Field details for a specific endpoint | jquants schema eq.daily |
Stock data (eq)
| What you want to do | Command | Update time |
|---|---|---|
| All stock master | jquants eq master |
Daily around 17:30 |
| Stock price OHLC | jquants eq daily |
Daily around 16:30 |
| Valuation indicators | jquants eq valuation |
Daily around 16:30 |
| Morning session OHLC | jquants eq am |
Daily around 12:00 |
| Minute bar data | jquants eq minute |
Daily around 16:30 |
| Investor-type trading status | jquants eq investor-types |
Weekly (Thu) around 18:00 |
| Earnings announcement scheduled date | jquants eq earnings-calendar |
Irregular around 19:00 |
| Stock price tick | jquants eq trades |
Daily around 16:30 |
Market data (mkt)
| What you want to do | Command | Update time |
|---|---|---|
| Trading breakdown | jquants mkt breakdown |
Daily around 18:00 |
| Daily published margin balance | jquants mkt margin-alert |
Daily around 16:30 |
| Margin trading balance | jquants mkt margin-interest |
Daily around 16:00 |
| Trading calendar | jquants mkt calendar |
Irregular |
| Short selling ratio by industry | jquants mkt short-ratio |
Daily around 16:30 |
| Short selling balance report | jquants mkt short-sale-report |
Daily around 17:30 |
Derivatives (deriv)
| What you want to do | Command | Update time |
|---|---|---|
| Futures OHLC | jquants deriv futures |
Daily around 27:00 |
| Options OHLC | jquants deriv options |
Daily around 27:00 |
| Nikkei 225 options | jquants deriv options-225 |
Daily around 27:00 |
EDINET document-derived data (edinet) * Standard plan or higher
| What you want to do | Command | Update time |
|---|---|---|
| Major shareholder status (annual report) | jquants edinet major-shareholders |
As needed (weekdays 8:00–17:59) |
| Policy-held shares (annual report) | jquants edinet cross-shareholdings |
As needed (weekdays 8:00–17:59) |
| Large shareholding report | jquants edinet large-volume-shareholders |
As needed (weekdays 8:00–17:59) |
Financial data (fins)
| What you want to do | Command | Update time |
|---|---|---|
| Financial statements | jquants fins details |
Daily around 18:00 (preliminary) / around 24:30 (final) |
| Dividend information | jquants fins dividend |
Daily around 12:00–19:00 |
| Earnings announcement scheduled date | jquants fins earnings-date |
Daily around 10:05 |
| Financial information summary | jquants fins summary |
Daily around 18:00 (preliminary) / around 24:30 (final) |
Index data (idx)
| What you want to do | Command | Update time |
|---|---|---|
| TOPIX index OHLC prices | jquants idx daily-topix |
Daily around 16:30 |
| Index OHLC prices | jquants idx daily |
Daily around 16:30 |
Timely disclosure (td) * TDnet/timely disclosure information add-on required
| What you want to do | Command | Update time |
|---|---|---|
| Timely disclosure index list | jquants td list |
Updated as needed |
| Timely disclosure file URL retrieval | jquants td files |
Updated as needed |
| Timely disclosure bulk download URL retrieval | jquants td bulk |
Daily around 26:00 |
Category Reference Files
Detailed command syntax, flags, and examples for each category are described in the reference files.If the information in the Quick Reference is sufficient, there is no need to read the reference.
Refer to the reference in the following cases:
| Category | Reference | Situations in which to refer |
|---|---|---|
| eq | references/commands-eq.md | Stock code, date, period filters,eq trades special behavior of |
| mkt | references/commands-mkt.md | --s33, --disc-date/--calc-date special flags such as |
| deriv | references/commands-deriv.md | --category, --contract-flag how to use |
| edinet | references/commands-edinet.md | Handling of nested items, exclusivity of edinet_code/code, individual specifications of the 3 commands |
| fins | references/commands-fins.md | fins details FS field of (JSON output required),fins earnings-date exclusive query of |
| idx | references/commands-idx.md | Index code specification, TOPIX |
| bulk | references/commands-bulk.md | Bulk DL criteria, workflow, endpoint list |
| td | references/commands-td.md | --cursor real-time polling by,--download how to use, file name conventions |
| plans | references/plans.md | API availability by plan, available period, add-on information |
| schedule | references/data-update-schedule.md | When you need to judge data freshness, details of update timing, or judgment examples by scenario |
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
Stock price trend analysis for a specific stock
# 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
Monthly data retrieval for all stocks (bulk)
# 個別APIでループしない。全銘柄は bulk を使う。
jquants bulk get --endpoint /equities/bars/daily --date 2026-03 --download
# 解凍して CSV として利用
gunzip *.gz
Retrieval of financial information
# 配当情報（期間指定）
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 internally uses the bulk API
eq trades differs from other eq commands in that it internally /equities/trades calls the bulk API of. Therefore:
--codeflag cannot be used--date YYYY-MMformat month specification is possible (individual API'sYYYY-MM-DDdiffers from)--downloadsave the file to the current directory with the flag
jquants eq trades --date 2025-12 # URL取得のみ
jquants eq trades --date 2025-12 --download # ファイルダウンロード
FS field of fins details
fins details The FS (Financial Statement) field of is a nested JSON object. In table display, it is abbreviated as "N items" .To retrieve complete data, use --output json .
deriv の --contract-flag
--contract-flag 1 retrieves only the front-month contract (the most actively traded contract). If omitted, data for all contract months is returned.deriv futures と deriv options Can be used with both of.
Rate Limits
The J-Quants API has a per-minute request limit set for each plan. By designing commands with the limit in mind, you can avoid unnecessary blocking.
Plan-specific limits (requests/minute)
| Plan | Limit |
|---|---|
| Free | 5 |
| Light | 60 |
| Standard | 120 |
| Premium | 500 |
Add-on-specific limits (applied independently of the plan)
| Add-on | Limit |
|---|---|
| Stock prices: minute bars and ticks | 60 |
| TDnet/timely disclosure information | 100 |
Behavior when limits are exceeded
- HTTP
429 Too Many Requestsis returned - If a large excess continues,for about 5 minutesaccess is completely blocked (immediate retries are counterproductive)
Key points for avoidance
- Do not use individual loops over all stocks × all dates —
bulk getfetch all stocks in one request with - Do not retry immediately upon receiving a 429 — wait for a while (tens of seconds to several minutes) before retrying
- Narrow down with query parameters — reduce unnecessary fields and date ranges, and retrieve all necessary data in one request
Subscription Plans & API Availability
Access availability and retrievable periods differ by plan for each API. Check the plan limits before suggesting commands. If the plan is unknown, present the command while specifying the required plan.
Minimum required plan quick reference
| Minimum required plan | CLI command |
|---|---|
| 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(a dedicated minute bar/tick add-on contract is required) |
| Add-on | td list, td files, td bulk(a TDnet/timely disclosure information add-on contract is required) |
Plan hierarchy: Free < Light < Standard < Premium (higher plans include all APIs of lower plans)
Free plan limits: CSV/bulk download not available (excluding
mkt calendar). API access only. Data is limited to the window from 12 weeks ago to 2 years and 12 weeks ago (the latest 12 weeks and past data older than 2 years cannot be retrieved).
For detailed retrievable periods and data ranges, see references/plans.md .
Data Freshness (update timing)
J-Quants API data is updated sequentially after market events.The relationship between the current time and the update timechanges the freshness of the data that can be retrieved.
Update summary by time period (JST)
| Approximate update time | Data reflected |
|---|---|
| 〜10:05 | Earnings announcement scheduled dates (fins earnings-date) are updated to the current day's published data |
| 〜12:00 | Morning session OHLC (eq am) is updated to the current day's data |
| 〜16:30 | Stock price OHLC, minute bars, ticks, indices, short selling ratio, and margin balances (daily) are updated to the current day's data |
| 〜17:30 | Issue master and short selling balance reports are updated |
| 〜18:00 | Trading breakdown, investor categories (weekly), and financial information (preliminary) are updated |
| 〜19:00 | Earnings announcement scheduled dates (March and September fiscal year-ends only,eq earnings-calendar) are updated (irregular, linked to JPX) |
| As needed | Data derived from EDINET documents (edinet system) is reflected as soon as disclosure occurs (weekdays 8:00–17:59) |
| 〜24:30 | Financial information (final figures) and financial statements (final figures) are updated |
| 〜27:00 | Derivatives (futures/options) are updated with the current day's data (27:00 = 3:00 AM the next day) |
Guidelines for agent judgment
- If asked for the current day's data before the update time: Say, "The current day's data will be reflected around XX:XX. At this point, the previous business day's data is the latest."
- Weekly data (by investor type): For investor type, the guideline for updates is Thursday 18:00. On other days of the week, the previous week's data is the latest. Margin trading balances (
mkt margin-interest) are daily (around 16:00 every business day) for applications on or after 2026-09-25 - Derivatives are updated at 27:00 (3:00 AM the next day): The previous day's data is not complete until early morning of the next business day
- When told "the data is old": Check the update time, weekly cycle, holidays, and plan period restrictions in that order
For detailed judgment flow and scenario examples, see references/data-update-schedule.md .
Common Pitfalls
| Incorrect | Correct way to write | Why |
|---|---|---|
eq daily --code X --output csv |
--output csv eq daily --code X |
Because clap parses flags after the subcommand as options of the subcommand |
--save out.csv eq daily(output not specified) |
--output csv --save out.csv eq daily |
The table format is not supported by --save . To save, explicitly specify csv/json/parquet |
mkt short-ratio --code 0050 |
mkt short-ratio --s33 0050 |
Because short-ratio is an API design that filters by the 33 industry categories, not by stock |
mkt short-sale-report --date 2024-08-01 |
--disc-date or --calc-date use |
Publication date and calculation date are different concepts.--date flag does not exist |
eq daily --date 2026-03(month only) |
--date is in YYYY-MM-DD format |
Month specification is supported only for bulk APIs. Individual APIs are by day |
In a loop over all stocks, eq daily --code X repeat |
bulk get --endpoint /equities/bars/daily --date YYYY-MM --download |
Avoid API rate limits & efficiency. All stocks can be fetched in one file |
--output parquet eq daily（--save not specified) |
--output parquet --save out.parquet eq daily |
Parquet cannot be streamed, so file saving is required |
-f date,code(lowercase field names) |
-f Date,Code（jquants schema <endpoint> check with) |
API field names are PascalCase. Case-sensitive |
fins details When displayed as a table with "N items" becomes |
--output json fins details use |
The FS field is a nested JSON object. It is summarized in table display |
| Retry immediately after receiving 429 | Wait several tens of seconds to several minutes before retrying | If the limit is greatly exceeded repeatedly, access is blocked for about 5 minutes. Immediate retries prolong the block |
On the Free plan, bulk get や --output csv use |
Use the individual API (eq daily --code X), or encourage upgrading to a higher plan |
The Free plan does not support CSV/bulk downloads (mkt calendar excluding). Available only via API |
With the Light plan, idx daily や deriv options-225 use |
Convey that the Standard plan is required | API requiring Standard or higher. For the correspondence between plans and commands, see references/plans.md |
16:00に eq daily obtain "today's stock price" and assume it is the latest |
Say "The current day's data is reflected around 16:30. At present, the data is from the previous business day" | The four stock price values are updated with the current day's data around 16:30. Before the update, the previous business day's data is the latest |
mkt margin-interest --published-date X --date Y specify both the publication date and the application date as in |
--published-date alone (--code use in combination with) is allowed |
The publication date and application date (--date/--from/--to) are mutually exclusive. For applications on or after 2026-09-25, daily data is reflected around 16:00 on each business day for the previous business day. For 2026-09-24 and earlier, only data as of the weekend is available, and PubDate and the 6 amount items are null |