Choose a Reliable Free Earnings API
Compare actual and estimated EPS, release timestamps, revision history, request limits, and usage rights before integrating earnings data.
Free earnings API: the short answer
A free earnings API should support the moment a company publishes results: identify the event, capture reported values and their accounting basis, preserve the consensus that existed immediately before publication, and expose when each item became available. This makes the endpoint useful for alerts, earnings cards, portfolio monitoring, and agent-generated briefs. It is not the same as an earnings calendar, a transcript feed, or a long historical factor dataset.
A free plan usually limits requests, symbols, history, bulk downloads, or commercial use. Treat it as an evaluation allowance, not guaranteed production capacity.
Confirm actual EPS, consensus EPS, revenue actuals and estimates, fiscal period, announcement time, currency, and the number of contributing analysts.
Quarter end is not the release time. Backtests need the timestamp when results became public, including whether the announcement was before or after market hours.
Query several completed quarters for one symbol, reconcile values with filings, then test revisions, missing estimates, pagination, and quota behavior.
What a useful earnings API should return
Each observation should identify the company, stable event and security identifiers, fiscal year and quarter, period end, reported currency, release timestamp, source, and status. Keep actual values separate from estimates so a later consensus refresh cannot overwrite what the market saw. Preliminary, reported, adjusted, restated, and provider-normalized values also need separate labels.
Resolve the legal issuer and reporting event before attaching results. Keep expected, confirmed, started, preliminary, reported, corrected, and cancelled states distinct, with exchange timezone and before-open, during-session, or after-close classification.
Capture reported and adjusted EPS, revenue, operating income, net income, guidance where available, reporting currency, and the filing or press-release reference. Labels must reveal whether EPS is basic, diluted, GAAP, IFRS, continuing-operations, or adjusted.
Store the estimate value, contributor count, estimate timestamp, high and low range, and methodology. Use the last eligible consensus before the release cutoff for a surprise calculation; a latest value recomputed after publication creates look-ahead bias.
Save actual and estimate components beside the absolute and percentage surprise. Percentage surprise becomes unstable when the estimate is near zero or changes sign, so the API should expose the formula and a validity flag rather than only a headline percentage.
Link each actual result to the earnings release, filing, or issuer source. Preserve preliminary and corrected versions with availability timestamps so a monitoring alert can be reproduced even after the official record changes.
Earnings-surprise example: if diluted GAAP EPS is $1.20 and the last eligible pre-release consensus is $1.00, the absolute surprise is $0.20 and the percentage surprise is ($1.20 - $1.00) ÷ |$1.00| = 20%. The same formula becomes much less informative near zero: actual EPS of $0.02 versus a $0.01 estimate produces a headline 100% surprise from only one cent. If the estimate is -$0.05 and actual EPS is $0.02, the company moved from expected loss to profit; a signed percentage can obscure that change. Store actual, estimate, absolute difference, accounting basis, estimate cutoff, contributor count, and a percentage-validity flag. Present “loss to profit” or “estimate near zero” when that is more faithful than a large percentage.
Release timestamps make earnings data usable
An earnings calendar may begin with an expected date, then move as the company confirms its schedule. The final record should distinguish expected, confirmed, and actual publication times. For event studies, record the exchange timezone and session because “after close” on one market may be the next calendar day elsewhere.
Revisions need equal care. Providers may correct actual EPS, replace preliminary figures, or recompute consensus after additional broker estimates arrive. Archive retrieval time and source version, and never silently rewrite a completed backtest.
The expected event time supports scheduling; the actual release time determines when results were tradable knowledge; the provider ingestion time measures delivery latency. Store all three rather than collapsing them into one date.
The same result may arrive through a press release, exchange announcement, filing, and vendor feed. Merge by company, fiscal period, event, source identity, and content hash while preserving every source reference.
For alerts and AI briefs, require event identity, accounting basis, release time, actual value, pre-release estimate, and source. If any critical item is missing, describe the result as incomplete instead of manufacturing a surprise.
How to choose a free earnings API for your use case
The best endpoint depends on the decision it supports. A portfolio alert needs dependable event status and low delivery delay. A research notebook may accept slower data but needs deeper history and stable revisions. An earnings card needs clean actual-versus-estimate fields, while an AI brief also needs source documents and enough context to explain what changed. Compare providers against that job rather than choosing the largest field list.
Prioritize confirmed event identity, actual publication time, completion status, corrections, source links, and predictable refresh behavior. Test before-open and after-close releases, postponed events, duplicate notifications, and the delay from issuer publication to API availability.
Require consistent fiscal-period mapping, several years of annual and quarterly history, point-in-time estimate snapshots, delisted-company coverage, and versioned restatements. A clean latest-value endpoint is not enough for a backtest if it rewrites old records with information learned later.
Require reported and adjusted values to remain separate, with currency, units, analyst count, guidance, and links to the release or filing. Generated explanations should identify missing evidence and cite the source behind material numbers rather than presenting every provider field as equally authoritative.
Translate the free allowance into expected calls per earnings day, including polling, retries, pagination, source retrieval, and traffic bursts. Confirm redistribution, caching, attribution, and commercial-use rights before a prototype becomes a customer-facing feature.
A reliable free earnings API integration workflow
Evaluate with completed events before automating live earnings. Use one large issuer, one smaller issuer, an off-calendar fiscal year, a loss-making quarter, a missing consensus, and a corrected result. The goal is not merely to receive HTTP 200, but to prove that the same event and accounting meaning survive retrieval, normalization, storage, and presentation.
Store request parameters, raw response, provider timestamp, retrieval time, source URL, plan name, and relevant rate-limit headers before transforming fields. A later parser or mapping correction should not erase the evidence originally received.
Resolve issuer, security, event ID, fiscal year, fiscal quarter, period end, currency, unit, and accounting basis. Reject an ambiguous record instead of guessing from ticker and calendar date alone.
Compare EPS, revenue, release time, and source status with the issuer release and regulatory filing. Record whether a difference comes from rounding, diluted versus basic shares, GAAP versus adjusted presentation, continuing operations, currency conversion, or a provider correction.
Track coverage, missing estimates, duplicate events, correction frequency, delivery latency, stale records, quota consumption, and schema failures. When a critical field is missing, publish an incomplete-data state rather than a fabricated surprise or confident summary.
Use QVeris to inspect earnings capabilities
QVeris helps developers and agents discover reported-results, event, estimate, and filing capabilities before integration, inspect callable contracts, and compare inputs, outputs, freshness, and access requirements. It can streamline routing, while the application still owns event matching, release-time logic, estimate cutoffs, accounting-basis checks, revisions, and the evidence attached to an earnings conclusion.
- Search for earnings calendars, reported results, or consensus-estimate capabilities by intent.
- Inspect symbol formats, fiscal-period parameters, response examples, and error behavior before writing an adapter.
- Keep licensing, revisions, coverage, timestamp quality, and quota checks in production acceptance.
FAQ
Yes. Public filings and several commercial services expose limited results or calendars without charge. Limits commonly apply to requests, history, symbols, estimates, or commercial use.
Actual EPS is the company’s reported result under a stated accounting basis. The estimate is an analyst consensus measured at a particular time; it must retain its timestamp and methodology.
Use a documented snapshot taken before the result became public, ideally the last eligible consensus before the release cutoff. Never use a post-release consensus revision for a historical surprise.
Keep reported GAAP or IFRS results separate from company-adjusted and provider-standardized figures. Preserve the reconciliation and excluded items rather than labelling every non-GAAP number simply “adjusted.”
Yes, when it exposes a stable event ID, actual release time, completion status, values, and source. Make alert delivery idempotent so corrections update the event instead of producing duplicate notifications.
Return the actual result with a missing-estimate reason. Do not treat the estimate as zero or calculate a surprise percentage; the result can still be compared with prior periods and company guidance.