Options

Initialization

All examples on this page assume the following initialization has been completed:

from tigeropen.tiger_open_config import TigerOpenClientConfig
from tigeropen.quote.quote_client import QuoteClient

client_config = TigerOpenClientConfig(props_path='your_config_directory_path')
quote_client = QuoteClient(client_config)

For details, see Prerequisites.

Get Option Expiration Dates

QuoteClient.get_option_expirations(symbols, market=None)

Description

Retrieves option expiration dates.

Request Frequency

For rate limits, see API Request Limits

Parameters

Parameter	Type	Required	Description
symbols	`list[str]`	Yes	Underlying symbols; maximum 30 symbols. For Hong Kong contracts, use symbols provided by get_option_symbols in format "CODE.HK"
market	`tigeropen.common.consts.Market`	No	Market, `Market.US` or `Market.HK`; default `None`

Returns

pandas.DataFrame

The meaning of each column is as follows:

Parameter	Type	Description
symbol	str	Underlying stock symbol
option_symbol	str	Option symbol; index options may differ from `symbol`
date	str	Expiration date in YYYY-MM-DD format
timestamp	int	Expiration date timestamp in milliseconds
period_tag	str	Option period tag, m for monthly options, w for weekly options

Example

from tigeropen.common.consts import Market
expiration = quote_client.get_option_expirations(symbols=['AAPL'], market=Market.US)
#for HK contracts
#expirationHK = quote_client.get_option_expirations(symbols=["MET.HK"],market=Market.HK)
print(expiration.head())

Example Response

  symbol        date      timestamp
0    AAPL  2019-01-11  1547182800000
1    AAPL  2019-01-18  1547787600000
2    AAPL  2019-01-25  1548392400000
3    AAPL  2019-02-01  1548997200000
4    AAPL  2019-02-08  1549602000000

Special option symbols for indices

S&P 500 (.SPX): monthly options use SPX; weekly and quarterly options use SPXW.
Nasdaq-100: monthly options use NDX; weekly options use NDXP.
VIX: monthly options use VIX; weekly options use VIXW.

Get Option Real-time Quotes

QuoteClient.get_option_briefs(identifiers, market=None, timezone=None)

Description

Retrieves option real-time quotes.

Request Frequency

For rate limits, see API Request Limits

Parameters

Parameter	Type	Required	Description
identifiers	`list[str]`	Yes	Option identifiers, up to 30
market	`tigeropen.common.consts.Market`	No	Market, US: US stocks, HK: Hong Kong stocks. Default: None (server infers from symbol)
timezone	str	No	Timezone, such as 'US/Eastern', 'Asia/Hong_Kong'

Returns

pandas.DataFrame

The meaning of each column is as follows:

Field	Type	Description
identifier	str	Option code
symbol	str	Underlying stock symbol
expiry	int	Expiration time in milliseconds at midnight
strike	float	Strike price
put_call	str	Option direction, `PUT` or `CALL`
multiplier	int	Contract multiplier; usually 100 for US options
bid_price	float	Bid price
bid_size	int	Bid size
ask_price	float	Ask price
ask_size	int	Ask size
latest_price	float	Latest price
latest_time	int	Latest trade timestamp in milliseconds
volume	int	Volume
high	float	High price
low	float	Low price
open	float	Open price
pre_close	float	Previous close price
open_interest	int	Open interest
change	float	Price change
rates_bonds	float	One-year US Treasury rate, updated daily, e.g., 0.0078 means actual rate: 0.78%
volatility	str	Historical volatility
mid_price	float	Mid price
mid_timestamp	int	Timestamp of the mid price
mark_price	float	Mark price
mark_timestamp	int	Timestamp of the mark price
pre_mark_price	float	Previous mark price
selling_return	float	Annualized return from selling

Example

from tigeropen.common.consts import Market
briefs = quote_client.get_option_briefs(['AAPL  230317C00135000'], market=Market.US)
# Hong Kong options
# briefs = quote_client.get_option_briefs(['TCH.HK 230317C00135000'], market=Market.HK)

