Options
Read this page to know everything you need to know about using the various Options HTTP endpoints.
See Async Support for REST endpoints for asynchronous use cases.
Docs below assume you have already read getting started page and know how to create the client. If you do not know how to create the client, first see General guide for clients & functions and create client as below. As always you can have all 5 different clients together.
import polygon
options_client = polygon.OptionsClient('KEY') # for usual sync client
async_options_client = polygon.OptionsClient('KEY', True) # for an async client
here is how the client initializer looks like:
- polygon.options.options.OptionsClient(api_key: str, use_async: bool = False, connect_timeout: int = 10, read_timeout: int = 10, pool_timeout: int = 10, max_connections: int | None = None, max_keepalive: int | None = None, write_timeout: int = 10)
Initiates a Client to be used to access all REST options endpoints.
- Parameters:
api_key – Your API Key. Visit your dashboard to get yours.
use_async – Set it to
True
to get async client. Defaults to usual non-async client.connect_timeout – The connection timeout in seconds. Defaults to 10. basically the number of seconds to wait for a connection to be established. Raises a
ConnectTimeout
if unable to connect within specified time limit.read_timeout – The read timeout in seconds. Defaults to 10. basically the number of seconds to wait for date to be received. Raises a
ReadTimeout
if unable to connect within the specified time limit.pool_timeout – The pool timeout in seconds. Defaults to 10. Basically the number of seconds to wait while trying to get a connection from connection pool. Do NOT change if you’re unsure of what it implies
max_connections – Max number of connections in the pool. Defaults to NO LIMITS. Do NOT change if you’re unsure of application
max_keepalive – max number of allowable keep alive connections in the pool. Defaults to no limit. Do NOT change if you’re unsure of the applications.
write_timeout – The write timeout in seconds. Defaults to 10. basically the number of seconds to wait for data to be written/posted. Raises a
WriteTimeout
if unable to connect within the specified time limit.
NOTE: if you don’t want to use the option symbol helper functions, then you can just go to the desired endpoint documentation from the list to left
Working with Option Symbols
So when you’re working with options (rest/websockets), you’ll certainly need the option symbols which contain the information about their underlying symbol, expiry, call_or_put and the strike price in a certain format. There are many formats to represent them and every data source/brokerage uses a different format to represent them.
for example Polygon.io tends to use This Format . For those who want to understand how this formatting works, Here is a guide (thanks to Ian from polygon support team).
The library is equipped with a few functions to make it easier for you to build, parse, convert, and detect format of option symbols without worrying about how the structure works.
This section has been written again following many changes in v1.0.8. If you were using option symbology in v1.0.7 or older, the documentation for that version is available [here](https://polygon.readthedocs.io/en/1.0.7/) although I’d suggest upgrading and making required (small) changes
The library supports the following symbol formats at the moment
Full Name |
Shorthand String |
---|---|
Polygon.io |
polygon |
Tradier |
tradier |
Trade Station |
trade_station |
Interactive Brokers |
ibkr |
TD Ameritrade |
tda |
Think Or Swim |
tos |
This section on option symbols is divided into these sections below.
Creating Option symbols from info as underlying, expiry, strike price, option type
Parsing Option symbols to extract info as underlying, expiry, strike price, option type
Converting an option symbol from one format to another. Works between all supported formats.
Detecting format of an option symbol. Basic detection based on some simple rules.
Creating Option Symbols
The function in this sub-section helps you to build option symbols from info as underlying symbol, expiry, strike
price & option type (call/put). The function to use is polygon.build_option_symbol
Since the default format is polygon.io you don’t need to specify a format if you’re only working with polygon option symbols.
Polygon has a rest endpoint in reference client to get all active contracts which you can filter based on many values such as underlying symbol and expiry dates.
In polygon format, If you wonder whether you need to worry about the
O:
prefix which some/all option endpoints expect, then to your ease, the library handles that for you (So you can pass a symbol without prefix to let’s say Option Snapshot function and the prefix will be added internally). If you want to be explicit, just passprefix_o=True
when building symbol.Note that both tradier and polygon happen to use the exact same symbol format and hence can be used interchangeably.
Example Code & Output for polygon/tradier format
import polygon
symbol1 = polygon.build_option_symbol('AMD', datetime.date(2022, 6, 28), 'call', 546.56)
symbol2 = polygon.build_option_symbol('TSLA', '220628', 'c', 546, _format='polygon')
symbol3 = polygon.build_option_symbol('A', '220628', 'put', 66.01, prefix_o=True)
# Outputs
# symbol1 -> AMD220628C00546560
# symbol2 -> TSLA220628C00546000
# symbol3 -> O:A220628P00066010
The same function can be used to create option symbols for any of the supported formats, just pass in the format you
need, either as a shorthand string from the table above, or use an enum from polygon.enums.OptionSymbolFormat
Using enums (like
OptionSymbolFormat.POLYGON
in example below) is a good way to ensure you only pass in correct shorthand strings. Your IDE auto completion would make your life much easier when working with enums.
Example code & outputs for multiple formats
from polygon import build_option_symbol # you can import the way you like, just showing the alternates
from polygon.enums import OptionSymbolFormat # optional, you can pass in shorthand strings too
symbol1 = polygon.build_option_symbol('AMD', datetime.date(2022, 6, 28), 'call', 546.56, _format='tda')
symbol2 = polygon.build_option_symbol('NVDA', '220628', 'c', 546, _format='tos')
symbol3 = polygon.build_option_symbol('TSLA', datetime.date(2022, 6, 28), 'put', 46.01, _format='tradier')
symbol4 = polygon.build_option_symbol('A', datetime.date(2022, 6, 28), 'p', 46.1, _format='ibkr')
symbol5 = polygon.build_option_symbol('AB', datetime.date(2022, 6, 28), 'p', 46.01, _format='trade_station')
symbol6 = polygon.build_option_symbol('PTON', '220628', 'p', 46, _format=OptionSymbolFormat.POLYGON) # using enum
# outputs
# symbol1 -> AMD_062822C546.56
# symbol2 -> .NVDA062822C546
# symbol3 -> TSLA220628P00046010
# symbol4 -> A 220628P00046100
# symbol5 -> AB 220628P46.01
# symbol5 -> PTON220628P00046000
For those who want more control, here is how the function signature and arguments look
- polygon.options.options.build_option_symbol(underlying_symbol: str, expiry, call_or_put, strike_price, _format='polygon', prefix_o: bool = False) str
Generic function to build option symbols for ALL supported formats:
polygon.enums.OptionSymbolFormat
. Default format ispolygon
.- Parameters:
underlying_symbol – The underlying stock ticker symbol.
expiry – The expiry date for the option. You can pass this argument as
datetime.datetime
ordatetime.date
object. Or a string in format:YYMMDD
. Using datetime objects is recommended.call_or_put – The option type. You can specify:
c
orcall
orp
orput
. Capital letters are also supported.strike_price – The strike price for the option. ALWAYS pass this as one number.
145
,240.5
,15.003
,56
,129.02
are all valid values. Try to keep up to 3 digits after the decimal point_format – The format to use when building symbol. Defaults to
polygon
. Supported formats arepolygon, tda, tos, ibkr, tradier, trade_station
. If you prefer to use convenient enums, seepolygon.enums.OptionSymbolFormat
prefix_o – Whether to prefix the symbol with
O:
. It is needed by polygon endpoints. However, all the library functions will automatically add this prefix if you pass in symbols without this prefix. This parameter is ignored if format is notpolygon
- Returns:
The option symbols string in the format specified
Parsing Option Symbols
The function in this sub-section helps you to extract info as underlying symbol, expiry, strike price & option type
(call/put) from an existing option symbol. Parsing is available on all supported formats. The function to use is
polygon.build_option_symbol
Since the default format is
polygon
, you don’t need to specify a format if you’re only working with polygon option symbols.Polygon symbols can be passed in with or without the prefix
O:
. Library will handle both internallyNote that both tradier and polygon happen to use the exact same symbol format and hence can be used interchangeably.
It is observed that some option symbols as returned by polygon endpoints happen to have a correction number within the symbol. The additional number is always between the underlying symbol and expiry. The lib handles that for you & parses the symbol accordingly.
An example of the corrected polygon symbol could be
XY1221015C00234000
. Notice the extra 1 afterXY
and before expiry221015
. The library would parse this symbol asXY221015C00234000
. The number could be any number according to a response from polygon support team.
NOTE: The parse function takes another optional argument, output_format
, defaulting to 'object'
.
Here is what it is for and how you can use it to your advantage.
- Output Format
The library provides 3 possible output formats when getting parsed info from an option symbol. They are
An object of class
polygon.options.options.OptionSymbol
(Default). You can access info as
obj.strike_price
obj.underlying_symbol
obj.expiry
obj.call_or_put
obj.option_symbol
As a list having elements:
[underlying_symbol, expiry, call_or_put, strike_price, option_symbol]
in this fixed orderAs a dict having the following keys:
underlying_symbol
expiry
call_or_put
strike_price
option_symbol
Example code and output for polygon/tradier formats
import polygon
parsed_details1 = polygon.parse_option_symbol('AMD211205C00156000')
parsed_details2 = polygon.parse_option_symbol('AMD211205C00156000', output_format=list)
parsed_details3 = polygon.parse_option_symbol('AMD211205C00156000', output_format=dict)
# outputs
# parsed_details1 would be an object having info as attributes as described in output format sub-section above
# parsed_details2 -> ['AMD', dt.date(2021, 12, 5), 'C', 156, 'AMD211205C00156000']
# parsed_details3 -> {'underlying_symbol': 'AMD', 'expiry': dt.date(2021, 12, 5), 'call_or_put': 'C', 'strike_price': 156, 'option_symbol': 'AMD211205C00156000'}
The same function can be used to parse option symbols in any of the supported formats, just pass in the format you
need, either as a shorthand string from the table above, or use an enum from polygon.enums.OptionSymbolFormat
Using enums (like
OptionSymbolFormat.POLYGON
in example below) is a good way to ensure you only pass in correct shorthand strings. Your IDE auto completion would make your life much easier when working with enums.
Example code & outputs for multiple formats
import polygon
parsed_details1 = polygon.parse_option_symbol('AMD211205C00156000', _format='tradier')
parsed_details2 = polygon.parse_option_symbol('AMD_062822P587.56', _format='tda', output_format=list)
parsed_details3 = polygon.parse_option_symbol('AB 220628P46.01', _format='trade_station', output_format=dict)
# outputs
# parsed_details1 would be an object having info as attributes as described in output format sub-section above
# parsed_details2 -> ['AMD', dt.date(2022, 6, 28), 'P', 587.56, 'AMD_062822P587.56']
# parsed_details3 -> {'underlying_symbol': 'AB', 'expiry': dt.date(2022, 6, 28), 'call_or_put': 'P', 'strike_price': 46.01, 'option_symbol': 'AB 220628P46.01'}
For those who want more control, here is how the function signature and arguments look
- polygon.options.options.parse_option_symbol(option_symbol: str, _format='polygon', output_format='object')
Generic function to build option symbols for ALL supported formats:
polygon.enums.OptionSymbolFormat
. Default format ispolygon
.- Parameters:
option_symbol – the option symbol you want to parse
_format – What format the symbol is in. If you don’t know the format you can use the
detect_option_symbol_format
function to detect the format (best effort detection). Supported formats arepolygon, tda, tos, ibkr, tradier, trade_station
. If you prefer to use convenient enums, seepolygon.enums.OptionSymbolFormat
. Default:polygon
output_format – Output format of the result. defaults to object. Set it to
dict
orlist
as needed.
- Returns:
The parsed info from symbol either as an object, list or a dict as indicated by
output_format
.
Converting Option Symbol Formats
The function in this sub-section helps you to convert an option symbol from one format to another. So if you want to convert a polygon option symbol to TD Ameritrade symbol (say to place an order), pass the symbol in this function, specify the formats and the library will do the conversions for you.
Example code and outputs
import polygon
symbol1 = polygon.convert_option_symbol_formats('AMD220628P00096050', from_format='polygon', to_format='tda')
symbol2 = polygon.convert_option_symbol_formats('AB 220628P46.01', from_format='trade_station', to_format='polygon')
symbol2 = polygon.convert_option_symbol_formats('NVDA220628C00546000', 'tradier', 'tos')
# outputs
# symbol1 -> AMD_062822P96.05
# symbol2 -> AB220628P00046010
# symbol3 -> .NVDA062822C546
For those who want more control, here is how the function signature and arguments look
- polygon.options.options.convert_option_symbol_formats(option_symbol: str, from_format: str, to_format: str) str
Convert an option symbol from one format to another within supported formats:
polygon.enums.OptionSymbolFormat
- Parameters:
option_symbol – The option symbol you want to convert
from_format – The format in which the option symbol is currently in. If you don’t know the format you can use the
detect_option_symbol_format
function to detect the format (best effort detection). Supported formats arepolygon, tda, tos, ibkr, tradier, trade_station
. If you prefer to use convenient enums, seepolygon.enums.OptionSymbolFormat
to_format – The format to which you want to convert the option symbol. Supported formats are
polygon, tda, tos, ibkr, tradier, trade_station
. If you prefer to use convenient enums, seepolygon.enums.OptionSymbolFormat
- Returns:
The converted option symbol as a string
Detecting Option Symbol Format
The function in this sub-section helps you to detect the symbol format of an option symbol programmatically. The function does basic detection according to some simple rules so test well before using this in production setting. It is almost always recommended to be explicit about formats.
Example code and outputs
import polygon
format1 = polygon.detect_option_symbol_format('AMD_062822P96.05')
format2 = polygon.detect_option_symbol_format('AB220628P00046010')
format3 = polygon.detect_option_symbol_format('.NVDA062822C546')
format4 = polygon.detect_option_symbol_format('AB 220628P46.01')
format5 = polygon.detect_option_symbol_format('AB 220628P00046045')
# outputs
# format1 -> 'tda'
# format2 -> 'polygon' # this also means tradier since both use exact same format
# format3 -> 'tos'
# format4 -> 'trade_station'
# format5 -> ['ibkr', 'trade_station']
For those who want more control, here is how the function signature and arguments look
- polygon.options.options.detect_option_symbol_format(option_symbol: str) str | bool | list
Detect what format a symbol is formed in. Supported formats are
polygon.enums.OptionSymbolFormat
. This function does basic detection according to some simple rules. Test well before using in production.- Parameters:
option_symbol – The option symbol to check the format of
- Returns:
Format’s shorthand string or list of strings if able to recognize the format.
False
otherwise. Possible shorthand strings arepolygon, tda, tos, ibkr, tradier, trade_station
Endpoints:
To use any of the below method, simply call it on the client you created above. so if you named your client client
,
you’d call the methods as client.get_trades
and so on. Async methods will need to be awaited, see Async Support for REST endpoints.
SMA
Simple Moving Average. This endpoint supports pagination. Passing all_pages=True
enables it. See Pagination Support for better info
- SyncOptionsClient.get_sma(symbol: str, timestamp=None, timespan='day', adjusted: bool = True, window_size: int = 50, series_type='close', include_underlying: bool = False, order='desc', limit: int = 5000, timestamp_lt=None, timestamp_lte=None, timestamp_gt=None, timestamp_gte=None, all_pages: bool = False, max_pages: int | None = None, merge_all_pages: bool = True, verbose: bool = False, raw_page_responses: bool = False, raw_response: bool = False)
Get the Simple Moving Average for an option contract
- Parameters:
symbol – The option symbol. You can pass it with or without the prefix
O:
. If you want to build option symbols from details such as expiry and strike price, use the option symbol functionstimestamp – Either a date with the format
YYYY-MM-DD
or a millisecond timestamp.timespan – Size of the aggregate time window. defaults to ‘day’. See
polygon.enums.Timespan
for choicesadjusted – Whether the aggregates used to calculate the simple moving average are adjusted for splits. By default, aggregates are adjusted. Set this to
False
to get results that are NOT adjusted for splits.window_size – The window size used to calculate the simple moving average (SMA). i.e. a window size of 10 with daily aggregates would result in a 10 day moving average.
series_type – The prices in the aggregate which will be used to calculate the SMA. The default
close
will result in using close prices to calculate the SMA. Seepolygon.enums.SeriesType
for choicesinclude_underlying – Whether to include the OCHLV aggregates used to calculate this indicator in the response. Defaults to False which only returns the SMA.
order – The order in which to return the results, ordered by timestamp. See
polygon.enums.SortOrder
for choices. Defaults to Descending (most recent first)limit – Limit the number of results returned, default is 5000 which is also the max
timestamp_lt – Only use results where timestamp is less than supplied value
timestamp_lte – Only use results where timestamp is less than or equal to supplied value
timestamp_gt – Only use results where timestamp is greater than supplied value
timestamp_gte – Only use results where timestamp is greater than or equal to supplied value
all_pages – Whether to paginate through next/previous pages internally. Defaults to False. If set to True, it will try to paginate through all pages and merge all pages internally for you.
max_pages – how many pages to fetch. Defaults to None which fetches all available pages. Change to an integer to fetch at most that many pages. This param is only considered if
all_pages
is set to Truemerge_all_pages – If this is True, returns a single merged response having all the data. If False, returns a list of all pages received. The list can be either a list of response objects or decoded data itself, controlled by parameter
raw_page_responses
. This argument is Only considered ifall_pages
is set to True. Default: Trueverbose – Set to True to print status messages during the pagination process. Defaults to False.
raw_page_responses – If this is true, the list of pages will be a list of corresponding Response objects. Else, it will be a list of actual data for pages. This parameter is only considered if
merge_all_pages
is set to False. Default: Falseraw_response – Whether to return the
Response
Object. Useful for when you need to say check the status code or inspect the headers. Defaults to False which returns the json decoded dictionary.
- Returns:
The response object
EMA
Exponential Moving Average. This endpoint supports pagination. Passing all_pages=True
enables it. See Pagination Support for better info
- SyncOptionsClient.get_ema(symbol: str, timestamp=None, timespan='day', adjusted: bool = True, window_size: int = 50, series_type='close', include_underlying: bool = False, order='desc', limit: int = 5000, timestamp_lt=None, timestamp_lte=None, timestamp_gt=None, timestamp_gte=None, all_pages: bool = False, max_pages: int | None = None, merge_all_pages: bool = True, verbose: bool = False, raw_page_responses: bool = False, raw_response: bool = False)
Get the Exponential Moving Average for an option contract
- Parameters:
symbol – The option symbol. You can pass it with or without the prefix
O:
. If you want to build option symbols from details such as expiry and strike price, use the option symbol functionstimestamp – Either a date with the format
YYYY-MM-DD
or a millisecond timestamp.timespan – Size of the aggregate time window. defaults to ‘day’. See
polygon.enums.Timespan
for choicesadjusted – Whether the aggregates used to calculate the EMA are adjusted for splits. By default, aggregates are adjusted. Set this to
False
to get results that are NOT adjusted for splits.window_size – The window size used to calculate the EMA. i.e. a window size of 10 with daily aggregates would result in a 10 day moving average.
series_type – The prices in the aggregate which will be used to calculate the EMA. The default
close
will result in using close prices to calculate the EMA. Seepolygon.enums.SeriesType
for choicesinclude_underlying – Whether to include the OCHLV aggregates used to calculate this indicator in the response. Defaults to False which only returns the EMA.
order – The order in which to return the results, ordered by timestamp. See
polygon.enums.SortOrder
for choices. Defaults to Descending (most recent first)limit – Limit the number of results returned, default is 5000 which is also the max
timestamp_lt – Only use results where timestamp is less than supplied value
timestamp_lte – Only use results where timestamp is less than or equal to supplied value
timestamp_gt – Only use results where timestamp is greater than supplied value
timestamp_gte – Only use results where timestamp is greater than or equal to supplied value
all_pages – Whether to paginate through next/previous pages internally. Defaults to False. If set to True, it will try to paginate through all pages and merge all pages internally for you.
max_pages – how many pages to fetch. Defaults to None which fetches all available pages. Change to an integer to fetch at most that many pages. This param is only considered if
all_pages
is set to Truemerge_all_pages – If this is True, returns a single merged response having all the data. If False, returns a list of all pages received. The list can be either a list of response objects or decoded data itself, controlled by parameter
raw_page_responses
. This argument is Only considered ifall_pages
is set to True. Default: Trueverbose – Set to True to print status messages during the pagination process. Defaults to False.
raw_page_responses – If this is true, the list of pages will be a list of corresponding Response objects. Else, it will be a list of actual data for pages. This parameter is only considered if
merge_all_pages
is set to False. Default: Falseraw_response – Whether to return the
Response
Object. Useful for when you need to say check the status code or inspect the headers. Defaults to False which returns the json decoded dictionary.
- Returns:
The response object
RSI
Relative Strength Index. This endpoint supports pagination. Passing all_pages=True
enables it. See Pagination Support for better info
- SyncOptionsClient.get_rsi(symbol: str, timestamp=None, timespan='day', adjusted: bool = True, window_size: int = 14, series_type='close', include_underlying: bool = False, order='desc', limit: int = 5000, timestamp_lt=None, timestamp_lte=None, timestamp_gt=None, timestamp_gte=None, all_pages: bool = False, max_pages: int | None = None, merge_all_pages: bool = True, verbose: bool = False, raw_page_responses: bool = False, raw_response: bool = False)
Get the Relative Strength Index for an option contract
- Parameters:
symbol – The option symbol. You can pass it with or without the prefix
O:
. If you want to build option symbols from details such as expiry and strike price, use the option symbol functionstimestamp – Either a date with the format
YYYY-MM-DD
or a millisecond timestamp.timespan – Size of the aggregate time window. defaults to ‘day’. See
polygon.enums.Timespan
for choicesadjusted – Whether the aggregates used to calculate the RSI are adjusted for splits. By default, aggregates are adjusted. Set this to
False
to get results that are NOT adjusted for splits.window_size – The window size used to calculate the RSI. i.e. a window size of 14 with daily aggregates would result in a 14 day RSI.
series_type – The prices in the aggregate which will be used to calculate the RSI. The default
close
will result in using close prices to calculate the RSI. Seepolygon.enums.SeriesType
for choicesinclude_underlying – Whether to include the OCHLV aggregates used to calculate this indicator in the response. Defaults to False which only returns the RSI.
order – The order in which to return the results, ordered by timestamp. See
polygon.enums.SortOrder
for choices. Defaults to Descending (most recent first)limit – Limit the number of results returned, default is 5000 which is also the max
timestamp_lt – Only use results where timestamp is less than supplied value
timestamp_lte – Only use results where timestamp is less than or equal to supplied value
timestamp_gt – Only use results where timestamp is greater than supplied value
timestamp_gte – Only use results where timestamp is greater than or equal to supplied value
all_pages – Whether to paginate through next/previous pages internally. Defaults to False. If set to True, it will try to paginate through all pages and merge all pages internally for you.
max_pages – how many pages to fetch. Defaults to None which fetches all available pages. Change to an integer to fetch at most that many pages. This param is only considered if
all_pages
is set to Truemerge_all_pages – If this is True, returns a single merged response having all the data. If False, returns a list of all pages received. The list can be either a list of response objects or decoded data itself, controlled by parameter
raw_page_responses
. This argument is Only considered ifall_pages
is set to True. Default: Trueverbose – Set to True to print status messages during the pagination process. Defaults to False.
raw_page_responses – If this is true, the list of pages will be a list of corresponding Response objects. Else, it will be a list of actual data for pages. This parameter is only considered if
merge_all_pages
is set to False. Default: Falseraw_response – Whether to return the
Response
Object. Useful for when you need to say check the status code or inspect the headers. Defaults to False which returns the json decoded dictionary.
- Returns:
The response object
MACD
Moving Average Convergence/Divergence. This endpoint supports pagination. Passing all_pages=True
enables it. See Pagination Support for better info
- SyncOptionsClient.get_macd(symbol: str, timestamp=None, timespan='day', adjusted: bool = True, long_window_size: int = 50, series_type='close', include_underlying: bool = False, order='desc', limit: int = 5000, timestamp_lt=None, timestamp_lte=None, timestamp_gt=None, timestamp_gte=None, short_window_size: int = 50, signal_window_size: int = 50, all_pages: bool = False, max_pages: int | None = None, merge_all_pages: bool = True, verbose: bool = False, raw_page_responses: bool = False, raw_response: bool = False)
Get the Moving Average Convergence/Divergence for an option contract
- Parameters:
symbol – The option symbol. You can pass it with or without the prefix
O:
. If you want to build option symbols from details such as expiry and strike price, use the option symbol functionstimestamp – Either a date with the format
YYYY-MM-DD
or a millisecond timestamp.timespan – Size of the aggregate time window. defaults to ‘day’. See
polygon.enums.Timespan
for choicesadjusted – Whether the aggregates used to calculate the MACD are adjusted for splits. By default, aggregates are adjusted. Set this to
False
to get results that are NOT adjusted for splits.long_window_size – The long window size used to calculate the MACD data
series_type – The prices in the aggregate which will be used to calculate the MACD. The default
close
will result in using close prices to calculate the MACD. Seepolygon.enums.SeriesType
for choicesinclude_underlying – Whether to include the OCHLV aggregates used to calculate this indicator in the response. Defaults to False which only returns the MACD.
order – The order in which to return the results, ordered by timestamp. See
polygon.enums.SortOrder
for choices. Defaults to Descending (most recent first)limit – Limit the number of results returned, default is 5000 which is also the max
timestamp_lt – Only use results where timestamp is less than supplied value
timestamp_lte – Only use results where timestamp is less than or equal to supplied value
timestamp_gt – Only use results where timestamp is greater than supplied value
timestamp_gte – Only use results where timestamp is greater than or equal to supplied value
short_window_size – The short window size used to calculate the MACD data
signal_window_size – The window size used to calculate the MACD signal line.
all_pages – Whether to paginate through next/previous pages internally. Defaults to False. If set to True, it will try to paginate through all pages and merge all pages internally for you.
max_pages – how many pages to fetch. Defaults to None which fetches all available pages. Change to an integer to fetch at most that many pages. This param is only considered if
all_pages
is set to Truemerge_all_pages – If this is True, returns a single merged response having all the data. If False, returns a list of all pages received. The list can be either a list of response objects or decoded data itself, controlled by parameter
raw_page_responses
. This argument is Only considered ifall_pages
is set to True. Default: Trueverbose – Set to True to print status messages during the pagination process. Defaults to False.
raw_page_responses – If this is true, the list of pages will be a list of corresponding Response objects. Else, it will be a list of actual data for pages. This parameter is only considered if
merge_all_pages
is set to False. Default: Falseraw_response – Whether to return the
Response
Object. Useful for when you need to say check the status code or inspect the headers. Defaults to False which returns the json decoded dictionary.
- Returns:
The response object
Get Trades
This endpoint supports pagination. Passing all_pages=True
enables it. See Pagination Support for better info
- SyncOptionsClient.get_trades(option_symbol: str, timestamp=None, timestamp_lt=None, timestamp_lte=None, timestamp_gt=None, timestamp_gte=None, sort='timestamp', limit: int = 5000, order='asc', all_pages: bool = False, max_pages: int | None = None, merge_all_pages: bool = True, verbose: bool = False, raw_page_responses: bool = False, raw_response: bool = False)
Get trades for an options ticker symbol in a given time range. Note that you need to have an option symbol in correct format for this endpoint. You can use
ReferenceClient.get_option_contracts
to query option contracts using many filter parameters such as underlying symbol etc. Official Docs- Parameters:
option_symbol – The options ticker symbol to get trades for. for e.g.
O:TSLA210903C00700000
. you can pass the symbol with or without the prefixO:
timestamp – Query by trade timestamp. You can supply a
date
,datetime
object or ananosecond UNIX timestamp
or a string in format:YYYY-MM-DD
.timestamp_lt – return results where timestamp is less than the given value. Can be date or date string or nanosecond timestamp
timestamp_lte – return results where timestamp is less than/equal to the given value. Can be date or date string or nanosecond timestamp
timestamp_gt – return results where timestamp is greater than the given value. Can be date or date string or nanosecond timestamp
timestamp_gte – return results where timestamp is greater than/equal to the given value. Can be date or date string or nanosecond timestamp
sort – Sort field used for ordering. Defaults to timestamp. See
polygon.enums.OptionTradesSort
for available choices.limit – Limit the number of results returned. Defaults to 5000. max is 50000.
order – order of the results. Defaults to
asc
. Seepolygon.enums.SortOrder
for info and available choices.all_pages – Whether to paginate through next/previous pages internally. Defaults to False. If set to True, it will try to paginate through all pages and merge all pages internally for you.
max_pages – how many pages to fetch. Defaults to None which fetches all available pages. Change to an integer to fetch at most that many pages. This param is only considered if
all_pages
is set to Truemerge_all_pages – If this is True, returns a single merged response having all the data. If False, returns a list of all pages received. The list can be either a list of response objects or decoded data itself, controlled by parameter
raw_page_responses
. This argument is Only considered ifall_pages
is set to True. Default: Trueverbose – Set to True to print status messages during the pagination process. Defaults to False.
raw_page_responses – If this is true, the list of pages will be a list of corresponding Response objects. Else, it will be a list of actual data for pages. This parameter is only considered if
merge_all_pages
is set to False. Default: Falseraw_response – whether to return the
Response
Object. Useful for when you need to say check the status code or inspect the headers. Defaults to False which returns the json decoded dictionary. This is ignored if pagination is set to True.
- Returns:
A JSON decoded Dictionary by default. Make
raw_response=True
to get underlying response object. If pagination is set to True, will return a merged response of all pages for convenience.
Get Quotes
This endpoint supports pagination. Passing all_pages=True
enables it. See Pagination Support for better info
- SyncOptionsClient.get_quotes(option_symbol: str, timestamp=None, timestamp_lt=None, timestamp_lte=None, timestamp_gt=None, timestamp_gte=None, sort='timestamp', limit: int = 5000, order='asc', all_pages: bool = False, max_pages: int | None = None, merge_all_pages: bool = True, verbose: bool = False, raw_page_responses: bool = False, raw_response: bool = False)
Get quotes for an options ticker symbol in a given time range. Note that you need to have an option symbol in correct format for this endpoint. You can use
ReferenceClient.get_option_contracts
to query option contracts using many filter parameters such as underlying symbol etc. Official Docs- Parameters:
option_symbol – The options ticker symbol to get quotes for. for e.g.
O:TSLA210903C00700000
. you can pass the symbol with or without the prefixO:
timestamp – Query by quote timestamp. You can supply a
date
,datetime
object or ananosecond UNIX timestamp
or a string in format:YYYY-MM-DD
.timestamp_lt – return results where timestamp is less than the given value. Can be date or date string or nanosecond timestamp
timestamp_lte – return results where timestamp is less than/equal to the given value. Can be date or date string or nanosecond timestamp
timestamp_gt – return results where timestamp is greater than the given value. Can be date or date string or nanosecond timestamp
timestamp_gte – return results where timestamp is greater than/equal to the given value. Can be date or date string or nanosecond timestamp
sort – Sort field used for ordering. Defaults to timestamp. See
polygon.enums.OptionQuotesSort
for available choices.limit – Limit the number of results returned. Defaults to 5000. max is 50000.
order – order of the results. Defaults to
asc
. Seepolygon.enums.SortOrder
for info and available choices.all_pages – Whether to paginate through next/previous pages internally. Defaults to False. If set to True, it will try to paginate through all pages and merge all pages internally for you.
max_pages – how many pages to fetch. Defaults to None which fetches all available pages. Change to an integer to fetch at most that many pages. This param is only considered if
all_pages
is set to Truemerge_all_pages – If this is True, returns a single merged response having all the data. If False, returns a list of all pages received. The list can be either a list of response objects or decoded data itself, controlled by parameter
raw_page_responses
. This argument is Only considered ifall_pages
is set to True. Default: Trueverbose – Set to True to print status messages during the pagination process. Defaults to False.
raw_page_responses – If this is true, the list of pages will be a list of corresponding Response objects. Else, it will be a list of actual data for pages. This parameter is only considered if
merge_all_pages
is set to False. Default: Falseraw_response – whether to return the
Response
Object. Useful for when you need to say check the status code or inspect the headers. Defaults to False which returns the json decoded dictionary. This is ignored if pagination is set to True.
- Returns:
A JSON decoded Dictionary by default. Make
raw_response=True
to get underlying response object. If pagination is set to True, will return a merged response of all pages for convenience.
Get Last Trade
- SyncOptionsClient.get_last_trade(ticker: str, raw_response: bool = False)
Get the most recent trade for a given options contract. Official Docs
- Parameters:
ticker – The ticker symbol of the options contract. Eg:
O:TSLA210903C00700000
raw_response – whether to return the
Response
Object. Useful for when you need to say check the status code or inspect the headers. Defaults to False which returns the json decoded dictionary.
- Returns:
Either a Dictionary or a Response object depending on value of
raw_response
. Defaults to Dict.
Get Daily Open Close
- SyncOptionsClient.get_daily_open_close(symbol: str, date, adjusted: bool = True, raw_response: bool = False)
Get the OCHLV and after-hours prices of a contract on a certain date. Official Docs
- Parameters:
symbol – The option symbol we want daily-OCHLV for. e.g.
O:FB210903C00700000
. You can pass it with or without the prefixO:
date – The date/day of the daily-OCHLV to retrieve. Could be
datetime
ordate
or stringYYYY-MM-DD
adjusted – whether the results are adjusted for splits. By default, results are adjusted. Set this to false to get results that are NOT adjusted for splits.
raw_response – whether to return the
Response
Object. Useful for when you need to say check the status code or inspect the headers. Defaults to False which returns the json decoded dictionary.
- Returns:
A JSON decoded Dictionary by default. Make
raw_response=True
to get underlying response object
Get Aggregate Bars
The library added a better aggregate function if you’re looking to get data for large time frames at minute/hour granularity.
(for example 15 years historical data , 1 minute candles)
See Bulk Aggregate Bars (Full Range) for complete details on how to use it well and control how it behaves.
- SyncOptionsClient.get_aggregate_bars(symbol: str, from_date, to_date, adjusted: bool = True, sort='asc', limit: int = 5000, multiplier: int = 1, timespan='day', full_range: bool = False, run_parallel: bool = True, max_concurrent_workers: int = 10, info: bool = True, warnings: bool = True, high_volatility: bool = False, raw_response: bool = False)
Get aggregate bars for an option contract over a given date range in custom time window sizes. For example, if
timespan = ‘minute’
andmultiplier = ‘5’
then 5-minute bars will be returned. Official Docs- Parameters:
symbol – The ticker symbol of the contract. e.g.
O:FB210903C00700000
. You can pass in with or without the prefixO:
from_date – The start of the aggregate time window. Could be
datetime
ordate
or stringYYYY-MM-DD
to_date – The end of the aggregate time window. Could be
datetime
ordate
or stringYYYY-MM-DD
adjusted – whether the results are adjusted for splits. By default, results are adjusted. Set this to false to get results that are NOT adjusted for splits.
sort – Sort the results by timestamp. See
polygon.enums.SortOrder
for choices.asc
default.limit – Limits the number of base aggregates queried to create the aggregate results. Max 50000 and Default 5000. see this article for more info.
multiplier – The size of the timespan multiplier. Must be a positive whole number. defaults to 1.
timespan – The size of the time window. See
polygon.enums.Timespan
for choices. defaults today
full_range – Default False. If set to True, it will get the ENTIRE range you specify and merge all the responses and return ONE single list with all data in it. You can control its behavior with the next few arguments.
run_parallel – Only considered if
full_range=True
. If set to true (default True), it will run an internal ThreadPool to get the responses. This is fine to do if you are not running your own ThreadPool. If you have many tickers to get aggs for, it’s better to either use the async version of it OR set this to False and spawn threads for each ticker yourself.max_concurrent_workers – Only considered if
run_parallel=True
. Defaults toyour cpu cores * 5
. controls how many worker threads to use in internal ThreadPoolinfo – Set to False to disable printing mild warnings / informational messages if any when fetching the aggs. E.g. if there was no data in a response but the response had an OK status
warnings – Set to False to disable printing warnings if any when fetching the aggs. Defaults to True.
high_volatility – Specifies whether the symbol/security in question is highly volatile which just means having a very high number of trades or being traded for a high duration (e.g. SPY, Bitcoin) If set to True, the lib will use a smaller chunk of time to ensure we don’t miss any data due to 50k candle limit. Defaults to False.
raw_response – whether to return the
Response
Object. Useful for when you need to say check the status code or inspect the headers. Defaults to False which returns the json decoded dictionary. Will be ignored iffull_range=True
- Returns:
A JSON decoded Dictionary by default. Make
raw_response=True
to get underlying response object. Iffull_range=True
, will return a single list with all the candles in it.
Get Previous Close
- SyncOptionsClient.get_previous_close(ticker: str, adjusted: bool = True, raw_response: bool = False)
Get the previous day’s open, high, low, and close (OHLC) for the specified option contract. Official Docs
- Parameters:
ticker – The ticker symbol of the options contract. Eg:
O:TSLA210903C00700000
adjusted – whether the results are adjusted for splits. By default, results are adjusted. Set this to false to get results that are NOT adjusted for splits.
raw_response – whether to return the
Response
Object. Useful for when you need to say check the status code or inspect the headers. Defaults to False which returns the json decoded dictionary.
- Returns:
Either a Dictionary or a Response object depending on value of
raw_response
. Defaults to Dict.
Get Snapshot
This endpoint supports pagination. Passing all_pages=True
enables it. See Pagination Support for better info
- SyncOptionsClient.get_snapshot(underlying_symbol: str, option_symbol: str, all_pages: bool = False, max_pages: int | None = None, merge_all_pages: bool = True, verbose: bool = False, raw_page_responses: bool = False, raw_response: bool = False)
Get the snapshot of an option contract for a stock equity. Official Docs
- Parameters:
underlying_symbol – The underlying ticker symbol of the option contract. e.g.
AMD
option_symbol – the option symbol. You can use use the Working with Option Symbols section to make it easy to work with option symbols in polygon or tda formats.
all_pages – Whether to paginate through next/previous pages internally. Defaults to False. If set to True, it will try to paginate through all pages and merge all pages internally for you.
max_pages – how many pages to fetch. Defaults to None which fetches all available pages. Change to an integer to fetch at most that many pages. This param is only considered if
all_pages
is set to Truemerge_all_pages – If this is True, returns a single merged response having all the data. If False, returns a list of all pages received. The list can be either a list of response objects or decoded data itself, controlled by parameter
raw_page_responses
. This argument is Only considered ifall_pages
is set to True. Default: Trueverbose – Set to True to print status messages during the pagination process. Defaults to False.
raw_page_responses – If this is true, the list of pages will be a list of corresponding Response objects. Else, it will be a list of actual data for pages. This parameter is only considered if
merge_all_pages
is set to False. Default: Falseraw_response – whether to return the
Response
Object. Useful for when you need to say check the status code or inspect the headers. Defaults to False which returns the json decoded dictionary. This is ignored if pagination is set to True.
- Returns:
A JSON decoded Dictionary by default. Make
raw_response=True
to get underlying response object. If pagination is set to True, will return a merged response of all pages for convenience.