Reference APIs

Read this page to know everything you need to know about using the various References 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 and create client as below. As always you can have all 5 different clients together.

import polygon

reference_client = polygon.ReferenceClient('KEY')  # for usual sync client
async_reference_client = polygon.ReferenceClient('KEY', True)  # for an async client

Get Tickers

This endpoint supports pagination. The library has support for pagination. See Pagination Support for info and examples

ReferenceClient.get_tickers(symbol: str = '', ticker_lt=None, ticker_lte=None, ticker_gt=None, ticker_gte=None, symbol_type='', market='', exchange: str = '', cusip: Optional[str] = None, cik: str = '', date=None, search: Optional[str] = None, active: bool = True, sort='ticker', order='asc', limit: int = 100, raw_response: bool = False) → Union[requests.models.Response, dict]

Query all ticker symbols which are supported by Polygon.io. This API currently includes Stocks/Equities, Crypto, and Forex. Official Docs

Parameters

  • symbol – Specify a ticker symbol. Defaults to empty string which queries all tickers.

  • ticker_lt – Return results where this field is less than the value given

  • ticker_lte – Return results where this field is less than or equal to the value given

  • ticker_gt – Return results where this field is greater than the value given

  • ticker_gte – Return results where this field is greater than or equal to the value given

  • symbol_type – Specify the type of the tickers. See polygon.enums.TickerType for common choices. Find all supported types via the Ticker Types API Defaults to empty string which queries all types.

  • market – Filter by market type. By default all markets are included. See polygon.enums.TickerMarketType for available choices.

  • exchange – Specify the primary exchange of the asset in the ISO code format. Find more information about the ISO codes at the ISO org website. Defaults to empty string which queries all exchanges.

  • cusip – Specify the CUSIP code of the asset you want to search for. Find more information about CUSIP codes on their website Defaults to empty string which queries all CUSIPs

  • cik – Specify the CIK of the asset you want to search for. Find more information about CIK codes at their website Defaults to empty string which queries all CIKs.

  • date – Specify a point in time to retrieve tickers available on that date. Defaults to the most recent available date. Could be datetime, date or a string YYYY-MM-DD

  • search – Search for terms within the ticker and/or company name. for eg MS will match matching symbols

  • active – Specify if the tickers returned should be actively traded on the queried date. Default is True

  • sort – The field to sort the results on. Default is ticker. If the search query parameter is present, sort is ignored and results are ordered by relevance. See polygon.enums.TickerSortType for available choices.

  • order – The order to sort the results on. Default is asc. See polygon.enums.SortOrder for available choices.

  • limit – Limit the size of the response, default is 100 and max is 1000. Pagination is supported by the pagination function below

  • raw_response – Whether or not 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 Ticker Types

ReferenceClient.get_ticker_types_v3(asset_class=None, locale=None, raw_response: bool = False) → Union[requests.models.Response, dict]

Get a mapping of ticker types to their descriptive names. Official Docs

Parameters

  • asset_class – Filter by asset class. see polygon.enums.AssetClass for choices

  • locale – Filter by locale. See polygon.enums.Locale for choices

  • raw_response – Whether or not 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 Ticker Details

ReferenceClient.get_ticker_details(symbol: str, raw_response: bool = False) → Union[requests.models.Response, dict]

Get details for a ticker symbol’s company/entity. This provides a general overview of the entity with information such as name, sector, exchange, logo and similar companies.

This endpoint will be replaced by get_ticker_details_vx() in future. Official Docs

Parameters

  • symbol – The ticker symbol of the stock/equity.

  • raw_response – Whether or not 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 Ticker Details vX

ReferenceClient.get_ticker_details_vx(symbol: str, date=None, raw_response: bool = False) → Union[requests.models.Response, dict]

This API is Experimental and will replace get_ticker_details() in future.

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

Parameters

  • symbol – The ticker symbol of the asset.

  • date – Specify a point in time to get information about the ticker available on that date. When retrieving information from SEC filings, we compare this date with the period of report date on the SEC filing. Defaults to the most recent available date.

  • raw_response – Whether or not 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 Option Contracts

This endpoint supports pagination. The library has support for pagination. See Pagination Support for info and examples

ReferenceClient.get_option_contracts(underlying_ticker: Optional[str] = None, ticker: Optional[str] = None, contract_type=None, expiration_date=None, expiration_date_lt=None, expiration_date_lte=None, expiration_date_gt=None, expiration_date_gte=None, order='asc', sort=None, limit=100, raw_response: bool = False) → Union[requests.models.Response, dict]

