IV/HV Rank (52-Week)
See whether a stock's options are expensive or cheap for that stock, rather than for the market. Each name's current implied and realized volatility is placed inside its own strict trailing 52-week range, as a 0 to 100 rank and a 0 to 100 percentile, with the highs and lows behind them.
Time premium against the name's own year.
iv_rank near 100 means implied vol is at the top of that ticker's last 52 weeks; near 0 means it is scraping its own floor.
Separate stretched pricing from a genuinely wild stock.
Read iv_rank next to hv_rank: implied high while realized is not is a different setup from both being high together.
See the band you are trading inside.
iv_52w_high, iv_52w_low, and iv_52w_median give the actual vol levels the rank is measured against, not just the score.
Which stocks have options that look unusually expensive compared with how they have been priced over the past year? Rank them, and tell me whether pricing that high has historically come back down.
Your agent turns that into each name's position inside its own trailing 52-week volatility range, then reads the settled history for what happened to that pricing over the following month.
High for this stock, not high for the market.
Implied volatility is the amount of future movement option prices are charging for; realized volatility is the amount the stock actually delivered. Both are quoted as annualized percentages, and both are useful only in context, because a 45% implied vol is unremarkable at one company and extraordinary at another. This dataset supplies that context by measuring each name against itself over the trailing year.
It does so two ways. Rank is position inside the band: how far the current value sits between the year's lowest and highest reading, scaled to 0 to 100. Percentile is share of the year spent below: what fraction of the trailing year's observations were lower than today, also scaled to 0 to 100. Both are computed for implied vol and for realized vol, from the same iv and hv series that feeds the IV/HV Premium dataset, over the same universe. A ticker appears only once it has a full year of history behind it.
Each row includes:
- Current annualized implied vol and 30-trading-day realized vol for the name.
- A 52-week rank and a 52-week percentile for each of them, both on a 0 to 100 scale.
- The trailing-year high, low, and median that each rank is measured against.
- n_obs_52w, the observation count in the window, which reads 252 once the name is warm.
- Cross-sectional percentile and z-score fields placing the name's IV Rank against the rest of the universe that day.
- A settlement flag separating today's provisional value from the fixed close-of-day number.
A rank of 100 says a name is at the top of its own year, not that its volatility is high. A quiet utility at rank 100 can still carry less implied vol than a biotech sitting at rank 10.
Volatility extremes come back, and the size of the move is measurable.
The published study ran 141,169 settled rows and asked the obvious question: when a name's implied vol is at the top of its own year, what happens next. Implied vol at the top of the range falls 24.9 vol points over the following month, while implied vol at the bottom rises 11.2. The pattern is monotonic across deciles, with a correlation of -0.36. That is a mean-reversion signal with a measurable size attached, which is what makes it usable for timing rather than just describing.
The second use is divergence. iv_rank and hv_rank are computed the same way from different inputs, so comparing them tells you which side of the pricing is stretched. Implied at the top of its range while realized sits mid-range means the market is charging for movement the stock has not been making, which is the classic short-premium setup and also the classic pre-catalyst trap. Both high together usually means the stock is genuinely in a different regime, and reversion has further to run than it looks. Because the rank is name-relative and the IV/HV ratio is market-relative, running both is how you tell a name that is expensive from a day when everything is expensive.
- Screen premium-selling candidates with min_iv_rank=80, then require that hv_rank is not equally elevated.
- Screen the other side with max_iv_rank for names whose implied vol sits near its own floor ahead of a catalyst.
- Use min_iv_percentile when you care how much of the year traded below the current level rather than where the extremes sit.
- Rank the ranks: iv_rank_cs_ranked says whether an IV Rank of 80 is unusual on a day when the whole market is stretched.
- Backtest reversion on the settled series with only_final=true, and check n_obs_52w is 252 before trusting a reading.
Measured against a strict 252-observation window, then frozen.
The inputs are the daily implied and realized vol series described on the IV/HV Premium page: the at-the-money implied vol from the listed expiry nearest 30 calendar days, and 30 trading days of close-to-close realized vol, both annualized, over the same point-in-time liquid US-equity universe. Every rank, percentile, high, low, and median on a row is computed from a strict window of the last 252 observations for that ticker, counted in observations rather than calendar days, so holidays and halts cannot quietly shorten it. n_obs_52w reports the count, and a ticker is not served at all until that window is full. Daily cross-sectional fields then place the name's IV Rank against the rest of the universe on the same date.
Today's row is live. Through the session it refreshes roughly every 30 minutes between 09:30 and 16:00 ET carrying is_final = 0, which marks a provisional value that can still move as implied vol moves. After the close, around 16:30 ET, the settled value is written with is_final = 1, and from that point the date is fixed and never retroactively altered. Every past date is always 1. By default the endpoint returns the latest value per date and ticker, which during the session is today's provisional number; pass only_final=true for settled rows only. Exactly one row per date and ticker is guaranteed either way.
The rank, the percentile, and the band underneath them.
The headline fields below are a subset. Every field, with exact types and semantics, is documented in the API reference.
| Field | Type | What it tells you |
|---|---|---|
| date | string | Trading date the reading was measured on |
| ticker | string | Underlying symbol |
| iv | float | Current annualized implied vol from the option nearest 30 days out |
| iv_rank | float | Where iv sits between its own 52-week low and high, 0 to 100 |
| iv_percentile | float | Share of the trailing year that traded below the current iv, 0 to 100 |
| iv_52w_high | float | Highest iv in the trailing year; the top of the band the rank is measured in |
| iv_52w_low | float | Lowest iv in the trailing year; iv_52w_median marks the middle of the same window |
| hv | float | Current annualized 30-trading-day realized vol |
| hv_rank | float | The same range position for realized vol; the divergence check against iv_rank |
| n_obs_52w | integer | Observations in the trailing-year window; reads 252 once the name is warm |
| iv_rank_cs_ranked | float | Where this name's IV Rank sits across the day's universe, 0 to 1; iv_rank_cs_z is the z-score form |
| is_final | integer | 0 for today's provisional intraday value, 1 for a settled row. Every past date is 1 |
One call returns a name's full volatility position.
One key works across the REST API, the hosted MCP server, and this dashboard. Every response is JSON with a { count, data } envelope.
import requests
url = "https://api.alphanume.com/v1/iv-rank"
params = {
"ticker": "AAPL",
"min_iv_rank": 80,
"only_final": "true",
"api_key": "alp_abc123"
}
r = requests.get(url, params=params)
print(r.json())curl "https://api.alphanume.com/v1/iv-rank?ticker=AAPL&min_iv_rank=80&only_final=true&api_key=alp_abc123"{
"count": 1,
"data": [
{
"date": "2026-06-12",
"ticker": "AAPL",
"iv": 0.1795,
"iv_rank": 31.4,
"iv_percentile": 28.0,
"iv_52w_high": 0.42,
"iv_52w_low": 0.135,
"iv_52w_median": 0.21,
"hv": 0.2333,
"hv_rank": 58.2,
"hv_percentile": 61.0,
"hv_52w_high": 0.39,
"hv_52w_low": 0.11,
"hv_52w_median": 0.20,
"n_obs_52w": 252,
"notional_volume": 8410000000,
"iv_rank_cs_ranked": 0.34,
"iv_rank_cs_z": -0.41,
"hv_rank_cs_ranked": 0.62,
"hv_rank_cs_z": 0.39,
"is_final": 1,
"last_updated": "2026-06-12 16:31:22"
}
]
}What this data does not claim.
- Rank is defined by the year's single highest and lowest readings, so one extreme day sets the band and compresses every reading after it. Percentile is not distorted the same way, which is why both are served.
- A ticker is absent until it has 252 observations, so recent listings and names newly added to the universe are missing rather than partially ranked.
- The scale is name-relative. A high rank is a statement about this stock's own year, never about its absolute volatility level or about the market.
- Nothing here is directional. The rank measures where volatility sits, not whether the stock is more likely to rise or fall.
- Rows carrying is_final = 0 are today's provisional intraday value and can move before the close. Pull with only_final=true for research.
Asked by researchers, answered plainly.
What is the difference between IV Rank and IV Percentile?
IV Rank measures position between the year's low and high, so it depends on two single observations. IV Percentile measures the share of the year that traded below the current value, so it depends on the whole distribution. They diverge most after a vol spike: one earnings-day print can lift the 52-week high enough to push rank down to 30 while percentile still reads 70, because the stock has spent most of the year lower. Rank answers how close to the extremes, percentile answers how unusual.
What does it mean when IV Rank is high but HV Rank is low?
The options market is charging for more movement than the stock has recently been making, relative to each measure's own year. That gap is usually anticipation: earnings, a trial readout, a regulatory date. It is the setup premium sellers look for and also the one that hurts most when the catalyst delivers, since the implied number is high precisely because something is scheduled.
Is IV Rank the same as the IV/HV ratio?
No, and they routinely disagree. The IV/HV ratio compares implied against realized right now, then against the rest of the market. IV Rank compares implied against the same name a year ago. A stock can be at rank 20, near its own vol floor, and still be the richest name in the market on ratio if its realized vol has collapsed even further. Screens that use both catch what either one alone misses.
How much history does IV Rank use?
A strict 252 observations, counted in trading days that the name actually has data for rather than as a calendar year. That means holidays, halts, and any gap in the underlying series cannot silently shorten the window. n_obs_52w reports the count on every row, and a ticker is not served until the window is full, so a partially warm reading never reaches the API.
Available with Pro. Enterprise for teams.
New REST API and MCP access requires Pro or Enterprise. Public dashboard previews are separate from a subscription. Pro includes the available historical record, current updates, REST, MCP, dashboard exports, and every standard dataset as it launches. Explore the dashboard preview before subscribing; its existing limits still apply.