核心结论
SEC 在 data.sec.gov 公开提供 submissions 与 XBRL facts JSON，无需 API key；完整申报正文与附件仍位于 EDGAR 归档中。
发行人数据使用十位补零 CIK，文件版本使用 accession number；同时保留表格、受理时间、报告期、主文档与来源 URL。
submissions 列出申报，归档路径保存提交的正文，XBRL 端点提供标签化事实。三者回答的问题不同，也需要不同解析方式。
使用说明性 User-Agent、统一限流、缓存、检查点、有限重试和来源核验。无需密钥的公共接口并不是无限制数据流。
免费 EDGAR API 的端点、字段与访问规则
官方 SEC EDGAR 接口是一组以原始来源为中心的数据产品，并非一个万能的“申报文件 API”。submissions 端点相当于发行人文件索引；归档 URL 指向某一份具体申报及其附件；XBRL 端点组织标签化事实；批量 ZIP 则适合大规模回填。可靠的客户端会根据问题选择数据层，而不是把所有任务都强塞进同一种响应结构。
把 submissions JSON 当作申报索引
使用十位补零 CIK 查询。recent 数组可提供表格、申报日与报告期、受理时间、accession number、主要文件、file number、film number 等元数据。更早历史可能位于响应引用的附加 submissions 文件中，只读取 recent 会造成不易察觉的历史缺口。
通过归档标识定位申报原文
使用 CIK、accession number 与主要文件名保留准确归档位置；申报索引页还可列出主文档和附件。提取章节前应保存原始 HTML 或 XML、内容哈希、抓取时间与 HTTP 元数据，确保派生正文可以复现。
获取 XBRL 事实时保留完整上下文
Company Facts 汇总一家发行人的多个概念，Company Concept 聚焦某个分类体系与标签，Frames 则按指定期间对齐多家申报主体。单独的数值并不完整，还需保留 taxonomy、concept、单位、起止日期、财务期间、表格、申报日、accession number 与维度上下文。
批量数据用于回填，API 用于增量
首次构建数据集时，可用批量 submissions 与 company facts 归档减少请求开销。记录归档版本和采集检查点，之后再通过发行人或文件级端点做增量更新，并按 accession number 消除重叠记录。
遵守 SEC 自动化访问规则
发送可识别的 User-Agent，在所有工作进程之间统一控制请求频率，缓存稳定响应，遵守限流信号，并使用带随机抖动的有限重试。持续监控 403、429 与 5xx；遇到错误时不应提高并发或轮换匿名身份。
比较免费的 SEC EDGAR API 接入方式
| 方式 | 可获得内容 | 优先核对 | 适用场景 |
|---|---|---|---|
| SEC data.sec.gov | 公开 submissions JSON、Company Facts、Company Concept 与批量 ZIP 文件。 | User-Agent 规范、CIK 格式、分类上下文和更新流程。 | 重视原始来源与审计的数据管道。 |
| Free vendor plan | 标准化 JSON、股票代码查询、分页，部分包含历史季度。 | 请求额度、历史、许可、修订处理和署名要求。 | 原型和小型研究工具。 |
| Sandbox or evaluation | 有限的机构、季度或样例返回，用于接入测试。 | 生产使用和完整覆盖是否需要付费。 | 字段结构和客户端验证。 |
| SEC 批量归档 | 用于本地采集的大规模 submissions 或 company facts 快照。 | 归档日期、解压体积、字段变化、检查点及与增量抓取的重叠。 | 首次历史回填与可复现研究数据集。 |
| 自建标准化层 | 自有发行人映射、正文解析、事实数据、搜索索引与变更流。 | 解析器维护、分类体系变化、修订文件、来源存储与运维成本。 | 需要自主控制、自定义语义与稳定审计链的产品。 |
如何接入免费的 EDGAR API
可以把 SEC submissions 响应中的一行归一化为下面的申报记录。示例值均为占位符；关键在于所有字段必须来自同一个数组索引，并保留发行人 CIK。
{
"cik": "CIK_PLACEHOLDER",
"accession_number": "ACCESSION_PLACEHOLDER",
"form": "10-K",
"filed_date": "YYYY-MM-DD",
"accepted_at": "YYYY-MM-DDThh:mm:ss-04:00",
"report_period": "YYYY-MM-DD",
"primary_document": "PRIMARY_DOCUMENT.htm",
"filing_index_url": "SEC_FILING_INDEX_URL",
"retrieved_at": "YYYY-MM-DDThh:mm:ssZ"
}必须保持 filings.recent 的行对齐关系。form、accessionNumber、filingDate 与 primaryDocument 等字段是并行数组。应使用同一索引读取并先组成完整记录，再按表格或日期筛选。若分别过滤各个数组，可能把表格、accession 和文档错误配对，却仍生成表面合法的 JSON。
步骤 1：先定义一份 EDGAR 数据契约
选择端点前先明确输出单位：申报元数据、不可变原始文件、附件列表、标准化 XBRL fact，还是跨公司 frame；同时定义必填标识、历史范围、更新要求、空值处理与证据链接。“获取 SEC 数据”过于宽泛，无法有效验收。
步骤 2：建立稳定的发行人与文件主键
可以由股票代码或公司名称解析 CIK，但持久化时应以 CIK 作为稳定发行人标识。accession number 保存为字符串，并保留 10-K/A 等修订表格，不要折叠进原文件。申报日、受理时间与报告期也应分开，因为它们支持不同的时间查询。
步骤 3：运行合规的抓取层
在 User-Agent 中标识应用与联系信息，设置连接和读取超时，统一控制并发，缓存不可变文件，并只对临时错误执行有限重试。记录 URL、状态、响应头、字节数、抓取时间、尝试次数与内容哈希，便于诊断。
步骤 4：标准化时不要抹掉证据
原始响应应与解析表并存。XBRL 数据需保留 taxonomy、concept、单位、日期、表格、财务期间字段、accession number 与维度；叙述正文则应保留文件 URL、章节边界方法、解析器版本和字符位置或锚点。任何提取结果都应能回到实际申报内容。
步骤 5：验证回填与增量流程
抽样与 EDGAR 核对发行人申报数量，纳入较早 submissions 文件，并测试修订申报、附件较多的文件和按 accession number 去重。之后模拟一次任务失败：从检查点恢复、重放一段日期窗口，并证明结果完整且具备幂等性。
QVeris 如何帮助查找 EDGAR 数据能力
QVeris 帮助智能体发现并检查可调用的金融数据能力。处理 EDGAR 任务时，应先明确输入是公司 CIK、股票代码、表格类型、accession number、XBRL concept 还是日期窗口，再检查必填字段、返回标识、更新频率、来源链接与服务限制。Agent 不应在未说明的情况下用 Company Facts 替代完整申报，也不应把尚未解析的股票代码直接当作 CIK。
- 使用 QVeris 工具详情发现相关 API 能力并检查必填输入。
- 如果任务专门针对机构持仓，而不是通用 EDGAR 接入，请查看免费 13F API 指南。
- 服务商覆盖、价格、许可与数据准确性仍需对照当前文档和 SEC 原始申报验证。
FAQ
官方 EDGAR API 是否免费且无需密钥？
是。SEC 的 submissions 与 XBRL 数据端点无需 API key。不过客户端仍需正确标识身份、遵守当前访问指引、合理缓存，并自行建设应用所需的解析与监控能力。
submissions JSON 和完整申报文件有什么区别？
submissions JSON 是申报元数据索引；真正提交的 HTML、XML、文本与附件位于 EDGAR 归档中。应通过 accession number 和主要文件元数据，把索引记录连接到准确的源文件。
查询财务数值应该使用哪个 EDGAR 端点？
查询一家发行人的多个概念可用 Company Facts，聚焦某个 taxonomy tag 可用 Company Concept，按期间跨主体对齐事实可用 Frames。务必保留单位、日期、表格、accession number 与维度，不能把名称相近的标签自动视为等价。
如何获取更早的申报历史？
读取发行人响应中引用的附加 submissions 文件，并通过归档路径下载原文。大规模首次采集可评估 SEC 批量归档，记录其版本，并按 accession number 与后续增量结果核对去重。
EDGAR 采集器应如何处理访问控制？
遵守 SEC 当前公开指引，标识应用，在所有工作进程之间统一控制频率，缓存不可变文件，遵守 Retry-After，并使用有限退避。持续监控错误率；如果访问响应表明流量过高，应主动暂停或降速。
怎样让 EDGAR 数据管道具备可审计性？
保存原始响应、官方 URL、CIK、accession number、表格、受理时间、申报日与报告期、抓取时间、内容哈希和解析器版本。派生事实或章节还应保留足够的来源位置信息，使转换过程可以复现。
EDGAR 权威参考与相关指南
请以 SEC 官方来源核对申报要求、披露时间和原始记录。服务商的免费套餐与调用额度可能变化，应以其最新官方文档为准。