Example Response

           identifier symbol         expiry strike put_call  multiplier  ask_price     open  \ 
NVDA  260116C00100000   NVDA  1768539600000  100.0     CALL         100      79.05       65  \  

ask_size  bid_price  bid_size  pre_close  latest_price latest_time  volume  open_interest \
    78.0        178      78.7       78.2          None          36   84175          78.09 \

 high    low  rates_bonds volatility  change 
79.57  77.89     0.036165     29.29%    -0.5

Get Option Chain

QuoteClient.get_option_chain(symbol, expiry, option_filter=None, return_greek_value=None, market=None, timezone=None, **kwargs)

Description

Retrieves option chain.

⚠️
Option-chain Greeks are deprecated
Greek-related option-chain request flags, filters/models, and response fields delta, gamma, theta, vega, and rho are Deprecated. Their values are updated daily and are not timely enough for intraday use. Do not use them for real-time trading decisions. Use Option Calculation Tools with current market inputs instead.

Request Frequency

For rate limits, see API Request Limits

Parameters

Parameter	Type	Required	Description
symbol	str	Yes	Underlying stock symbol
expiry	str or int	Yes	Option expiration date, numeric timestamp in milliseconds or date string, e.g., 1705640400000 or '2024-01-19'
option_filter	`tigeropen.quote.domain.filter.OptionFilter`	No	Filter parameters, optional
return_greek_value	bool	No	Deprecated. Whether to return daily-updated Greek values; do not use them for real-time trading decisions
market	`tigeropen.common.consts.Market`	No	Market, supports US/HK. Default: None (server infers from symbol)
timezone	str	No	Timezone, such as 'US/Eastern', 'Asia/Hong_Kong'

Filter parameters:

For all filtering indicators except the inthe_money attribute, other indicators use field names with min suffix (representing minimum range value) or _max suffix (representing maximum range value), such as delta_min, theta_max. See code examples.

OptionFilter filterable indicators are as follows:

Parameter	Type	Required	Description
implied_volatility	float	No	Implied volatility, reflecting the market's expectation of future stock price volatility. Higher implied volatility indicates expected greater price volatility.
in_the_money	bool	No	Whether the option is in the money
open_interest	int	No	Open interest, the number of contracts held by market participants at the end of each trading day. Reflects market depth and liquidity.
delta	float	No	Deprecated. Daily-updated Delta filter; not suitable for intraday use
gamma	float	No	Deprecated. Daily-updated Gamma filter; not suitable for intraday use
theta	float	No	Deprecated. Daily-updated Theta filter; not suitable for intraday use
vega	float	No	Deprecated. Daily-updated Vega filter; not suitable for intraday use
rho	float	No	Deprecated. Daily-updated Rho filter; not suitable for intraday use

Returns

pandas.DataFrame

Field Name	Type	Description
identifier	str	Option code
symbol	str	Underlying stock symbol for the option
expiry	int	Option expiration date, millisecond timestamp
strike	float	Strike price
put_call	str	Option direction
multiplier	int	Multiplier
ask_price	float	Ask price
ask_size	int	Ask size
bid_price	float	Bid price
bid_size	int	Bid size
pre_close	float	Previous close
latest_price	float	Latest price
last_timestamp	int	Latest trade timestamp in milliseconds
volume	int	Volume
open_interest	int	Open interest quantity
implied_vol	float	Implied volatility
delta	float	Deprecated. Daily-updated Delta; not suitable for intraday use
gamma	float	Deprecated. Daily-updated Gamma; not suitable for intraday use
theta	float	Deprecated. Daily-updated Theta; not suitable for intraday use
vega	float	Deprecated. Daily-updated Vega; not suitable for intraday use
rho	float	Deprecated. Daily-updated Rho; not suitable for intraday use

Example

import pandas as pd
from tigeropen.common.consts import Market
from tigeropen.quote.domain.filter import OptionFilter

option_chain = quote_client.get_option_chain(symbol='AAPL', expiry='2024-01-19', market=Market.US)
print(option_chain)

