Stocks / Equities

Overview

This documentation is organized as a 1:1 mirror of the IEX Cloud Stocks Documentation.

The Stock object is instantiated with one or more symbols (equities, ETFs, etc.) and allows access to most endpoints:

In [1]: from iexfinance.stocks import Stock

In [2]: aapl = Stock("AAPL")

In [3]: aapl.get_price()
Out[3]: 
         AAPL
price  125.67

Certain endpoints such as Historical Data, which are unrelated to specific symbols, are supported by top-level functions (i.e. iexfinance.stocks.get_historical_data). This function is optimized to achieve the lowest possible message count for retrieval in a single request.

In [4]: from iexfinance.stocks import get_historical_data

In [5]: get_historical_data("AAPL", start="20190101", end="20200101",
   ...:                     output_format='pandas').head()
   ...: 
Out[5]: 
              close     high      low  ...      label    change changePercent
2019-01-02  39.8300  40.4235  39.5461  ...  Jan 2, 19  0.046839        0.0011
2019-01-03  36.0248  36.5600  36.7000  ...  Jan 3, 19 -4.023278       -0.1003
2019-01-04  37.8320  38.4251  36.9500  ...  Jan 4, 19  1.576739        0.0432
2019-01-07  38.8298  37.2466  37.9140  ...  Jan 7, 19 -0.083850       -0.0023
2019-01-08  37.7237  39.0220  37.3800  ...  Jan 8, 19  0.716480        0.0195

[5 rows x 25 columns]

See Additional Methods for more a list of methods available.

Endpoints

Contents

• Stocks / Equities

  • Overview

  • Endpoints

  • Advanced Stats

  • Balance Sheet

  • Book

  • Cash Flow

  • Charts

  • Company

  • Delayed Quote

  • Dividends (Basic)

  • Earnings

  • Estimates

  • Financials

  • Fund Ownership

  • Historical Prices

  • Income Statement

  • Insider Roster

  • Insider Summary

  • Insider Transactions

  • Institutional Ownership

  • Key Stats

  • Largest Trades

  • Logo

  • OHLC

  • Open/Close Price

  • Peer Groups

  • Previous Day Price

  • Price Only

  • Price Target

  • Quote

  • Relevant Stocks

  • Splits (Basic)

  • Time Series

  • Volume by Venue

  • Additional Methods

The Stock object

The Stock object allows retrieval of endpoints (Earnings, Quote, etc) for up to 100 symbols at once.

class iexfinance.stocks.base.Stock(symbols=None, **kwargs)

Base class for obtaining data from the Stock endpoints of IEX.

symbols

Symbol or list-like collection of symbols

Type

str or list-like (list, tuple, pandas.Series, pandas.Index)

output_format

Type

str, default ‘pandas’, optional

token

Authentication token (required for use with IEX Cloud)

Type

str, optional

Basic Usage Example

In [6]: from iexfinance.stocks import Stock

In [7]: aapl = Stock("aapl")

In [8]: aapl.get_price()
Out[8]: 
         AAPL
price  126.36

Advanced Stats

Stock.get_advanced_stats(**kwargs)

Reference: https://iexcloud.io/docs/api/#advanced-stats

Data Weighting: 3,000 per symbol + Key Stats weight

Notes

Only included with paid subscription plans.

Balance Sheet

Stock.get_balance_sheet(**kwargs)

Balance Sheet

Pulls balance sheet data. Available quarterly (12 quarters) and annually (4 years)

Reference: https://iexcloud.io/docs/api/#balance-sheet

Data Weighting: 3000 per symbol per period

Parameters

• period (str, default 'quarter', optional) – Allows you to specify annual or quarterly balance sheet. Value should be annual or quarter.

• last (int, default 1, optional) – Specify the number of quarters or years to return. You can specify up to 12 quarters or 4 years.

Book

Stock.get_book()

Book

Reference: https://iexcloud.io/docs/api/#book

Note

This endpoint does not support pandas DataFrame output formatting.

Data Weighting: 1 per quote returned

Cash Flow

Stock.get_cash_flow(**kwargs)

Cash Flow

Pulls cash flow data. Available quarterly (4 quarters) or annually (4 years).

