Hand-drawn workflow for analyst inputs, normalized consensus estimates, API responses, revisions, and application decisions

核心摘要

分析师预测数据 API 应保留市场对企业未来经营表现的预期如何随时间变化。核心记录是针对某项指标和某个财务报告期形成的预测，并带有明确的数据时点、参与统计人数、预测分布、币种、单位和计算方法。本页聚焦未来每股收益、营业收入、EBITDA、现金流和增长率预测；投资评级与目标价属于另一类分析师评级数据。

返回哪些数据

接口按公司、财务报告期和数据时点返回未来每股收益、营业收入、EBITDA、现金流和增长率等一致预期。

“免费”的实际含义

免费套餐可能限制可查询的证券代码数量、API 请求次数、历史数据范围、预测贡献机构明细或商业使用权限。

关键元数据

参与统计的分析师或机构数量、预期值区间、财务报告期、币种、相关时间戳和预期修订记录。

主要风险

把最新一致预期当作历史时点实际可获得的数据，会在回测中引入前视偏差。

选择 API 前先理解分析师预期数据

分析师预期属于预测数据，并非公司披露的实际业绩。数据服务商会把各机构提交的预测归入相应财务报告期，统一单位和会计口径，剔除过期或不符合条件的预测，再计算一致预期。即使字段名称相同，参与统计的机构范围、截止时间、调整规则，以及采用均值还是中位数都可能不同。因此，只有一个当前值不足以支持研究或预期修订分析。

公司、指标与财务报告期身份

接口应提供稳定的公司 ID、证券背景、预测指标、财年、财季或年度期间、报告期末、预期类型和会计口径。只有日历年度标签和股票代码并不足以准确识别一条预测。

一致预期分布

除均值或中位数外，还应提供参与统计的分析师或机构数量、最高值、最低值、标准差或其他离散程度指标，并说明预测纳入规则。两名分析师形成的一致预期与二十名分析师形成的结果不能同等看待。

单项预测与数据新鲜度

许可允许时，应保留贡献者匿名 ID、预测值、提交时间、是否纳入一致预期和最后复核时间。如果只能获得汇总数据，至少要提供预测年龄和贡献者数量。

时间字段与研究截止点

应区分分析师提交时间、供应商接收时间、处理时间、一致预期观察时间、API 响应时间和研究截止时点，并确保决策只使用当时已经可获得的信息。

修订历史与方向

保留此前快照，并基于明确版本计算一日、七日、三十日和上次财报以来的变化。上调与下调预测应分别计数，不能把所有一致预期变化视为相同信号。

合并数值前，应先建立完整的预测身份。“下一季度 EPS”不足以作为数据键，因为两个供应商可能用同一标签表示不同会计口径或财务期间。下列维度必须与数值一起保存，不能只写在说明文档中。

身份维度	需要区分的示例	缺失后果
指标口径	GAAP EPS、调整后 EPS、持续经营 EPS、基本 EPS 与摊薄 EPS。	一致预期会混入并非针对同一披露指标的预测。
期间类型	财务季度、财年、自然年、滚动期间或长期增长预测期。	季度预测被错误地与年度或滚动值比较。
期间身份	财务期间标签、起止日期、持续时间和公司财年截止规则。	非自然年度公司的财年第二季度被映射到错误自然季度。
数值上下文	每股或总额、币种、数量级、单位、拆股口径，以及披露值或标准化值状态。	百万单位与完整金额混用，或拆股前 EPS 与拆股后预测直接比较。
快照资格	截止时点、贡献者数量、过期剔除、撤回状态和方法版本。	今天修订后的贡献者集合被静默回填到历史日期。

财务期间映射示例：假设某零售公司的财年第二季度截止于 2026 年 7 月 31 日。由于公司财年在 2027 年初结束，一个来源可能将其标为 FY2027 Q2，另一个界面则按自然时间归到 2026 Q3。两个标签可能描述同一期间，但必须通过稳定公司 ID、期末日期、期间长度和财年规则确认。相反，即使都对应这个期间，1.20 美元的调整后 EPS 一致预期与 0.85 美元的 GAAP 摊薄 EPS 一致预期也必须分别保存。

免费分析师预测数据 API 评估清单

检查项	应确认的内容	重要性	风险信号
覆盖范围	交易所、股票代码、指标和财务报告期。	支持查询的股票代码很多，并不代表分析师预期数据覆盖充分。	无法按股票代码测试数据是否可用。
历史数据	历史时点快照和预期修订日期。	回测必须使用各决策日当时已可获得的数据。	仅提供最新值查询接口，无法还原历史时点数据。
计算方法	均值或中位数、贡献者资格、新鲜度、调整规则和币种换算。	字段要具备可比性，构造方法也必须一致。	只返回一致预期数值，没有方法说明。
预测分布	数量、最高值、最低值、离散程度、预测年龄及上调或下调次数。	除均值外，预测置信度和分歧程度同样重要。	仅提供经过舍入的一致均值。
更正记录	延迟提交、预测撤回、期间重新映射和供应商更正。	历史快照必须保持可复现。	此前版本在更新后消失。
调用额度	调用次数、突发调用上限、分页方式和额度重置规则。	一次股票筛选可能涉及多个股票代码和财务报告期，因此会消耗大量调用额度。	未说明触发 HTTP 429 后应如何处理。
许可范围	展示、存储、再分发和商业使用权限。	免费访问不代表可以不受限制地使用或再利用数据。	条款未说明衍生数据或分析结果的使用权限。

