ticker | The stock ticker symbol, uppercased (e.g. “AAPL”). |
as_of_date | The calendar date the snapshot reflects, in YYYY-MM-DD format. |
spot | The underlying spot price at the snapshot, or null when unavailable. |
context | Event context: next_earnings carries the upcoming earnings date, the number of calendar days until it, and whether it is confirmed (null when no upcoming date is known). |
volatility | Volatility block, all in percent points: iv_30 (30-day constant-maturity at-the-money implied vol), hv_20 (20-day realized vol), iv_vs_hv (their spread), skew (near-the-money put-minus-call IV), iv_rank and iv_percentile (position of today’s IV30 in its own trailing-year range and the share of days below it, 0-100), iv_1y_low / iv_1y_high (the year’s IV extremes with their dates), and hv_rank (the interim realized-vol rank). Rank, percentile, and the 1-year extremes are null until the daily series has collected a year of history. |
flow | Today’s options volume: total volume with the put and call splits, pc_ratio (put ÷ call volume), vs_avg_30d (today vs the trailing 30-day average, 1.15 = 115%), pc_5d_avg (trailing 5-day average volume P/C), and pc_percentile_1y (today’s volume P/C percentile in the trailing year, 0-100). The averages and percentile are null while the daily series accumulates. |
positioning | The accumulated open-interest book: open_interest with the put and call splits, pc_ratio, vs_avg_30d (today’s OI vs its trailing 30-day average), max_pain (the strike with the least total option value at expiry, the expiry it applies to, and spot_vs = spot ÷ strike − 1), and top_strikes (the largest open-interest strikes per side as [strike, share-of-side-OI] pairs). |
expected_move | Per-expiry expected moves from the at-the-money straddle: expiry, days ahead, pct (the ±% move) and dollars (the ± dollar move). The entry on or after the next earnings date carries post_earnings: true so the event-spanning move is never missed. |
probability | Lognormal price bands at one target expiry (the first post-earnings expiry when one is known): expiry, method, and bands with the p10/p25/p50/p75/p90 price levels. Null when no bands could be computed. |
derived | Quotable plain-English sentences summarizing flow, volatility, and the priced-in move. The first sentence doubles as a headline. |
flags | Notable conditions on this snapshot (e.g. volume_above_average, iv_rank_high, pc_volume_high_extreme, chain_truncated). |
scope | What was summarized: selection (full_chain or partial_chain when the fetch cap stopped at a prefix), contracts_analyzed, expirations_covered, and pages_fetched. |
data_quality | Reading reliability: status (“ok”, “thin” for a sparse or zero-volume chain, or “no_data”), history (status and days_collected for the trailing daily series the rank/average fields depend on), and an optional note describing any caveat. |
methodology | A versioned description of how each figure is computed (iv_30, hv_20, skew, expected_move, probability_bands, max_pain, and the flag_thresholds), so explanations stay grounded in the actual computation. |
