alterlab-edgartools

edgartools — SEC EDGAR 数据

用于访问自 1994 年以来所有 SEC 文件并提取结构化数据的 Python 库。

何时使用此技能

• 为公司或特定时期检索指定文件（10-K、10-Q、8-K、DEF 14A、S-1、13F、Form 4、SC 13D/G、Form D）
• 提取按提交原样提供的财务报表或 XBRL 事实，包括跨期拼接
• 在申报者层面获取内幕交易、机构持仓或委托书／薪酬数据
• 从 EDGAR 获取公司元数据（CIK、SIC、财年结束日、申报者状态）

不适用场景

场景	改用
市场价格、OHLCV、报价或技术指标	alterlab-alpha-vantage
按 FRED 系列 ID 获取宏观经济时间序列（GDP、公司利润、利率）	alterlab-fred
OFR 发布的 Form PF 汇总对冲基金统计数据	alterlab-hedgefund-monitor
联邦债务、财政部报表或拍卖结果	alterlab-usfiscaldata

身份验证（必需）

SEC 要求 API 访问者提供身份信息。执行任何操作前，务必设置身份信息：

from edgar import set_identity
set_identity("Your Name [email protected]")

通过环境变量设置以避免硬编码：EDGAR_IDENTITY="Your Name [email protected]"。

edgartools 会将此身份作为 SEC 要求的 HTTP User-Agent 发送（"Sample Company Name AdminContact@.com"），并默认将自身请求速率限制为每秒 9 次（EDGAR_RATE_LIMIT_PER_SEC），低于 SEC 每秒 10 次的公平访问上限。访问 sec.gov 时请保留此默认值，因为超过上限的 IP 地址可能会被 SEC 屏蔽。

安装

uv pip install edgartools
# For AI/MCP features:
uv pip install "edgartools[ai]"

此处的 API 示例已针对 edgartools 5.58.0 版本验证（截至 2026-09 的当前版本）。如需无需 venv 运行一次性命令：uv run --with edgartools python ...。在 5.x 中，cashflow_statement() 是已弃用的别名（将在 6.0 中移除）——请使用 cash_flow_statement()。

核心工作流

查找公司

from edgar import Company, find

company = Company("AAPL")        # by ticker
company = Company(320193)         # by CIK (fastest)
results = find("Apple")           # by name search

获取文件

# Company filings
filings = company.get_filings(form="10-K")
filing = filings.latest()

# Global search across all filings
from edgar import get_filings
filings = get_filings(2024, 1, form="10-K")

# By accession number
from edgar import get_by_accession_number
filing = get_by_accession_number("0000320193-23-000106")

提取结构化数据

# Form-specific object (most common approach)
tenk = filing.obj()              # Returns TenK, EightK, Form4, ThirteenF, etc.

# Financial statements (10-K/10-Q)
financials = company.get_financials()     # annual
financials = company.get_quarterly_financials()  # quarterly
income = financials.income_statement()
balance = financials.balance_sheet()
cashflow = financials.cash_flow_statement()

# XBRL data
xbrl = filing.xbrl()
income = xbrl.statements.income_statement()

访问文件内容

text = filing.text()             # plain text
html = filing.html()             # HTML
md = filing.markdown()           # markdown (good for LLM processing)
filing.open()                    # open in browser

关键公司属性

company.name                     # "Apple Inc."
company.cik                      # 320193
company.get_ticker()             # "AAPL" (primary); company.tickers -> list
company.industry                 # "ELECTRONIC COMPUTERS"
company.sic                      # "3571"
company.shares_outstanding       # 15115785000.0
company.public_float             # 2899948348000.0
company.fiscal_year_end          # "0930"
company.get_exchanges()          # ["Nasdaq"]

表格类型 → 对象映射

表格类型	对象	关键属性
10-K	TenK	financials、income_statement、balance_sheet、risk_factors
10-Q	TenQ	financials、income_statement、balance_sheet
8-K	EightK	items、press_releases
Form 4	Form4	reporting_owners、insider_name、market_trades、to_dataframe()
13F-HR	ThirteenF	infotable、total_value、holdings
DEF 14A	ProxyStatement	executive_compensation、voting_proposals、peo_total_comp
SC 13D/G	Schedule13D / Schedule13G	total_shares、total_percent、items（13D）
Form D	FormD	offering_data、related_persons、primary_issuer

重要：filing.financials 不存在。请使用 filing.obj().financials。

常见问题

• filing.financials → AttributeError；请使用 filing.obj().financials
• get_filings() 没有 limit 参数；请使用 .head(n) 或 .latest(n)
• 多期分析时优先使用 amendments=False（修订文件可能不完整）
• 访问可选数据前，务必检查是否为 None

参考文件

需要详细信息时，请加载以下文件：

• companies.md — 查找公司、筛选、批量查询、Company API
• filings.md — 处理申报文件、附件、展品、Filings 集合 API
• financial-data.md — 财务报表、便捷方法、DataFrame 导出、多期间分析
• xbrl.md — XBRL 解析、事实查询、多期间拼接、标准化
• data-objects.md — 所有受支持的表格类型及其结构化对象
• entity-facts.md — EntityFacts API、FactQuery、FinancialStatement、FinancialFact
• ai-integration.md — MCP 服务设置、Skills 安装、.docs 和 .to_context() 属性

报告的每个数据都要注明对应申报文件（公司、表格类型、accession number、申报日期）。

属于 AlterLab Academic Skills 套件的一部分。