List currently active options contracts Official Docs

Parameters

  • underlying_ticker – Query for contracts relating to an underlying stock ticker.

  • ticker – Query for a contract by option ticker.

  • contract_type – Query by the type of contract. see polygon.enums.OptionsContractType for choices

  • expiration_date – Query by contract expiration date. either datetime, date or string YYYY-MM-DD

  • expiration_date_lt – expiration date less than given value

  • expiration_date_lte – expiration date less than equal to given value

  • expiration_date_gt – expiration_date greater than given value

  • expiration_date_gte – expiration_date greater than equal to given value

  • order – Order of results. See polygon.enums.SortOrder for choices.

  • sort – Sort field for ordering. See polygon.enums.OptionsContractsSortType for choices.

  • limit – Number of results to return

  • raw_response – Whether or not 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 Ticker News

This endpoint supports pagination. The library has support for pagination. See Pagination Support for info and examples

ReferenceClient.get_ticker_news(symbol: Optional[str] = None, limit: int = 100, order='desc', sort='published_utc', ticker_lt=None, ticker_lte=None, ticker_gt=None, ticker_gte=None, published_utc=None, published_utc_lt=None, published_utc_lte=None, published_utc_gt=None, published_utc_gte=None, raw_response: bool = False) → Union[requests.models.Response, dict]

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. Official Docs

Parameters

  • symbol – To get news mentioning the name given. Defaults to empty string which doesn’t filter tickers

  • limit – Limit the size of the response, default is 100 and max is 1000. Use pagination helper function for larger responses.

  • order – Order the results. See polygon.enums.SortOrder for choices.

  • sort – The field key to sort. See polygon.enums.TickerNewsSort for choices.

  • ticker_lt – Return results where this field is less than the value.

  • ticker_lte – Return results where this field is less than or equal to the value.

  • ticker_gt – Return results where this field is greater than the value

  • ticker_gte – Return results where this field is greater than or equal to the value.

  • published_utc – A date string YYYY-MM-DD or datetime for published date time filters.

  • published_utc_lt – Return results where this field is less than the value given

  • published_utc_lte – Return results where this field is less than or equal to the value given

  • published_utc_gt – Return results where this field is greater than the value given

  • published_utc_gte – Return results where this field is greater than or equal to the value given

  • raw_response – Whether or not 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 Stock dividends

ReferenceClient.get_stock_dividends(symbol: str, raw_response: bool = False) → Union[requests.models.Response, dict]

Get a list of historical dividends for a stock, including the relevant dates and the amount of the dividend. Official Docs

Parameters

  • symbol – The ticker symbol of the stock/equity.

  • raw_response – Whether or not 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 Stock Financials

ReferenceClient.get_stock_financials(symbol: str, limit: int = 100, report_type=None, sort=None, raw_response: bool = False) → Union[requests.models.Response, dict]

Get historical financial data for a stock ticker. This API will be replaced by get_stock_financials_vx() in future. Official Docs

Parameters

  • symbol – The ticker symbol of the stock/equity.

  • limit – Limit the number of results. Defaults to 100

  • report_type – Specify a type of report to return. see polygon.enums.StockReportType for choices. Defaults to None

  • sort – The key for sorting the results. see polygon.enums.StockFinancialsSortType for choices.

  • raw_response – Whether or not 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 Stock financials vX

ReferenceClient.get_stock_financials_vx(ticker: Optional[str] = None, cik: Optional[str] = None, company_name: Optional[str] = None, company_name_search: Optional[str] = None, sic: Optional[str] = None, filing_date=None, filing_date_lt=None, filing_date_lte=None, filing_date_gt=None, filing_date_gte=None, period_of_report_date=None, period_of_report_date_lt=None, period_of_report_date_lte=None, period_of_report_date_gt=None, period_of_report_date_gte=None, time_frame=None, include_sources: bool = False, order='asc', limit: int = 50, sort='filing_date', raw_response: bool = False)

Get historical financial data for a stock ticker. The financials data is extracted from XBRL from company SEC filings using this methodology Official Docs

This API is experimental and will replace get_stock_financials() in future.

