Free Analyst Estimates API
Data Guide & Checklist免费分析师预测数据 API
选型与使用指南
Evaluate free EPS, revenue, and price-target estimates without mistaking latest consensus for historical truth.
评估免费的每股收益、营收和目标价预期数据，
避免把最新一致预期误当成历史时点实际可获得的数据。
TL;DR核心摘要
An analyst estimates API should preserve how expectations for future company performance change over time. The core record is a forecast for a named metric and fiscal period, observed at a specific as-of time, with contributor count, distribution, currency, units, and methodology. This page focuses on forward EPS, revenue, EBITDA, cash flow, and growth forecasts; recommendation ratings and price targets belong to a separate analyst-ratings workflow.
分析师预测数据 API 应保留市场对企业未来经营表现的预期如何随时间变化。核心记录是针对某项指标和某个财务报告期形成的预测，并带有明确的数据时点、参与统计人数、预测分布、币种、单位和计算方法。本页聚焦未来每股收益、营业收入、EBITDA、现金流和增长率预测；投资评级与目标价属于另一类分析师评级数据。
Forward EPS, revenue, EBITDA, cash-flow, and growth consensus by company, fiscal period, and as-of time.
Free plans may limit symbols, calls, history, contributor detail, or commercial use.
Contributor count, range, period, currency, timestamps, revisions.
Latest consensus can create look-ahead bias when treated as historical truth.
接口按公司、财务报告期和数据时点返回未来每股收益、营业收入、EBITDA、现金流和增长率等一致预期。
免费套餐可能限制可查询的证券代码数量、API 请求次数、历史数据范围、预测贡献机构明细或商业使用权限。
参与统计的分析师或机构数量、预期值区间、财务报告期、币种、相关时间戳和预期修订记录。
把最新一致预期当作历史时点实际可获得的数据，会在回测中引入前视偏差。
Understand the estimate data before choosing an API选择 API 前先理解分析师预期数据
Analyst estimates are forecasts, not company-reported facts. Providers map submissions to fiscal periods, normalize units and accounting bases, remove stale or ineligible contributions, then calculate consensus. Identically named fields can use different contributors, cut-off times, adjustment rules, or mean-versus-median methods. A single current value is therefore not enough for research or revision analysis.
分析师预期属于预测数据，并非公司披露的实际业绩。数据服务商会把各机构提交的预测归入相应财务报告期，统一单位和会计口径，剔除过期或不符合条件的预测，再计算一致预期。即使字段名称相同，参与统计的机构范围、截止时间、调整规则，以及采用均值还是中位数都可能不同。因此，只有一个当前值不足以支持研究或预期修订分析。
Require stable company ID, security context, metric, fiscal year, quarter or annual period, period end, estimate type, and accounting basis. Calendar labels and a ticker alone are insufficient.
Mean or median should include contributor count, high, low, standard deviation or another dispersion measure, and eligibility method. A consensus based on two analysts is not equivalent to one based on twenty.
When licensing permits, retain contributor pseudonym or ID, submitted value, submission time, inclusion status, and last review. If only aggregate data is available, require age and contributor-count fields.
Distinguish analyst submission time, vendor receipt, vendor processing, consensus observation, API response, and the research cutoff. Use only information available before the decision time.
Preserve prior snapshots and derive one-day, seven-day, thirty-day, and since-last-report changes from explicit versions. Count upward and downward revisions separately rather than treating every consensus move alike.
接口应提供稳定的公司 ID、证券背景、预测指标、财年、财季或年度期间、报告期末、预期类型和会计口径。只有日历年度标签和股票代码并不足以准确识别一条预测。
除均值或中位数外，还应提供参与统计的分析师或机构数量、最高值、最低值、标准差或其他离散程度指标，并说明预测纳入规则。两名分析师形成的一致预期与二十名分析师形成的结果不能同等看待。
许可允许时，应保留贡献者匿名 ID、预测值、提交时间、是否纳入一致预期和最后复核时间。如果只能获得汇总数据，至少要提供预测年龄和贡献者数量。
应区分分析师提交时间、供应商接收时间、处理时间、一致预期观察时间、API 响应时间和研究截止时点，并确保决策只使用当时已经可获得的信息。
保留此前快照，并基于明确版本计算一日、七日、三十日和上次财报以来的变化。上调与下调预测应分别计数，不能把所有一致预期变化视为相同信号。
Before combining values, construct an estimate identity. “EPS for next quarter” is not a sufficient key because two providers can attach the same label to different accounting and period definitions. The dimensions below belong beside the value, not in informal documentation.
合并数值前，应先建立完整的预测身份。“下一季度 EPS”不足以作为数据键，因为两个供应商可能用同一标签表示不同会计口径或财务期间。下列维度必须与数值一起保存，不能只写在说明文档中。
| Identity dimension身份维度 | Examples to distinguish需要区分的示例 | Failure caused by omission缺失后果 |
|---|---|---|
| Metric basis指标口径 | GAAP EPS, adjusted EPS, continuing-operations EPS, basic EPS, diluted EPS.GAAP EPS、调整后 EPS、持续经营 EPS、基本 EPS 与摊薄 EPS。 | A consensus mixes forecasts that do not predict the same reported measure.一致预期会混入并非针对同一披露指标的预测。 |
| Period type期间类型 | Fiscal quarter, fiscal year, calendar year, trailing period, or long-term growth horizon.财务季度、财年、自然年、滚动期间或长期增长预测期。 | A quarterly forecast is compared with an annual or trailing value.季度预测被错误地与年度或滚动值比较。 |
| Period identity期间身份 | Fiscal label, start date, end date, duration, and company fiscal-year-end convention.财务期间标签、起止日期、持续时间和公司财年截止规则。 | A non-calendar issuer's fiscal Q2 is mapped to the wrong calendar quarter.非自然年度公司的财年第二季度被映射到错误自然季度。 |
| Value context数值上下文 | Per share or total, currency, scale, units, split basis, and reported or normalized status.每股或总额、币种、数量级、单位、拆股口径，以及披露值或标准化值状态。 | Millions are mixed with full units, or pre-split EPS is compared with post-split forecasts.百万单位与完整金额混用，或拆股前 EPS 与拆股后预测直接比较。 |
| Snapshot eligibility快照资格 | As-of cutoff, contributor count, stale exclusion, withdrawal status, and methodology version.截止时点、贡献者数量、过期剔除、撤回状态和方法版本。 | Today's revised contributor set is silently attached to a historical date.今天修订后的贡献者集合被静默回填到历史日期。 |
Fiscal mapping example: assume a retailer's fiscal Q2 ends on 2026-07-31. One source calls it FY2027 Q2 because the fiscal year ends in early 2027; another user interface groups the release under calendar 2026 Q3. These labels can describe the same period, but only the stable company ID, period end, duration, and fiscal-year convention prove it. Conversely, an adjusted EPS consensus of $1.20 and a GAAP diluted EPS consensus of $0.85 must remain separate even when both belong to that period.
财务期间映射示例：假设某零售公司的财年第二季度截止于 2026 年 7 月 31 日。由于公司财年在 2027 年初结束，一个来源可能将其标为 FY2027 Q2，另一个界面则按自然时间归到 2026 Q3。两个标签可能描述同一期间，但必须通过稳定公司 ID、期末日期、期间长度和财年规则确认。相反，即使都对应这个期间，1.20 美元的调整后 EPS 一致预期与 0.85 美元的 GAAP 摊薄 EPS 一致预期也必须分别保存。
Free analyst estimates API evaluation checklist免费分析师预测数据 API 评估清单
| Check检查项 | Ask for应确认的内容 | Why it matters重要性 | Warning sign风险信号 |
|---|---|---|---|
| Coverage覆盖范围 | Exchanges, symbols, metrics, periods.交易所、股票代码、指标和财务报告期。 | Symbol lists may hide sparse estimates.支持查询的股票代码很多，并不代表分析师预期数据覆盖充分。 | No availability test.无法按股票代码测试数据是否可用。 |
| History历史数据 | Point-in-time snapshots and revision dates.历史时点快照和预期修订日期。 | Backtests must use values known on the decision date.回测必须使用各决策日当时已可获得的数据。 | Only a latest-value endpoint.仅提供最新值查询接口，无法还原历史时点数据。 |
| Methodology计算方法 | Mean or median, contributor eligibility, staleness, adjustments, currency conversion.均值或中位数、贡献者资格、新鲜度、调整规则和币种换算。 | Comparable fields require comparable construction.字段要具备可比性，构造方法也必须一致。 | Consensus value with no definition.只返回一致预期数值，没有方法说明。 |
| Distribution预测分布 | Count, high, low, dispersion, age, and revisions up or down.数量、最高值、最低值、离散程度、预测年龄及上调或下调次数。 | Confidence and disagreement matter beside the mean.除均值外，预测置信度和分歧程度同样重要。 | Only a rounded average.仅提供经过舍入的一致均值。 |
| Corrections更正记录 | Late submissions, withdrawn estimates, period remapping, and vendor corrections.延迟提交、预测撤回、期间重新映射和供应商更正。 | Historical snapshots must remain reproducible.历史快照必须保持可复现。 | Prior versions disappear.此前版本在更新后消失。 |
| Quota调用额度 | Calls, bursts, pagination, reset rules.调用次数、突发调用上限、分页方式和额度重置规则。 | Screens may require many calls.一次股票筛选可能涉及多个股票代码和财务报告期，因此会消耗大量调用额度。 | Unclear HTTP 429 behavior.未说明触发 HTTP 429 后应如何处理。 |
| License许可范围 | Display, storage, redistribution, and commercial rights.展示、存储、再分发和商业使用权限。 | Free access does not imply unrestricted reuse.免费访问不代表可以不受限制地使用或再利用数据。 | Terms do not address derived outputs.条款未说明衍生数据或分析结果的使用权限。 |
Implementation playbook for reliable estimate data可靠接入分析师预期数据的实践方法
Specify target metrics, forecast horizons, fiscal-period mapping, accounting basis, minimum contributor count, maximum staleness, required history, cutoff times, and licensed product use before selecting an endpoint.
Keep raw payloads and source metadata, then map company identity, units, currency, periods, estimate types, and adjustment basis. Never retain only the rounded consensus.
A cache key without metric, fiscal period, estimate basis, and observation time can return the wrong forecast. Store immutable snapshots and derive the latest view separately.
Preserve null, contributor count, status, age, and reason; never convert missing data to zero. Flag consensus below the research system's minimum contributor threshold.
Refresh near-term periods more often, back off on rate limits, record when each changed value arrived, and alert on sudden contributor loss, period remapping, stale consensus, or methodology changes.
Snapshot two candidate sources at an identical pre-earnings cutoff and compare metric definition, fiscal-period mapping, contributor count, median or mean method, stale-estimate exclusion, currency, and adjustment basis. Differences are not automatically errors, but they must be explainable before one source is used for surprise calculations, screening, or model training.
选择接口前，明确目标指标、预测周期、财务期间映射、会计口径、最低贡献者数量、最长数据年龄、历史需求、截止时间和许可用途。
保留 API 原始响应和来源元数据，再统一映射公司身份、单位、币种、财务报告期、预期类型和调整口径。不能只保存经过舍入的一致预期值。
缓存键缺少指标、财务报告期、预测口径或观察时间时，可能返回错误预测。不可变快照与最新视图应分开存储。
保留空值、贡献者数量、状态、数据年龄和缺失原因，切勿把缺失数据转换为零。如果贡献者数量低于研究系统规定的阈值，应明确标记。
近期报告期应提高刷新频率，触发限流时退避重试，并记录每次变动的首次到达时间。贡献者骤减、期间重新映射、一致预期过期或方法变化都应触发告警。
在同一个财报发布前截止时点保存两个候选来源的快照，并比较指标定义、财务期间映射、贡献者数量、均值或中位数方法、过期预测剔除规则、币种和调整口径。来源之间存在差异并不一定是错误，但在用于超预期计算、筛选或模型训练前，必须能够解释差异从何而来。
When results arrive, do not compare the actual value with the API's current consensus. Select the last eligible snapshot observed before the company released the result, then match the reported metric to the same basis, period, currency, units, and share adjustment. Preserve the result publication time and any later restatement separately.
实际业绩公布后，不能拿实际值与 API 当前显示的一致预期直接比较。应选择公司发布结果之前最后一个符合条件的快照，再确认实际指标与预测采用相同的口径、期间、币种、单位和每股调整基础。业绩发布时间与后续重述时间也要分别保存。
| Surprise case超预期计算场景 | Calculation计算方法 | Interpretation rule解释规则 |
|---|---|---|
| Positive EPS consensus正数 EPS 预期 | Consensus $1.00, actual $1.10: absolute surprise +$0.10; percentage surprise 10%.一致预期 1.00 美元，实际值 1.10 美元：绝对差 +0.10 美元，百分比差异 10%。 | Valid only when both values use the same EPS basis and split adjustment.只有两者采用相同 EPS 口径和拆股调整时才有效。 |
| Negative consensus负数预期 | Consensus -$0.20, actual -$0.10: the company lost $0.10 less per share than expected.一致预期 -0.20 美元，实际值 -0.10 美元：每股亏损比预期少 0.10 美元。 | Lead with the absolute difference and direction; percentage formulas around negative values are easy to misread.应优先展示绝对差与改善方向；负数附近的百分比公式很容易被误解。 |
| Zero or near-zero consensus零值或接近零的预期 | Consensus $0.00, actual $0.03: absolute surprise +$0.03; percentage surprise is undefined.一致预期 0.00 美元，实际值 0.03 美元：绝对差 +0.03 美元，百分比差异无定义。 | Return null with an explicit reason instead of infinity or a fabricated percentage.百分比字段应返回空值并说明原因，不能返回无穷大或虚构比例。 |
| Revised actual实际值后续重述 | Keep the first reported actual and the restated value as separate versions linked to the same fiscal period.首次披露实际值与重述值应作为不同版本，关联到同一财务期间。 | Event studies may use the first release; current analysis may prefer the latest verified figure.事件研究可能需要首次披露值，当前分析则可能采用最新核验值。 |
Revision breadth is different from consensus change: if six analysts raise EPS by $0.02 and one analyst cuts by $0.20, the mean may fall even though breadth is strongly positive. Store upward, downward, unchanged, added, and withdrawn contribution counts beside the consensus change. This lets users distinguish broad directional agreement from one large outlier revision.
修订广度不等于一致预期变化：如果六名分析师分别把 EPS 上调 0.02 美元，另一名分析师却下调 0.20 美元，均值仍可能下降，但修订广度明显偏正。应在一致预期变化旁同时保存上调、下调、未变、新增和撤回贡献的数量，帮助用户区分广泛的方向共识与单个大幅异常修订。
Find and compare analyst estimate capabilities with QVeris使用 QVeris 查找并比较分析师预期数据工具
QVeris helps agents discover forward-estimate and consensus capabilities, inspect schemas, and call a selected tool. It can simplify provider access, while the application still owns fiscal-period mapping, point-in-time cutoff rules, contributor thresholds, revision calculations, null handling, and the licensing decision. Provider documentation remains authoritative for coverage and limits.
QVeris 可帮助智能体发现前瞻预测和一致预期能力、检查数据结构并调用选定工具。它能够简化供应商访问，但财务期间映射、历史时点截止规则、贡献者数量阈值、修订计算、空值处理和许可判断仍由应用方负责。数据覆盖范围和套餐限制应以供应商文档为准。
- Search for forward EPS, revenue, EBITDA, cash flow, contributor count, dispersion, and revision dates.
- Inspect schemas before integrating; endpoint names can hide different time semantics.
- Test representative symbols, then verify results against filings and provider documentation.
- 搜索未来每股收益、营业收入、EBITDA、现金流、贡献者数量、预测分散程度和修订日期。
- 接入前先检查数据结构；名称相似的接口，其时间字段含义也可能不同。
- 使用具有代表性的股票代码进行测试，再对照公司披露文件和数据服务商文档核验结果。
FAQ常见问题
Confirm service levels, commercial rights, quota headroom, coverage, and a migration path.
One estimate is one forecast; consensus aggregates a defined contributor set.
No. Use point-in-time snapshots available on each decision date.
Request metric, value, unit, currency, fiscal period, contributor count, range, and timestamps.
Either can be valid. The median is less sensitive to outliers; the mean reflects every included value. Store the method and distribution so users understand the result.
That depends on the horizon and use case. Track the age of each contribution and the aggregate; exclude or flag values older than the documented policy rather than assuming every included forecast is current.
Revision breadth compares the number of upward and downward forecast changes over a defined window. It needs contributor-level or direction-count data and should not be inferred from consensus change alone.
Only after checking contributor universe, cutoff, mean or median method, adjustment basis, currency, fiscal-period mapping, staleness policy, and correction history.
应确认服务等级、商业使用权、配额余量、数据覆盖范围，并制定后续迁移方案。
单项预测来自一名分析师或一家机构；一致预期则汇总一组预先界定的分析师或机构所给出的预测。
不可以。回测应使用每个决策日当时可获得的时点快照。
优先获取指标、数值、单位、币种、财务报告期、参与统计的分析师或机构数量、取值区间及相关时间戳。
两者都可能合理。中位数受极端值影响较小，均值则反映所有纳入预测。应同时保存计算方法和预测分布，帮助用户理解结果。
这取决于预测周期和使用场景。应记录每项贡献和汇总结果的数据年龄，并按照明确政策剔除或标记过期值，不能假设纳入计算的所有预测都仍然有效。
修订广度比较一个明确窗口内上调和下调预测的数量，需要单项贡献或方向统计数据，不能只根据一致预期均值的变化推断。
只有在贡献者范围、统计截止时间、均值或中位数方法、调整口径、币种、财务期间映射、过期规则和更正历史一致后，才具有可比性。