option_filter = OptionFilter(
    implied_volatility_min=0.5,
    implied_volatility_max=0.9,
    open_interest_min=100,
    in_the_money=True,
)
option_chain = quote_client.get_option_chain('AAPL', '2024-01-19', option_filter=option_filter, market=Market.US)
print(option_chain)

# Convert expiry time format
option_chain['expiry_date'] = pd.to_datetime(option_chain['expiry'], unit='ms').dt.tz_localize('UTC').dt.tz_convert('US/Eastern')

Example Response

  symbol         expiry             identifier strike put_call  volume  latest_price  \       
0   AAPL  1689912000000  AAPL  230721C00095000   95.0     CALL       0         80.47        
1   AAPL  1689912000000  AAPL  230721C00100000  100.0     CALL       0         73.50       

pre_close  open_interest  multiplier  implied_vol     delta     gamma     theta      vega \
    80.47            117         100     0.989442  0.957255  0.001332 -0.061754  0.059986 \
    76.85            206         100     0.903816  0.955884  0.001497 -0.058678  0.060930 \

rho                    expiry_date
0.133840 2023-07-21 00:00:00-04:00
0.141341 2023-07-21 00:00:00-04:00

Get Option Depth Quotes

QuoteClient.get_option_depth(identifiers: list[str], market, timezone=None)

Description

Retrieves option depth market data. Supports US and Hong Kong market options.

Request Frequency

For rate limits, see API Request Limits

Parameters

Parameter	Type	Required	Description
identifiers	`list[str]`	Yes	List of option codes, up to 30, e.g., ['AAPL 220128C000175000']. Format Description
market	`tigeropen.common.consts.Market`	No	Market, US/HK. Default: Market.US
timezone	str	No	Timezone, default value is 'US/Eastern', Hong Kong options need to pass 'Asia/Hong_Kong'

Returns

dict

Structure as follows:

Parameter	Type	Description
identifier	str	Option symbol
asks	`list[tuple]`	Ask information
bids	`list[tuple]`	Bid information

Each item in asks and bids is a tuple, with tuple elements composed of (price, volume, timestamp, code)

Example

from tigeropen.common.consts import Market
from tigeropen.common.util.contract_utils import get_option_identifier
identifier = 'AAPL 240119P00134000'
# Or generated from four elements
# identifier = get_option_identifier('AAPL', '20240119', 'PUT', 134)


result = quote_client.get_option_depth([identifier], market=Market.US)
print(result)

Example Response

Single underlying:

{'identifier': 'ADBE 240816C00560000', 
 'asks': [(18.3, 36, 1719852973090, 'PHLX'), (18.3, 19, 1719852973090, 'EDGX'), (18.3, 14, 1719852972660, 'MPRL'), (18.3, 14, 1719852972512, 'BOX'), (18.3, 13, 1719852973090, 'EMLD'), (18.3, 12, 1719852973090, 'MIAX'), (18.3, 11, 1719852969837, 'ISE'), (18.3, 10, 1719852973487, 'AMEX'), (18.3, 10, 1719852973090, 'CBOE'), (18.3, 7, 1719852973090, 'GEM'), (18.3, 7, 1719852969591, 'MCRY'), (18.3, 7, 1719852969585, 'BZX'), (18.3, 6, 1719852969647, 'NSDQ'), (18.3, 4, 1719852973525, 'ARCA'), (18.3, 3, 1719852972512, 'MEMX'), (18.3, 3, 1719852969818, 'C2'), (18.3, 2, 1719852973422, 'BX')], 
 'bids': [(17.9, 8, 1719852972512, 'BOX'), (17.9, 7, 1719852973487, 'AMEX'), (17.9, 6, 1719852973090, 'EMLD'), (17.9, 6, 1719852972660, 'MPRL'), (17.9, 6, 1719852969837, 'ISE'), (17.9, 5, 1719852973422, 'BX'), (17.9, 5, 1719852973090, 'PHLX'), (17.9, 5, 1719852969647, 'NSDQ'), (17.9, 5, 1719852969591, 'MCRY'), (17.9, 4, 1719852973090, 'EDGX'), (17.9, 4, 1719852973090, 'MIAX'), (17.9, 3, 1719852973525, 'ARCA'), (17.9, 2, 1719852973090, 'CBOE'), (17.9, 2, 1719852973090, 'GEM'), (17.9, 2, 1719852969818, 'C2'), (17.9, 1, 1719852969585, 'BZX'), (17.85, 6, 1719852972512, 'MEMX')]
}

