Build with a Free Earnings Data API使用免费财报数据 API构建应用
Compare the fields, timing, limits, and checks needed for dependable earnings workflows.
比较字段、数据时效、使用限制与校验要求，
构建可靠的财报数据工作流。
TL;DR核心摘要
A historical earnings data API should preserve a point-in-time record of reported results, analyst-consensus snapshots, surprise calculations, release times, and later revisions across many companies and quarters. Its main value is a reproducible research panel for event studies, screening, and model features—not only a feed of the latest result. A dataset that keeps only today's consensus or latest corrected EPS cannot reproduce what investors knew before an older announcement.
历史财报数据 API 应按公司和财季保留实际业绩、分析师一致预期快照、业绩超预期计算、发布时间以及后续修订，形成历史时点数据。它的主要价值是为事件研究、股票筛选和模型特征提供可复现的研究面板，而不只是推送最新一期结果。如果数据集只保留今天看到的一致预期或最新更正后的每股收益，就无法还原过去某次财报发布前市场实际掌握的信息。
A free earnings data API can power calendars, alerts, screening, research notes, and event-driven agent workflows.
Require a stable symbol, fiscal period, report date, reported EPS, estimated EPS, currency, and update timestamp.
免费财报数据 API 可用于构建财报日历、提醒与筛选功能、研究笔记，以及事件驱动的智能体工作流。
每条记录至少应包含可稳定识别公司的股票代码、财务报告期、财报披露日期、实际每股收益、预期每股收益、币种和数据更新时间。
Fields a useful earnings API should return实用的财报数据 API 应返回哪些字段
The keyword sounds simple, but a research-grade dataset needs more than one row per quarter. Separate company and security identity, fiscal period, scheduled event, actual release, reported result, every eligible estimate snapshot, provider ingestion time, and revision version. This prevents a calendar date from being mistaken for publication time and a post-release estimate from leaking into a historical surprise calculation.
这个需求看似简单，但研究级数据集不能只为每个季度保存一行结果。公司与证券身份、财务报告期、计划披露事件、实际发布时间、企业披露值、每个符合条件的预期快照、供应商入库时间和修订版本都应分开。这样才能避免把财报日历日期误作发布时间，也能防止发布后更新的预期值进入历史超预期计算。
Capture legal company ID, security and exchange, fiscal year, fiscal quarter, period end, and event ID. Preserve ticker and fiscal-calendar changes with effective dates instead of treating them as new companies.
Keep the scheduled date, confirmation status, expected session, actual release timestamp, timezone, source timestamp, and provider ingestion time separately. Historical studies should use the instant results became public.
Store reported and adjusted EPS, revenue, and other target metrics with currency, GAAP or IFRS basis, basic or diluted label, continuing-operations scope, and source. Do not collapse company-adjusted and reported values into one field.
Retain estimate value, observation time, contributor count, dispersion, high and low range, and methodology for every required cutoff. The pre-release snapshot and the latest snapshot answer different questions.
Save actual and estimate components with absolute and percentage surprise, a near-zero denominator flag, revision history, and the market session used for any return window. Derived fields need formulas and version IDs.
For a representative earnings season, compare the company's release, regulatory filing, and API response for the same metric and period. Record whether differences come from GAAP versus adjusted presentation, continuing operations, currency conversion, share basis, rounding, or a later correction. Define which source wins for each field instead of silently accepting the newest number.
记录法律公司 ID、证券与交易所、财年、财季、报告期末和事件 ID。证券代码或财年发生变化时，应按生效日期保留映射，而不能把同一家公司误当作新主体。
分别保存计划日期、确认状态、预计发布时段、实际发布时间、时区、来源时间和供应商入库时间。历史事件研究应以结果真正公开的时点为准。
保存企业披露和调整后的每股收益、营业收入及其他目标指标，同时注明币种、GAAP 或 IFRS 口径、基本或稀释后每股收益、持续经营范围和来源。公司调整值与原始披露值不能合并到同一字段。
针对每个研究截止时点，保存预期值、观察时间、分析师数量、预测分散程度、区间上下限和计算方法。发布前快照与今天看到的最新快照回答的是不同问题。
将实际值和预期值与绝对差额、百分比差额、近零分母标记、修订历史及收益窗口所采用的交易时段一并保存。所有衍生字段都应带有公式和版本 ID。
选择一个有代表性的财报季，对同一指标和期间逐一核对公司新闻稿、监管申报文件与 API 响应。差异可能来自 GAAP 与调整后口径、持续经营范围、币种换算、股数基础、舍入或后续更正。每个字段都应预先定义来源优先级，不能简单接受最后出现的数字。
Worked reconciliation example: compare like with like财报口径对账示例：实际值与预期必须同口径
Assume a company release reports GAAP diluted EPS of $0.80 and company-adjusted diluted EPS of $1.05 for the same quarter. The final pre-release consensus snapshot is $1.00, and its methodology says “adjusted diluted EPS.” The valid surprise comparison is therefore ($1.05 − $1.00) ÷ $1.00 = +5%. Comparing GAAP actual EPS of $0.80 with that adjusted consensus would produce ($0.80 − $1.00) ÷ $1.00 = −20% and reverse the direction of the conclusion even though every individual number is genuine.
Store the two actuals as separate facts, link each to the release table and later filing, and label the estimate’s accounting basis, share basis, contributor count, and observation cutoff. Keep the issuer’s reconciliation from GAAP to adjusted earnings as evidence rather than deriving an undocumented adjustment locally. If the API cannot establish that actual and estimate use compatible definitions, return the raw values with a comparability warning and leave percentage surprise unset. A later provider correction should append a new version and identify which derived results must be recalculated; it should not silently overwrite the historical record used by an earlier study.
财报口径对账示例：实际值与预期必须同口径
假设公司新闻稿针对同一季度披露的 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 无法证明实际值与预期采用兼容定义，应返回原始值并提示“不可直接比较”，同时不计算百分比超预期。供应商后来更正数据时，应追加新版本并标记哪些衍生结果需要重算，不能静默覆盖早期研究使用的历史记录。
Which free earnings data source should you start with?免费财报数据应从哪一种来源开始？
The best starting point depends on whether the application needs authoritative reported facts, a ready-made earnings calendar, analyst estimates, or all three. These sources are complementary rather than interchangeable. A regulator can establish what the company filed, but it does not provide a precomputed analyst consensus; a convenient market-data endpoint can supply estimates and surprise fields, but those values still need a documented cutoff and a reconciliation path back to the company release or filing.
应从哪种来源开始，取决于应用需要的是权威披露值、可直接使用的财报日历、分析师一致预期，还是三者兼备。这些来源彼此补充，不能简单互换。监管数据可以确认公司正式申报了什么，却不会直接提供计算好的分析师一致预期；市场数据接口虽然能够返回预期值和超预期字段，但仍要明确预期的截止时点，并能回溯到公司新闻稿或监管文件进行对账。
| Starting point起点 | What it provides可获得的内容 | Best fit适合场景 | What remains unresolved仍需解决的问题 |
|---|---|---|---|
| SEC EDGAR | Public filing history and extracted XBRL facts without an API key; submissions and XBRL data are updated as filings are disseminated.无需 API Key 即可获取公开申报历史和提取后的 XBRL 财务事实；申报与 XBRL 数据会随文件公开而更新。 | Authoritative US issuer facts, filing timestamps, and reconciliation.核对美国发行人的权威披露值、申报时间和数据差异。 | No ready-made analyst consensus, surprise panel, or universal adjusted-EPS mapping.不直接提供分析师一致预期、超预期研究面板或统一的调整后 EPS 映射。 |
| Alpha Vantage | An earnings-history endpoint with annual and quarterly EPS; quarterly records include estimates and surprise metrics. A separate calendar endpoint covers expected events.财报历史接口提供年度和季度 EPS，季度记录还包含预期值和超预期指标；另有独立的预期财报日历接口。 | Small prototypes, notebooks, and symbol-level research that need a simple response.适合需要简单响应的小型原型、研究笔记和单只股票分析。 | The official support page currently states up to 25 free requests per day for most datasets; confirm endpoint eligibility, history, and commercial rights before relying on it.官方支持页目前说明多数数据集的免费额度最高为每天 25 次请求；正式使用前仍要确认具体接口是否开放、历史深度及商业使用权限。 |
| Financial Modeling Prep | A documented earnings-calendar response with announcement dates, estimated EPS, and actual EPS for public companies.文档化的财报日历响应，包含上市公司的公告日期、预期 EPS 和实际 EPS。 | Calendar screens and workflows that need estimated and actual values in one normalized interface.适合希望通过统一接口同时取得日历、预期值和实际值的应用。 | Plan access, historical depth, revision behavior, and redistribution rights can change; verify the current entitlement instead of assuming every documented field is free.套餐权限、历史深度、修订方式和再分发权可能变化；不能因为字段出现在文档中，就默认免费套餐一定可用。 |
| Company releases plus filings公司新闻稿与监管文件组合 | Management-presented GAAP and non-GAAP results, tables, explanations, and the primary disclosure context.企业呈现的 GAAP 与非 GAAP 业绩、表格、解释及第一手披露背景。 | High-confidence verification and custom extraction for a smaller company universe.适合对较小公司池进行高可信核验和定制提取。 | Document discovery, table extraction, taxonomy mapping, corrections, and scaling must be engineered locally.文件发现、表格提取、分类映射、更正处理和规模化采集都需要自行实现。 |
A practical hybrid is to use a calendar or market-data API for discovery, then reconcile important reported values against the release or filing. Store both records rather than replacing one with the other: the vendor record preserves delivery behavior and consensus context, while the primary source preserves what the issuer formally disclosed.
更实用的组合方式，是先用财报日历或市场数据 API 发现事件，再把重要的实际披露值与公司新闻稿或监管文件核对。两类记录应同时保存，而不是用其中一条覆盖另一条：供应商记录保留数据到达过程和一致预期背景，第一手来源则保留公司正式披露的内容。
How to evaluate a free plan before integration接入前如何评估免费套餐
| Check检查项 | Question to ask需要确认的问题 | Why it matters为何重要 |
|---|---|---|
| Coverage覆盖范围 | Which exchanges, security types, and historical years are included?覆盖哪些交易所和证券类别？历史数据可追溯多少年？ | A global label may hide US-only or large-cap-only records.标称“全球覆盖”的套餐，实际可能只提供美国市场或大盘股的数据。 |
| Data timing数据时效 | When do scheduled dates, confirmations, results, and revisions appear?计划披露日期、日期确认状态、实际业绩和后续修订分别何时更新？ | Calendars and live alerts tolerate different delays.财报日历与实时提醒对数据延迟的容忍度不同。 |
| Point-in-time estimates历史时点预期 | Are consensus snapshots timestamped and available before and after each result?是否保存每次财报前后带时间戳的一致预期快照？ | Latest-only consensus creates look-ahead bias.只保留最新一致预期会产生前视偏差。 |
| Revisions数据修订 | Are actuals, estimates, surprise fields, and source changes versioned?实际值、预期值、超预期字段和来源变化是否保留版本？ | Silent rewrites make historical results irreproducible.静默改写会使历史研究无法复现。 |
| Completeness完整性 | How are missing estimates, cancelled events, duplicate sources, and inactive securities represented?如何表示预期缺失、事件取消、来源重复和非活跃证券？ | Zeros and dropped rows can bias samples.用零代替或直接删除记录会造成样本偏差。 |
| Request limits请求频率限制 | What are the per-minute, daily, and monthly quotas?每分钟、每天和每月的请求配额分别是多少？ | A high monthly quota can still fail during earnings season bursts.即使月度配额很高，财报季的请求高峰仍可能导致调用失败。 |
| License许可范围 | Are caching, redistribution, display, and commercial use allowed?是否允许缓存、再分发、公开展示和商业使用？ | Technical access does not grant every product right.接口可调用，并不代表已获准在所有产品场景中使用这些数据。 |
Build a small earnings-data acceptance test建立一套小型财报数据验收测试
Do not evaluate an API with one familiar ticker and one clean quarter. Build a compact truth set that forces the provider to reveal how it handles identity, timing, accounting variants, revisions, and missing data. Ten carefully chosen events usually expose more than hundreds of unchecked rows.
不要只用一只熟悉的股票和一个数据整齐的季度评估接口。应建立一个精简但有针对性的真值集，迫使数据源暴露其对主体身份、发布时间、会计口径、修订和缺失值的处理方式。十个经过认真挑选的事件，往往比几百行未经核对的数据更能发现问题。
Include a normal US quarter, a loss with negative EPS, an estimate near zero, a split, a fiscal-year change, an ADR or cross-listing, a late schedule change, a corrected filing, a company-adjusted result, and a security that later delisted.
For every event, compare the issuer publication time, regulator acceptance time, and provider arrival time. A correct number that arrives after the alert window still fails a real-time use case.
Rebuild absolute and percentage surprise from the selected actual and estimate versions. Verify currency, diluted or basic share basis, split adjustment, denominator policy, and rounding before accepting the vendor result.
Define required-field completeness, maximum arrival lag, duplicate tolerance, identity match rate, revision retention, and reconciliation thresholds. Record a failure as missing, late, ambiguous, inconsistent, or unauthorized rather than one generic error.
样本应包括普通美国公司季度、亏损且 EPS 为负的季度、预期接近零的季度、拆股、财年变更、ADR 或跨市场上市、临时改期、更正申报、公司调整后业绩，以及后来退市的证券。
对每个事件比较企业发布时间、监管机构接收时间和供应商到达时间。数字即使正确，只要晚于提醒窗口到达，就不符合实时使用场景。
使用明确选定的实际值和预期值版本，重算绝对差额与百分比差额；在接受供应商结果前，核对币种、稀释或基本股数口径、拆股调整、分母规则和舍入方式。
明确必填字段完整率、最大到达延迟、重复容忍度、主体匹配率、修订保留要求和对账差异阈值，并将失败区分为缺失、迟到、存在歧义、口径不一致或无权使用，而不是统一记成一个错误。
A reliable integration workflow可靠的接入流程
- Write the research cutoff policy first: define which estimate snapshot, event timestamp, accounting basis, and market session belong in each historical row.
- Ingest company and event identities before facts, and preserve expected, confirmed, actual, provider-arrival, and revision times as separate columns.
- Append actual and estimate versions instead of overwriting them; derive surprise fields from explicitly selected component versions.
- Schedule calendar refreshes separately from post-announcement result polling, back off on HTTP 429 responses, cache stable history, and expose quota usage.
- Re-fetch recent events because report times, EPS values, and estimates may be corrected, then rerun only the affected derived features.
- Test split-adjusted and unadjusted EPS, negative and near-zero estimates, missing consensus, cross-listed symbols, fiscal-year changes, cancelled events, and daylight-saving boundaries.
- 先制定研究截止规则，明确历史记录应采用哪个预期快照、事件时间、会计口径和市场交易时段。
- 先接入公司与事件身份，再接入业绩数据，并将预计、确认、实际发布、供应商到达和修订时间分别保存。
- 实际值和预期值应追加版本而不是覆盖旧记录，超预期字段必须由明确选定的构成版本计算。
- 财报日历刷新和财报公布后的业绩轮询应分开调度；收到 HTTP 429 响应时退避重试，缓存稳定历史数据，并展示配额使用情况。
- 近期事件需要重新拉取，因为发布时间、每股收益和预期可能被更正；更正后只重新计算受影响的衍生特征。
- 测试拆股调整前后的每股收益、负数和接近零的预期、预期缺失、跨市场上市、财年变更、事件取消及夏令时边界。
Use QVeris to discover the right earnings capability用 QVeris 查找合适的财报数据服务
QVeris helps agents discover and inspect historical earnings, estimates, events, and filing capabilities before calling them. Compare schemas, coverage, authentication, limits, timestamps, and version behavior against the research contract. QVeris can simplify capability access; the application still owns point-in-time cutoffs, identity mapping, surprise formulas, revision history, and bias controls.
QVeris 可帮助智能体在调用前发现并评估历史业绩、分析师预期、财报事件和监管文件能力，并按照研究契约比较数据结构、覆盖范围、鉴权方式、限制、时间戳和版本行为。QVeris 能够简化能力访问，但历史时点截止规则、主体映射、超预期公式、修订历史和偏差控制仍由应用方负责。
Open the QVeris tool details to inspect available capabilities, inspect inputs and outputs, and choose an interface your application can validate. For broader context, compare this guide with the free financial statements API and free company fundamentals API guides.
你可以通过QVeris 工具详情搜索可用的数据服务，查看输入与输出，并选择便于应用校验的接口。若需更全面地了解相关基本面数据，可将本指南与免费财务报表 API和免费公司基本面 API指南对照阅读。
FAQ常见问题
Often, but depth varies. Some plans expose only recent quarters, latest-only estimates, or a limited symbol universe, so verify point-in-time history with difficult sample companies.
Not necessarily. Scheduled dates may update daily, while reported results may arrive minutes or hours after release. Measure source-to-provider delay separately from API response time.
Each actual, estimate, event status, and correction has an availability timestamp and retained prior versions. A query can reconstruct only the information available at a chosen historical cutoff.
Keep the absolute difference and flag percentage surprise as unstable or unavailable when the estimate is zero, near zero, or opposite in sign. Publish the formula and threshold.
Reported filings and normalized datasets may use different split-adjustment states. Store the adjustment basis and factor, and compare actual and estimate EPS only when both use the same basis.
Yes if it includes actual release times, pre-release estimate snapshots, stable securities, market sessions, revisions, and an unbiased historical universe. Calendar dates alone are insufficient.
通常可以，但历史深度差异很大。有些免费套餐只提供最近几个季度、最新预期或有限证券范围，因此应使用复杂样本验证是否真正具备历史时点数据。
不一定。预定日期可能每天更新一次，实际业绩则可能在发布数分钟或数小时后才录入。应分别测量来源到供应商的延迟和 API 自身响应时间。
每个实际值、预期值、事件状态和更正都带有可得时间，并保留此前版本，使查询能够严格还原某一历史截止时点之前已经公开的信息。
应保留绝对差额；当预期为零、接近零或与实际值异号时，应把百分比标记为不稳定或不可用，并公开公式与判断阈值。
企业原始财报与标准化数据集可能采用不同的拆股调整状态。应保存调整口径和因子，只有实际值与预期值采用相同口径时才能比较。
可以，前提是具备实际发布时间、发布前预期快照、稳定证券标识、交易时段、修订版本和无偏历史股票池。只有财报日历日期远远不够。