> ## Documentation Index
> Fetch the complete documentation index at: https://scalarfield.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Earnings Calendar & Results

> Earnings report dates, EPS actuals, and consensus estimates for US equities. Covers both historical results and upcoming scheduled reports.

<Info>**Python function:** `getEarningsData()`</Info>

| Specification      | Value                                 |
| ------------------ | ------------------------------------- |
| Delivery Frequency | continuous, real-time                 |
| Data Frequency     | event-driven (quarterly earnings)     |
| Coverage           | All US equities with earnings reports |
| Source             | Benzinga                              |
| Availability       | Free                                  |

# Product Overview

## Overview

Earnings Calendar & Results provides structured data on quarterly earnings reports for US equities. The dataset includes both **historical results** (actual EPS vs. consensus estimates) and **upcoming scheduled reports** (with estimated EPS and release timing).

Each row represents a single earnings event for a company — the date of the report, the fiscal period, the time of release, and the actual and estimated EPS values.

## Data Pipeline

Scalar Field proxies earnings data in real-time from the Benzinga API. Each query fetches live data directly — there is no local caching delay. This means upcoming earnings dates and freshly reported results are available as soon as the upstream source publishes them.

# Querying the Data

## Basic Usage

```python theme={null}
from scalarlib import getEarningsData

# Earnings for specific tickers in a date range
data = getEarningsData(['AAPL', 'GOOGL', 'MSFT'], '2025-01-01', '2025-12-31')
aapl_earnings = data['AAPL']

# All tickers with earnings in a date range
data = getEarningsData(None, '2025-01-01', '2025-12-31')
```

<Info>For upcoming earnings, set `end_date` to a future date. `epsActual` will be `None` for reports that have not yet been released.</Info>

## Parameters

| Parameter    | Type                | Required | Description                                                                  |
| ------------ | ------------------- | -------- | ---------------------------------------------------------------------------- |
| `tickers`    | list of str or None | No       | Stock symbol(s). `None` returns all tickers with earnings in the date range. |
| `start_date` | str                 | Yes      | Start date (`YYYY-MM-DD`).                                                   |
| `end_date`   | str                 | Yes      | End date (`YYYY-MM-DD`). Use a future date to include upcoming earnings.     |

## Return Schema

Returns `Dict[str, pd.DataFrame]` keyed by ticker symbol. Each DataFrame:

| Column                 | Type            | Description                                                                            |
| ---------------------- | --------------- | -------------------------------------------------------------------------------------- |
| `Date`                 | datetime64\[ns] | Date of the earnings report                                                            |
| `symbol`               | string          | Ticker symbol                                                                          |
| `earningsReportPeriod` | string          | Fiscal period (e.g. `"2025-Q3"`)                                                       |
| `earnings_time`        | string          | Time of release (e.g. `"16:30:00"`)                                                    |
| `epsActual`            | float or None   | Actual earnings per share. `None` for future earnings that have not yet been reported. |
| `epsEstimate`          | float           | Consensus EPS estimate prior to the report                                             |

<Info>When aligning earnings data with price data, remember that earnings dates may fall on non-trading days. Use `getClosestTradingDate()` to find the nearest trading session.</Info>