Polygon.io Modules

Stocks Endpoint

polygon.stocks.aggregates(stock_ticker, multiplier, timespan, from_date, to_date, external=False, **query_params)

Returns

Get aggregate bars for a stock over a given date range in custom time window sizes.

Parameters

stock_ticker (required, string) – The ticker symbol of the stock.
multiplier (required, integer) – The size of the timespan multiplier.
timespan (required, string, [minute, hour, day, week, month, quarter, year]) – The size of the time window.
from (required, string, date ex. '2021-07-22') – The start of the aggregate time window.
to (required, string, date ex. '2021-07-22') – The end of the aggregate time window.
external (optional, string) – Your Polygon API key if you are not using environment variables.
adjusted (optional, boolean, default True) – Whether or not the results are adjusted for splits. Set this to false to get results that are NOT adjusted for splits.
sort (optional, string, [desc, asc]) – Sort the results by timestamp.
limit (optional, integer, default 5000, max 50000) – Limits the number of base aggregates queried to create the aggregate results.

polygon.stocks.daily_open_close(stock_ticker, date, external=False, **query_params)

Returns

Get the open, close and afterhours prices of a stock symbol on a certain date.

Parameters

stock_ticker (required, string) – The ticker symbol of the stock.
date (required, string, date ex. '2021-07-22') – The beginning date for the aggregate window.
external (optional, string) – Your Polygon API key if you are not using environment variables.
adjusted (optional, boolean, default True) – Whether or not the results are adjusted for splits. Set this to false to get results that are NOT adjusted for splits.

polygon.stocks.dividends_v3(external=False, **query_params)

Returns

Get a list of historical cash dividends, including the ticker symbol, declaration date, ex-dividend date, record date, pay date, frequency, and amount.

Parameters

external (optional, string) – Your Polygon API key if you are not using environment variables.
stock_ticker (required, string) – The ticker symbol of the stock.
ex_dividend_date (optional, string, date ex. '2021-07-22') – Query by ex-dividend date with the format YYYY-MM-DD.
record_date (optional, string, date ex. '2021-07-22') – Query by record date with the format YYYY-MM-DD.
declaration_date (optional, string, date ex. '2021-07-22') – Query by declaration date with the format YYYY-MM-DD.
pay_date (optional, string, date ex. '2021-07-22') – Query by pay date with the format YYYY-MM-DD.
frequency (optional, integer, eg. [0,1,2,4,12]) – Query by the number of times per year the dividend is paid out.
cash_amount (optional, float) – Query by the cash amount of the dividend.
dividend_type (optional, string, Consistent Dividends = CD, Special Cash Dividends = [SC]) – Query by the type of dividend.
order (optional, string, [desc, asc]) – Order results based on the sort field.
limit (optional, integer, default 5000, max 50000) – Limits the number of base aggregates queried to create the aggregate results.
sort (optional, string) – Sort field used for ordering.

polygon.stocks.financials(external=False, **query_params)

This API is experimental. :return: Get historical financial data for a stock ticker.

Parameters

external (optional, string) – Your Polygon API key if you are not using environment variables.
stock_ticker (required, string) – The ticker symbol of the stock.
cik –
company_name –
sic –

:param : :type : :param : :type : :param : :type : :param : :type : :param order: Order results based on the sort field. :type order: optional, string, [desc, asc] :param limit: Limits the number of base aggregates queried to create the aggregate results. :type limit: optional, integer, default 5000, max 50000 :param sort: Sort field used for ordering. :type sort: optional, string

polygon.stocks.grouped_daily(date, external=False, **query_params)

Returns

Get the daily open, high, low, and close (OHLC) for the entire stocks/equities markets.

Parameters

date (required, string, date ex. '2021-07-22') – The beginning date for the aggregate window.
external (optional, string) – Your Polygon API key if you are not using environment variables.
adjusted (optional, boolean, default True) – Whether or not the results are adjusted for splits. Set this to false to get results that are NOT adjusted for splits.

