{"id":8565,"date":"2026-01-10T07:51:53","date_gmt":"2026-01-10T11:51:53","guid":{"rendered":"https:\/\/www.benzinga.com\/apis\/blog\/\/"},"modified":"2026-01-12T13:09:13","modified_gmt":"2026-01-12T17:09:13","slug":"mastering-the-earnings-api-earnings-calendars-and-surprise-detection-with-python","status":"publish","type":"post","link":"https:\/\/www.benzinga.com\/apis\/blog\/mastering-the-earnings-api-earnings-calendars-and-surprise-detection-with-python\/","title":{"rendered":"Mastering the Earnings API: Earnings Calendars and Surprise Detection with Python"},"content":{"rendered":"\n
\"\"<\/figure>\n\n\n\n

Introduction<\/h2>\n\n\n\n

Earnings announcements are one of the few scheduled events that consistently move markets. Prices react not just to the reported numbers, but to how those numbers compare with expectations. A small miss can matter more than a strong result if the market was positioned differently going in.<\/p>\n\n\n\n

Benzinga\u2019s Earnings Calendar API<\/strong><\/a> provides a structured view of these events. It includes the announcement timing, consensus estimates, reported results and calculated surprise metrics. This makes it possible to track upcoming earnings, review past results and identify where expectations and reality diverged.<\/p>\n\n\n\n

In this article, we walk through the Earnings endpoint and show how to work with the data using Python. We start with basic extraction, move on to identifying earnings surprises, and then look at how prices behaved after those events using daily bars. The focus is on building clear, repeatable workflows around earnings data rather than predictive models.<\/p>\n\n\n\n

How Earnings Expectations and Surprises Work<\/h2>\n\n\n\n

What the Market Is Actually Comparing<\/h3>\n\n\n\n

By the time a company reports earnings, the numbers themselves are rarely a surprise. Analysts have already published estimates, and those expectations are priced in well before the announcement.<\/p>\n\n\n\n

What the market reacts to is the comparison. Reported EPS versus the estimate. Reported revenue versus the estimate. That gap is what traders look at first, often before reading anything else.<\/p>\n\n\n\n

This is why a stock can drop after reporting \u201cgood\u201d numbers or rally after reporting weaker ones. The result only matters relative to what was expected.<\/p>\n\n\n\n

What an Earnings Surprise Really Represents<\/h3>\n\n\n\n

An earnings surprise is simply the difference between what was expected and what was reported. It can be positive or negative, and it can be small or large. The direction tells you whether expectations were beaten or missed. The size tells you how meaningful that miss or beat might be.<\/p>\n\n\n\n

EPS surprises tend to get more immediate attention, especially in the first reaction. Revenue surprises often matter more when growth is the focus, or when margins are already under pressure. The Earnings endpoint includes both, along with the calculated surprise values, so you don\u2019t have to compute them manually.<\/p>\n\n\n\n

Why Size Matters More Than Direction<\/h3>\n\n\n\n

Not every beat leads to a move, and not every miss causes a sell-off. Small deviations are common and often ignored. Larger surprises are what usually trigger follow-through.<\/p>\n\n\n\n

This is where surprise magnitude becomes useful. It helps separate routine earnings updates from events that actually change how the market views the company, at least in the short term.<\/p>\n\n\n\n

That distinction becomes important once you start filtering events or looking at how prices behaved after earnings, which we\u2019ll get to later in the article.<\/p>\n\n\n\n

Earnings Calendar Endpoint Walkthrough<\/h2>\n\n\n\n

The Earnings Calendar endpoint<\/a> returns one row per earnings event. Each entry combines timing, expectations, reported results and surprise metrics in a single structure. The endpoint is designed to answer a simple question: what was expected, what was reported, and when did it happen.<\/p>\n\n\n\n

Base Request<\/h3>\n\n\n\n

A minimal request looks like this:<\/p>\n\n\n

\nimport requests\n\napi_key = "YOUR BENZINGA API KEY"\nurl = "https:\/\/api.benzinga.com\/api\/v2.1\/calendar\/earnings"\n\nheaders = {"accept": "application\/json"}\nparams = {\n    "token": api_key,\n    "parameters[tickers]": "AAPL",\n    "pagesize": 10\n}\n\nr = requests.get(url, params=params, headers=headers)\ndata = r.json()\ndata["earnings"][0]\n<\/pre><\/div>\n\n\n
The response contains an earnings array, where each element represents a single earnings announcement.<\/p>\n\n\n\n
{‘currency’: ‘USD’,
 ‘date’: ‘2026-10-29’,
 ‘date_confirmed’: 0,
 ‘eps’: ”,
 ‘eps_est’: ‘1.990’,
 ‘eps_prior’: ‘1.850’,
 ‘eps_surprise’: ”,
 ‘eps_surprise_percent’: ”,
 ‘eps_type’: ”,
 ‘exchange’: ‘NASDAQ’,
 ‘id’: ‘69030cfb619d3a00015b72a3’,
 ‘importance’: 5,
 ‘isin’: ‘US0378331005’,
 ‘name’: ‘Apple’,
 ‘notes’: ”,
 ‘period’: ‘Q4’,
 ‘period_year’: 2026,
 ‘revenue’: ”,
 ‘revenue_est’: ”,
 ‘revenue_prior’: ‘102466000000.000’,
 ‘revenue_surprise’: ”,
 ‘revenue_surprise_percent’: ”
 ‘revenue_type’: ”,
 ‘ticker’: ‘AAPL’,
 ‘time’: ’16:00:00′,
 ‘updated’: 1766187011}
<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
Key Query Parameters<\/h3>\n\n\n\n
Most use cases rely on a small set of parameters.<\/p>\n\n\n\n
Parameter<\/strong><\/td>Description<\/strong><\/td><\/tr>
tickers<\/td>One or more comma-separated symbols.<\/td><\/tr>
date<\/td>Earnings scheduled or reported on a specific day.<\/td><\/tr>
date_from, date_to<\/td>Date range for historical or upcoming earnings.<\/td><\/tr>
importance<\/td>Filter by relevance score (0\u20135).<\/td><\/tr>
pagesize, page<\/td>Pagination controls.<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
This is enough to pull upcoming earnings, review historical results or focus on higher-impact events.<\/p>\n\n\n\n
Response Fields<\/h3>\n\n\n\n
Each record returned by the Earnings Calendar endpoint represents a single earnings event. Some fields are populated only after earnings are reported, while others are available in advance.<\/p>\n\n\n\n
Event Timing and Identification:<\/strong>
<\/strong><\/h4>\n\n\n\n
Field<\/strong><\/td>Meaning<\/strong><\/td><\/tr>
ticker<\/td>Stock symbol.<\/td><\/tr>
name<\/td>Company name.<\/td><\/tr>
exchange<\/td>Listing exchange.<\/td><\/tr>
date<\/td>Scheduled or reported earnings date.<\/td><\/tr>
time<\/td>Time of the earnings release.<\/td><\/tr>
period<\/td>Fiscal quarter (e.g. Q1, Q2).<\/td><\/tr>
period_year<\/td>Fiscal year.<\/td><\/tr>
date_confirmed<\/td>Whether the earnings date is confirmed.<\/td><\/tr>
updated<\/td>Last update timestamp.<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
EPS Data:<\/strong>
<\/strong><\/h4>\n\n\n\n
Field<\/strong><\/td>Meaning<\/strong><\/td><\/tr>
eps_est<\/td>Consensus EPS estimate.<\/td><\/tr>
eps<\/td>Reported EPS. Empty before release.<\/td><\/tr>
eps_prior<\/td>EPS from the prior period.<\/td><\/tr>
eps_surprise<\/td>EPS difference vs estimate.<\/td><\/tr>
eps_surprise_percent<\/td>EPS surprise percentage.<\/td><\/tr>
eps_type<\/td>EPS classification when applicable.<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
Before earnings are released, only the estimate and prior values are populated. Surprise fields remain empty until results are reported.<\/p>\n\n\n\n
Revenue Data:<\/strong>
<\/strong><\/h4>\n\n\n\n
Field<\/strong><\/td>Meaning<\/strong><\/td><\/tr>
revenue_est<\/td>Consensus revenue estimate.<\/td><\/tr>
revenue<\/td>Reported revenue.<\/td><\/tr>
revenue_prior<\/td>Revenue from the prior period.<\/td><\/tr>
revenue_surprise<\/td>Revenue difference vs estimate.<\/td><\/tr>
revenue_surprise_percent<\/td>Revenue surprise percentage.<\/td><\/tr>
revenue_type<\/td>Revenue classification when applicable.<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
As with EPS, revenue surprise fields are filled only after the announcement.<\/p>\n\n\n\n
Metadata:<\/strong>
<\/strong><\/h4>\n\n\n\n
Field<\/strong><\/td>Meaning<\/strong><\/td><\/tr>
importance<\/td>Relevance score (0\u20135).<\/td><\/tr>
currency<\/td>Reporting currency.<\/td><\/tr>
isin<\/td>Security identifier.<\/td><\/tr>
notes<\/td>Optional notes field.<\/td><\/tr>
id<\/td>Unique earnings record ID.<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
A key thing to note is that empty strings are common for fields that are not yet applicable. Any downstream logic should account for that rather than assuming numeric values are always present.<\/p>\n\n\n\n
Use Case 1: Basic Earnings Data Extraction<\/h2>\n\n\n\n
The most common use of the Earnings Calendar endpoint is simply pulling structured earnings data and making it usable. This includes upcoming announcements, historical earnings for a stock, and separating reported results from estimates.<\/p>\n\n\n\n
Fetch Upcoming Earnings for a Date Range<\/h3>\n\n\n\n
To pull upcoming earnings, you typically filter by date or a date range. At this stage, most result fields such as reported EPS or revenue will be empty, while estimates and prior-period values are available.<\/p>\n\n\n
\nimport requests\nimport pandas as pd\n\napi_key = "YOUR BENZINGA API KEY"\nurl = "https:\/\/api.benzinga.com\/api\/v2.1\/calendar\/earnings"\n\nheaders = {"accept": "application\/json"}\nparams = {\n    "token": api_key,\n    "parameters[date_from]": "2026-10-01",\n    "parameters[date_to]": "2026-10-31",\n    "pagesize": 10\n}\n\nr = requests.get(url, params=params, headers=headers)\nearnings = r.json()["earnings"]\n\ndf = pd.DataFrame(earnings)\ndf[["ticker", "date", "time", "eps_est", "eps_prior", "importance"]]\n<\/pre><\/div>\n\n\n
\"\"<\/figure>\n\n\n\n
This is useful for building earnings calendars, alerts, or simple watchlists ahead of announcements.<\/p>\n\n\n\n
Pull Historical Earnings for a Single Stock<\/h3>\n\n\n\n
Once earnings have been reported, the same endpoint can be used to retrieve historical results for a ticker.<\/p>\n\n\n
\nparams = {\n    "token": api_key,\n    "parameters[tickers]": "AAPL",\n    "pagesize": 10\n}\n\nr = requests.get(url, params=params, headers=headers)\nearnings = r.json()["earnings"]\n\ndf = pd.DataFrame(earnings)\ndf[["date", "period", "eps_est", "eps", "eps_surprise", "eps_surprise_percent"]]\n<\/pre><\/div>\n\n\n
\"\"<\/figure>\n\n\n\n
At this point, reported values and surprise metrics begin to appear. Empty strings in unreleased fields should be handled explicitly before any calculations.<\/p>\n\n\n\n
Separating Reported vs Upcoming Events<\/h3>\n\n\n\n
Because the endpoint mixes upcoming and past events, a simple filter helps keep things clean.<\/p>\n\n\n
\nreported = df[df["eps"].astype(str).str.strip() != ""]\nupcoming = df[df["eps"].astype(str).str.strip() == ""]\n<\/pre><\/div>\n\n\n
This distinction becomes important later when analyzing surprises or linking earnings events to price data. Upcoming entries are useful for planning. Reported entries are what you analyze.<\/p>\n\n\n\n
Use Case 2: Earnings Surprise Detection<\/h2>\n\n\n\n
Once earnings are reported, the surprise fields become the most useful part of the response. They let you quickly see where results diverged from expectations, without having to calculate anything manually.<\/p>\n\n\n\n
Identifying Beats and Misses<\/h3>\n\n\n\n
The simplest way to work with earnings surprises is to separate positive and negative outcomes. This can be done using the surprise percentage fields once reported values are available.<\/p>\n\n\n
\ndf["eps_surprise_percent"] = pd.to_numeric(\n    df["eps_surprise_percent"], errors="coerce"\n)\n\nbeats = df[df["eps_surprise_percent"] > 0]\nmisses = df[df["eps_surprise_percent"] < 0]\n\nbeats[["ticker", "date", "eps_est", "eps", "eps_surprise_percent"]]\n<\/pre><\/div>\n\n\n
This immediately highlights which companies exceeded expectations and which fell short.<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
This output shows multiple quarters of earnings for the same stock, with both the estimates and reported EPS visible. In each case here, the reported EPS is higher than the estimate, which results in a positive surprise percentage. This confirms that the filtering logic is correctly isolating earnings beats and excluding upcoming or unreleased events.<\/p>\n\n\n\n
Ranking Surprises by Magnitude<\/h3>\n\n\n\n
Not all beats or misses matter equally. Ranking surprises by size helps surface events that were more likely to influence sentiment.<\/p>\n\n\n
\nranked = df.dropna(subset=["eps_surprise_percent"]) \\\n           .sort_values("eps_surprise_percent", ascending=False)\n\nranked[["ticker", "date", "eps_surprise_percent"]].head(10)\n<\/pre><\/div>\n\n\n
Large surprises tend to draw more attention, especially when paired with higher importance scores.<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
Here, the same earnings events are reordered by surprise size. The most recent quarter is not necessarily the largest surprise. Instead, the ranking highlights which earnings releases deviated most from expectations, regardless of timing. This makes it easier to spot quarters that were genuinely unexpected rather than just \u201cbetter than expected.\u201d<\/p>\n\n\n\n
Filtering High-Impact Earnings<\/h3>\n\n\n\n
The importance field is useful for narrowing the dataset to earnings that are more likely to be widely followed.<\/p>\n\n\n
\nhigh_impact = df[\n    (df["importance"] >= 4) &\n    (df["eps_surprise_percent"].notna())\n]\n\nhigh_impact[\n    ["ticker", "date", "eps_surprise_percent", "importance"]\n]\n<\/pre><\/div>\n\n\n
This keeps the focus on events where expectations, results, and market attention all intersect. These filtered datasets are typically what you would pass into further analysis or event-based workflows.<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
Once the importance filter is applied, the dataset narrows to earnings events that Benzinga classifies as highly relevant. In this case, all listed earnings carry the maximum importance score, which makes them suitable candidates for deeper analysis or price reaction studies. This step helps remove low-signal earnings before moving on to market impact analysis.<\/p>\n\n\n\n
Use Case 3: Post-Earnings Price Reaction<\/h2>\n\n\n\n
Once earnings surprises are identified, the next step is to see how the market responded. Rather than focusing on intraday volatility, this section looks at daily price behavior after the earnings announcement. The goal is not prediction. It is to understand follow-through.<\/p>\n\n\n\n
Preparing Earnings Events for Analysis<\/h3>\n\n\n\n
We start with reported earnings only and keep the fields needed for alignment.<\/p>\n\n\n
\nevents = df[\n    df["eps_surprise_percent"].notna()\n][["ticker", "date", "eps_surprise_percent"]].copy()\n\nevents["date"] = pd.to_datetime(events["date"])\nevents\n<\/pre><\/div>\n\n\n
\"\"<\/figure>\n\n\n\n
This ensures we are working only with completed earnings events.<\/p>\n\n\n\n
Pull Daily Price Data Around Earnings<\/h3>\n\n\n\n
For each earnings event, we fetch daily bars using the Benzinga Bars API endpoint<\/a> around each earnings date and align the event with the next available trading session.<\/p>\n\n\n
\ndef get_next_close(ticker, event_date):\n    bars_url = "https:\/\/api.benzinga.com\/api\/v2\/bars"\n    params = {\n        "token": api_key,\n        "symbols": ticker,\n        "interval": "1day",\n        "from": event_date.strftime("%Y-%m-%d"),\n        "to": (event_date + pd.Timedelta(days=5)).strftime("%Y-%m-%d")\n    }\n    r = requests.get(bars_url, params=params, headers=headers).json()\n    bars = pd.DataFrame(r[0]["candles"])\n    return bars.iloc[0]["close"], bars.iloc[1]["close"]\n<\/pre><\/div>\n\n\n
This gives us:<\/p>\n\n\n\n