Reference: https://iexcloud.io/docs/api/#cash-flow

Data Weighting: 1000 per symbol per period

Parameters

• period (str, default 'quarter', optional) – Allows you to specify annual or quarterly cash flows. Value should be annual or quarter.

• last (int, default 1, optional) – Specify the number of quarters or years to return. You can specify up to 12 quarters or 4 years.

Charts

Stock.get_chart(**kwargs)

Chart

See also

get_historical_prices

Company

Stock.get_company(**kwargs)

Company

Reference: https://iexcloud.io/docs/api/#company

Data Weighting: 1

Delayed Quote

Stock.get_delayed_quote()

Delayed Quote

Reference: https://iexcloud.io/docs/api/#delayed-quote

Data Weighting: 1 per symbol per quote

Dividends (Basic)

Stock.get_dividends(**kwargs)

Dividends

Reference: https://iexcloud.io/docs/api/#dividends

Data Weighting: 10 per symbol per period returned

Parameters

range (str, default '1m', optional) – Time period of dividends to return Choose from [5y,`2y`,`1y`,`ytd`,`6m`,`3m`,`1m`, next]

Earnings

Warning

Beginning December 1, 2020, use of this endpoint will require additional entitlements. Full details can be found in the IEX Cloud Help Center. See here for additional information.

Stock.get_earnings(**kwargs)

Earnings

Earnings data for a given company including the actual EPS, consensus, and fiscal period. Earnings are available quarterly (last 4 quarters) and annually (last 4 years).

Reference: https://iexcloud.io/docs/api/#earnings

Data Weighting: 1000 per symbol per period

Parameters

• period (str, default 'quarter', optional) – Allows you to specify annual or quarterly earnings. Value should be annual or quarter.

• last (int, default 1, optional) – Specify the number of quarters or years to return. You can specify up to 4 quarters or 4 years.

Estimates

Warning

Beginning December 1, 2020, use of this endpoint will require additional entitlements. Full details can be found in the IEX Cloud Help Center. See here for additional information.

Stock.get_estimates(**kwargs)

Estimates

Provides the latest consensus estimate for the next fiscal period

Reference: https://iexcloud.io/docs/api/#estimates

Data Weighting: 10000 per symbol per period

Parameters

• last (int, default 1, optional) –

• period (str, default quarter, optional) –

Financials

Stock.get_financials(**kwargs)

Financials

Pulls income statement, balance sheet, and cash flow data from the most recent reported quarter.

Reference: https://iexcloud.io/docs/api/#financials

Data Weighting: 5000 per symbol per period

Parameters

period (str, default 'quarter', optional) – Allows you to specify annual or quarterly financials. Value should be annual or quarter.

Fund Ownership

Stock.get_fund_ownership()

Fund Ownership

Returns the top 10 fund holders, meaning any firm not defined as buy-side or sell-side such as mutual funds, pension funds, endowments, investment firms, and other large entities that manage funds on behalf of others.

Reference: https://iexcloud.io/docs/api/#fund-ownership

Data Weighting: 10000 per symbol per period

Historical Prices

Note

The Stock.get_historical_prices method is an exact mirror of the Historical Prices (chart) endpoint and accepts all parameters, but is not optimized. Use get_historical_data for optimized message counts. get_historical_data accepts start, end (optional) along with the parameter close_only, and no other parameters.

The method used to obtain historical prices from a Stock object:

In [9]: from iexfinance.stocks import Stock

In [10]: aapl = Stock("AAPL")

In [11]: aapl.get_historical_prices()
Out[11]: 
             close      high      low  ...       label    change changePercent