polygon.stocks.last_quote(stock_ticker, external=False, **query_params)

Returns

Get the most recent NBBO (Quote) tick for a given stock.

Parameters

stock_ticker (required, string) – The ticker symbol of the stock.
external (optional, string) – Your Polygon API key if you are not using environment variables.

polygon.stocks.last_trade(stock_ticker, external=False, **query_params)

Returns: Get the most recent trade for a given stock.
Parameters: stock_ticker (required, string) – The ticker symbol of the stock.

polygon.stocks.previous_close(stock_ticker, external=False, **query_params)

Returns

Get the previous day’s open, high, low, and close (OHLC) for the specified stock ticker.

Parameters

stock_ticker (required, string) – The ticker symbol of the stock.
external (optional, string) – Your Polygon API key if you are not using environment variables.
adjusted (optional, boolean, default True) – Whether or not the results are adjusted for splits. Set this to false to get results that are NOT adjusted for splits.

polygon.stocks.quotes_v2(stock_ticker, external=False, **query_params)

Returns

Get NBBO quotes for a given ticker symbol on a specified date.

Parameters

stock_ticker (required, string) – The ticker symbol of the stock.
date (required, string, date ex. '2021-07-22') – The beginning date for the aggregate window.
external (optional, string) – Your Polygon API key if you are not using environment variables.
timestamp (optional, string, date or nanosecond timestamp) – Query by timestamp. Either a date with the format YYYY-MM-DD or a nanosecond timestamp.
timestamp_limit (optional, integer) – The maximum timestamps allowed in the results.
reverse (optional, boolean) – Reverse the order of the results.
limit (optional, integer, default 5000, max 50000) – Limits the number of base aggregates queried to create the aggregate results.

polygon.stocks.quotes_v3(stock_ticker, external=False, **query_params)

Returns

Get NBBO quotes for a ticker symbol in a given time range.

Parameters

stock_ticker (required, string) – The ticker symbol of the stock.
external (optional, string) – Your Polygon API key if you are not using environment variables.
timestamp (optional, string, date or nanosecond timestamp) – Query by timestamp. Either a date with the format YYYY-MM-DD or a nanosecond timestamp.
order (optional, string, [desc, asc]) – Order results based on the sort field.
limit (optional, integer, default 5000, max 50000) – Limits the number of base aggregates queried to create the aggregate results.
sort (optional, string) – Sort field used for ordering.

polygon.stocks.snapshot_all(external=False, **query_params)

Returns

Get the most up-to-date market data for all traded stock symbols.

Parameters

external (optional, string) – Your Polygon API key if you are not using environment variables.
tickers (optional, string, list of tickers) – A comma separated list of tickers to get snapshots for.

polygon.stocks.snapshot_gain_lose(direction, external=False, **query_params)

Returns

Get the most up-to-date market data for the current top 20 gainers or losers of the day in the stocks/equities markets.

Parameters

direction (required, string, [gainers, losers]) – The direction of the snapshot results to return.
external (optional, string) – Your Polygon API key if you are not using environment variables.

polygon.stocks.snapshot_ticker(stock_ticker, external=False, **query_params)

Returns

Get the most up-to-date market data for a single traded stock ticker.

Parameters

stock_ticker (required, string) – The ticker symbol of the stock.
external (optional, string) – Your Polygon API key if you are not using environment variables.

polygon.stocks.stock_splits_v3(external=False, **query_params)

Returns

Get a list of historical stock splits, including the ticker symbol, the execution date, and the factors of the split ratio.

Parameters

external (optional, string) – Your Polygon API key if you are not using environment variables.
stock_ticker (required, string) – The ticker symbol of the stock.
execution_date (optional, string, date ex. '2021-07-22') – Query by execution date.

:param reverse_split:Query for reverse splits only. :type reverse_split: optional, boolean :param order: Order results based on the sort field. :type order: optional, string, [desc, asc] :param limit: Limits the number of base aggregates queried to create the aggregate results. :type limit: optional, integer, default 5000, max 50000 :param sort: Sort field used for ordering. :type sort: optional, string