Multiple underlyings:

{'ADBE 240816C00560000': 
    {'identifier': 'ADBE 240816C00560000', 
     'asks': [(18.3, 36, 1719852973090, 'PHLX'), (18.3, 19, 1719852973090, 'EDGX'), (18.3, 14, 1719852972660, 'MPRL'), (18.3, 14, 1719852972512, 'BOX'), (18.3, 13, 1719852973090, 'EMLD'), (18.3, 12, 1719852973090, 'MIAX'), (18.3, 11, 1719852969837, 'ISE'), (18.3, 10, 1719852973487, 'AMEX'), (18.3, 10, 1719852973090, 'CBOE'), (18.3, 7, 1719852973090, 'GEM'), (18.3, 7, 1719852969591, 'MCRY'), (18.3, 7, 1719852969585, 'BZX'), (18.3, 6, 1719852969647, 'NSDQ'), (18.3, 4, 1719852973525, 'ARCA'), (18.3, 3, 1719852972512, 'MEMX'), (18.3, 3, 1719852969818, 'C2'), (18.3, 2, 1719852973422, 'BX')], 
     'bids': [(17.9, 8, 1719852972512, 'BOX'), (17.9, 7, 1719852973487, 'AMEX'), (17.9, 6, 1719852973090, 'EMLD'), (17.9, 6, 1719852972660, 'MPRL'), (17.9, 6, 1719852969837, 'ISE'), (17.9, 5, 1719852973422, 'BX'), (17.9, 5, 1719852973090, 'PHLX'), (17.9, 5, 1719852969647, 'NSDQ'), (17.9, 5, 1719852969591, 'MCRY'), (17.9, 4, 1719852973090, 'EDGX'), (17.9, 4, 1719852973090, 'MIAX'), (17.9, 3, 1719852973525, 'ARCA'), (17.9, 2, 1719852973090, 'CBOE'), (17.9, 2, 1719852973090, 'GEM'), (17.9, 2, 1719852969818, 'C2'), (17.9, 1, 1719852969585, 'BZX'), (17.85, 6, 1719852972512, 'MEMX')]}, 
 'ADBE 240816P00560000': 
    {'identifier': 'ADBE 240816P00560000', 
     'asks': [(17.45, 6, 1719863999000, 'BOX'), (17.45, 5, 1719863999000, 'EMLD'), (17.45, 5, 1719863999000, 'PHLX'), (17.45, 1, 1719863999000, 'CBOE'), (17.45, 1, 1719863999000, 'ISE'), (17.45, 1, 1719863999000, 'ARCA'), (17.45, 1, 1719863999000, 'MPRL'), (17.45, 1, 1719863999000, 'NSDQ'), (17.45, 1, 1719863999000, 'BX'), (17.45, 1, 1719863999000, 'C2'), (17.45, 1, 1719863999000, 'BZX'), (21.65, 4, 1719863999000, 'EDGX'), (22.0, 2, 1719863999000, 'AMEX'), (27.3, 1, 1719863999000, 'GEM'), (27.5, 1, 1719863999000, 'MIAX'), (28.0, 1, 1719863999000, 'MCRY'), (0.0, 0, 1719864000000, 'MEMX')], 
     'bids': [(17.05, 6, 1719863999000, 'ISE'), (17.05, 5, 1719863999000, 'BOX'), (17.05, 5, 1719863999000, 'PHLX'), (17.05, 3, 1719863999000, 'MCRY'), (17.05, 2, 1719863999000, 'ARCA'), (17.05, 2, 1719863999000, 'MPRL'), (17.05, 2, 1719863999000, 'NSDQ'), (17.05, 2, 1719863999000, 'BX'), (17.05, 2, 1719863999000, 'BZX'), (17.05, 1, 1719863999000, 'AMEX'), (17.05, 1, 1719863999000, 'CBOE'), (17.05, 1, 1719863999000, 'GEM'), (17.05, 1, 1719863999000, 'C2'), (15.6, 1, 1719863999000, 'EDGX'), (15.5, 1, 1719863999000, 'MIAX'), (11.95, 1, 1719863999000, 'EMLD'), (0.0, 0, 1719864000000, 'MEMX')]}
  }

