sec-data

SEC Data — SEC EDGAR から財務諸表を取得

secfi ライブラリと SEC の XBRL facts JSON API を使用して、SEC EDGAR から構造化された財務データにアクセスします。

XBRL 提出書類から 損益計算書、貸借対照表、キャッシュフロー計算書 を構造化 JSON／CSV 形式で直接取得します。

US-GAAP（米国企業）と IFRS（外国企業）に対応しており、概念を自動でマッピングします。

---

依存関係

pip install secfi

pandas と requests が必要です（secfi に含まれています）。

---

仕組み

SEC は、2 つの JSON エンドポイントを通じて構造化された財務データを公開しています。

エンドポイント	説明
Company Facts	https://data.sec.gov/api/xbrl/companyfacts/CIK{CIK}.json — すべての XBRL データ
Company Concept	https://data.sec.gov/api/xbrl/companyconcept/CIK{CIK}/us-gaap/{concept}.json — ある概念の履歴

一般的な流れ：

1. secfi.getCiks() → ティッカーの CIK を取得
2. companyfacts/CIK{cik}.json を取得 → すべての構造化財務データを取得
3. スクリプトがタクソノミーに応じて、US-GAAP と IFRS の概念を自動でマッピング

対応タクソノミー

タクソノミー	企業	フォーム	例
us-gaap	米国企業	10-K, 10-Q	AAPL, MSFT, NVDA
ifrs-full	外国企業（Foreign Private Issuers）	20-F, 6-K	GGAL, BABA, SAP, SPOT

スクリプトはタクソノミーを自動で検出し、US-GAAP と IFRS のマッピングを使用して概念を解決します。

---

認証

HEADERS = {"User-Agent": "[email protected]"}

SEC は、有効な User-Agent を指定しないリクエストをブロックします（403 Forbidden）。secfi が内部で使用しているものと同じメールアドレスを使用してください。

---

メインスクリプト：fetch_financials.py

# AAPL (US-GAAP) — todo
python scripts/fetch_financials.py --ticker AAPL --all

# GGAL (IFRS) — todo
python scripts/fetch_financials.py --ticker GGAL --all

# Solo income statement
python scripts/fetch_financials.py --ticker MSFT --income

# Solo balance + cash flow
python scripts/fetch_financials.py --ticker NVDA --balance --cashflow

# Todos los conceptos disponibles (no solo core)
python scripts/fetch_financials.py --ticker AAPL --all --all-concepts

# Output personalizado
python scripts/fetch_financials.py --ticker AAPL --all --output data/aapl

# Solo anual (default)
python scripts/fetch_financials.py --ticker AAPL --all

# Incluir trimestral también
python scripts/fetch_financials.py --ticker AAPL --all --quarterly

使用可能なフラグ

フラグ	説明
--ticker, -t	照会するティッカー（必須）
--all	損益計算書、貸借対照表、キャッシュフロー計算書を取得
--income	損益計算書のみ
--balance	貸借対照表のみ
--cashflow	キャッシュフロー計算書のみ
--all-concepts	タクソノミー内のすべての使用可能な概念（デフォルト：コア概念のみ）
--annual	年次データのみ（デフォルト）
--quarterly	四半期データを含める
--output, -o	出力ファイルのプレフィックス
--quiet, -q	詳細な出力を表示しない

生成される出力

{ticker}_financials.json          → JSON completo con todos los conceptos
{ticker}_financials.csv           → CSV tabular aplanado (concepto x entry)
{ticker}_financials_income_annual.csv  → Matriz concepto x año (income)
{ticker}_financials_balance_annual.csv → Matriz concepto x año (balance)
{ticker}_financials_cashflow_annual.csv → Matriz concepto x año (cash flow)

IFRS の自動マッピング

このスクリプトには、33 以上の US-GAAP 概念を対応する IFRS 概念にマッピングした辞書 IFRS_MAP が含まれています。例：

US-GAAP	IFRS (ifrs-full)
Revenues	RevenueAndOperatingIncome
OperatingIncomeLoss	ProfitLossFromOperatingActivities
NetIncomeLoss	ProfitLoss
StockholdersEquity	Equity
NetCashProvidedByUsedInOperatingActivities	CashFlowsFromUsedInOperatingActivities

フリーキャッシュフロー（FCF）

スクリプトは FCF を自動で計算します。

FCF = Operating CF - CAPEX

US-GAAP と IFRS の両方に対応しています。

---

テスト済み

AAPL（US-GAAP）— 55 個の概念を抽出 ✅

>> Company facts: 4053 KB
>> Income: 13 conceptos x 17 años
>> Balance: 24 conceptos x 17 años
>> Cash flow: 18 conceptos x 17 años
>> FCF 2025: $98.7B

GGAL（IFRS）— 40 個の概念を抽出 ✅

>> Company facts: 724 KB
>> Revenue: $7.72B (2024) · Net Income: $1.76B (2024)
>> Balance: Assets $35.3B · Equity $6.58B
>> Cash flow: Operating $3.80B · FCF $3.57B

---

レート制限

制限	動作
約 10 req/s	SEC の制限
API キー不要	公開されていますが、メールアドレスを含む User-Agent が必要です
過去のデータ	変更されません — レスポンスをキャッシュしてください

---

よくあるエラー

エラー	原因	解決方法
403 Forbidden	User-Agent が無効	[email protected] を使用
404 Not Found	CIK が正しくない	secfi.getCiks() で確認
Ticker not found	SEC に登録されていない	SEC に報告を提出している企業のみ
KeyError: us-gaap	IFRS を使用	スクリプトが自動で解決します

---

スキルの構成

skills/sec-data/
├── SKILL.md                           # Este archivo
├── references/
│   └── FINANCIALS_REFERENCE.md        # Referencia completa: todos los conceptos + mapping IFRS
└── scripts/
    └── fetch_financials.py            # Script principal con mapping IFRS automático