2020-11-12  124.75  121.6000  119.050  ...  Nov 12, 20         0             0
2020-11-13  122.34  120.6212  117.960  ...  Nov 13, 20  0.051529        0.0004
2020-11-16  124.80  125.9000  121.276  ...  Nov 16, 20  1.083507        0.0090
2020-11-17  121.41  125.1832  124.560  ...  Nov 17, 20 -0.946305       -0.0079
2020-11-18  121.90  121.4500      121  ...  Nov 18, 20 -1.396242       -0.0115
2020-11-19  122.15  119.8100  117.330  ...  Nov 19, 20  0.617824        0.0053
2020-11-20  120.40  120.4900  119.210  ...  Nov 20, 20 -1.329465       -0.0110
2020-11-23  119.24  117.7164  119.350  ...  Nov 23, 20 -3.592947       -0.0302
2020-11-24  118.17  117.9600  117.730  ...  Nov 24, 20  1.352659        0.0119
2020-11-25  119.10  117.1500  119.530  ...  Nov 25, 20  0.896958        0.0075
2020-11-27  120.68  117.6300  116.700  ...  Nov 27, 20  0.575378        0.0048
2020-11-30  120.77  126.1200  118.700  ...  Nov 30, 20  2.507935        0.0212
2020-12-01  127.66  125.5623  123.660  ...   Dec 1, 20  3.836405        0.0315
2020-12-02  129.04  124.9300  126.580  ...   Dec 2, 20  0.371817        0.0029
2020-12-03  124.64  124.0700  123.930  ...   Dec 3, 20 -0.146481       -0.0011
2020-12-04  123.76  124.7568  125.030  ...   Dec 4, 20 -0.722274       -0.0058
2020-12-07  125.47  130.0800  126.180  ...   Dec 7, 20  1.500000        0.0127
2020-12-08  129.26  128.0500  128.490  ...   Dec 8, 20  0.641853        0.0053
2020-12-09  122.37  128.9200      125  ...   Dec 9, 20 -2.604838       -0.0217
2020-12-10  128.51  126.2400  123.290  ...  Dec 10, 20  1.522212        0.0130
2020-12-11  125.88  125.4000  126.440  ...  Dec 11, 20 -0.830034       -0.0068

[21 rows x 25 columns]

Historical time series data is also available through the optimized top-level get_historical_data and get_historical_intraday functions of stocks, which source the Historical Prices endpoint, and accept a date or date range for retrieval.

Daily data can be retrieved from up to 15 years before the current date.

Daily

To obtain daily historical data, use get_historical_data.

iexfinance.stocks.get_historical_data(symbols, start=None, end=None, close_only=False, **kwargs)

Function to obtain historical date for a symbol or list of symbols. Return an instance of HistoricalReader

Reference: https://iextrading.com/developer/docs/#chart

Parameters

• symbols (str or list) – A symbol or list of symbols

• start (string, int, date, datetime, Timestamp) – Starting date. Parses many different kind of date representations (e.g., ‘JAN-01-2010’, ‘1/1/10’, ‘Jan, 1, 1980’). Defaults to 1 year before current date.

• end (string, int, date, datetime, Timestamp) – Ending date

• close_only (bool, default False) – Returns adjusted data only with keys date, close, and volume

• kwargs – Additional Request Parameters (see base class)

Returns

Historical stock prices over date range, start to end

Return type

list or DataFrame

Example

In [12]: from iexfinance.stocks import get_historical_data

In [13]: from datetime import datetime

In [14]: start = datetime(2017, 2, 9)

In [15]: end = datetime(2017, 5, 24)

In [16]: f = get_historical_data('AAPL', start, end, output_format='pandas')

In [17]: f.loc["2017-02-09"]
Out[17]: 
close                           34.175000
high                            34.166100
low                             34.100000
open                            33.055100
symbol                               AAPL
volume                          117241549
id                      LHISTESR_ICORAICP
key                                  APLA
subkey                                  0
updated                     1617953028803
changeOverTime                   0.180040
marketChangeOverTime             0.179436
uOpen                          134.700000
uClose                         136.100000
uHigh                          135.717000
uLow                           135.980000
uVolume                          29517415
fOpen                           32.373400
fClose                          32.409500
fHigh                           32.716700
fLow                            32.140000
fVolume                         118474813
label                           Feb 9, 17
change                           0.095431
changePercent                    0.002900
Name: 2017-02-09 00:00:00, dtype: object

Minutely

To obtain one-minute intraday data for a given date, use get_historical_intraday. Note: this endpoint has a maximum of one symbol and a single date.

iexfinance.stocks.get_historical_intraday(symbol, date=None, **kwargs)