Get Option Tick-by-Tick Trade Data

QuoteClient.get_option_trade_ticks(identifiers)

Description

Retrieves option tick-by-tick trade data.

Request Frequency

For rate limits, see API Request Limits

Parameters

Parameter	Type	Required	Description
identifiers	`list[str]`	Yes	List of option codes, up to 30, e.g., ['AAPL 220128C000175000']. Format Description
timezone	str	No	Default US/Eastern. When querying non-U.S. options, specify the corresponding timezone

Returns

pandas.DataFrame

Structure as follows:

Parameter	Type	Description
symbol	str	Underlying stock symbol for the option
expiry	str	Option expiration time in YYYY-MM-DD format
put_call	str	Option direction
strike	float	Strike price
time	int	Trade time
price	float	Trade price
volume	int	Trade volume

Example

from tigeropen.common.util.contract_utils import get_option_identifier
identifier =  'AAPL 240119P00134000'
# Or generated from four elements
# identifier = get_option_identifier('AAPL', '20240119', 'PUT', 134)


option_trade_ticks = quote_client.get_option_trade_ticks([identifier])

Example Response

                identifier symbol         expiry put_call  strike           time  price  volume
0    AAPL  220128C00175000   AAPL  1643346000000     CALL   175.0  1640701803177   9.38       9
1    AAPL  220128C00175000   AAPL  1643346000000     CALL   175.0  1640701803177   9.38       1
2    AAPL  220128C00175000   AAPL  1643346000000     CALL   175.0  1640701803846   9.46       7
3    AAPL  220128C00175000   AAPL  1643346000000     CALL   175.0  1640701806266   9.55       1
4    AAPL  220128C00175000   AAPL  1643346000000     CALL   175.0  1640701918302   9.08       1
...                    ...    ...            ...      ...     ...            ...    ...    ...
111  AAPL  220128C00175000   AAPL  1643346000000     CALL   175.0  1640722112754   8.91      25
112  AAPL  220128C00175000   AAPL  1643346000000     CALL   175.0  1640723067491   9.00       4
113  AAPL  220128C00175000   AAPL  1643346000000     CALL   175.0  1640723585351   8.85       4
114  AAPL  220128C00175000   AAPL  1643346000000     CALL   175.0  1640724302670   9.13       2
115  AAPL  220128C00175000   AAPL  1643346000000     CALL   175.0  1640724600973   8.85       1

Get Option K-Line Data

QuoteClient.get_option_bars(identifiers, begin_time=-1, end_time=4070880000000, period=BarPeriod.DAY, limit=None, sort_dir=None, market=None, timezone=None)

Description

Retrieves option candlestick bars.

Request Frequency

For rate limits, see API Request Limits

Parameters

Parameter Name	Type	Required	Description
identifiers	list[str]	Yes	Option identifiers; maximum 30 per request, e.g., `['AAPL 220128C000175000']`. See Format Description
begin_time	str or int	No	Start time, millisecond timestamp or date string, e.g. 1643346000000 or '2019-01-01'. Default: -1 (earliest available)
end_time	str or int	No	End time, millisecond timestamp or date string, e.g. 1643346000000 or '2019-01-01'. Default: 4070880000000 (far future)
period	tigeropen.common.consts.BarPeriod	No	Bar period: DAY (daily), ONE_MINUTE (1 minute), FIVE_MINUTES (5 minutes), HALF_HOUR (30 minutes), or ONE_HOUR (60 minutes)
limit	int	No	Number of bars returned per option
sort_dir	tigeropen.common.consts.SortDirection	No	Sort order, enum ASC/DESC, default ASC
market	tigeropen.common.consts.Market	No	Market, US: US stocks, HK: Hong Kong stocks. Default: None (server infers from identifier)
timezone	str	No	Time zone, e.g. 'US/Eastern', 'Asia/Hong_Kong'

