取得データのローカル保存とキャッシュ戦略 | 生成AIxPythonで始める株式分析|Python×J-Quants

J-Quants の API は便利ですが、毎回フルで叩くとレート制限に当たり、時間もかかります。本記事では、取得データを Parquet と SQLite でローカル保存し、必要な分だけ差分取得する設計の考え方を整理します。

キャッシュの全体像

設計の方向性は、データの性質によって変えます。

データ	更新頻度	推奨フォーマット
銘柄一覧(`/equities/master`)	日次〜数日	Parquet(スナップショット単位)
日次株価(`/equities/bars/daily`)	日次(営業日終了後)	Parquet(銘柄 × 月)+ メタ管理
財務情報(`/fins/summary`)	不定期(開示時)	SQLite(クエリ性が要る場合)

「読み込みの速さと圧縮率」を重視するなら Parquet、「条件絞り込みのクエリ性」を重視するなら SQLite が無難です。

ディレクトリ構成の例

整理しやすい構成の例です。実プロジェクトでは合うように変えてください。

data/jquants/
  listed/
    listed_info_2026-05-11.parquet
  prices/
    7203/
      7203_2024.parquet
      7203_2025.parquet
    9984/
      9984_2024.parquet
  statements.sqlite
  meta.json          # 最終更新日などのメタ情報

銘柄ごと・年ごとにファイルを分けると、追記時の I/O が小さく済みます。

Parquet で日次株価を保存する

Parquet は列志向で、pandas との相性が良いフォーマットです。pyarrow か fastparquet のどちらかが入っていれば使えます。

1
from pathlib import Path
2
import pandas as pd
3

4

5
def save_prices(df: pd.DataFrame, code: str, base_dir: Path) -> None:
6
    """銘柄ごと・年ごとに分けて Parquet で保存する。"""
7
    if df.empty:
8
        return
9
    df = df.copy()
10
    df["Date"] = pd.to_datetime(df["Date"])
11
    df["year"] = df["Date"].dt.year
12
    out_dir = base_dir / code
13
    out_dir.mkdir(parents=True, exist_ok=True)
14
    for year, group in df.groupby("year"):
15
        path = out_dir / f"{code}_{year}.parquet"
16
        # 既存ファイルがあるなら結合して重複除去
17
        if path.exists():
18
            existing = pd.read_parquet(path)
19
            merged = pd.concat([existing, group], ignore_index=True)
20
            merged = merged.drop_duplicates(subset=["Date", "Code"], keep="last")
21
        else:
22
            merged = group
23
        merged = merged.sort_values("Date").drop(columns=["year"])
24
        merged.to_parquet(path, index=False)
25

26

27
base_dir = Path("data/jquants/prices")
28
# save_prices(prices, "7203", base_dir)

関連ページ: #6-5「日次株価四本値を取得する」

drop_duplicates を入れておくと、再取得時の重複を防げます。

差分更新の設計

毎回フルで取らずに「最終取得日 → 今日まで」だけ取得する流れです。

1
import json
2
from datetime import date, timedelta
3
from pathlib import Path
4

5
META_PATH = Path("data/jquants/meta.json")
6

7

8
def load_meta() -> dict:
9
    if META_PATH.exists():
10
        return json.loads(META_PATH.read_text(encoding="utf-8"))
11
    return {}
12

13

14
def save_meta(meta: dict) -> None:
15
    META_PATH.parent.mkdir(parents=True, exist_ok=True)
16
    META_PATH.write_text(json.dumps(meta, ensure_ascii=False, indent=2), encoding="utf-8")
17

18

19
def update_prices(api_key: str, code: str, today: date, base_dir: Path) -> None:
20
    """code の最終取得日から today までを取って保存する。"""
21
    meta = load_meta()
22
    last_date_str = meta.get("prices", {}).get(code)
23

24
    # 最終取得日の翌日から開始(なければ十分に古い日付)
25
    if last_date_str:
26
        date_from = (date.fromisoformat(last_date_str) + timedelta(days=1)).isoformat()
27
    else:
28
        date_from = "2020-01-01"
29

30
    if date_from > today.isoformat():
31
        return  # 取得不要
32

33
    df = fetch_daily_quotes(api_key, code, date_from, today.isoformat())
34
    if df.empty:
35
        return
36
    save_prices(df, code, base_dir)
37

38
    meta.setdefault("prices", {})[code] = today.isoformat()
39
    save_meta(meta)

関連ページ: #6-5「日次株価四本値を取得する」

ポイントは次の 2 点です。

メタファイル(meta.json)に銘柄ごとの最終取得日を残す
取得範囲は 最終取得日の翌日から今日まで に絞る

これだけでも、フル取得との通信量・時間に大きな差が出ます。

全銘柄保存と日付単位ファイル