polygon.stocks.ticker_details(stock_ticker, external=False, **query_params)

Returns

Get a single ticker supported by Polygon.io. This response will have detailed information about the ticker and the company behind it.

Parameters

stock_ticker (required, string) – The ticker symbol of the stock.
external (optional, string) – Your Polygon API key if you are not using environment variables.
date (optional, string, date ex. '2021-07-22') – The beginning date for the aggregate window.

polygon.stocks.trades(stock_ticker, date, external=False, **query_params)

Returns

Get trades for a given ticker symbol on a specified date.

Parameters

stock_ticker (required, string) – The ticker symbol of the stock.
date (required, string, date ex. '2021-07-22') – The beginning date for the aggregate window.
external (optional, string) – Your Polygon API key if you are not using environment variables.
timestamp (optional, string, date or nanosecond timestamp) – Query by timestamp. Either a date with the format YYYY-MM-DD or a nanosecond timestamp.
timestamp_limit (optional, integer) – The maximum timestamps allowed in the results.
reverse (optional, boolean) – Reverse the order of the results.
limit (optional, integer, default 5000, max 50000) – Limits the number of base aggregates queried to create the aggregate results.

polygon.stocks.trades_v3(stock_ticker, external=False, **query_params)

Returns

Get trades for a ticker symbol in a given time range.

Parameters

stock_ticker (required, string) – The ticker symbol of the stock.
external (optional, string) – Your Polygon API key if you are not using environment variables.
timestamp (optional, string, date or nanosecond timestamp) – Query by timestamp. Either a date with the format YYYY-MM-DD or a nanosecond timestamp.
order (optional, string, [desc, asc]) – Order results based on the sort field.
limit (optional, integer, default 5000, max 50000) – Limits the number of base aggregates queried to create the aggregate results.
sort (optional, string) – Sort field used for ordering.

Options Endpoint

polygon.options.aggregates(options_ticker, multiplier, timespan, from_date, to_date, external=False, **query_params)

Returns

Get aggregate bars for an option contract over a given date range in custom time window sizes.

Parameters

options_ticker (required, string) – The ticker symbol of the options contract.
multiplier (required, integer) – The size of the timespan multiplier.
timespan (required, string, [minute, hour, day, week, month, quarter, year]) – The size of the time window.
from (required, string, date ex. '2021-07-22') – The start of the aggregate time window.
to (required, string, date ex. '2021-07-22') – The end of the aggregate time window.
external (optional, string) – Your Polygon API key if you are not using environment variables.
adjusted (optional, boolean, default True) – Whether or not the results are adjusted for splits. Set this to false to get results that are NOT adjusted for splits.
sort (optional, string, [desc, asc]) – Sort the results by timestamp.
limit (optional, integer, default 5000, max 50000) – Limits the number of base aggregates queried to create the aggregate results.

polygon.options.daily_open_close(options_ticker, date, external=False, **query_params)

Returns

Get the open, close and afterhours prices of an options contract on a certain date.

Parameters

options_ticker (required, string) – The ticker symbol of the options contract.
date (required, string, date ex. '2021-07-22') – The beginning date for the aggregate window.
external (optional, string) – Your Polygon API key if you are not using environment variables.
adjusted (optional, boolean, default True) – Whether or not the results are adjusted for splits. Set this to false to get results that are NOT adjusted for splits.

polygon.options.last_trade(options_ticker, external=False, **query_params)

Returns

Get the most recent trade for a given options contract.

Parameters

options_ticker (required, string) – The ticker symbol of the options contract.
external (optional, string) – Your Polygon API key if you are not using environment variables.

polygon.options.options_contract(options_ticker, external=False, **query_params)

Returns

Get an options contract.

Parameters

options_ticker (required, string) – The ticker symbol of the options contract.
external (optional, string) – Your Polygon API key if you are not using environment variables.
as_of (optional, string, date ex. '2021-07-22', default is today) – Specify a point in time for the contract as of this date with format YYYY-MM-DD

