核心摘要
历史财报数据 API 应按公司和财季保留实际业绩、分析师一致预期快照、业绩超预期计算、发布时间以及后续修订，形成历史时点数据。它的主要价值是为事件研究、股票筛选和模型特征提供可复现的研究面板，而不只是推送最新一期结果。如果数据集只保留今天看到的一致预期或最新更正后的每股收益，就无法还原过去某次财报发布前市场实际掌握的信息。
免费财报数据 API 可用于构建财报日历、提醒与筛选功能、研究笔记，以及事件驱动的智能体工作流。
每条记录至少应包含可稳定识别公司的股票代码、财务报告期、财报披露日期、实际每股收益、预期每股收益、币种和数据更新时间。
实用的财报数据 API 应返回哪些字段
这个需求看似简单，但研究级数据集不能只为每个季度保存一行结果。公司与证券身份、财务报告期、计划披露事件、实际发布时间、企业披露值、每个符合条件的预期快照、供应商入库时间和修订版本都应分开。这样才能避免把财报日历日期误作发布时间，也能防止发布后更新的预期值进入历史超预期计算。
记录法律公司 ID、证券与交易所、财年、财季、报告期末和事件 ID。证券代码或财年发生变化时，应按生效日期保留映射，而不能把同一家公司误当作新主体。
分别保存计划日期、确认状态、预计发布时段、实际发布时间、时区、来源时间和供应商入库时间。历史事件研究应以结果真正公开的时点为准。
保存企业披露和调整后的每股收益、营业收入及其他目标指标，同时注明币种、GAAP 或 IFRS 口径、基本或稀释后每股收益、持续经营范围和来源。公司调整值与原始披露值不能合并到同一字段。
针对每个研究截止时点，保存预期值、观察时间、分析师数量、预测分散程度、区间上下限和计算方法。发布前快照与今天看到的最新快照回答的是不同问题。
将实际值和预期值与绝对差额、百分比差额、近零分母标记、修订历史及收益窗口所采用的交易时段一并保存。所有衍生字段都应带有公式和版本 ID。
选择一个有代表性的财报季，对同一指标和期间逐一核对公司新闻稿、监管申报文件与 API 响应。差异可能来自 GAAP 与调整后口径、持续经营范围、币种换算、股数基础、舍入或后续更正。每个字段都应预先定义来源优先级，不能简单接受最后出现的数字。
财报口径对账示例：实际值与预期必须同口径
财报口径对账示例：实际值与预期必须同口径
假设公司新闻稿针对同一季度披露的 GAAP 稀释每股收益为 0.80 美元，公司调整后稀释每股收益为 1.05 美元；财报发布前最后一份一致预期快照为 1.00 美元，方法说明明确写的是“调整后稀释每股收益”。因此，正确的超预期幅度应为 (1.05 − 1.00) ÷ 1.00 = +5%。如果错误地用 0.80 美元的 GAAP 实际值去比较调整后一致预期，就会得到 (0.80 − 1.00) ÷ 1.00 = −20%，结论方向完全相反，尽管参与计算的每个数字单独看都是真实的。
两项实际值应作为不同财务事实保存，分别关联新闻稿表格及后续监管文件；一致预期还要标注会计口径、股数基础、贡献分析师数量和观察截止时间。公司从 GAAP 到调整后业绩的调节表应作为证据保留，不能由本地系统自行编造调整项。如果 API 无法证明实际值与预期采用兼容定义，应返回原始值并提示“不可直接比较”，同时不计算百分比超预期。供应商后来更正数据时，应追加新版本并标记哪些衍生结果需要重算，不能静默覆盖早期研究使用的历史记录。
免费财报数据应从哪一种来源开始？
应从哪种来源开始，取决于应用需要的是权威披露值、可直接使用的财报日历、分析师一致预期，还是三者兼备。这些来源彼此补充，不能简单互换。监管数据可以确认公司正式申报了什么，却不会直接提供计算好的分析师一致预期；市场数据接口虽然能够返回预期值和超预期字段，但仍要明确预期的截止时点，并能回溯到公司新闻稿或监管文件进行对账。
| 起点 | 可获得的内容 | 适合场景 | 仍需解决的问题 |
|---|---|---|---|
| SEC EDGAR | 无需 API Key 即可获取公开申报历史和提取后的 XBRL 财务事实；申报与 XBRL 数据会随文件公开而更新。 | 核对美国发行人的权威披露值、申报时间和数据差异。 | 不直接提供分析师一致预期、超预期研究面板或统一的调整后 EPS 映射。 |
| Alpha Vantage | 财报历史接口提供年度和季度 EPS，季度记录还包含预期值和超预期指标；另有独立的预期财报日历接口。 | 适合需要简单响应的小型原型、研究笔记和单只股票分析。 | 官方支持页目前说明多数数据集的免费额度最高为每天 25 次请求；正式使用前仍要确认具体接口是否开放、历史深度及商业使用权限。 |
| Financial Modeling Prep | 文档化的财报日历响应，包含上市公司的公告日期、预期 EPS 和实际 EPS。 | 适合希望通过统一接口同时取得日历、预期值和实际值的应用。 | 套餐权限、历史深度、修订方式和再分发权可能变化；不能因为字段出现在文档中，就默认免费套餐一定可用。 |
| 公司新闻稿与监管文件组合 | 企业呈现的 GAAP 与非 GAAP 业绩、表格、解释及第一手披露背景。 | 适合对较小公司池进行高可信核验和定制提取。 | 文件发现、表格提取、分类映射、更正处理和规模化采集都需要自行实现。 |
更实用的组合方式，是先用财报日历或市场数据 API 发现事件，再把重要的实际披露值与公司新闻稿或监管文件核对。两类记录应同时保存，而不是用其中一条覆盖另一条：供应商记录保留数据到达过程和一致预期背景，第一手来源则保留公司正式披露的内容。
接入前如何评估免费套餐
| 检查项 | 需要确认的问题 | 为何重要 |
|---|---|---|
| 覆盖范围 | 覆盖哪些交易所和证券类别？历史数据可追溯多少年？ | 标称“全球覆盖”的套餐，实际可能只提供美国市场或大盘股的数据。 |
| 数据时效 | 计划披露日期、日期确认状态、实际业绩和后续修订分别何时更新？ | 财报日历与实时提醒对数据延迟的容忍度不同。 |
| 历史时点预期 | 是否保存每次财报前后带时间戳的一致预期快照？ | 只保留最新一致预期会产生前视偏差。 |
| 数据修订 | 实际值、预期值、超预期字段和来源变化是否保留版本？ | 静默改写会使历史研究无法复现。 |
| 完整性 | 如何表示预期缺失、事件取消、来源重复和非活跃证券？ | 用零代替或直接删除记录会造成样本偏差。 |
| 请求频率限制 | 每分钟、每天和每月的请求配额分别是多少？ | 即使月度配额很高，财报季的请求高峰仍可能导致调用失败。 |
| 许可范围 | 是否允许缓存、再分发、公开展示和商业使用？ | 接口可调用，并不代表已获准在所有产品场景中使用这些数据。 |
建立一套小型财报数据验收测试
不要只用一只熟悉的股票和一个数据整齐的季度评估接口。应建立一个精简但有针对性的真值集，迫使数据源暴露其对主体身份、发布时间、会计口径、修订和缺失值的处理方式。十个经过认真挑选的事件，往往比几百行未经核对的数据更能发现问题。
样本应包括普通美国公司季度、亏损且 EPS 为负的季度、预期接近零的季度、拆股、财年变更、ADR 或跨市场上市、临时改期、更正申报、公司调整后业绩，以及后来退市的证券。
对每个事件比较企业发布时间、监管机构接收时间和供应商到达时间。数字即使正确，只要晚于提醒窗口到达，就不符合实时使用场景。
使用明确选定的实际值和预期值版本，重算绝对差额与百分比差额；在接受供应商结果前，核对币种、稀释或基本股数口径、拆股调整、分母规则和舍入方式。
明确必填字段完整率、最大到达延迟、重复容忍度、主体匹配率、修订保留要求和对账差异阈值，并将失败区分为缺失、迟到、存在歧义、口径不一致或无权使用，而不是统一记成一个错误。
可靠的接入流程
- 先制定研究截止规则，明确历史记录应采用哪个预期快照、事件时间、会计口径和市场交易时段。
- 先接入公司与事件身份，再接入业绩数据，并将预计、确认、实际发布、供应商到达和修订时间分别保存。
- 实际值和预期值应追加版本而不是覆盖旧记录，超预期字段必须由明确选定的构成版本计算。
- 财报日历刷新和财报公布后的业绩轮询应分开调度；收到 HTTP 429 响应时退避重试，缓存稳定历史数据，并展示配额使用情况。
- 近期事件需要重新拉取，因为发布时间、每股收益和预期可能被更正；更正后只重新计算受影响的衍生特征。
- 测试拆股调整前后的每股收益、负数和接近零的预期、预期缺失、跨市场上市、财年变更、事件取消及夏令时边界。
用 QVeris 查找合适的财报数据服务
QVeris 可帮助智能体在调用前发现并评估历史业绩、分析师预期、财报事件和监管文件能力，并按照研究契约比较数据结构、覆盖范围、鉴权方式、限制、时间戳和版本行为。QVeris 能够简化能力访问，但历史时点截止规则、主体映射、超预期公式、修订历史和偏差控制仍由应用方负责。
你可以通过QVeris 工具详情搜索可用的数据服务，查看输入与输出，并选择便于应用校验的接口。若需更全面地了解相关基本面数据，可将本指南与REST API 参考和QVeris Finance 提供商。
常见问题
通常可以，但历史深度差异很大。有些免费套餐只提供最近几个季度、最新预期或有限证券范围，因此应使用复杂样本验证是否真正具备历史时点数据。
不一定。预定日期可能每天更新一次，实际业绩则可能在发布数分钟或数小时后才录入。应分别测量来源到供应商的延迟和 API 自身响应时间。
每个实际值、预期值、事件状态和更正都带有可得时间，并保留此前版本，使查询能够严格还原某一历史截止时点之前已经公开的信息。
应保留绝对差额；当预期为零、接近零或与实际值异号时，应把百分比标记为不稳定或不可用，并公开公式与判断阈值。
企业原始财报与标准化数据集可能采用不同的拆股调整状态。应保存调整口径和因子，只有实际值与预期值采用相同口径时才能比较。
可以，前提是具备实际发布时间、发布前预期快照、稳定证券标识、交易时段、修订版本和无偏历史股票池。只有财报日历日期远远不够。