Earnings Preview

# Earnings Preview

Generate a pre-earnings briefing for any stock using Yahoo Finance data.

## What it does

- Shows upcoming earnings date and key dates
- Presents consensus EPS and revenue estimates with analyst count and range
- Reviews the company's historical beat/miss track record (last 4 quarters)
- Summarizes analyst sentiment (buy/hold/sell distribution, price targets)
- Highlights key metrics to watch based on recent quarterly trends

## Triggers

`earnings preview for AAPL`, `what to expect from TSLA earnings`, `MSFT reports next week`, `pre-earnings analysis`, `what are analysts expecting`, `will GOOGL beat earnings`, `earnings beat/miss history`, `upcoming earnings`, `consensus estimates`, `EPS expectations`, `what's the street expecting`, `earnings season preview`

## Prerequisites

- Python 3.8+
- `yfinance` (auto-installed if missing)

## Platform

All platforms (Claude Code, Claude.ai, other agents)

## Setup

No setup required — yfinance pulls data from Yahoo Finance without authentication.

## Reference Files

- `references/api_reference.md` — yfinance API reference for earnings and estimate methods


# Earnings Preview — yfinance API Reference

Detailed reference for the yfinance methods used by the earnings-preview skill.

---

## Calendar

```python
ticker.calendar
```

Returns a dictionary with upcoming events:
- `Earnings Date` — list of datetime objects (usually a range like [start, end])
- `Ex-Dividend Date` — next ex-dividend date
- `Dividend Date` — next dividend payment date

**Edge cases:**
- Some tickers return an empty dict if no upcoming events are scheduled
- Earnings dates may show as a 2-day range (the company hasn't specified exact date/time)

---

## Earnings Estimate

```python
ticker.earnings_estimate
```

Returns a DataFrame indexed by period:
- `0q` — current quarter
- `+1q` — next quarter
- `0y` — current year
- `+1y` — next year

Columns:
- `numberOfAnalysts` — number of analysts covering
- `avg` — consensus average EPS
- `low` — lowest estimate
- `high` — highest estimate
- `yearAgoEps` — EPS from the same period last year
- `growth` — expected growth rate (decimal, e.g., 0.127 = 12.7%)

---

## Revenue Estimate

```python
ticker.revenue_estimate
```

Same structure as `earnings_estimate` but for revenue:
- `numberOfAnalysts`, `avg`, `low`, `high`, `yearAgoRevenue`, `growth`

**Note**: Revenue figures are in raw numbers (not millions/billions). Format appropriately for display.

---

## Earnings History

```python
ticker.earnings_history
```

Returns a DataFrame with the last 4 quarters of actual vs estimated earnings:

Columns:
- `epsEstimate` — consensus EPS estimate at the time
- `epsActual` — reported EPS
- `epsDifference` — actual minus estimate
- `surprisePercent` — surprise as a percentage (decimal)

Index is datetime of each earnings report.

**Note**: `surprisePercent` is already in decimal form (0.037 = 3.7%). Multiply by 100 for display.

---

## Analyst Price Targets

```python
ticker.analyst_price_targets
```

Returns a dictionary:
- `current` — current price
- `low` — lowest analyst target
- `high` — highest analyst target
- `mean` — average target
- `median` — median target

---

## Recommendations

```python
ticker.recommendations
```

Returns a DataFrame with recommendation counts by period. Columns typically:
- `strongBuy`, `buy`, `hold`, `sell`, `strongSell`
- Index represents the period

Use the most recent row for current analyst sentiment distribution.

---

## Quarterly Financial Statements

```python
ticker.quarterly_income_stmt   # Income statement
ticker.quarterly_balance_sheet  # Balance sheet
ticker.quarterly_cashflow       # Cash flow
```

Each returns a DataFrame with financial line items as rows and quarter dates as columns (most recent first).

Key income statement rows for earnings preview:
- `Total Revenue`
- `Gross Profit`
- `Operating Income`
- `Net Income`
- `Basic EPS` / `Diluted EPS`
- `EBITDA`

**Tip**: Compare the last 2-4 quarters to ident