Returns

pandas.DataFrame

Structure as follows:

Parameter Name	Type	Description
identifier	str	Option code
symbol	str	Underlying stock symbol
expiry	int	Expiry date, millisecond timestamp
put_call	str	Option direction
strike	float	Strike price
time	int	Bar time, millisecond timestamp
open	float	Opening price
high	float	Highest price
low	float	Lowest price
close	float	Closing price
volume	int	Trading volume
open_interest	int	Open interest

Example

from tigeropen.common.consts import BarPeriod, Market
from tigeropen.common.util.contract_utils import get_option_identifier
identifier =  'AAPL 190104P00134000'
# Or generated from four elements
# identifier = get_option_identifier('AAPL', '20190104', 'PUT', 134)

bars = quote_client.get_option_bars([identifier],period = BarPeriod.DAY, market=Market.US)
print(bars)

# Convert time format
bars['expiry_date'] = pd.to_datetime(bars['expiry'], unit='ms').dt.tz_localize('UTC').dt.tz_convert('US/Eastern')
bars['time_date'] = pd.to_datetime(bars['time'], unit='ms').dt.tz_localize('UTC').dt.tz_convert('US/Eastern')

Example Response

           identifier symbol         expiry put_call  strike           time   open   high  \ 
AAPL  220128C00175000   AAPL  1643346000000     CALL   175.0  1639026000000   8.92   9.80  \                  AAPL  220128C00175000   AAPL  1643346000000     CALL   175.0  1639112400000   9.05  10.80  \   AAPL  220128C00175000   AAPL  1643346000000     CALL   175.0  1639371600000  11.70  12.50  \

 low  close  volume  open_interest               expiry_date                 time_date
8.00   8.20     364              0 2022-01-28 00:00:00-05:00 2021-12-09 00:00:00-05:00
7.80  10.80     277            177 2022-01-28 00:00:00-05:00 2021-12-10 00:00:00-05:00
8.72   8.75     304            328 2022-01-28 00:00:00-05:00 2021-12-13 00:00:00-05:00

Get Option Intraday Data

QuoteClient.get_option_timeline(identifiers, market=None, begin_time=None, timezone=None)

Description

Retrieves intraday data for options.

Request Frequency

For rate limits, see API Request Limits

Parameters

Parameter	Type	Required	Description
identifiers	str or list[str]	Yes	One or more option identifiers. See Format Description
market	Market or str	No	Market code: `US` or `HK`. If omitted, the server determines the market from the identifiers
begin_time	str or int	No	Start date as `yyyy-MM-dd` or a Unix timestamp in milliseconds
timezone	str	No	Time zone used to interpret dates. Defaults to New York time for US options and Hong Kong time for HK options

Returns

Field	Type	Description
identifier	str	Option symbol
symbol	str	Underlying stock symbol
put_call	str	Call or Put (CALL/PUT)
expiry	int	Expiry time
strike	str	Strike price
pre_close	float	Previous day's closing price
volume	int	Trading volume
avg_price	float	Average trading price
price	float	Latest price
time	int	Current time-series time

Example

from tigeropen.common.consts import BarPeriod, Market
from tigeropen.common.util.contract_utils import get_option_identifier
identifier =  'TCH.HK 250929C00510000'
# Or generated from four elements
# identifier = get_option_identifier('TCH.HK', '20190104', 'PUT', 134)

result = quote_client.get_option_timeline([identifier], market=Market.HK)
print(result)

Example Response

                identifier  symbol         expiry put_call  strike  pre_close  price  \
0    TCH.HK250929C00510000  TCH.HK  1759075200000     CALL  510.00      29.36  29.36  \
1    TCH.HK250929C00510000  TCH.HK  1759075200000     CALL  510.00      29.36  29.36  \
2    TCH.HK250929C00510000  TCH.HK  1759075200000     CALL  510.00      29.36  29.36  \

