適時開示関連のAPIを追加

jquantsapi/apis/base.py

@@ -3,8 +3,6 @@
 from abc import ABC, abstractmethod
 from typing import Any, Protocol
 
-import pandas as pd  # type: ignore
-
 
 class SupportsRequest(Protocol):
     """
@@ -37,7 +35,7 @@ class BaseApi(ABC):
     version: str
 
     @abstractmethod
-    def execute(self, client: SupportsRequest, **params: Any) -> pd.DataFrame:
+    def execute(self, client: SupportsRequest, **params: Any) -> Any:
         """
         実際に API を実行し、結果を DataFrame で返す。
 

jquantsapi/apis/v2/bulk.py

@@ -14,6 +14,7 @@ class BulkListApiV2(BaseApi):
     v2 の Bulk List API (`/bulk/list`) のラッパークラス。
 
     指定したエンドポイントで取得可能なデータ一覧を取得します。
+    `endpoint` または `date` のどちらかは必須です。
     """
 
     name = "bulk_list"
@@ -24,14 +25,22 @@ def execute(
         client: SupportsRequest,
         *,
         endpoint: Union[str, BulkEndpoint] = "",
+        date: str = "",
+        from_date: str = "",
+        to_date: str = "",
         **kwargs: Any,
     ) -> pd.DataFrame:
         """
         v2 `/bulk/list` を実行し、取得可能なデータ一覧を DataFrame で返す。
 
         Args:
             client: v2 `ClientV2` インスタンスを想定
-            endpoint: 取得したいデータのエンドポイント (例: "/equities/master")
+            endpoint: 取得したいデータのエンドポイント (例: "/equities/master")。
+                      `date` と排他的に使用します。
+            date: 対象日付 (YYYY-MM, YYYYMM, YYYY-MM-DD, YYYYMMDD)。
+                  `endpoint` と排他的に使用します。
+            from_date: 取得期間の開始日。`endpoint` 指定時のみ使用可能。
+            to_date: 取得期間の終了日。`endpoint` 指定時のみ使用可能。
         """
         url = f"{client.JQUANTS_API_BASE}/bulk/list"
 
@@ -40,7 +49,15 @@ def execute(
             endpoint.value if isinstance(endpoint, BulkEndpoint) else endpoint
         )
 
-        params: dict[str, Any] = {"endpoint": endpoint_str}
+        params: dict[str, Any] = {}
+        if endpoint_str:
+            params["endpoint"] = endpoint_str
+        if date:
+            params["date"] = date
+        if from_date:
+            params["from"] = from_date
+        if to_date:
+            params["to"] = to_date
 
         resp = client._get(url, params)  # type: ignore[arg-type]
         payload = resp.json()
@@ -73,21 +90,36 @@ def execute(
         client: SupportsRequest,
         *,
         key: str = "",
+        endpoint: Union[str, BulkEndpoint] = "",
+        date: str = "",
         **kwargs: Any,
     ) -> str:
         """
         v2 `/bulk/get` を実行し、ダウンロードURLを取得する。
 
         Args:
             client: v2 `ClientV2` インスタンスを想定
