# Stock Analyzer — Data Source Reference

This describes what data is actually available from each source your app touches, so we know what's realistic to add to the table/chart.

## 1. Yahoo Finance (via `yfinance` in `scraper.py`)

This is your primary data source — the one that populates the table and chart. Based on the error traces you've shared (`quoteSummary`, `period=1mo`), `scraper.py` is using the `yfinance` Python library, which wraps Yahoo's internal quote/history endpoints.

### Real-time / snapshot fields (`Ticker.info` or `Ticker.fast_info`)
| Field | Description |
|---|---|
| `regularMarketPrice` | Current (or last) trade price |
| `regularMarketTime` | **Actual timestamp of that last trade/quote** — this is what should drive your displayed timestamp instead of the moment the query ran |
| `previousClose` | Prior session's closing price — needed for change/% change |
| `open`, `dayHigh`, `dayLow` | Today's session range |
| `fiftyTwoWeekHigh`, `fiftyTwoWeekLow` | 52-week range |
| `volume` | Shares traded today |
| `marketCap` | Market capitalization (not available for indices like `^DJI`) |
| `currency`, `exchange` | Quote currency and listing exchange |
| `marketState` | Yahoo's own flag: `PRE`, `REGULAR`, `POST`, `CLOSED` — more reliable than computing market hours ourselves |

**Note:** for index symbols (`^DJI`, `^GSPC`, `^IXIC`), some fields like `marketCap` and `volume` are not meaningful and will be null/absent — expect the table to handle missing values gracefully for those rows.

### Historical data (`Ticker.history(period=...)`)
Supported `period` values: `1d`, `5d`, `1mo`, `3mo`, `6mo`, `1y`, `2y`, `5y`, `10y`, `ytd`, `max`
Supported `interval` values: `1m`, `2m`, `5m`, `15m`, `30m`, `60m`, `1d`, `1wk`, `1mo` (intraday intervals only work within the last ~60 days)

For the chart period buttons you asked for (7d / 30d / 6mo / 1yr), the mapping would be:
| Button | `yfinance` call |
|---|---|
| 7 Day | `period='7d', interval='1d'` |
| 30 Day | `period='1mo', interval='1d'` |
| 6 Month | `period='6mo', interval='1d'` |
| 1 Year | `period='1y', interval='1wk'` (weekly points keep the payload small; daily works too if you want more granularity) |

Each `.history()` call returns `Open`, `High`, `Low`, `Close`, `Volume` per row — enough to also support candlestick charts later, not just a line chart, if that's ever of interest.

### Rate limits / reliability
`yfinance` scrapes Yahoo's undocumented endpoints, not an official paid API — it can intermittently 404 or rate-limit under heavy use (as you've already seen). There's no SLA. If this app grows beyond personal use, a paid provider (see below) would be more stable.

## 2. Google Finance (currently: direct link only)

Your app currently only **opens a link** to `https://www.google.com/finance/quote/SYMBOL` — it doesn't fetch any structured data from Google. Google has no public/free API for this; scraping their finance pages isn't something I'd recommend building since it violates their Terms of Service and breaks without warning. If you want a second data source with an actual API, better options are:

| Provider | Free tier | Notes |
|---|---|---|
| **IEX Cloud** | Limited free tier | Real-time-ish US equities, official API |
| **Alpha Vantage** | 25 requests/day free | Historical + intraday, indices supported |
| **Finnhub** | 60 calls/min free | You've used this before for your stock dashboard project |
| **Twelve Data** | 800 requests/day free | Good index support |

None of these are drop-in replacements for `yfinance`'s zero-cost, no-signup convenience, but they're worth knowing about if reliability becomes a real problem.

---

**Bottom line for your requested features:**
- ✅ **Correct source timestamp** — use `regularMarketTime` from yfinance instead of PHP's `date()` call time
- ✅ **Change from previous close** — `regularMarketPrice - previousClose`, already available per-symbol
- ✅ **52-week high/low** — `fiftyTwoWeekHigh` / `fiftyTwoWeekLow`, already available per-symbol
- ✅ **7d/30d/6mo/1yr chart toggle** — all achievable via `.history(period=...)`, just need `scraper.py` to accept a period parameter and the frontend to pass it

All four are doable with what yfinance already exposes — no new data source needed. I just need to see `scraper.py` to wire them in correctly rather than guessing its current structure.