Free Analyst Estimates API
Data Guide & Checklist
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.
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.
Understand the estimate data before choosing an 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.
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.
| Identity dimension | Examples to distinguish | Failure caused by omission |
|---|---|---|
| Metric basis | GAAP EPS, adjusted EPS, continuing-operations EPS, basic EPS, diluted 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. |
| 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.
Free analyst estimates API evaluation checklist
| 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. |
| 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.
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.
| Surprise case | Calculation | Interpretation rule |
|---|---|---|
| Positive EPS consensus | Consensus $1.00, actual $1.10: absolute surprise +$0.10; percentage surprise 10%. | Valid only when both values use the same EPS basis and split adjustment. |
| Negative consensus | Consensus -$0.20, actual -$0.10: the company lost $0.10 less per share than expected. | 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. | 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.
Find and compare analyst estimate capabilities with 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.
- 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.
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.