avg_price           time  volume
29.360000  1750901400000       0
29.360000  1750901460000       0
29.360000  1750901520000       0

Get Hong Kong Option Symbol

QuoteClient.get_option_symbols(market = Market.HK, lang = Language.en_US)

Description

Retrieves Hong Kong option symbol, for example, the code for 00700 is TCH.HK.

Request Frequency

For rate limits, see API Request Limits

Parameters

Parameter Name	Type	Required	Description
market	`tigeropen.common.consts.Market`	No	Market.HK
lang	`Language`	No	Language for returned information, optional, defaults to English

Returns

pandas.DataFrame

Structure as follows:

Parameter Name	Type	Description
symbol	str	Option code, e.g. TCH.HK
name	str	Name
underlying_symbol	str	Hong Kong stock symbol, e.g. 00700

Example

from tigeropen.common.util.contract_utils import get_option_identifier
result = quote_client.get_option_symbols()
print(result)

Example Response

     symbol name underlying_symbol
0    ALC.HK  ALC             02600
1    CRG.HK  CRG             00390
2    PAI.HK  PAI             02318
3    XCC.HK  XCC             00939
4    XTW.HK  XTW             00788
5    SHL.HK  SHL             00968
6    GHL.HK  GHL             00868
7    HEX.HK  HEX             00388
8    ACC.HK  ACC             00914
9    STC.HK  STC             02888

Get Option Analysis Indicators

QuoteClient.get_option_analysis(symbols, period=OptionAnalysisPeriod.FIFTY_TWO_WEEK, market=None, require_volatility_list=None, lang=None)

Description

Obtain option analysis indicators, including data such as implied volatility, historical volatility, IV/HV ratio, call-put ratio, IV percentile, IV ranking, etc.

Request Frequency

For rate limits, see API Request Limits

Parameters

Parameter Name	Type	Required	Description
symbols	`List[str]` or `List[dict]`	Yes	List of stock symbols, up to 10 symbols. It can be a list of strings such as `["AAPL", "TSLA"]`, a list of dictionaries such as `[{"symbol": "AAPL", "period": "26week"}]`, or a mixed format
period	`tigeropen.common.consts.OptionAnalysisPeriod`	No	Analysis period, defaults to FIFTY_TWO_WEEK. Optional values: THREE_YEAR, FIFTY_TWO_WEEK, TWENTY_SIX_WEEK, THIRTEEN_WEEK
market	`tigeropen.common.consts.Market`	No	Market, such as Market.US, Market.HK
require_volatility_list	bool	No	Whether to return volatility list data (historical volatility, implied volatility, and other time series data)
lang	`Language`	No	Language of the returned information, not required, defaults to English

Return

A list of List[OptionAnalysis] objects, where each object has the following structure:

Attribute Name	Type	Description
symbol	str	Stock symbol
implied_vol_30_days	float	Implied volatility of the underlying asset. It is obtained by comprehensively weighted calculation of the implied volatility of some options in the option chain, which is the IV of the underlying asset. It reflects the overall fluctuation of the option chain in the next 30 days, and this data also has reference value for the underlying stock.
his_volatility	float	Historical volatility of the underlying asset. It reflects the actual fluctuation of the underlying asset in the past 30 days and is used to measure the degree to which the underlying asset deviates from its average price.
iv_his_v_ratio	float	Ratio of implied volatility to historical volatility
call_put_ratio	float	Call-put ratio
iv_metric	IVMetric	Implied volatility indicator object
volatility_list	List[VolatilityListItem]	Volatility list, only returned when `require_volatility_list=True`

IVMetric Object Structure：