Function to obtain intraday one-minute pricing data for one symbol on a given date (defaults to current date)

Parameters

• symbol (str) – A single ticker

• date (datetime.datetime, default current date) – Desired date for intraday retrieval, defaults to today

• kwargs – Additional Request Parameters (see base class)

Returns

Intraday pricing data for specified symbol on given date

Return type

list or DataFrame

In [18]: from datetime import datetime

In [19]: from iexfinance.stocks import get_historical_intraday

In [20]: date = datetime(2018, 11, 27)

In [21]: data = get_historical_intraday("AAPL", date, output_format='pandas')

In [22]: data.head()
Out[22]: 
Empty DataFrame
Columns: []
Index: []

Closing Prices Only

To retrieve closing prices only, use get_historical_data and set close_only=True:

In [23]: from iexfinance.stocks import get_historical_data

In [24]: get_historical_data("AAPL", "20190617", close_only=True)
Out[24]: 
               close     volume
2019-06-17   49.4962   59126555
2019-06-18   52.0920  110609385
2019-06-19   50.7238   85471129
2019-06-20   50.1670   86835800
2019-06-21   51.9550  195176500
...              ...        ...
2020-12-07  128.9600   90169986
2020-12-08  126.8600   82284222
2020-12-09  125.5100  115659941
2020-12-10  125.2100   84296616
2020-12-11  127.3900   90169096

[378 rows x 2 columns]

Income Statement

Stock.get_income_statement(**kwargs)

Income Statement

Pulls income statement data. Available quarterly (4 quarters) or annually (4 years).

Reference: https://iexcloud.io/docs/api/#income-statement

Data Weighting: 1000 per symbol per period

Parameters

period (str, default 'quarterly', optional) – Allows you to specify annual or quarterly income statement. Defaults to quarterly. Values should be annual or quarter

Insider Roster

Stock.get_insider_roster()

Insider Roster

Returns the top 10 insiders, with the most recent information.

Reference: https://iexcloud.io/docs/api/#insider-roster

Data Weighting: 5000 per symbol

Insider Summary

Stock.get_insider_summary()

Insider Summary

Returns aggregated insiders summary data for the last 6 months.

Reference: https://iexcloud.io/docs/api/#insider-summary

Data Weighting: 5000 per symbol

Insider Transactions

Stock.get_insider_transactions()

Insider Transactions

Returns insider transactions.

Reference: https://iexcloud.io/docs/api/#insider-transactions

Data Weighting: 50 per transaction

Institutional Ownership

Stock.get_institutional_ownership()

Institutional Ownership

Returns the top 10 institutional holders, defined as buy-side or sell-side firms.

Reference: https://iexcloud.io/docs/api/#institutional-ownership

Data Weighting: 10000 per symbol per period

Key Stats

Stock.get_key_stats(**kwargs)

Reference: https://iexcloud.io/docs/api/#key-stats

Parameters

stat (str, optional) – Case sensitive string matching the name of a single key to return one value.Ex: If you only want the next earnings date, you would use nextEarningsDate.

Largest Trades

Stock.get_largest_trades()

Reference: https://iexcloud.io/docs/api/#largest-trades

Logo

Stock.get_logo()

Reference: https://iexcloud.io/docs/api/#logo

OHLC

Stock.get_ohlc()

OHLC

Returns the official open and close for a give symbol.

Reference: https://iexcloud.io/docs/api/#ohlc

Data Weighting: 2 per symbol

Open/Close Price

See also

Time Series is an alias for the OHLC endpoint

Stock.get_open_close()

Open/Close Price

Reference: https://iexcloud.io/docs/api/#open-close-price

Data Weighting: 2 per symbol

Notes

Open/Close Price is an alias for the OHLC endpoint, and will return the same

Peer Groups

Stock.get_peers()

Peers

Reference:https://iexcloud.io/docs/api/#peers

Data Weighting: 500 per call

Notes

Only allows JSON format (pandas not supported).

Previous Day Price

Warning

get_previous has been deprecated and renamed get_previous_day_prices.

Stock.get_previous_day_prices()

Previous Day Prices