可靠接入分析师预期数据的实践方法

先制定预测数据契约

选择接口前，明确目标指标、预测周期、财务期间映射、会计口径、最低贡献者数量、最长数据年龄、历史需求、截止时间和许可用途。

保存原始贡献与标准化快照

保留 API 原始响应和来源元数据，再统一映射公司身份、单位、币种、财务报告期、预期类型和调整口径。不能只保存经过舍入的一致预期值。

按指标、报告期和数据时点建立数据键

缓存键缺少指标、财务报告期、预测口径或观察时间时，可能返回错误预测。不可变快照与最新视图应分开存储。

保留空值和小样本所表达的信息

保留空值、贡献者数量、状态、数据年龄和缺失原因，切勿把缺失数据转换为零。如果贡献者数量低于研究系统规定的阈值，应明确标记。

监控修订、质量漂移与配额

近期报告期应提高刷新频率，触发限流时退避重试，并记录每次变动的首次到达时间。贡献者骤减、期间重新映射、一致预期过期或方法变化都应触发告警。

在同一截止时点比较一致预期来源

在同一个财报发布前截止时点保存两个候选来源的快照，并比较指标定义、财务期间映射、贡献者数量、均值或中位数方法、过期预测剔除规则、币种和调整口径。来源之间存在差异并不一定是错误，但在用于超预期计算、筛选或模型训练前，必须能够解释差异从何而来。

实际业绩公布后，不能拿实际值与 API 当前显示的一致预期直接比较。应选择公司发布结果之前最后一个符合条件的快照，再确认实际指标与预测采用相同的口径、期间、币种、单位和每股调整基础。业绩发布时间与后续重述时间也要分别保存。

超预期计算场景	计算方法	解释规则
正数 EPS 预期	一致预期 `1.00 美元`，实际值 `1.10 美元`：绝对差 `+0.10 美元`，百分比差异 `10%`。	只有两者采用相同 EPS 口径和拆股调整时才有效。
负数预期	一致预期 `-0.20 美元`，实际值 `-0.10 美元`：每股亏损比预期少 `0.10 美元`。	应优先展示绝对差与改善方向；负数附近的百分比公式很容易被误解。
零值或接近零的预期	一致预期 `0.00 美元`，实际值 `0.03 美元`：绝对差 `+0.03 美元`，百分比差异无定义。	百分比字段应返回空值并说明原因，不能返回无穷大或虚构比例。
实际值后续重述	首次披露实际值与重述值应作为不同版本，关联到同一财务期间。	事件研究可能需要首次披露值，当前分析则可能采用最新核验值。

修订广度不等于一致预期变化：如果六名分析师分别把 EPS 上调 0.02 美元，另一名分析师却下调 0.20 美元，均值仍可能下降，但修订广度明显偏正。应在一致预期变化旁同时保存上调、下调、未变、新增和撤回贡献的数量，帮助用户区分广泛的方向共识与单个大幅异常修订。

使用 QVeris 查找并比较分析师预期数据工具

QVeris 可帮助智能体发现前瞻预测和一致预期能力、检查数据结构并调用选定工具。它能够简化供应商访问，但财务期间映射、历史时点截止规则、贡献者数量阈值、修订计算、空值处理和许可判断仍由应用方负责。数据覆盖范围和套餐限制应以供应商文档为准。

搜索未来每股收益、营业收入、EBITDA、现金流、贡献者数量、预测分散程度和修订日期。
接入前先检查数据结构；名称相似的接口，其时间字段含义也可能不同。
使用具有代表性的股票代码进行测试，再对照公司披露文件和数据服务商文档核验结果。

常见问题

免费 API 适合用于生产环境吗？

应确认服务等级、商业使用权、配额余量、数据覆盖范围，并制定后续迁移方案。

一致预期与单项预测有何区别？

单项预测来自一名分析师或一家机构；一致预期则汇总一组预先界定的分析师或机构所给出的预测。

最新一致预期可用于回测吗？

不可以。回测应使用每个决策日当时可获得的时点快照。

应优先获取哪些字段？

优先获取指标、数值、单位、币种、财务报告期、参与统计的分析师或机构数量、取值区间及相关时间戳。

一致预期应该采用均值还是中位数？

两者都可能合理。中位数受极端值影响较小，均值则反映所有纳入预测。应同时保存计算方法和预测分布，帮助用户理解结果。

分析师预测多久会被视为过期？

这取决于预测周期和使用场景。应记录每项贡献和汇总结果的数据年龄，并按照明确政策剔除或标记过期值，不能假设纳入计算的所有预测都仍然有效。

什么是预测修订广度？

修订广度比较一个明确窗口内上调和下调预测的数量，需要单项贡献或方向统计数据，不能只根据一致预期均值的变化推断。

不同供应商的预期数据可以直接比较吗？

只有在贡献者范围、统计截止时间、均值或中位数方法、调整口径、币种、财务期间映射、过期规则和更正历史一致后，才具有可比性。

外部参考链接

SEC EDGAR Investor.gov 分析师建议打开工具详情 QVeris 文档