Stocks / Equities¶
Overview¶
This documentation is organized as a 1:1 mirror of the IEX Cloud Stocks/Equities 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 128.71
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.77 41.1086 39.77 ... Jan 2, 19 0.046392 0.0011
2019-01-03 37.0146 37.51 35.7 ... Jan 3, 19 -3.938462 -0.1038
2019-01-04 37.797 38.3638 36.35 ... Jan 4, 19 1.533941 0.044
2019-01-07 38.3483 38.3596 36.563 ... Jan 7, 19 -0.085323 -0.0022
2019-01-08 39.5379 39.5379 37.22 ... Jan 8, 19 0.728955 0.0197
[5 rows x 26 columns]
See Additional Methods for more a list of methods available.
Endpoints¶
Contents
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: str or list-like (list, tuple, pandas.Series, pandas.Index)
Symbol or list-like collection of symbols
output_format: str, default ‘pandas’, optional token: str, optional
Authentication token (required for use with IEX Cloud)
Basic Usage Example¶
In [6]: from iexfinance.stocks import Stock
In [7]: aapl = Stock("aapl")
In [8]: aapl.get_price()
Out[8]:
AAPL
price 125.87
Advanced Stats¶
- Stock.get_advanced_stats(**kwargs)¶
Reference: https://iexcloud.io/docs/api/#advanced-stats
Data Weighting:
3,000per symbol + Key Stats weightOnly 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:
3000per symbol per period- 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
DataFrameoutput formatting.Data Weighting:
1per 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:
1000per symbol per period- 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.
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:
1per symbol per quote
Dividends (Basic)¶
- Stock.get_dividends(**kwargs)¶
Dividends
Reference: https://iexcloud.io/docs/api/#dividends
Data Weighting:
10per symbol per period returned- 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:
1000per symbol per period- 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:
10000per symbol per periodlast: 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:
5000per symbol per period- 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:
10000per 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
2021-05-03 133.98 135.99 132.11 ... May 3, 21 0 0
2021-05-04 131.16 133.2 127.8 ... May 4, 21 -4.917404 -0.0364
2021-05-05 134.3 134.9 129.29 ... May 5, 21 0.25 0.002
2021-05-06 130.91 131.78 128.92 ... May 6, 21 1.713041 0.0128
2021-05-07 135.05 136.32 130.781 ... May 7, 21 0.479626 0.0037
2021-05-10 130.15 131.22 130.15 ... May 10, 21 -3.507105 -0.0261
2021-05-11 130.16 130.16 124.2 ... May 11, 21 -0.965399 -0.0076
2021-05-12 124.01 128.7 124.01 ... May 12, 21 -3.26372 -0.0261
2021-05-13 129.89 129.89 128.12 ... May 13, 21 2.235031 0.0186
2021-05-14 130.58 131.2 127.25 ... May 14, 21 2.521045 0.0204
2021-05-17 127.19 130.85 127.19 ... May 17, 21 -1.192821 -0.0096
2021-05-18 126.2 132.69 125.32 ... May 18, 21 -1.452903 -0.0113
2021-05-19 127.41 129.613 122.98 ... May 19, 21 -0.165777 -0.0013
2021-05-20 131.71 131.71 129.27 ... May 20, 21 2.720626 0.021
2021-05-21 126.74 130.05 126.74 ... May 21, 21 -1.967022 -0.0153
2021-05-24 128.4 131.43 126.06 ... May 24, 21 1.68495 0.0136
2021-05-25 129.3 133.08 129.3 ... May 25, 21 -0.201956 -0.0017
2021-05-26 131.35 132.11 128.846 ... May 26, 21 -0.05247 -0.0004
2021-05-27 130.96 132.13 126.55 ... May 27, 21 -1.606911 -0.0125
2021-05-28 126.91 130.87 126.91 ... May 28, 21 -0.676525 -0.0055
2021-06-01 128.9 131.5 126.93 ... Jun 1, 21 -0.332007 -0.0026
2021-06-02 125.47 127.32 125.47 ... Jun 2, 21 0.798892 0.0066
[22 rows x 26 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://iexcloud.io/docs/api/#historical-prices
- symbols: str or list
A symbol or list of symbols
- startstring, 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.
- endstring, int, date, datetime, Timestamp
Ending date
- close_only: bool, default False
Returns adjusted data only with keys
date,close, andvolume- kwargs:
Additional Request Parameters (see base class)
- list or DataFrame
Historical stock prices over date range, start to end
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 33.307
high 34.5024
low 33.11
open 34.5024
symbol AAPL
volume 115187066
id HOCEIR_RSSCLITPAI
key LAAP
subkey
date 2017-02-09
updated 1633810330221
changeOverTime 0.362783
marketChangeOverTime 0.352541
uOpen 136.55
uClose 132.99
uHigh 133.689
uLow 133.75
uVolume 28742004
fOpen 32.5787
fClose 32.039
fHigh 31.5336
fLow 31.7019
fVolume 117789014
label Feb 9, 17
change 0.095136
changePercent 0.003
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)
- 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)
- list or DataFrame
Intraday pricing data for specified symbol on given date
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 50.2019 61162475
2019-06-18 51.5319 110800965
2019-06-19 50.7203 86146848
2019-06-20 51.121 90286903
2019-06-21 51.95 192460432
... ... ...
2021-05-26 132.8 57691211
2021-05-27 128 95999565
2021-05-28 126.18 73705807
2021-06-01 128.47 70698252
2021-06-02 130.54 60857550
[495 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:
1000per symbol per period- 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:
5000per 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:
5000per symbol
Insider Transactions¶
- Stock.get_insider_transactions()¶
Insider Transactions
Returns insider transactions.
Reference: https://iexcloud.io/docs/api/#insider-transactions
Data Weighting:
50per 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:
10000per symbol per period
Key Stats¶
- Stock.get_key_stats(**kwargs)¶
Reference: https://iexcloud.io/docs/api/#key-stats
- 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:
2per 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:
2per symbolOpen/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:
500per callOnly 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-day-price
Data Weighting:
2per symbol
Price Only¶
- Stock.get_price()¶
Price
Reference: https://iexcloud.io/docs/api/#price-only
1per 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:
500per symbol
Quote¶
- Stock.get_quote(**kwargs)¶
Quote
Reference: https://iexcloud.io/docs/api/#quote
Data Weighting:
1per quote- 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)¶
DEPRECATED
Examples¶
In [25]: from iexfinance.stocks import get_sector_performance
In [26]: get_sector_performance(output_format='pandas')
Out[26]:
type ... lastUpdated
rneyEg sector ... 1649148088195
t EestlaeRa sector ... 1662623307037
Tlhcnyoego sector ... 1624684818127
iistlUtie sector ... 1654160321109
Cpsemr eSsnuaolt sector ... 1667114952565
aalsnFicin sector ... 1697539489702
Cat aherHle sector ... 1637010585600
siIludsratn sector ... 1629899227812
oatSirminvCmioecsuen c sector ... 1639799572191
rruiDa tnremscneoCyios sector ... 1654986367200
raislMeta sector ... 1675709198097
[11 rows x 4 columns]
Splits (Basic)¶
- Stock.get_splits(**kwargs)¶
Splits
Reference: https://iexcloud.io/docs/api/#splits
- 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:
20per 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_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]:
companyName ... isUSMarketOpen
symbol ...
AMC AMC Entertainment Holdings Inc - Class A ... False
KOSS Koss Corp. ... False
CNST Constellation Pharmaceuticals Inc ... False
BBBY Bed, Bath & Beyond Inc. ... False
PETS Petmed Express, Inc. ... False
EXPR Express Inc. ... False
UONE Urban One Inc - Class A ... False
BB BlackBerry Ltd ... False
SKLZ Skillz Inc - Class A ... False
[9 rows x 54 columns]