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

The short way

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:

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 as above. The licence on every plan is personal and non-commercial.

Surprises free, estimates paid. 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'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'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'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 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 covers the date and confirmation fields of the same feed.

A named consensus you can read but not take. Koyfin and 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 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 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 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 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 covers the free EDGAR endpoints. 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. 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; the APIs that sell estimates beside prices are in market data APIs.