tdnet (youseiushida/tdnet)

tdnet

https://github.com/youseiushida/tdnet
Admin
A Python library for fetching and parsing TDnet timely disclosure documents, with automatic XBRL...

Tokens:19,741
Snippets:124
Trust Score:6.3
Update:1 month ago
Show doc for...
Context Summary (auto-generated)
Raw
# tdnet

**tdnet** は [TDnet（適時開示情報伝達システム）](https://www.release.tdnet.info/) の開示書類を取得・解析する Python ライブラリです。決算短信・業績予想修正・配当予想修正などの XBRL を自動パースし、230以上の正規化キー（CK: Canonical Key）で J-GAAP / IFRS / US-GAAP の財務数値を統一的に抽出できます。

API キーは不要で、インストールしたらすぐに使用可能です。内部の HTTP 通信には httpx を、iXBRL 解析には xbrl-core を使用しています。デフォルトのデータソースは [やのしんWEB-API](https://webapi.yanoshin.jp/) で、TDnet サイトの直接スクレイピングも可能です。XBRL/PDF は公開後2-3営業日で403エラーになるため、日次バッチでの取得を推奨します。

## 開示一覧の取得 - tdnet.documents()

開示書類の一覧を取得するメイン関数です。日付指定・証券コード指定・最新取得など、様々な条件で開示一覧を取得できます。戻り値は `Filing` オブジェクトのリストです。

```python
import tdnet

# 特定日付の開示一覧を取得（XBRL 付きのみ）
filings = tdnet.documents("20260304", has_xbrl=True)
print(f"取得件数: {len(filings)}")
# 取得件数: 45

# 証券コードで絞り込み（直近の開示）
filings = tdnet.documents(code=7203, has_xbrl=True, limit=10)
for f in filings:
    print(f"{f.pubdate} {f.title}")
# 2026-03-04 15:30:00 2026年1月期 決算短信〔日本基準〕（連結）
# 2025-12-01 09:00:00 配当予想の修正に関するお知らせ

# 最新の開示一覧
filings = tdnet.documents(has_xbrl=True)

# release.tdnet.info からの直接スクレイピング
filings = tdnet.documents("20260304", source="scrape")
```

## 期間指定での一覧取得 - list_by_range()

複数日にまたがる期間を指定して開示一覧を取得します。日次バッチ処理などで利用します。

```python
from tdnet import list_by_range

# 期間指定で開示一覧を取得
items = list_by_range("20260301", "20260305", has_xbrl=True)
print(f"期間内の開示: {len(items)} 件")

for item in items[:3]:
    print(f"{item['pubdate']} {item['company_code']} {item['title']}")
# 2026-03-01 15:00:00 7203 2026年3月期 第3四半期決算短信〔IFRS〕（連結）
# 2026-03-02 09:30:00 9984 業績予想の修正に関するお知らせ
# 2026-03-03 15:30:00 6758 2026年3月期 決算短信〔IFRS〕（連結）
```

## TDnet 検索 - search()

キーワードと期間を指定して TDnet の開示を検索します。

```python
from tdnet import search

# キーワード検索
results = search(start_date="20260301", end_date="20260305", keyword="業績予想")
print(f"検索結果: {len(results)} 件")

for item in results[:3]:
    print(f"{item['company_code']} {item['company_name']}: {item['title']}")
# 9984 ソフトバンクグループ: 業績予想の修正に関するお知らせ
# 7203 トヨタ自動車: 業績予想の修正に関するお知らせ
# 6758 ソニーグループ: 通期業績予想の修正に関するお知らせ
```

## Filing オブジェクト

開示書類1件を表すオブジェクトです。メタデータの参照、XBRL のパース、PDF の取得ができます。

```python
import tdnet

filings = tdnet.documents("20260304", has_xbrl=True)
f = filings[0]

# メタデータ
print(f.company_code)   # '25900'
print(f.company_name)   # 'ＤｙＤｏ'
print(f.title)          # '2026年1月期 決算短信〔日本基準〕（連結）'
print(f.pubdate)        # '2026-03-04 15:30:00'
print(f.has_xbrl)       # True
print(f.doc_id)         # '575305'
print(f.markets_string) # '東'

# XBRL パース → Statements
stmts = f.xbrl()
print(f"XBRL items: {len(stmts)}")

# XBRL ZIP の生バイト取得（キャッシュ対応）
zip_data = f.fetch_xbrl()
print(f"ZIP size: {len(zip_data)} bytes")

# PDF 取得
pdf_data = f.fetch_pdf()
with open("disclosure.pdf", "wb") as fp:
    fp.write(pdf_data)
```

## 正規化キー（CK）による値取得 - extract_values()

Statements を1パス走査し、正規化キー（CK: Canonical Key）で財務数値を抽出します。J-GAAP / IFRS / US-GAAP の異なる科目名を統一的に扱えます。

```python
import tdnet
from tdnet import CK, extract_values, extracted_to_dict

# 開示を取得してパース
filings = tdnet.documents("20260304", has_xbrl=True)
f = [f for f in filings if "決算短信" in f.title][0]
stmts = f.xbrl()

# PL（損益計算書）の主要指標を取得
result = extract_values(
    stmts,
    [CK.REVENUE, CK.COST_OF_SALES, CK.GROSS_PROFIT,
     CK.SGA_EXPENSES, CK.OPERATING_INCOME,
     CK.ORDINARY_INCOME, CK.NET_INCOME_PARENT],
    period="current",
    consolidated=True,
)
row = extracted_to_dict(result)
for k, v in row.items():
    print(f"{k}: {v}")
# revenue: 237189000000
# cost_of_sales: 156423000000
# gross_profit: 80766000000
# sga_expenses: 65432000000
# operating_income: 15334000000
# ordinary_income: 16012000000
# net_income_parent: 10845000000

# BS（貸借対照表）
result = extract_values(stmts, [
    CK.TOTAL_ASSETS, CK.CURRENT_ASSETS, CK.NONCURRENT_ASSETS,
    CK.TOTAL_LIABILITIES, CK.NET_ASSETS,
    CK.CASH_AND_DEPOSITS, CK.INVENTORIES,
    CK.SHAREHOLDERS_EQUITY, CK.RETAINED_EARNINGS,
], period="current", consolidated=True)

# CF（キャッシュフロー計算書）
result = extract_values(stmts, [
    CK.OPERATING_CF, CK.INVESTING_CF, CK.FINANCING_CF,
    CK.DEPRECIATION_CF, CK.PURCHASE_PPE_CF,
], period="current", consolidated=True)

# KPI
result = extract_values(stmts, [
    CK.EPS, CK.BPS, CK.ROE, CK.ROA,
    CK.EQUITY_RATIO, CK.OPERATING_MARGIN,
], period="current", consolidated=True)
```

## 全マッピング可能 CK の自動抽出

`keys` を省略すると、マッピング可能な全ての正規化キーを自動抽出します。

```python
from tdnet import extract_values

# 全 CK を自動抽出
all_result = extract_values(stmts, period="current", consolidated=True)
print(f"取得: {len(all_result)} CKs")

for k, ev in sorted(all_result.items()):
    if ev is not None:
        print(f"  {k}: {ev.value}")
# 取得: 85 CKs
#   bps: 1523.45
#   cash_and_deposits: 30657000000
#   eps: 234.56
#   equity_ratio: 45.2
#   ...
```

## 前期比較・非連結取得

当期と前期を比較したり、非連結（個別）の数値を取得できます。

```python
from tdnet import CK, extract_values, extracted_to_dict

# 当期の売上高
current = extracted_to_dict(
    extract_values(stmts, [CK.REVENUE], period="current", consolidated=True)
)
# 前期の売上高
prior = extracted_to_dict(
    extract_values(stmts, [CK.REVENUE], period="prior", consolidated=True)
)
print(f"当期売上: {current.get(CK.REVENUE)}")
print(f"前期売上: {prior.get(CK.REVENUE)}")
# 当期売上: 237189000000
# 前期売上: 225634000000

# 非連結（個別）で取得
# 注: 配当 (DPS) は常に非連結で取得
result = extract_values(stmts, [CK.DPS], period="current", consolidated=False)
row = extracted_to_dict(result)
print(f"1株当たり配当: {row.get(CK.DPS)}")
# 1株当たり配当: 50.0
```

## 変動率・変動額の取得

決算短信サマリーの前年同期比や業績予想修正の変動情報を取得できます。

```python
from tdnet import CK, extract_values, extracted_to_dict

# 変動率（前年同期比）
result = extract_values(stmts, [
    CK.CHANGE_REVENUE,
    CK.CHANGE_OPERATING_INCOME,
    CK.CHANGE_NET_INCOME_PARENT,
], period="current", consolidated=True)
row = extracted_to_dict(result)
print(f"売上高増減率: {row.get(CK.CHANGE_REVENUE)}%")
print(f"営業利益増減率: {row.get(CK.CHANGE_OPERATING_INCOME)}%")
# 売上高増減率: 5.1%
# 営業利益増減率: 12.3%

# 変動額
result = extract_values(stmts, [
    CK.AMOUNT_CHANGE_REVENUE,
    CK.AMOUNT_CHANGE_OPERATING_INCOME,
], period="current", consolidated=True)
```

## 業績予想の取得

業績予想（ForecastMember ディメンション付きの科目）を抽出します。

```python
from tdnet import CK, extract_values, extracted_to_dict

result = extract_values(stmts, [
    CK.FORECAST_REVENUE,
    CK.FORECAST_OPERATING_INCOME,
    CK.FORECAST_NET_INCOME_PARENT,
    CK.FORECAST_EPS,
    CK.FORECAST_DPS,
])
row = extracted_to_dict(result)
print(f"予想売上高: {row.get(CK.FORECAST_REVENUE)}")
print(f"予想営業利益: {row.get(CK.FORECAST_OPERATING_INCOME)}")
print(f"予想EPS: {row.get(CK.FORECAST_EPS)}")
# 予想売上高: 250000000000
# 予想営業利益: 18000000000
# 予想EPS: 280.00
```

## ExtractedValue の詳細

`extract_values()` の戻り値は `dict[str, ExtractedValue | None]` です。元の LineItem やマッパー情報にアクセスできます。

```python
from tdnet import CK, extract_values

result = extract_values(stmts, [CK.REVENUE], period="current", consolidated=True)
ev = result[CK.REVENUE]

if ev is not None:
    print(ev.value)          # Decimal('237189000000')
    print(ev.canonical_key)  # 'revenue'
    print(ev.mapper_name)    # 'summary_mapper'

    # 元の LineItem にアクセス
    item = ev.item
    print(item.local_name)   # 'NetSales'
    print(item.label_ja)     # LabelInfo(text='売上高', source=LabelSource.STANDARD)
    print(item.period)       # DurationPeriod(start_date=date(2025, 2, 1), end_date=date(2026, 1, 31))
```

## ローカル XBRL の解析 - parse_zip() / parse_ixbrl_files()

別途ダウンロードした XBRL ZIP ファイルや iXBRL ファイルを直接解析できます。API 通信は不要です。

```python
from tdnet import parse_zip, parse_ixbrl_files, CK, extract_values, extracted_to_dict

# ZIP ファイルから解析
with open("140120250306553722.zip", "rb") as f:
    zip_data = f.read()

stmts = parse_zip(zip_data)

result = extract_values(
    stmts,
    [CK.REVENUE, CK.OPERATING_INCOME, CK.NET_INCOME_PARENT],
    period="current",
    consolidated=True,
)
row = extracted_to_dict(result)
for k, v in row.items():
    print(f"{k}: {v}")
# revenue: 237189000000
# operating_income: 15334000000
# net_income_parent: 10845000000

# iXBRL ファイルを直接解析
files = {
    "summary-ixbrl.htm": open("summary-ixbrl.htm", "rb").read(),
    "attachment-ixbrl.htm": open("attachment-ixbrl.htm", "rb").read(),
}
stmts = parse_ixbrl_files(files)
```

## CK 以外の FACT へのアクセス

CK にマッピングされていない科目は `local_name` / `search()` / イテレーションで直接取得できます。

```python
# local_name で直接取得
item = stmts["AllowanceForDoubtfulAccountsCA"]
item = stmts.get("AllowanceForDoubtfulAccountsCA")  # None if not found
if item:
    print(item.value)
# 123456000

# キーワード検索（ラベル・local_name を部分一致）
items = stmts.search("貸倒")
for item in items:
    print(f"{item.local_name}: {item.value}")
# AllowanceForDoubtfulAccountsCA: 123456000
# ProvisionForDoubtfulAccountsSGA: 5000000

# 全件走査
for item in stmts:
    if "SGA" in item.local_name:
        print(f"{item.local_name}: {item.value}")
# SellingGeneralAndAdministrativeExpenses: 65432000000
# DepreciationSGA: 3456000000
```

## LineItem の属性

各 LineItem は XBRL の全ての情報を保持しています。

```python
for item in stmts:
    if item.local_name == "CashAndDeposits":
        print(f"local_name: {item.local_name}")      # 'CashAndDeposits'
        print(f"namespace_uri: {item.namespace_uri}") # 'http://disclosure.edinet-fsa.go.jp/...'
        print(f"value: {item.value}")                 # Decimal('30657000000')
        print(f"unit_ref: {item.unit_ref}")           # 'JPY'
        print(f"decimals: {item.decimals}")           # '-6'
        print(f"period: {item.period}")               # InstantPeriod / DurationPeriod
        print(f"dimensions: {item.dimensions}")       # tuple[DimensionMember, ...]
        print(f"label_ja: {item.label_ja}")           # LabelInfo(text='現金及び預金', source=...)
        print(f"label_en: {item.label_en}")           # LabelInfo(text='Cash and deposits', source=...)
        break
```

## 財務諸表コンテナ

`Statements` から個別の財務諸表（PL/BS/CF/CI/SS）を組み立てることができます。

```python
# 損益計算書
pl = stmts.income_statement(consolidated=True, period="current")
for item in pl:
    print(f"{item.label_ja.text}: {item.value}")

# 貸借対照表
bs = stmts.balance_sheet(consolidated=True, period="current")

# キャッシュフロー計算書
cf = stmts.cash_flow_statement(consolidated=True, period="current")

# 包括利益計算書
ci = stmts.comprehensive_income(consolidated=True, period="current")

# 株主資本等変動計算書
eq = stmts.equity_statement(consolidated=True, period="current")
```

## カスタムマッパーの追加 - dict_mapper()

独自のマッピングを追加して、CK にない科目を名寄せできます。

```python
from tdnet import dict_mapper, summary_mapper, statement_mapper, extract_values

# カスタムマッピングを定義
custom = dict_mapper({
    "GainOnSalesOfInvestmentSecuritiesEI": "custom_gain_investment_sales",
    "LossOnRetirementOfNoncurrentAssetsEL": "custom_loss_retirement",
})

# カスタムマッパーをパイプラインに追加
result = extract_values(
    stmts,
    ["custom_gain_investment_sales", "custom_loss_retirement"],
    mapper=[summary_mapper, statement_mapper, custom],
)
print(result.get("custom_gain_investment_sales"))

# 関数で直接マッパーを書くことも可能
from tdnet import ConceptMapper, MapperContext
from tdnet.models.types import LineItem

def my_mapper(item: LineItem, ctx: MapperContext) -> str | None:
    if item.local_name == "SpecialConcept":
        return "my_special_key"
    return None
```

## pandas 連携

Statements や FinancialStatement を DataFrame に変換し、CSV/Parquet/Excel に出力できます。

```python
import tdnet
from tdnet import CK, extract_values

filings = tdnet.documents("20260304", has_xbrl=True)
f = [f for f in filings if "決算短信" in f.title][0]
stmts = f.xbrl()

# 全 LineItem を DataFrame に変換
df = stmts.to_dataframe()
print(df[["label_ja", "value", "local_name"]].head())
#                 label_ja           value                    local_name
# 0               売上高  2.371890e+11                         NetSales
# 1             売上原価  1.564230e+11                     CostOfSales
# 2           売上総利益  8.076600e+10                     GrossProfit
# 3  販売費及び一般管理費  6.543200e+10  SellingGeneralAndAdministrative
# 4             営業利益  1.533400e+10                 OperatingIncome

# CSV / Parquet / Excel 出力
stmts.to_csv("output.csv")
stmts.to_parquet("output.parquet")
stmts.to_excel("output.xlsx")

# 個別の財務諸表も DataFrame 変換可能
pl_df = stmts.income_statement().to_dataframe()
bs_df = stmts.balance_sheet().to_dataframe()
```

## 複数銘柄の一括処理

複数の開示を一括で処理するパターンです。

```python
import tdnet
from tdnet import CK, extract_values, extracted_to_dict

filings = tdnet.documents("20260304", has_xbrl=True)

results = []
for f in filings:
    if "決算短信" not in f.title:
        continue

    stmts = f.xbrl()
    result = extract_values(
        stmts,
        [CK.REVENUE, CK.OPERATING_INCOME, CK.NET_INCOME_PARENT],
        period="current",
        consolidated=True,
    )
    row = extracted_to_dict(result)

    results.append({
        "code": f.company_code,
        "name": f.company_name,
        "revenue": row.get(CK.REVENUE),
        "operating_income": row.get(CK.OPERATING_INCOME),
        "net_income": row.get(CK.NET_INCOME_PARENT),
    })
    print(f"{f.company_code} {f.company_name}: 売上={row.get(CK.REVENUE)}")

# 25900 ＤｙＤｏ: 売上=237189000000
# 7203 トヨタ自動車: 売上=45678900000000
# ...
```

## キャッシュ設定

`cache_dir` を設定すると、XBRL ZIP のダウンロードをディスクキャッシュします。

```python
import tdnet
from tdnet.cache import cache_info, clear_cache

# キャッシュを有効化
tdnet.configure(cache_dir="./cache")

# 以降の fetch_xbrl() はキャッシュを使用
filings = tdnet.documents("20260304", has_xbrl=True)
f = filings[0]
stmts = f.xbrl()  # 初回はダウンロード
stmts = f.xbrl()  # 2回目以降はキャッシュから読み込み

# キャッシュ情報
info = cache_info()
print(f"enabled: {info.enabled}")
print(f"entries: {info.entry_count}")
print(f"size: {info.total_bytes} bytes")
# enabled: True
# entries: 15
# size: 4532100 bytes

# キャッシュクリア
clear_cache()
```

## グローバル設定 - configure()

HTTP タイムアウト、リトライ回数、レート制限などを設定できます。

```python
import tdnet

tdnet.configure(
    cache_dir="./cache",       # キャッシュディレクトリ（None で無効）
    timeout=60.0,              # HTTP タイムアウト秒（デフォルト: 30）
    max_retries=5,             # リトライ回数（デフォルト: 3）
    rate_limit=2.0,            # リクエスト間隔秒（デフォルト: 1.0）
    taxonomy_path=None,        # タクソノミパス（None でバンドル使用）
)

# 通信エラー（タイムアウト、接続エラー）および HTTP 429/500 番台は
# 指数バックオフで自動リトライされます
```

## エラーハンドリング

すべての例外は `TdnetError` を継承しています。

```python
import tdnet
from tdnet import TdnetError, TdnetAPIError, TdnetParseError, TdnetConfigError

filings = tdnet.documents("20260304", has_xbrl=True)
f = filings[0]

try:
    stmts = f.xbrl()
except TdnetAPIError as e:
    # HTTP エラー（403 Forbidden など）
    print(f"HTTP {e.status_code}: {e}")
except TdnetParseError as e:
    # XBRL / HTML 解析エラー
    print(f"Parse error: {e}")
except TdnetConfigError as e:
    # 設定に関するエラー
    print(f"Config error: {e}")
except TdnetError as e:
    # その他のエラー
    print(f"Error: {e}")
```

## CK 一覧（主要）

`CK` は `StrEnum` です。`CK.REVENUE == "revenue"` が `True` になります。

```python
from tdnet import CK

# PL（損益計算書）
CK.REVENUE              # 'revenue' - 売上高
CK.COST_OF_SALES        # 'cost_of_sales' - 売上原価
CK.GROSS_PROFIT         # 'gross_profit' - 売上総利益
CK.SGA_EXPENSES         # 'sga_expenses' - 販管費
CK.OPERATING_INCOME     # 'operating_income' - 営業利益
CK.ORDINARY_INCOME      # 'ordinary_income' - 経常利益
CK.NET_INCOME_PARENT    # 'net_income_parent' - 親会社株主帰属純利益
CK.NET_INCOME           # 'net_income' - 当期純利益

# BS（貸借対照表）
CK.TOTAL_ASSETS         # 'total_assets' - 総資産
CK.CURRENT_ASSETS       # 'current_assets' - 流動資産
CK.NONCURRENT_ASSETS    # 'noncurrent_assets' - 固定資産
CK.CASH_AND_DEPOSITS    # 'cash_and_deposits' - 現金及び預金
CK.INVENTORIES          # 'inventories' - 棚卸資産
CK.TOTAL_LIABILITIES    # 'total_liabilities' - 負債合計
CK.NET_ASSETS           # 'net_assets' - 純資産
CK.SHAREHOLDERS_EQUITY  # 'shareholders_equity' - 株主資本

# CF（キャッシュフロー計算書）
CK.OPERATING_CF         # 'operating_cf' - 営業CF
CK.INVESTING_CF         # 'investing_cf' - 投資CF
CK.FINANCING_CF         # 'financing_cf' - 財務CF
CK.DEPRECIATION_CF      # 'depreciation_cf' - 減価償却費
CK.CASH_END             # 'cash_end' - 期末現金残高

# KPI
CK.EPS                  # 'eps' - 1株当たり利益
CK.BPS                  # 'bps' - 1株当たり純資産
CK.DPS                  # 'dps' - 1株当たり配当
CK.ROE                  # 'roe' - 自己資本利益率
CK.ROA                  # 'roa' - 総資産利益率
CK.EQUITY_RATIO         # 'equity_ratio' - 自己資本比率

# 変動率
CK.CHANGE_REVENUE           # 'change_revenue' - 売上高増減率
CK.CHANGE_OPERATING_INCOME  # 'change_operating_income' - 営業利益増減率
CK.CHANGE_NET_INCOME_PARENT # 'change_net_income_parent' - 純利益増減率

# 業績予想
CK.FORECAST_REVENUE           # 'forecast_revenue' - 予想売上高
CK.FORECAST_OPERATING_INCOME  # 'forecast_operating_income' - 予想営業利益
CK.FORECAST_NET_INCOME_PARENT # 'forecast_net_income_parent' - 予想純利益
CK.FORECAST_EPS               # 'forecast_eps' - 予想EPS
CK.FORECAST_DPS               # 'forecast_dps' - 予想配当
```

## まとめ

tdnet は、日本の上場企業の決算短信・業績予想修正・配当予想修正などの TDnet 開示書類を取得・解析するためのライブラリです。主なユースケースとして、(1) 決算短信からの財務数値の自動抽出、(2) 複数銘柄の一括処理による財務データベースの構築、(3) 業績予想の修正情報の監視、(4) 前年同期比較・増減率の分析などがあります。

正規化キー（CK）を使用することで、J-GAAP・IFRS・US-GAAP の異なる会計基準間で共通のキーを使って財務数値にアクセスできます。230以上の CK が定義されており、PL/BS/CF の主要科目から KPI、業種別（銀行・保険・証券）、ESG 指標まで幅広くカバーしています。pandas との連携により、取得したデータを DataFrame に変換して CSV/Parquet/Excel に出力したり、データ分析パイプラインに組み込むことが容易です。