Coverage
What you get
| Item | Detail |
|---|---|
| Product code | STK-EARNINGS |
| Coverage | US-listed companies |
| Contents | Report dates and times, confirmed flags, EPS and revenue actuals built from 8-K filings, historical surprises. Consensus estimates and analyst ratings on Enterprise |
| Granularity | One record per company per fiscal quarter |
| History | Historical earnings dates and actuals for the full US market |
| Delivery | REST and CSV or Parquet files |
| Update speed | Calendar updated daily; actuals after each filing |
The calendar is the part most traders need most of the time: is there a report inside my holding period? Actuals matter for backtests on post-earnings drift. Estimates are licensed from third parties, which is why they sit on Enterprise and the rest doesn't.
Schema
Schema
| Field | Type | Required | Description |
|---|---|---|---|
symbol |
string | yes | Our ticker |
report_date |
string | yes | Announcement date |
report_time |
string | yes | before_open, after_close, during_market, unknown |
is_confirmed |
boolean | yes | Date confirmed by the company |
fiscal_year |
number | yes | Fiscal year |
fiscal_period |
string | yes | Q1 to Q4 |
eps_estimate |
number | optional | Consensus EPS |
eps_actual |
number | optional | Reported EPS (null before release) |
eps_surprise |
number | optional | Actual minus estimate |
eps_surprise_percent |
number | optional | Surprise as percent |
revenue_estimate |
number | optional | Consensus revenue |
revenue_actual |
number | optional | Reported revenue |
revenue_surprise_percent |
number | optional | Surprise as percent |
estimate_count |
number | optional | Analysts in consensus |
currency |
string | yes | Reporting currency |
updated_at |
string | yes | ISO 8601 UTC |
Analyst rating records (Enterprise) carry symbol, date, analyst_firm, action, rating_current, rating_prior, price_target_current and price_target_prior.
Example record (illustrative values; estimate fields need the Enterprise licence):
{
"symbol": "NVDA",
"report_date": "2026-11-19",
"report_time": "after_close",
"is_confirmed": true,
"fiscal_year": 2027,
"fiscal_period": "Q3",
"eps_estimate": 1.24,
"eps_actual": 1.31,
"eps_surprise": 0.07,
"eps_surprise_percent": 5.65,
"revenue_estimate": 54800000000,
"revenue_actual": 56210000000,
"revenue_surprise_percent": 2.57,
"estimate_count": 41,
"currency": "USD",
"updated_at": "2026-11-19T21:24:10Z"
}
Sample data
Sample data
No free earnings sample yet. A sample file is available on request: send a list of tickers and we'll return their recent report dates and actuals in this schema.
If you want reported numbers today, the free US Company Financials sample has quarterly revenue, net income and diluted EPS for eight large caps, straight from SEC filings.
Use cases
Use cases
Avoiding earnings in a swing strategy. Before opening a position, check for a report_date inside your planned holding period. Skip the trade or cut size when is_confirmed is true.
Earnings straddle timing. report_time decides which session takes the gap. after_close means the move shows up at the next open, so you'd hold an options position through that night, not the one before.
Post-earnings drift backtests. Sort historical reports by eps_surprise_percent (Enterprise) or by the change in eps_actual versus the same quarter last year (Starter), then measure returns over the next 20 sessions.
Building an earnings week watchlist. Query the coming five trading days, filter to your universe and sort by report_date and report_time.
Code
Code examples
Example: next week's confirmed reports.
curl "https://api.marketdata.co/v1/stocks/earnings?start=2026-11-23&end=2026-11-27&is_confirmed=true" \
-H "Authorization: Bearer $MARKETDATA_API_KEY"
Example: Python, year-over-year EPS change for one ticker.
import os
import requests
import pandas as pd
resp = requests.get(
"https://api.marketdata.co/v1/stocks/earnings",
params={"symbol": "NVDA", "start": "2023-01-01"},
headers={"Authorization": f"Bearer {os.environ['MARKETDATA_API_KEY']}"},
)
resp.raise_for_status()
e = pd.DataFrame(resp.json()["results"]).sort_values("report_date")
e["eps_yoy"] = e["eps_actual"] - e["eps_actual"].shift(4)
print(e[["report_date", "fiscal_period", "eps_actual", "eps_yoy"]].tail(8))
Pricing
Pricing
| Plan | Earnings data |
|---|---|
| Free, $0 | Earnings calendar (dates only) |
| Starter, $29/mo | Adds actuals from 8-K filings and historical surprises |
| Enterprise, quote | Consensus estimates and analyst ratings (licensed) |
Dataset: historical earnings dates and actuals for the full US market, $99 one-off. Among the providers we studied, earnings data costs $59 to $2,499 a month, median $99, and 3 offer a partial version for free.
Side by side
How we compare
20 of the 50 providers we studied sell earnings data. The median price is $99 because most bundle licensed estimates. We split them: dates and actuals, which we can build from public SEC filings, start free and on Starter, and estimates are on Enterprise for those who need them. The calendar uses the same symbol as our bars, so joining reports to price moves takes one merge.
FAQ
Frequently asked questions
What is the difference between before_open and after_close?
before_open reports come out before the 9:30 New York open, so the price reaction happens that same day. after_close reports come after 16:00, and the reaction shows up the next session.
Are EPS figures adjusted?
eps_actual on Starter is the reported figure from the company's filing, typically GAAP. Adjusted, non-GAAP EPS is how most consensus estimates are framed, which is why surprise fields come with the licensed estimates.
How do you know a date is confirmed?
is_confirmed is true once the company has announced the date. Before that, the date is a projection based on the company's past reporting pattern.
What time zone is report_date in?
It is the US trading date of the announcement. updated_at is a UTC timestamp.
Do you have earnings call transcripts?
Not at launch. Transcripts are a licensed product and not part of this line.
What formats are available?
JSON from the API, and CSV or Parquet for the $99 history file.
Keep reading
Related
- Asset hub: Stocks
- Symbols: AAPL, MSFT, NVDA, AMZN, GOOGL, META
- Docs: API Reference: Fundamentals and SEC Filings
- Learn: Implied Volatility and IV Rank for Options Traders