polygon.options.options_contracts(external=False, **query_params)

Returns

Query for historical options contracts. This provides both active and expired options contracts.

Parameters

underlying_asset (required, string) – The underlying ticker symbol of the option contract.
external (optional, string) – Your Polygon API key if you are not using environment variables.
contract_type (optional, string) – Query by the type of contract.
expiration_date (optional, string, date ex. '2021-07-22') – Query by contract expiration with date format YYYY-MM-DD.
as_of (optional, string, date ex. '2021-07-22', default is today) – Specify a point in time for the contract as of this date with format YYYY-MM-DD
strike_price (optional, float) – Query by strike price of a contract.
expired (optional, boolean, default false) – Query for expired contracts
order (optional, string, [desc, asc]) – Order results based on the sort field.
limit (optional, integer, default 5000, max 50000) – Limits the number of base aggregates queried to create the aggregate results.
sort (optional, string) – Sort field used for ordering.

polygon.options.previous_close(options_ticker, external=False, **query_params)

Returns

Get the previous day’s open, high, low, and close (OHLC) for the specified option contract.

Parameters

options_ticker (required, string) – The ticker symbol of the options contract.
external (optional, string) – Your Polygon API key if you are not using environment variables.
adjusted (optional, boolean, default True) – Whether or not the results are adjusted for splits. Set this to false to get results that are NOT adjusted for splits.

polygon.options.quotes(options_ticker, external=False, **query_params)

Returns

Get quotes for an options ticker symbol in a given time range.

Parameters

options_ticker (required, string) – The ticker symbol of the options contract.
external (optional, string) – Your Polygon API key if you are not using environment variables.
timestamp (optional, string, date or nanosecond timestamp) – Query by timestamp. Either a date with the format YYYY-MM-DD or a nanosecond timestamp.
order (optional, string, [desc, asc]) – Order results based on the sort field.
limit (optional, integer, default 5000, max 50000) – Limits the number of base aggregates queried to create the aggregate results.
sort (optional, string) – Sort field used for ordering.

polygon.options.snapshot_options(underlying_asset, option_contract, external=False, **query_params)

Returns

Get the snapshot of an option contract for a stock equity.

Parameters

underlying_asset (required, string) – The underlying ticker symbol of the option contract.
option_contract (required, string) – The option contract identifier.
external (optional, string) – Your Polygon API key if you are not using environment variables.

polygon.options.trades(options_ticker, external=False, **query_params)

Returns

Get trades for an options ticker symbol in a given time range.

Parameters

options_ticker (required, string) – The ticker symbol of the options contract.
external (optional, string) – Your Polygon API key if you are not using environment variables.
timestamp (optional, string, date or nanosecond timestamp) – Query by timestamp. Either a date with the format YYYY-MM-DD or a nanosecond timestamp.
order (optional, string, [desc, asc]) – Order results based on the sort field.
limit (optional, integer, default 5000, max 50000) – Limits the number of base aggregates queried to create the aggregate results.
sort (optional, string) – Sort field used for ordering.

Forex Endpoint

polygon.forex.aggregates(forex_ticker, multiplier, timespan, from_date, to_date, external=False, **query_params)

Returns

Get aggregate bars for a forex pair over a given date range in custom time window sizes.

Parameters

forex_ticker (required, string) – The ticker symbol of the currency pair.
multiplier (required, integer) – The size of the timespan multiplier.
timespan (required, string, [minute, hour, day, week, month, quarter, year]) – The size of the time window.
from_date (required, string, date ex. '2021-07-22') – The start of the aggregate time window.
to (required, string, date ex. '2021-07-22') – The end of the aggregate time window.
external (optional, string) – Your Polygon API key if you are not using environment variables.
adjusted (optional, boolean, default True) – Whether or not the results are adjusted for splits. Set this to false to get results that are NOT adjusted for splits.
sort (optional, string, [desc, asc]) – Sort the results by timestamp.
limit (optional, integer, default 5000, max 50000) – Limits the number of base aggregates queried to create the aggregate results.

