J-Quants API Client for Python

The following environment is required for jquants-api-client:

• Python: 3.10 or higher.
• pandas: 2.2 or higher (supports pandas 3.x).

Note on pandas 3.x compatibility: If using pandas 3.x, the dtype of returned DataFrames may change:

• String columns: object $\rightarrow$ str
• Date columns: datetime64[ns] $\rightarrow$ datetime64[us]

If your processing logic depends on specific pandas dtypes, please account for these changes.

Install the library using pip to access the J-Quants API via Python.

pip install jquants-api-client

For a guided introduction to using the J-Quants API V2 and performing basic data retrieval with ClientV2, you can use the official Google Colab starter notebook. This notebook is executable and provides a step-by-step explanation of the client's usage.

https://colab.research.google.com/github/J-Quants/jquants-api-client-python/blob/master/examples/20260119-007-jquants-api-v2-starter.ipynb

The client requires an API key obtained from the J-Quants API Dashboard. You can provide the key in several ways. The configuration is loaded in the following order (later sources overwrite earlier ones):

1. /content/drive/MyDrive/drive_ws/secret/jquants-api.toml (Google Colab only)
2. ${HOME}/.jquants-api/jquants-api.toml
3. jquants-api.toml (local directory)
4. Environment variable JQUANTS_API_CLIENT_CONFIG_FILE (points to a config file)
5. Environment variable JQUANTS_API_KEY (direct key string)

To use a TOML configuration file, use the following format:

[jquants-api-client]
api_key = "YOUR_API_KEY"

[jquants-api-client]
api_key = "*****"

J-Quants API V2 uses an API key (x-api-key) for authentication. You can configure the ClientV2 class using one of the following three methods:

Method 1: Direct Argument

Pass the api_key directly to the ClientV2 constructor.

Method 2: Environment Variable

Set the JQUANTS_API_KEY environment variable. The client will automatically detect it.

Method 3: Configuration File

Create a jquants-api.toml file in ~/.jquants-api/ or the current directory with the following structure.

# Method 1: Direct Argument
cli = jquantsapi.ClientV2(api_key="your-api-key")

# Method 2: Environment Variable
# export JQUANTS_API_KEY="your-api-key"
cli = jquantsapi.ClientV2()

# Method 3: Configuration File (jquants-api.toml)
# [jquants-api-client]
# api_key = "your-api-key"

Install the J-Quants API Python client library using pip.

%pip install jquants-api-client

Methods ending in _range (e.g., get_eq_bars_daily_range, get_fin_summary_range) perform parallel API requests for the specified date range. This increases the risk of hitting rate limits.

If you exceed the rate limit, the API returns an HTTP 429 Too Many Requests error. To avoid this:

• Avoid very wide date ranges in a single call.
• Avoid executing multiple _range requests in a short period.
• If a 429 occurs, wait for a period before retrying or split the request into smaller date segments.

Use jquantsapi.ClientV2 to interact with the V2 API. You can pass the api_key directly to the constructor or rely on the JQUANTS_API_KEY environment variable. API responses are returned as pandas DataFrames.

from datetime import datetime
from dateutil import tz
import jquantsapi

# Using an explicit API key
my_api_key: str = "*****"
cli = jquantsapi.ClientV2(api_key=my_api_key)

# Fetching daily price range data
df = cli.get_eq_bars_daily_range(
    start_dt=datetime(2022, 7, 25, tzinfo=tz.gettz("Asia/Tokyo")),
    end_dt=datetime(2022, 7, 26, tzinfo=tz.gettz("Asia/Tokyo")),
)
print(df)

# Alternatively, if JQUANTS_API_KEY is set in environment variables:
# cli = jquantsapi.ClientV2()

Retrieve quarterly and annual financial results for listed companies.

Single Stock Summary

Use get_fin_summary(code="...") to get data for a specific company.

Range Summary with Caching

Use get_fin_summary_range() to fetch data over a period. You can provide a cache_dir argument to save the results locally. Subsequent calls will use the cache, reducing API consumption.

import os
from datetime import datetime, timedelta

# Single stock
df_fins = cli.get_fin_summary(code="86970")

# Range with caching
cache_dir = os.path.expanduser("~/.jquants/cache")
d_from = datetime.now() - timedelta(days=30)
d_to = datetime.now() - timedelta(days=1)

df_fins_range = cli.get_fin_summary_range(
    start_dt=d_from.strftime("%Y%m%d"),
    end_dt=d_to.strftime("%Y%m%d"),
    cache_dir=cache_dir
)

Retrieve daily stock price data for a specific stock code. The data includes adjusted prices (accounting for stock splits/mergers) and unadjusted prices.

Note: The code parameter typically requires a 5-digit string (e.g., 86970 for JPX).

# Get daily prices for a specific stock (e.g., JPX 8697)
df_price = cli.get_eq_bars_daily(code="86970")