「指定日の全銘柄」を取りに行くなら、日付ごとにファイルを分けるのが便利です。

data/jquants/prices_by_date/
  2024-01-04.parquet
  2024-01-05.parquet
  ...

新しい日が増えるだけで、過去ファイルは触らずに済みます。バックアップや差分同期も楽です。

SQLite で財務情報を保存する

財務情報は「特定の銘柄の特定期だけ取り出す」「業種で絞る」のようなクエリが入りがちです。SQLite に入れておくと、SQL で扱いやすくなります。

1
import sqlite3
2
import pandas as pd
3
from pathlib import Path
4

5

6
def save_statements(statements: pd.DataFrame, db_path: Path) -> None:
7
    """財務情報を SQLite に追記する(主キーで重複を弾く)。"""
8
    conn = sqlite3.connect(db_path)
9
    try:
10
        conn.execute(
11
            """
12
            CREATE TABLE IF NOT EXISTS statements (
13
                Code TEXT,
14
                DiscDate TEXT,
15
                DocType TEXT,
16
                CurPerType TEXT,
17
                Sales REAL,
18
                OP REAL,
19
                NP REAL,
20
                EPS REAL,
21
                Eq REAL,
22
                TA REAL,
23
                PRIMARY KEY (Code, DiscDate, DocType)
24
            )
25
            """
26
        )
27
        cols = [
28
            "Code", "DiscDate", "DocType", "CurPerType",
29
            "Sales", "OP", "NP", "EPS",
30
            "Eq", "TA",
31
        ]
32
        existing = [c for c in cols if c in statements.columns]
33
        records = statements[existing].to_dict(orient="records")
34
        placeholders = ", ".join("?" for _ in existing)
35
        sql = f"INSERT OR REPLACE INTO statements ({', '.join(existing)}) VALUES ({placeholders})"
36
        conn.executemany(sql, [tuple(r.get(c) for c in existing) for r in records])
37
        conn.commit()
38
    finally:
39
        conn.close()

INSERT OR REPLACE を使えば、同じ主キー(銘柄 × 開示日 × 文書種別)で再取得した行を上書きできます。

クエリ例です。

1
def query_fy(code: str, db_path: Path) -> pd.DataFrame:
2
    """通期(FY)決算だけを取り出す。"""
3
    conn = sqlite3.connect(db_path)
4
    try:
5
        return pd.read_sql_query(
6
            """
7
            SELECT *
8
            FROM statements
9
            WHERE Code = :code
10
              AND CurPerType = 'FY'
11
            ORDER BY DiscDate
12
            """,
13
            conn,
14
            params={"code": code},
15
        )
16
    finally:
17
        conn.close()

キャッシュの一貫性

ローカルキャッシュを長く使うと、次のような不整合が起きやすくなります。

株式分割があり、過去の調整済み終値の値が変わる
決算修正の再開示で、過去の EPS が変わる
業種コードや市場区分の改定が反映されていない

対策の方向性は次のとおりです。

対策	説明
整合性チェック	直近 N 日分は再取得して一致を確認
完全再構築モード	コマンドラインオプションで「全消去 → 全取得」を選べるように
更新ログ	何を、いつ、どこまで取得したかを残す(`meta.json` の拡張)

少なくとも、月に 1 回は完全再構築するスケジュールを組んでおくと安全です。

注意点

ファイル容量が大きくなりやすいため、Parquet の圧縮(snappy / zstd)は有効化しておく
バックアップを取るかどうかを設計時点で決める(クラウドストレージ・別ディスク等)
個人情報・認証情報は キャッシュしない(API キーは環境変数管理のまま。キャッシュ対象はあくまで取得データ)
共有マシンで使う場合は、キャッシュの保存場所のアクセス権を確認する

生成AI へのプロンプト例

差分更新ジョブを生成する例です。

J-Quants API の銘柄一覧と日次株価を、以下の方針でローカルに保存・更新する
Python スクリプトを書いてください。

要件:
- 認証は API キーを環境変数 JQUANTS_API_KEY から読み、x-api-key ヘッダに乗せる
- 銘柄一覧は data/jquants/listed/listed_info_<日付>.parquet として保存
- 日次株価は銘柄ごと・年ごとに data/jquants/prices/<code>/<code>_<年>.parquet
- meta.json に銘柄ごとの最終取得日を残し、差分のみ取得
- 取得失敗時は指数バックオフで 3 回までリトライ
- pandas 2.2 系の API を使う
- 関数は適切に分割し、main() でまとめる

まとめ

銘柄一覧 / 日次株価は Parquet、財務情報は SQLite が扱いやすい
差分更新には「最終取得日」のメタ管理が必須
株式分割や決算修正で過去データが変わるため、定期的な再構築を組み込む
認証情報はキャッシュ対象に含めず、環境変数で管理する

目次