polygon.forex.conversion(from_date, to, external=False, **query_params)

Returns

Get currency conversions using the latest market conversion rates. Note than you can convert in both directions.

Parameters

from_date (required, string, date ex. '2021-07-22') – The start of the aggregate time window.
to (required, string, date ex. '2021-07-22') – The end of the aggregate time window.
external (optional, string) – Your Polygon API key if you are not using environment variables.
amount (optional, integer) – The amount to convert, with a decimal.
precision (optional, integer) – The decimal precision of the conversion. Defaults to 2 which is 2 decimal places accuracy.

polygon.forex.grouped_daily(date, external=False, **query_params)

Returns

Get the daily open, high, low, and close (OHLC) for the entire forex markets.

Parameters

date (required, string, date ex. '2021-07-22') – The beginning date for the aggregate window.
external (optional, string) – Your Polygon API key if you are not using environment variables.
adjusted (optional, boolean, default True) – Whether or not the results are adjusted for splits. Set this to false to get results that are NOT adjusted for splits.

polygon.forex.historic_ticks(from_date, to, date, external=False, **query_params)

Returns

Get historic ticks for a forex currency pair.

Parameters

from_date (required, string, date ex. '2021-07-22') – The start of the aggregate time window.
to (required, string, date ex. '2021-07-22') – The end of the aggregate time window.
date (required, string, date ex. '2021-07-22') – The beginning date for the aggregate window.
external (optional, string) – Your Polygon API key if you are not using environment variables.
offset (optional, string, date or nanosecond timestamp) – The timestamp offset, used for pagination. This is the offset at which to start the results.
limit (optional, integer, default 5000, max 50000) – Limits the number of base aggregates queried to create the aggregate results.

polygon.forex.last_pair_quote(from_date, to, external=False, **query_params)

Returns

Get the last quote tick for a forex currency pair.

Parameters

from_date (required, string, date ex. '2021-07-22') – The start of the aggregate time window.
to (required, string, date ex. '2021-07-22') – The end of the aggregate time window.
external (optional, string) – Your Polygon API key if you are not using environment variables.

polygon.forex.previous_close(forex_ticker, external=False, **query_params)

Returns

Get the previous day’s open, high, low, and close (OHLC) for the specified forex pair.

Parameters

forex_ticker (required, string) – The ticker symbol of the currency pair.
external (optional, string) – Your Polygon API key if you are not using environment variables.
adjusted (optional, boolean, default True) – Whether or not the results are adjusted for splits. Set this to false to get results that are NOT adjusted for splits.

polygon.forex.quotes(forex_ticker, external=False, **query_params)

Returns

Get BBO quotes for a ticker symbol in a given time range.

Parameters

forex_ticker (required, string) – The ticker symbol of the currency pair.
external (optional, string) – Your Polygon API key if you are not using environment variables.
timestamp (optional, string, date or nanosecond timestamp) – Query by timestamp. Either a date with the format YYYY-MM-DD or a nanosecond timestamp.
order (optional, string, [desc, asc]) – Order results based on the sort field.
limit (optional, integer, default 5000, max 50000) – Limits the number of base aggregates queried to create the aggregate results.
sort (optional, string) – Sort field used for ordering.

polygon.forex.snapshot_all(external=False, **query_params)

Returns

Get the current minute, day, and previous day’s aggregate, as well as the last trade and quote for all traded forex symbols.

Parameters

external (optional, string) – Your Polygon API key if you are not using environment variables.
tickers (optional, string, list of tickers) – A comma separated list of tickers to get snapshots for.

polygon.forex.snapshot_gain_lose(direction, external=False, **query_params)

Returns

Get the current top 20 gainers or losers of the day in forex markets.

Parameters

direction (required, string, [gainers, losers]) – The direction of the snapshot results to return.
external (optional, string) – Your Polygon API key if you are not using environment variables.

