# How to get analyst estimates, revisions and earnings surprises as data

Consensus EPS and revenue, how it moved, and actual against estimate, from a free key up — and why two sources' consensus and surprise rarely match.

*https://stockmarketstack.com/how-to/get-analyst-estimates-as-data · next to Fundamental Data & Stock Research Platforms*

**Answer:** Alpha Vantage returns consensus EPS and revenue on a free key, with the analyst count and the average 7, 30, 60 and 90 days ago; its EARNINGS call adds reported against estimated EPS. Finnhub, Financial Modeling Prep, EODHD and Twelve Data sell the same shapes. Nobody hands you the past consensus: snapshot it daily. Check the basis, usually adjusted, and which consensus a surprise was measured against.

## The tools that do this

*In the order this page recommends trying them. Paid placement does not affect this order.*

1. [Alpha Vantage](https://stockmarketstack.com/tools/alpha-vantage.md) — EARNINGS_ESTIMATES and EARNINGS on the free key, 25 requests a day. Consensus with high, low, count and 7 to 90-day history; surprises back to 1996.
2. [Finnhub](https://stockmarketstack.com/tools/finnhub.md) — Surprises back to 2000, the last four quarters free. Estimates are a paid product from $75, and the average includes Finnhub's own estimates.
3. [Financial Modeling Prep](https://stockmarketstack.com/tools/financial-modeling-prep.md) — Revenue, EBITDA, EBIT, net income and EPS ranges per fiscal year or quarter, each with its analyst count; a separate call gives actual against estimate.
4. [EODHD](https://stockmarketstack.com/tools/eodhd.md) — One fundamentals call returns Earnings::Trend, with revisions, and Earnings::History, with surprise percent. 10 API calls a request, from $59.99.
5. [Twelve Data](https://stockmarketstack.com/tools/twelve-data.md) — earnings_estimate, eps_trend and eps_revisions in the same 7-to-90-day shape, at 20 credits a symbol and on the Ultra plan only, from $329.
6. [Benzinga News API](https://stockmarketstack.com/tools/benzinga-news-api.md) — Licensed per-report rows with eps_est, eps_surprise and an eps_type for the basis. Quoted, with no public price.

## The short way

[Alpha Vantage](https://stockmarketstack.com/tools/alpha-vantage) has both halves on a free key. `EARNINGS_ESTIMATES` is the
consensus going forward and `EARNINGS` is the record of actual against estimate. The free key
allows 25 requests a day, and both are one request per company:

```python
import csv
import datetime

import requests

AV = "https://www.alphavantage.co/query"

def get(function, symbol):
    r = requests.get(AV, params={"function": function, "symbol": symbol,
                                 "apikey": "YOUR_API_KEY"}, timeout=30)
    r.raise_for_status()
    return r.json()

# 1. Today's consensus, appended to a file so that the history is yours.
today = datetime.date.today().isoformat()
with open("estimates_snapshots.csv", "a", newline="") as f:
    w = csv.writer(f)
    for e in get("EARNINGS_ESTIMATES", "IBM")["estimates"]:
        w.writerow([today, "IBM", e["horizon"], e["date"], e["eps_estimate_average"],
                    e["eps_estimate_analyst_count"], e["eps_estimate_average_30_days_ago"],
                    e["revenue_estimate_average"]])

# 2. Reported against estimated EPS, and the surprise recomputed rather than trusted.
for q in get("EARNINGS", "IBM")["quarterlyEarnings"][:4]:
    actual, est = float(q["reportedEPS"]), float(q["estimatedEPS"])
    print(q["fiscalDateEnding"], q["reportedDate"], actual, est,
          round((actual - est) / abs(est) * 100, 2), q["surprisePercentage"])
```

Each estimate row is a fiscal period, a `horizon` of `fiscal quarter` or `fiscal year`, and the
average, high, low and analyst count for EPS and for revenue. It also has
`eps_estimate_average_7_days_ago` through `_90_days_ago` and the count of upward and downward
revisions over the trailing 7 and 30 days. Run on 9 October 2026, IBM's file had 41 rows, from the
fiscal year ending December 2027 back to the quarter ended June 2017. `quarterlyEarnings` had 122
quarters back to March 1996. Each row has the report date, `reportedEPS`, `estimatedEPS`,
`surprise`, `surprisePercentage` and a pre- or post-market `reportTime`.

Run the snapshot step every day. Nothing on this page will give you the consensus as it stood on
a date you did not save.

## What the options are

**Free, with a revision history four points long.** [Alpha Vantage](https://stockmarketstack.com/tools/alpha-vantage) as
above. The licence on every plan is personal and non-commercial.

**Surprises free, estimates paid.** [Finnhub](https://stockmarketstack.com/tools/finnhub)'s `/stock/earnings` returns actual,
estimate, `surprise` and `surprisePercent` per quarter, documented as "going back to 2000". The
free key gets the last four quarters. `/stock/eps-estimate` and `/stock/revenue-estimate` take
`freq=annual` or `quarterly` and return `epsAvg`, `epsHigh`, `epsLow` and `numberAnalysts` per
period. Both are marked "Premium Access Required", and estimates are a separate product from $75 a
month. The specification describes `epsAvg` as the "average EPS estimates including Finnhub's
proprietary estimates". `/stock/recommendation` returns monthly counts of strong-buy to
strong-sell ratings, and `/stock/price-target` the target range.

**Wide ranges by fiscal year.** [Financial Modeling Prep](https://stockmarketstack.com/tools/financial-modeling-prep)'s
`/stable/analyst-estimates` takes `symbol` and `period` (`annual` or `quarter`) and pages up to
1,000 rows. Each row is keyed by the fiscal period's end date. It carries low, high and average for
revenue, EBITDA, EBIT, net income, SG&A and EPS, with `numAnalystsRevenue` and `numAnalystsEps`
counted separately. The documentation's sample reaches Apple's fiscal year ending 27 September
2030. `/stable/earnings` gives each report's `epsActual` against `epsEstimated`, with revenue and a
`lastUpdated` date, and `/stable/earnings-surprises-bulk?year=` returns a year of them for every
company at once.

**Everything in one fundamentals call.** [EODHD](https://stockmarketstack.com/tools/eodhd)'s fundamentals endpoint takes
`filter=Earnings::Trend` or `filter=Earnings::History`. `Trend` holds EPS and revenue consensus by
quarter and year, with trend values and revision counts. `History` holds each report's
`epsActual`, `epsEstimate`, `epsDifference` and `surprisePercent`, with `beforeAfterMarket` and
`currency`. A fundamentals request costs 10 API calls, and fundamentals start with the $59.99 plan.
Its separate `/api/calendar/trends` returns the consensus as it stood 7, 30, 60 and 90 days
earlier.

**The same shape, a higher plan.** [Twelve Data](https://stockmarketstack.com/tools/twelve-data)'s `/earnings_estimate`,
`/eps_trend` and `/eps_revisions` return current-quarter, next-quarter, current-year and next-year
rows, with the trend at 7, 30, 60 and 90 days ago and revisions over the last week and month. All
three are Ultra-plan endpoints at 20 credits per symbol, so this is a route for someone already on
Ultra rather than a reason to buy it.

**A licensed calendar with the surprise attached.** The [Benzinga](https://stockmarketstack.com/tools/benzinga-news-api) suite
includes an earnings calendar whose rows carry `eps_est`, described as "analyst consensus",
`eps_prior`, `eps_surprise` and `eps_surprise_percent`, the same for revenue, and an `eps_type`
field for the basis. It is licensed by quote, like the rest of Benzinga's data. The [earnings
calendar how-to](https://stockmarketstack.com/how-to/get-an-earnings-calendar-as-data) covers the date and confirmation fields
of the same feed.

**A named consensus you can read but not take.** [Koyfin](https://stockmarketstack.com/tools/koyfin) and [TIKR](https://stockmarketstack.com/tools/tikr)
both show S&P Capital IQ consensus estimates. TIKR shows how many analysts contributed to a
number, never which ones. Neither has an API. Koyfin says the data vendor blocks export of estimates for global
equities, and TIKR's export starts at its Pro plan. They are the place to check a number whose
source you know, not a feed.

## Where this breaks

**"Consensus" is somebody's average of somebody's analysts.** Finnhub's average includes its own
proprietary estimates, and its earnings calendar says estimates come "from both sell-side and
buy-side analysts". Koyfin and TIKR name S&P Capital IQ. Alpha Vantage, Financial Modeling Prep,
EODHD and Twelve Data name no supplier in the documentation read on 9 October 2026. The counts
differ inside a single row, too: Financial Modeling Prep's sample has 16 analysts behind the
revenue figure and 7 behind EPS. Store the source and the analyst count beside every number, and
never mix two vendors' consensus in one column. [Why consensus estimates
differ](https://stockmarketstack.com/guides/why-consensus-estimates-differ) explains who collects the estimates and what each
aggregator decides.

**The actual is usually adjusted, and the label is usually missing.** IBM's release of 22 July 2026
gives second-quarter diluted EPS of $2.27 on a GAAP basis and $2.93 on an operating, non-GAAP basis.
Alpha Vantage's `reportedEPS` for that quarter is 2.93, against an estimate of 2.93: a zero
surprise on the adjusted number. Finnhub documents its earnings calendar as non-GAAP. Benzinga's
`eps_type` is empty in its own example. The others say nothing. A surprise is only meaningful when
the actual and the estimate are on the same basis. A GAAP actual against an adjusted consensus
produces a "miss" that is an accounting difference. [Non-GAAP](https://stockmarketstack.com/glossary/non-gaap) has the
definitions.

**The surprise can be measured against a consensus you are not shown.** Alpha Vantage's two IBM
endpoints, read on the same day, disagree about the estimate for the same quarter more than once.
For the quarter ended March 2022, `EARNINGS_ESTIMATES` gives an average of 1.38. `EARNINGS` gives
`estimatedEPS` 1.42 and a surprise of −1.41% on a reported 1.40. Against 1.38 the same 1.40 is a
1.45% beat. For September 2023 the two are 2.01 and 2.13. Neither endpoint says when its estimate
was frozen. Recompute the surprise yourself, as the code above does, against the estimate you
stored before the report, and keep the vendor's figure in its own column.

**The consensus you fetch today overwrites the one you fetched yesterday.** Every endpoint on this
page returns the current value. Alpha Vantage, Twelve Data and EODHD add the averages 7, 30, 60 and
90 days earlier, which is four points and not a history. A quarter that has already reported shows
its last value, not the one in force a month before the report. Re-pulling later answers a
different question from the one a backtest asks. It is the [point-in-time](https://stockmarketstack.com/glossary/point-in-time)
problem in its plainest form, and the daily snapshot in the code above is the only fix that does
not cost an institutional licence.

**Fiscal periods are labelled three ways, and one sample gets it wrong.** Financial Modeling Prep
keys estimates by the fiscal period's end date. Alpha Vantage uses `fiscalDateEnding`. Finnhub uses
a `year` and `quarter`, and its own sample response for `/stock/earnings` labels an Apple actual
of 1.88 as period `2023-03-31`, quarter 1 of 2023. Apple reported $1.88 for the quarter that ended
on 31 December 2022, its fiscal first quarter of 2023. Alpha Vantage's `annualEarnings` has a
trap of its own: on 9 October 2026 IBM's first annual row was dated 2026-09-30 with 4.84. That is
the sum of the two quarters IBM had reported, 1.91 and 2.93, a partial year under an annual label.
Join estimates to actuals on the period end date, with a few days' tolerance, and check one known
quarter by hand against the company's own release. [The earnings calendar
how-to](https://stockmarketstack.com/how-to/get-an-earnings-calendar-as-data) covers fiscal labels in more depth.

**Revisions are counts, not reasons.** An upward revision count of 11 says eleven estimates moved
up, not by how much or why, and the counts cover trailing 7 and 30-day windows that slide each day.
Alpha Vantage returns `null` for some revision counts where others are zero. Treat null as
"not reported", not as no revisions.

## If you outgrow this

**When you need the estimate history rather than today's value**, a daily snapshot builds it going
forward but not backward. Point-in-time estimate histories are sold to institutions under the
aggregators' own names, and they are priced by quote. Budget for that before promising a backtest
over past revisions.

**When the job is the report rather than the estimate**, the filing is the primary source. US
results are furnished on Form 8-K under Item 2.02, and [getting SEC filings as
data](https://stockmarketstack.com/how-to/get-sec-filings-as-data) covers the free EDGAR endpoints. [Earnings call
transcripts as data](https://stockmarketstack.com/how-to/get-earnings-call-transcripts-as-data) covers what management said
about guidance.

**When the numbers go in front of other people**, every self-serve plan on this page is personal
use, and showing the data in a product is [redistribution](https://stockmarketstack.com/glossary/redistribution). That is an
Enterprise contract at Finnhub and Financial Modeling Prep, and a commercial plan from $399 a month
at EODHD.

The research terminals that show a named consensus beside the financials are in [fundamentals and
research platforms](https://stockmarketstack.com/categories/fundamentals-research); the APIs that sell estimates beside prices
are in [market data APIs](https://stockmarketstack.com/categories/market-data-apis).

## FAQ

### Is there a free API for consensus EPS estimates?

Yes. Alpha Vantage's EARNINGS_ESTIMATES carries no premium mark in its documentation, read on 9 October 2026, and returns quarterly and annual EPS and revenue consensus with the high, low, analyst count and the averages 7, 30, 60 and 90 days earlier. The free key allows 25 requests a day. Finnhub's free key gets the last four quarters of surprises but not the estimates themselves.

### Can I get what the consensus was on a past date?

Not from these APIs, beyond four fixed look-backs. The 7, 30, 60 and 90-days-ago fields that Alpha Vantage, Twelve Data and EODHD return are four points, not a series, and a past quarter's row shows its last value before the report. A day-by-day history of the consensus is the one thing you have to build yourself, by saving a snapshot every day.

### Why does my surprise percentage differ from the one on a news site?

Because the two were measured against different numbers. A surprise is actual minus estimate, and both halves vary by source. The consensus depends on which analysts the aggregator collects and when it froze the number. The actual may be GAAP or adjusted. Even within one vendor they can disagree. Alpha Vantage's IBM rows put the estimate for the March 2022 quarter at 1.38 in one endpoint and 1.42 in the other, and the sign of the surprise depends on which you use.

### Are earnings estimates GAAP or adjusted?

Mostly adjusted, and rarely labelled. Finnhub documents its earnings calendar as non-GAAP. Benzinga has an eps_type field, empty in its own example. Alpha Vantage, Financial Modeling Prep, EODHD and Twelve Data state no basis. Alpha Vantage's reported EPS for IBM's June 2026 quarter is 2.93, IBM's operating figure, not its GAAP 2.27.

## Sources

1. [Alpha Vantage API Documentation — Earnings Estimates and Earnings History](https://www.alphavantage.co/documentation/) — Alpha Vantage, read 2026-10-09
2. [Finnhub API specification (stock/eps-estimate, stock/earnings, calendar/earnings)](https://finnhub.io/static/swagger.json) — Finnhub, read 2026-10-09
3. [Financial Estimates API](https://site.financialmodelingprep.com/developer/docs/stable/financial-estimates) — Financial Modeling Prep, read 2026-10-09
4. [Earnings Report API](https://site.financialmodelingprep.com/developer/docs/stable/earnings-company) — Financial Modeling Prep, read 2026-10-09
5. [Fundamental Data API — Earnings section](https://eodhd.com/financial-apis/stock-etfs-fundamental-data-feeds) — EODHD, read 2026-10-09
6. [EPS trend — API documentation](https://twelvedata.com/docs/analysis/eps-trend) — Twelve Data, read 2026-10-09
7. [Earnings — Calendar API reference](https://docs.benzinga.com/api-reference/calendar-api/get-earnings) — Benzinga, read 2026-10-09
8. [IBM Releases Second-Quarter Results](https://newsroom.ibm.com/2026-07-22-IBM-RELEASES-SECOND-QUARTER-RESULTS) — IBM, 2026-07-22
9. [Apple reports first quarter results](https://www.apple.com/newsroom/2023/02/apple-reports-first-quarter-results/) — Apple, 2023-02-02. A results release for a quarter long closed; it is cited for the figure Apple reported, which nothing supersedes.

*Last updated 2026-10-09. A reference page, corrected in place — not a dated post.*