Attribute	Type	Description
period	str	Period, like: "52week"、"26week"
percentile	float	Implied Volatility Percentile. IV Percentile is also a relative indicator that counts, over the past year, how many days have an implied volatility lower than the current one. The calculation formula is: IV Percentile = Number of days in a year with IV lower than the current IV / Trading days The value range of IV Percentile fluctuates between 0% and 100%; when IV Percentile is 0%, it means that in the past year, 0% of the trading days have an IV lower than the current IV; when IV Percentile is 100%, it means that in the past year, 100% of the trading days have an IV lower than the current IV.
rank	float	Implied Volatility Ranking. IV Rank is a relative indicator that calculates the current relative position of IV based on the highest and lowest IV values of the underlying asset over the past year. The calculation formula is: IV Rank = (Current IV - Lowest IV in 1 year) / (Highest IV in 1 year - Lowest IV in 1 year) The value range of IV Rank fluctuates between 0 and 1; when IV Rank is 0, it indicates that the current IV is in the lower range within the past year; when IV Rank is 1, it indicates that the current IV is in the higher range within the past year

Attribute

Type

Description

period

str

Period, like: "52week"、"26week"

percentile

float

Implied Volatility Percentile. IV Percentile is also a relative indicator that counts, over the past year, how many days have an implied volatility lower than the current one. The calculation formula is:

IV Percentile = Number of days in a year with IV lower than the current IV / Trading days

The value range of IV Percentile fluctuates between 0% and 100%; when IV Percentile is 0%, it means that in the past year, 0% of the trading days have an IV lower than the current IV; when IV Percentile is 100%, it means that in the past year, 100% of the trading days have an IV lower than the current IV.

rank

float

Implied Volatility Ranking. IV Rank is a relative indicator that calculates the current relative position of IV based on the highest and lowest IV values of the underlying asset over the past year. The calculation formula is:

IV Rank = (Current IV - Lowest IV in 1 year) / (Highest IV in 1 year - Lowest IV in 1 year)

The value range of IV Rank fluctuates between 0 and 1; when IV Rank is 0, it indicates that the current IV is in the lower range within the past year; when IV Rank is 1, it indicates that the current IV is in the higher range within the past year

VolatilityListItem Object Structure (returned when require_volatility_list=True):

Attribute	Type	Description
implied_vol	float	Implied volatility
percentile	float	IV percentile
rank	float	IV rank
his_volatility	float	Historical volatility
timestamp	int	Timestamp in milliseconds

Example

from tigeropen.common.consts import Market, OptionAnalysisPeriod
# Specify the period using an enumeration
result = quote_client.get_option_analysis(
    symbols=['AAPL', 'TSLA'],
    period=OptionAnalysisPeriod.FIFTY_TWO_WEEK,
    market=Market.US
)

print(result)

# Specify different periods for different stocks
result = quote_client.get_option_analysis(
    symbols=[
        {"symbol": "AAPL", "period": "52week"},
        {"symbol": "TSLA", "period": "26week"}
    ],
    market=Market.US
)

# Return volatility list data
result = quote_client.get_option_analysis(
    symbols=['AAPL'],
    period=OptionAnalysisPeriod.FIFTY_TWO_WEEK,
    market=Market.US,
    require_volatility_list=True
)
for item in result:
    print(item.symbol, item.volatility_list)

Example Response

[OptionAnalysis({"symbol": "AAPL", "implied_vol_30_days": 0.3071, "his_volatility": 0.1967, "iv_his_v_ratio": 1.5617, "call_put_ratio": 0.0, "iv_metric": IVMetric({"period": "52week", "percentile": 0.527363184079602, "rank": 0.18213875790384876})}),
 OptionAnalysis({"symbol": "TSLA", "implied_vol_30_days": 0.5162, "his_volatility": 0.3603, "iv_his_v_ratio": 1.4328, "call_put_ratio": 0.0, "iv_metric": IVMetric({"period": "52week", "percentile": 0.08, "rank": 0.04194153521422974})})]

Example Response (with require_volatility_list=True):

[OptionAnalysis({"symbol": "AAPL", "implied_vol_30_days": 0.3071, ..., "volatility_list": [VolatilityListItem({"implied_vol": 0.3012, "percentile": 0.512, "rank": 0.175, "his_volatility": 0.1923, "timestamp": 1709856000000}), ...]})]