Parameters

  • ticker – Filter query by company ticker.

  • cik – filter the Query by central index key (CIK) Number

  • company_name – filter the query by company name

  • company_name_search – partial match text search for company names

  • sic – Query by standard industrial classification (SIC)

  • filing_date – Query by the date when the filing with financials data was filed. datetime/date or string YYYY-MM-DD

  • filing_date_lt – filter for filing date less than given value

  • filing_date_lte – filter for filing date less than equal to given value

  • filing_date_gt – filter for filing date greater than given value

  • filing_date_gte – filter for filing date greater than equal to given value

  • period_of_report_date – query by The period of report for the filing with financials data. datetime/date or string in format: YYY-MM-DD.

  • period_of_report_date_lt – filter for period of report date less than given value

  • period_of_report_date_lte – filter for period of report date less than equal to given value

  • period_of_report_date_gt – filter for period of report date greater than given value

  • period_of_report_date_gte – filter for period of report date greater than equal to given value

  • time_frame – Query by timeframe. Annual financials originate from 10-K filings, and quarterly financials originate from 10-Q filings. Note: Most companies do not file quarterly reports for Q4 and instead include those financials in their annual report, so some companies my not return quarterly financials for Q4. See polygon.enums.StockFinancialsTimeframe for choices.

  • include_sources – Whether or not to include the xpath and formula attributes for each financial data point. See the xpath and formula response attributes for more info. False by default

  • order – Order results based on the sort field. ‘asc’ by default. See polygon.enums.SortOrder for choices.

  • limit – number of max results to obtain. defaults to 50.

  • sort – Sort field key used for ordering. ‘filing_date’ default. see polygon.enums.StockFinancialsSortKey for choices.

  • raw_response – Whether or not 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 Stock Splits

ReferenceClient.get_stock_splits(symbol: str, raw_response: bool = False) → Union[requests.models.Response, dict]

Get a list of historical stock splits for a ticker symbol, including the execution and payment dates of the stock split, and the split ratio. Official Docs

Parameters

  • symbol – The ticker symbol of the stock/equity.

  • raw_response – Whether or not 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 Market Holidays

ReferenceClient.get_market_holidays(raw_response: bool = False) → Union[requests.models.Response, dict]

Get upcoming market holidays and their open/close times. Official Docs

Parameters

raw_response – Whether or not 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 Market Status

ReferenceClient.get_market_status(raw_response: bool = False) → Union[requests.models.Response, dict]

Get the current trading status of the exchanges and overall financial markets. Official Docs

Parameters

raw_response – Whether or not 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 Condition Mappings

ReferenceClient.get_condition_mappings(tick_type='trades', raw_response: bool = False) → Union[requests.models.Response, dict]

Get a unified numerical mapping for conditions on trades and quotes. Each feed/exchange uses its own set of codes to identify conditions, so the same condition may have a different code depending on the originator of the data. Polygon.io defines its own mapping to allow for uniformly identifying a condition across feeds/exchanges. Official Docs

Parameters

  • tick_type – The type of ticks to return mappings for. Defaults to ‘trades’. See polygon.enums.ConditionMappingTickType for choices.

  • raw_response – Whether or not 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 Conditions

ReferenceClient.get_conditions(asset_class=None, data_type=None, id=None, sip=None, order=None, limit: int = 50, sort='name', raw_response: bool = False)

List all conditions that Polygon.io uses. Official Docs

Parameters

  • asset_class – Filter for conditions within a given asset class. See polygon.enums.AssetClass for choices. Defaults to all assets.

  • data_type – Filter by data type. See polygon.enums.ConditionsDataType for choices. defaults to all.

  • id – Filter for conditions with a given ID

  • sip – Filter by SIP. If the condition contains a mapping for that SIP, the condition will be returned.

  • order – Order results. See polygon.enums.SortOrder for choices.

  • limit – limit the number of results. defaults to 50.

  • sort – Sort field used for ordering. Defaults to ‘name’. See polygon.enums.ConditionsSortKey for choices.

  • raw_response – Whether or not 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 Exchanges

ReferenceClient.get_exchanges(asset_class=None, locale=None, raw_response: bool = False)

List all exchanges that Polygon.io knows about. Official Docs

Parameters

  • asset_class – filter by asset class. See polygon.enums.AssetClass for choices.

  • locale – Filter by locale name. See polygon.enums.Locale

  • raw_response – Whether or not 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 Locales

ReferenceClient.get_locales(raw_response: bool = False) → Union[requests.models.Response, dict]

Get a list of locales currently supported by Polygon.io. Official Docs

Parameters

raw_response – Whether or not 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 Markets

ReferenceClient.get_markets(raw_response: bool = False) → Union[requests.models.Response, dict]

Get a list of markets that are currently supported by Polygon.io. Official Docs

Parameters

raw_response – Whether or not 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