How to Get IV Rank and IV Percentile Data via API

Pull IV rank and IV percentile for any ticker, or screen the whole market, with Alphanume's IV/HV Rank endpoint.

IV rank and IV percentile both place current implied volatility inside a trailing window, but they answer slightly different questions. Rank measures where you sit in the high-to-low band; percentile measures how much of the year traded below you. The Alphanume IV/HV Rank (52-Week) endpoint returns both, for a single name or across the universe.

The endpoint

GET https://api.alphanume.com/v1/iv-rank

Authenticate with ?api_key=alp_your_key or an X-API-Key header. The key filters are min_iv_rank and max_iv_rank, min_hv_rank and max_hv_rank, min_iv_percentile, and only_final for settled rows.

Get one ticker

import requests

r = requests.get(
    "https://api.alphanume.com/v1/iv-rank",
    params={"ticker": "AAPL", "only_final": "true", "api_key": "alp_your_key"},
)
row = r.json()["data"][0]
print(row["iv_rank"], row["iv_percentile"], row["iv_52w_high"], row["iv_52w_low"])

Screen the whole market

Drop the ticker and filter on rank to find every name with elevated implied volatility:

GET https://api.alphanume.com/v1/iv-rank?min_iv_rank=80&only_final=true&api_key=alp_your_key

A high iv_rank flags names trading near the top of their yearly volatility band, which is where premium sellers tend to look. Cross-reference iv_rank against hv_rank to find divergences, where the market is pricing more or less volatility than the stock has recently realized.

Final versus provisional rows

Each row carries an is_final flag. For live screening, use the provisional rows that refresh through the session. For backtests, pass only_final=true so you only ever see settled values, which keeps your history honest.

Access and limits

IV/HV Rank is on the free tier as a rolling 30-day delayed window, with Pro at 600 requests per minute. A ticker appears only after a full year of history. Start with a free Alphanume API key and the API documentation, or explore it on Alphanume.

Reading rank and percentile together

Rank and percentile answer subtly different questions, and reading them together is more informative than either alone. Rank tells you where current implied volatility sits in the high-to-low band; percentile tells you how much of the year traded below it. A high rank with a lower percentile, for instance, hints at a recent spike rather than a sustained elevated level.

The endpoint returns both for a single ticker or across the universe, alongside the 52-week high, low, and median, and the matching realized-volatility fields. Comparing iv_rank against hv_rank surfaces names where the market is pricing more or less movement than the stock has recently delivered, which is where mispriced options tend to hide.

Frequently asked questions

What is the IV rank endpoint?

GET https://api.alphanume.com/v1/iv-rank. Authenticate with ?api_key=alp_your_key or an X-API-Key header. Pass a ticker for one name or filter to screen the market.

Which filters are available?

min_iv_rank and max_iv_rank, min_hv_rank and max_hv_rank, min_iv_percentile, and only_final for settled rows.

How do I screen for high implied volatility?

Call the endpoint with min_iv_rank=80 and only_final=true to return every name trading near the top of its yearly volatility band.

What does an IV rank versus HV rank divergence tell me?

It flags names where the market is pricing more or less volatility than the stock has recently realized, which can point to mispriced options.

Should I use final or provisional rows?

Use provisional rows for live screening and only_final=true for backtests. The is_final flag on each row tells you which is which.