-            key: BulkListで取得したKey
+            key: BulkListで取得したKey。`endpoint` + `date` と排他的に使用します。
+            endpoint: 取得するデータのエンドポイント名。`date` と組み合わせて使用します。
+            date: 対象日付 (YYYY-MM, YYYYMM, YYYY-MM-DD, YYYYMMDD)。`endpoint` と組み合わせて使用します。
 
         Returns:
             str: ダウンロードURL
         """
         url = f"{client.JQUANTS_API_BASE}/bulk/get"
 
-        params: dict[str, Any] = {"key": key}
+        # BulkEndpointの場合はvalue(str)を取得
+        endpoint_str = (
+            endpoint.value if isinstance(endpoint, BulkEndpoint) else endpoint
+        )
+
+        params: dict[str, Any] = {}
+        if key:
+            params["key"] = key
+        if endpoint_str:
+            params["endpoint"] = endpoint_str
+        if date:
+            params["date"] = date
 
         resp = client._get(url, params)  # type: ignore[arg-type]
         payload = resp.json()

jquantsapi/apis/v2/td.py

@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+
+import pandas as pd  # type: ignore
+
+from jquantsapi import constants
+from jquantsapi.apis.base import BaseApi, SupportsRequest
+
+
+class TdListApiV2(BaseApi):
+    """
+    v2 の TDnet/適時開示インデックス一覧 API (`/td/list`) のラッパークラス。
+
+    `date` または `code` のどちらかは必須です。
+    """
+
+    name = "td_list"
+    version = "v2"
+
+    def execute(
+        self,
+        client: SupportsRequest,
+        *,
+        date: str = "",
+        code: str = "",
+        from_date: str = "",
+        to_date: str = "",
+        disc_items: str = "",
+        cursor: str = "",
+        **kwargs: Any,
+    ) -> tuple[pd.DataFrame, Optional[str]]:
+        """
+        v2 `/td/list` を実行し、(適時開示インデックス一覧, cursor) を返す。
+
+        pagination_key が返された場合は自動的に全件取得します。
+        cursor はレスポンスの最終ページに含まれる場合に返却されます（含まれない場合は None）。
+
+        Args:
+            client: v2 `ClientV2` インスタンスを想定
+            date: 開示日 (YYYYMMDD or YYYY-MM-DD)。`code` と排他的に使用します。
+            code: 銘柄コード。`date` と排他的に使用します。
+            from_date: 取得開始日。`code` と組み合わせて使用します。
+            to_date: 取得終了日。`code` と組み合わせて使用します。
+            disc_items: 公開項目コード（カンマ区切りで複数指定可能）。
+            cursor: 前回レスポンスで返却された cursor。差分取得に使用します。
+                    `pagination_key` と同時指定不可。
+        Returns:
+            tuple[pd.DataFrame, Optional[str]]:
+                - DataFrame: 取得した開示一覧
+                - cursor: レスポンスに含まれる cursor（含まれない場合は None）
+        """
+        url = f"{client.JQUANTS_API_BASE}/td/list"
+
+        params: dict[str, Any] = {}
+        if date:
+            params["date"] = date
+        if code:
+            params["code"] = code
+        if from_date:
+            params["from"] = from_date
+        if to_date:
+            params["to"] = to_date
+        if disc_items:
+            params["discItems"] = disc_items
+        if cursor:
+            params["cursor"] = cursor
+
+        all_data: list[dict[str, Any]] = []
+        returned_cursor: Optional[str] = None
+        query = dict(params)
+
+        while True:
+            resp = client._get(url, query)  # type: ignore[arg-type]
+            payload = resp.json()
+            all_data.extend(payload.get("data", []))
+            returned_cursor = payload.get("cursor")
+
+            pagination_key = payload.get("pagination_key")
+            if not pagination_key:
+                break
+            query["pagination_key"] = pagination_key
+
+        cols = constants.TD_LIST_COLUMNS_V2
+        if not all_data:
+            return pd.DataFrame(columns=cols), returned_cursor
+
+        df = pd.DataFrame.from_records(all_data)
+        if "DiscDate" in df.columns:
+            df["DiscDate"] = pd.to_datetime(df["DiscDate"], errors="coerce")
+
+        return df[cols].reset_index(drop=True), returned_cursor
+
+
+class TdFilesApiV2(BaseApi):
+    """
+    v2 の TDnet/適時開示ファイル取得 API (`/td/files`) のラッパークラス。
+
+    開示番号に対応するファイルのダウンロードURLを取得します。
+    """
+
+    name = "td_files"
+    version = "v2"
+
+    def execute(
+        self,
+        client: SupportsRequest,
+        *,
+        disc_no: str = "",
+        docs: str = "",
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        """
+        v2 `/td/files` を実行し、ダウンロードURL情報を dict で返す。
+
+        Args:
+            client: v2 `ClientV2` インスタンスを想定
+            disc_no: 開示番号（14桁）
+            docs: 取得するファイル種別（カンマ区切り: g/s/x）。省略時は全種別。
+
+        Returns:
+            dict: ``discNo`` と ``files`` (pdf/summaryPdf/xbrl の URL) を含む辞書
+        """
+        url = f"{client.JQUANTS_API_BASE}/td/files"
+
+        params: dict[str, Any] = {"discNo": disc_no}
+        if docs:
+            params["docs"] = docs
+
+        resp = client._get(url, params)  # type: ignore[arg-type]
+        return resp.json()
+
+
+class TdBulkApiV2(BaseApi):
+    """
+    v2 の TDnet/適時開示インデックス一括ダウンロード API (`/td/bulk`) のラッパークラス。
+
+    過去5年分の適時開示インデックスを収録した CSV (gzip) のダウンロードURLと
+    最終更新日時を取得します。
+    """
+
+    name = "td_bulk"
+    version = "v2"
+
+    def execute(
+        self,
+        client: SupportsRequest,
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        """
+        v2 `/td/bulk` を実行し、一括ダウンロード情報を dict で返す。
+
+        Returns:
+            dict: ``lastUpdated`` と ``url`` を含む辞書
+        """
+        url = f"{client.JQUANTS_API_BASE}/td/bulk"
+        resp = client._get(url, {})  # type: ignore[arg-type]
+        return resp.json()