sec-data

SEC Data — 来自 SEC EDGAR 的财务报表

通过 secfi 库和 SEC 的 XBRL facts JSON API 获取 SEC EDGAR 的结构化财务数据。

直接从 XBRL filings 获取结构化 JSON/CSV 格式的 income statements、balance sheets、cash flow statements。

支持 US-GAAP（美国公司）和 IFRS（外国公司），并自动映射概念。

---

依赖

pip install secfi

需要 pandas 和 requests（随 secfi 一起提供）。

---

工作原理

SEC 通过两个 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
--income	仅获取 income statement
--balance	仅获取 balance sheet
--cashflow	仅获取 cash flow statement
--all-concepts	获取分类标准中所有可用概念（默认：仅 core）
--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 映射

脚本包含一个 IFRS_MAP 字典，其中有 33+ 个映射到对应 IFRS 概念的 US-GAAP 概念。例如：

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 key	公开接口，需要包含电子邮箱的 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