SEC Filing Scraper - 美股EDGAR公告检索工具

基于 SEC EDGAR 公开 JSON API，支持按股票代码(Ticker)和日期范围搜索公告、批量下载文档、导出Excel。

能力

搜索公告：按股票代码 + 日期范围搜索SEC EDGAR公告
批量下载：下载公告主文档到本地目录
元数据导出：输出结构化JSON或Excel（含超链接）
表格分类：自动识别表格类型（10-K年度报告、10-Q季度报告、8-K重大事项等）

使用方式

调用 scripts/sec_scraper.py 脚本：

# 搜索某只股票的公告
python3 "$SKILL_DIR/scripts/sec_scraper.py" search --ticker AAPL

# 搜索指定日期范围
python3 "$SKILL_DIR/scripts/sec_scraper.py" search --ticker WETH --from 2026-01-01 --to 2026-04-23

# 按表格类型过滤
python3 "$SKILL_DIR/scripts/sec_scraper.py" search --ticker BGM --form 8-K

# 下载公告文档
python3 "$SKILL_DIR/scripts/sec_scraper.py" download --ticker WETH --from 2026-01-01 --output ./sec_docs

# 导出为Excel
python3 "$SKILL_DIR/scripts/sec_scraper.py" search --ticker BGM --format xlsx --output filings.xlsx

# 限制返回数量
python3 "$SKILL_DIR/scripts/sec_scraper.py" search --ticker AAPL --max-records 20

参数说明

| 参数 | 说明 | 默认值 | |------|------|--------| | search | 子命令：搜索公告元数据 | - | | download | 子命令：搜索并下载文档 | - | | --ticker | 股票代码（如 AAPL, TSLA） | 必填 | | --from | 起始日期（YYYY-MM-DD） | 不限 | | --to | 结束日期（YYYY-MM-DD） | 不限 | | --form | 表格类型过滤（如 8-K, 10-K） | 全部 | | --max-records | 限制返回数量 | 0=不限 | | --format | 输出格式：text/xlsx | text | | --output | 输出文件路径/目录 | 自动生成 |

数据字段

每条公告包含以下字段：

ticker: 股票代码（如 AAPL）
cik: SEC中央索引键（10位零填充）
company_name: 公司名称
form: 表格类型（如 10-K, 8-K）
form_description: 类型中文说明
filing_date: 提交日期
report_date: 报告期间
accession_number: SEC存取号
primary_document: 主文档文件名
primary_doc_description: 文档描述
document_url: 主文档直接链接
index_url: 公告索引目录链接
items: 披露项目（8-K等）

常见表格类型

| Form | 说明 | |------|------| | 10-K | 年度报告 | | 10-Q | 季度报告 | | 8-K | 重大事项报告 | | 20-F | 外国公司年度报告 | | 6-K | 外国公司重大事项报告 | | 4 | 内部人持股变动 | | S-1 | 招股说明书 | | DEF 14A | 股东大会委托书 |

技术原理

使用 SEC EDGAR 公开 JSON API：

Company Tickers: https://www.sec.gov/files/company_tickers.json - Ticker → CIK 映射
Submissions: https://data.sec.gov/submissions/CIK{cik}.json - 公司所有提交记录
Filing Documents: https://www.sec.gov/Archives/edgar/data/{cik}/{accn}/{doc}

该 API 支持：

按股票代码筛选（自动Ticker→CIK转换）
按日期范围和表格类型查询
无需API Key，只需设置User-Agent请求头
速率限制：10请求/秒（脚本已内置限速）

注意事项

SEC API 要求设置 User-Agent 请求头（格式：AppName/Version email@domain），脚本已内置默认值
cik_str 在 company_tickers.json 中可能是 int 或 string 类型，脚本已自动处理
下载的文档格式取决于SEC原始文件（多为 .htm/.html，部分为 .pdf）

审计场景示例

获取美股客户特定期间的全部公告列表
批量下载10-K/10-Q/8-K用于审计底稿
检查某公司SEC披露的及时性和完整性
对比不同期间的公告类型和数量变化