polygon.forex.snapshot_ticker(forex_ticker, external=False, **query_params)

:return:Get the current minute, day, and previous day’s aggregate, as well as the last trade and quote for a single traded currency symbol.

Parameters

forex_ticker (required, string) – The ticker symbol of the currency pair.
external (optional, string) – Your Polygon API key if you are not using environment variables.

Reference Endpoint

polygon.reference.conditions(external=False, **query_params)

Returns

List all conditions that Polygon.io uses.

Parameters

external (optional, string) – Your Polygon API key if you are not using environment variables.
asset_class (optional, string) – The asset class by which you would like to filter results.
data_type (optional, string) – The data type by which you would like to filter results.
id (optional, integer) – Filter for conditions with a given ID.
sip (optional, string, [CTA, UTP, OPRA]) – Filter by SIP. If the condition contains a mapping for that SIP, the condition will be returned.
order (optional, string, [desc, asc]) – Order results based on the sort field.
limit (optional, integer, default 5000, max 50000) – Limits the number of base aggregates queried to create the aggregate results.
sort (optional, string) – Sort field used for ordering.

polygon.reference.exchanges(external=False, **query_params)

Returns

List all exchanges that Polygon.io knows about.

Parameters

external (optional, string) – Your Polygon API key if you are not using environment variables.
asset_class (optional, string) – The asset class by which you would like to filter results.
locale (optional, string) – The locale by which you would like to filter results.

polygon.reference.market_holidays(external=False, **query_params)

Returns: Get upcoming market holidays and their open/close times.
Parameters: external (optional, string) – Your Polygon API key if you are not using environment variables.

polygon.reference.market_status(external=False, **query_params)

Returns: Get the current trading status of the exchanges and overall financial markets.
Parameters: external (optional, string) – Your Polygon API key if you are not using environment variables.

polygon.reference.ticker_news(external=False, **query_params)

Returns

Get the most recent news articles relating to a stock ticker symbol, including a summary of the article and a link to the original source.

Parameters

external (optional, string) – Your Polygon API key if you are not using environment variables.
ticker (optional, string) – The ticker for which you would like to query information for.
published_utc (optional, string, date ex. '2021-07-22') – Return results published on, before, or after this date.
order (optional, string, [desc, asc]) – Order results based on the sort field.
limit (optional, integer, default 5000, max 50000) – Limits the number of base aggregates queried to create the aggregate results.
sort (optional, string) – Sort field used for ordering.

polygon.reference.ticker_types(external=False, **query_params)

Returns

List all ticker types that Polygon.io has.

Parameters

external (optional, string) – Your Polygon API key if you are not using environment variables.
asset_class (optional, string) – The asset class by which you would like to filter results.
locale (optional, string) – The locale by which you would like to filter results.

polygon.reference.tickers(external=False, **query_params)

Returns

Query all ticker symbols which are supported by Polygon.io.

Parameters

external (optional, string) – Your Polygon API key if you are not using environment variables.
ticker (optional, string) – The ticker for which you would like to query information for.
type (optional, string, default is to query all types) – The type of the ticker, Available through Polygon.io’s Ticker Types API.
market (optional, string, default is to query all markets) – The market you would like to filter results by.
exchange (optional, string, default is to query all exchanges) – The primary exchange of the asset in the ISO code format.
cusip (optional, string, default is to query all CUSIPs) – The CUSIP code of the asset you want to search for.
cik (optional, string, default is to query all CIKs) – The CIK of the asset you want to search for.
date (optional, string, date ex. '2021-07-22', default is most recent date) – Specify a point in time to retrieve tickers available on that date.
search (optional, string) – Search for terms within the ticker and/or company name.
active (optional, boolean, default is true) – Specify if the tickers returned should be actively traded on the queried date
sort (optional, string) – Sort field used for ordering.
order (optional, string, [desc, asc]) – Order results based on the sort field.
limit (optional, integer, default 5000, max 50000) – Limits the number of base aggregates queried to create the aggregate results.