This returns previous day adjusted price data for one or more stocks

Reference: https://iexcloud.io/docs/api/#previous

Data Weighting: 2 per symbol

Price Only

Stock.get_price()

Price

Reference: https://iexcloud.io/docs/api/#price

1 per symbol

Price Target

Warning

Beginning December 1, 2020, use of this endpoint will require additional entitlements. Full details can be found in the IEX Cloud Help Center. See here for additional information.

Stock.get_price_target()

Price Target

Provides the latest avg, high, and low analyst price target for a symbol.

Reference: https://iexcloud.io/docs/api/#price-target

Data Weighting: 500 per symbol

Quote

Stock.get_quote(**kwargs)

Quote

Reference: https://iexcloud.io/docs/api/#quote

Data Weighting: 1 per quote

Parameters

displayPercent (bool, defaults to false, optional) – If set to true, all percentage values will be multiplied by a factor of 100.

Relevant Stocks

Stock.get_relevant_stocks(**kwargs)

Relevant Stocks

Similar to the peers endpoint, except this will return most active market symbols when peers are not available. If the symbols returned are not peers, the peers key will be false. This is not intended to represent a definitive or accurate list of peers, and is subject to change at any time.

Reference: https://iexcloud.io/docs/api/#relevant-stocks

Data Weighting: 500 per call

Examples

In [25]: from iexfinance.stocks import get_sector_performance

In [26]: get_sector_performance(output_format='pandas')
Out[26]: 
                          type  ...    lastUpdated
ni cCeoSoniemcaimuvrst  sector  ...  1623797041072
lutaInsdris             sector  ...  1687600232131
eSsloenrs uatmCp        sector  ...  1669720777186
tUieisilt               sector  ...  1612095377674
tEt Rlaeeas             sector  ...  1671678522739
coyoglhTne              sector  ...  1642468316286
HCalaeethr              sector  ...  1671529113034
roit CceseirrynasDnmou  sector  ...  1611166677271
talMasier               sector  ...  1630915964628
nicaanlisF              sector  ...  1608955012257
ryEgen                  sector  ...  1636232053173

[11 rows x 4 columns]

Splits (Basic)

Stock.get_splits(**kwargs)

Splits

Reference: https://iexcloud.io/docs/api/#splits

Parameters

range (str, default '1m', optional) – Time period of splits to return. Choose from [5y,`2y`,`1y`,`ytd`,`6m`,`3m`,`1m`, next].

Time Series

See also

Time Series is an alias for the Chart endpoint

Stock.get_time_series(**kwargs)

Time Series

See also

get_historical_prices

Volume by Venue

Stock.get_volume_by_venue()

Volume by Venue

Reference: https://iexcloud.io/docs/api/#volume-by-venue

Data Weighting: 20 per call

Additional Methods

In addition, various additional Stock methods are provided for certain endpoints. These methods will allow retrieval of a single datapoint, such as get_open, get_company_name, etc. Field methods are displayed below the endpoint methods for which they are available (namely Quote and Key Stats).

Key Stats

Stock.get_beta()

Stock.get_short_interest()

Stock.get_short_ratio()

Stock.get_latest_eps()

Stock.get_shares_outstanding()

Stock.get_float()

Stock.get_eps_consensus()

Quote

Stock.get_company_name()

Stock.get_sector()

Stock.get_open()

Stock.get_close()

Stock.get_years_high()

Stock.get_years_low()

Stock.get_ytd_change()

Stock.get_volume()

Stock.get_market_cap()

Market Movers

The List endpoint of stocks provides information about market movers from a given trading day. iexfinance implements these market mover lists with the functions listed below. These functions return a list of quotes of the top-10 symbols in each list.

• Gainers (stocks.get_market_gainers)

• Losers (stocks.get_market_losers)

• Most Active (stocks.get_market_most_active)

• IEX Volume (stocks.get_market_iex_volume)

• IEX Percent (stocks.get_market_iex_percent)

• In Focus (stocks.get_market_in_focus)

In [27]: from iexfinance.stocks import get_market_gainers

In [28]: get_market_gainers()
Out[28]: 
Empty DataFrame
Columns: []
Index: []