Japan's Stock Exchange Has an Official API for Individuals. Almost Nobody Outside Japan Knows About It.

#python #finance #datascience #api

A practical developer's guide to J-Quants — the Japan Exchange Group's official market data API — from someone who has been running backtests and a daily pipeline on it for months.

If you've ever tried to analyze the Japanese stock market programmatically from outside Japan, you know the data situation looks hostile. Bloomberg is enterprise money. yfinance gives you prices but its Japanese fundamentals are patchy. Most tutorials just tell you to trade the US market instead.

Here's what almost nobody writes about in English: the Tokyo Stock Exchange's parent company (JPX) runs an official data API for individual investors, and the free tier is genuinely useful. It's called J-Quants, it has an English version of the site, and I've been using it for months as the backbone of a rule-based research pipeline (the build log is here).

This is the guide I wish had existed when I started.

What you get, and what it costs

Plan	Price/month	History	Catch
Free	¥0	2 years	12-week delay on data
Light	¥1,650 (~$11)	5 years	—
Standard	¥3,300 (~$22)	10 years	—
Premium	¥16,500 (~$110)	20 years	—

The 12-week delay on the free tier sounds disqualifying until you realize what it's actually for: backtesting. Historical research doesn't care about the delay. For live tracking I fill the gap with yfinance — delayed official data for the heavy lifting, free real-ish-time quotes for marking to market. That combination costs ¥0.

One thing to check before you build anything: the license is personal use. No redistribution, no commercial resale of the data. Build your own research tools, not a public data product.

The API in three endpoints

The current version (V2) uses plain API-key auth — a x-api-key header, no token-refresh dance. The three endpoints I use daily:

/v2/equities/master — all listed companies: code, name, market segment, sector, size classification
/v2/equities/bars/daily — daily OHLCV
/v2/fins/summary — financial statements, including company-issued forecasts (more on why that's special below)

A minimal client that handles the two things the docs won't hold your hand through — pagination and rate limits:

import time, requests

API = "https://api.jquants.com/v2"
HEADERS = {"x-api-key": YOUR_KEY}

def get_all(path: str, params: dict | None = None) -> list[dict]:
    """Follow pagination_key until exhausted; back off on 429s."""
    params, rows, data_key = dict(params or {}), [], None
    while True:
        for attempt in range(5):                      # 429 -> exponential backoff
            r = requests.get(f"{API}{path}", headers=HEADERS,
                             params=params, timeout=60)
            if r.status_code == 429:
                time.sleep(1.5 * (attempt + 1) ** 2)
                continue
            break
        r.raise_for_status()
        j = r.json()
        if data_key is None:                          # payload key varies by endpoint
            data_key = next(k for k in j if k != "pagination_key")
        rows.extend(j[data_key])
        if not j.get("pagination_key"):
            return rows
        params["pagination_key"] = j["pagination_key"]

Two production notes baked into that snippet:

The payload key changes per endpoint (bars, summary, …), so detect it instead of hardcoding.
Throttle yourself. I keep a minimum 250ms between requests on top of the backoff; full-universe pulls run for a while and the API will 429 you without it.

The feature US-market people don't believe: company-issued guidance

Here's the structurally interesting part. Japanese listed companies publish their own earnings forecasts as part of standard disclosure — next fiscal year's revenue, operating profit, EPS, straight from management, machine-readable in /v2/fins/summary.

If you've only worked with US data, let that sink in: no scraping analyst consensus, no paying a vendor for estimates. The company itself tells you what it expects, updates it when things change, and the exchange serves it to you in JSON.

This enables research that's genuinely hard to do cheaply elsewhere. My own use: post-earnings drift studies keyed on guidance revisions (did management raise the forecast?) and value screens using forward EPS from the source rather than trailing numbers. Whether those strategies survive scrutiny is a separate question — mine mostly didn't — but the data access is remarkable for ¥0.

Gotchas from months of production use

Cache aggressively, including empty responses. My first full-universe backtest spent half its runtime re-requesting data that legitimately didn't exist (delisted names, holidays, pre-IPO dates). The fix that mattered wasn't caching hits — it was caching misses:

def fetch_cached(key: str, fetch_fn):
    path = CACHE_DIR / f"{key}.parquet"
    if path.exists():
        df = pd.read_parquet(path)
        return None if df.empty else df       # cached "nothing" is an answer too
    df = fetch_fn()
    df.to_parquet(path)                       # persist even when empty
    return None if df.empty else df

Corporate actions will bite your event studies. Stock splits show up in disclosures; if you join fundamentals to prices naively, a 1:3 split looks like earnings collapsing by two-thirds. Adjust before you celebrate a "signal."

Guard against one-off earnings spikes. Company forecasts make forward-valuation screens easy, but a company selling its headquarters building looks spectacularly "cheap" for exactly one year. My screens exclude implausible earnings yields — if it looks too good, it's usually an asset sale, not a business.

Free-tier delay shapes your architecture. Twelve weeks of delay means the free tier can't tell you about this quarter. Design around it: J-Quants for research and screening, a real-time source for execution-time prices. Keeping those two concerns in separate modules made this painless.

Is it worth it?

For anyone who wants to do serious, reproducible research on a major market without a data budget: yes, emphatically. An official exchange API with fundamentals and management guidance, a usable free tier, pandas-friendly JSON, and an English site — I don't know of an equivalent offer from any other major exchange.

The Japanese market itself is having a moment with international investors. The tooling to study it properly is sitting right there, mostly undocumented in English. Now you know.

I use J-Quants under its personal-use license for my own research. Nothing here is investment advice. If you build something with it, I'd genuinely like to hear about it in the comments.

DEV Community