.. image:: https://travis-ci.org/addisonlynch/iexfinance.svg?branch=master :target: https://travis-ci.org/addisonlynch/iexfinance
.. image:: https://codecov.io/gh/addisonlynch/iexfinance/branch/master/graphs/badge.svg?branch=master :target: https://codecov.io/gh/addisonlynch/iexfinance
.. image:: https://badge.fury.io/py/iexfinance.svg :target: https://badge.fury.io/py/iexfinance
.. image:: https://img.shields.io/badge/License-Apache%202.0-blue.svg :target: https://opensource.org/licenses/Apache-2.0
Python SDK for IEX Cloud <https://iexcloud.io>. Architecture mirrors
that of the IEX Cloud API (and its documentation <https://iexcloud.io/docs/api/>).
An easy-to-use toolkit to obtain data for Stocks, ETFs, Mutual Funds, Forex/Currencies, Options, Commodities, Bonds, and Cryptocurrencies:
.. image:: https://raw.githubusercontent.com/addisonlynch/iexfinance/master/docs/source/images/iexexample.gif
Stable documentation is hosted on
github.io <https://addisonlynch.github.io/iexfinance/stable/>__.
Development documentation <https://addisonlynch.github.io/iexfinance/devel/>__ is also available for the latest changes in master.
From PyPI with pip (latest stable release):
$ pip3 install iexfinance
From development repository (dev version):
.. code:: bash
$ git clone https://github.com/addisonlynch/iexfinance.git
$ cd iexfinance
$ python3 setup.py installAn IEX Cloud account is required to acecss the IEX Cloud API. Various plans <https://iexcloud.io/pricing/>__
are availalbe, free, paid, and pay-as-you-go.
Your IEX Cloud (secret) authentication token can be passed to any function or at the instantiation of a Stock object.
The easiest way to store a token is in the IEX_TOKEN environment variable.
Passing as an Argument
The authentication token can also be passed to any function call:
.. code-block:: python
from iexfinance.refdata import get_symbols
get_symbols(token="<YOUR-TOKEN>")
or at the instantiation of a ``Stock`` object:
.. code-block:: python
from iexfinance.stocks import Stock
a = Stock("AAPL", token="<YOUR-TOKEN>")
a.get_quote()
How This Package is Structured
------------------------------
``iexfinance`` is designed to mirror the structure of the IEX Cloud API. The
following IEX Cloud endpoint groups are mapped to their respective
``iexfinance`` modules:
The most commonly-used
endpoints are the `Stocks <https://iexcloud.io/docs/api/#stocks>`__
endpoints, which allow access to various information regarding equities,
including quotes, historical prices, dividends, and much more.
The ``Stock`` `object <https://addisonlynch.github.io/iexfinance/stable/stocks.html#the-stock-object>`__
provides access to most endpoints, and can be instantiated with a symbol or
list of symbols:
.. code-block:: python
from iexfinance.stocks import Stock
aapl = Stock("AAPL")
aapl.get_balance_sheet()
The rest of the package is designed as a 1:1 mirror. For example, using the
`Alternative Data <https://iexcloud.io/docs/api/#alternative-data>`__ endpoint
group, obtain the `Social Sentiment <https://iexcloud.io/docs/api/#social-sentiment>`__ endpoint with
``iexfinance.altdata.get_social_sentiment``:
.. code-block:: python
from iexfinance.altdata import get_social_sentiment
get_social_sentiment("AAPL")
Common Usage Examples
---------------------
The `iex-examples <https://github.com/addisonlynch/iex-examples>`__ repository provides a number of detailed examples of iexfinance usage. Basic examples are also provided below.
Real-time QuotesTo obtain real-time quotes for one or more symbols, use the get_price
method of the Stock object:
.. code:: python
from iexfinance.stocks import Stock
tsla = Stock('TSLA')
tsla.get_price()or for multiple symbols, use a list or list-like object (Tuple, Pandas Series, etc.):
.. code:: python
batch = Stock(["TSLA", "AAPL"])
batch.get_price()Historical Data
It's possible to obtain historical data using ``get_historical_data`` and
``get_historical_intraday``.
Daily
^^^^^
To obtain daily historical price data for one or more symbols, use the
``get_historical_data`` function. This will return a daily time-series of the ticker
requested over the desired date range (``start`` and ``end`` passed as
``datetime.datetime`` objects):
.. code:: python
from datetime import datetime
from iexfinance.stocks import get_historical_data
start = datetime(2017, 1, 1)
end = datetime(2018, 1, 1)
df = get_historical_data("TSLA", start, end)
To obtain daily closing prices only (reduces message count), set
``close_only=True``:
.. code:: python
df = get_historical_data("TSLA", "20190617", close_only=True)
For Pandas DataFrame output formatting, pass ``output_format``:
.. code:: python
df = get_historical_data("TSLA", start, end, output_format='pandas')
It's really simple to plot this data, using `matplotlib <https://matplotlib.org/>`__:
.. code:: python
import matplotlib.pyplot as plt
df.plot()
plt.show()
Minutely (Intraday)
^^^^^^^^^^^^^^^^^^^
To obtain historical intraday data, use ``get_historical_intraday`` as follows.
Pass an optional ``date`` to specify a date within three months prior to the
current day (default is current date):
.. code:: python
from datetime import datetime
from iexfinance.stocks import get_historical_intraday
date = datetime(2018, 11, 27)
get_historical_intraday("AAPL", date)
or for a Pandas Dataframe indexed by each minute:
.. code:: python
get_historical_intraday("AAPL", output_format='pandas')
FundamentalsFinancial Statements ^^^^^^^^^^^^^^^^^^^^
Balance Sheet <https://addisonlynch.github.io/iexfinance/stable/stocks.html#balance-sheet>__
.. code-block:: python
from iexfinance.stocks import Stock
aapl = Stock("AAPL")
aapl.get_balance_sheet()Income Statement <https://addisonlynch.github.io/iexfinance/stable/stocks.html#income-statement>__
.. code-block:: python
aapl.get_income_statement()Cash Flow <https://addisonlynch.github.io/iexfinance/stable/stocks.html#cash-flow>__
.. code-block:: python
aapl.get_cash_flow()Modeling/Valuation Tools ^^^^^^^^^^^^^^^^^^^^^^^^
Analyst Estimates <https://addisonlynch.github.io/iexfinance/stable/stocks.html#estimates>__
.. code-block:: python
from iexfinance.stocks import Stock
aapl = Stock("AAPL")
aapl.get_estimates()Price Target <https://addisonlynch.github.io/iexfinance/stable/stocks.html#price-target>__
.. code-block:: python
aapl.get_price_target()Social Sentiment ^^^^^^^^^^^^^^^^
.. code-block:: python
from iexfinance.altdata import get_social_sentiment
get_social_sentiment("AAPL")CEO Compensation ^^^^^^^^^^^^^^^^
.. code-block:: python
from iexfinance.altdata import get_ceo_compensation
get_ceo_compensation("AAPL")Fund and Institutional Ownership ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: python
from iexfinance.stocks import Stock
aapl = Stock("AAPL")
# Fund ownership
aapl.get_fund_ownership()
# Institutional ownership
aapl.get_institutional_ownership()Reference Data
`List of Symbols IEX supports for API calls <https://addisonlynch.github.io/iexfinance/stable/refdata.html#symbols>`__
.. code-block:: python
from iexfinance.refdata import get_symbols
get_symbols()
`List of Symbols IEX supports for trading <https://addisonlynch.github.io/iexfinance/stable/refdata.html#iex-symbols>`__
.. code-block:: python
from iexfinance.refdata import get_iex_symbols
get_iex_symbols()
Account UsageMessage Count <https://addisonlynch.github.io/iexfinance/stable/account.html#usage>__
.. code-block:: python
from iexfinance.account import get_usage
get_usage(quota_type='messages')API Status
`IEX Cloud API Status <http://addisonlynch.github.io/iexfinance/stable/apistatus.html#iexfinance.tools.api.get_api_status>`__
.. code-block:: python
from iexfinance.account import get_api_status
get_api_status()
Configuration
-------------
.. _config.formatting:
Output Formatting
-----------------
By default, ``iexfinance`` returns data for most endpoints in a `pandas <https://pandas.pydata.org/>`__ ``DataFrame``.
Selecting ``json`` as the output format returns data formatted *exactly* as received from
the IEX Endpoint. Configuring ``iexfinance``'s output format can be done in two ways:
.. _config.formatting.env:
Environment Variable (Recommended)For persistent configuration of a specified output format, use the environment
variable IEX_OUTPUT_FORMAT. This value will be overridden by the
output_format argument if it is passed.
macOS/Linux ^^^^^^^^^^^
Type the following command into your terminal:
.. code-block:: bash
$ export IEX_OUTPUT_FORMAT=pandasWindows ^^^^^^^
See here <https://superuser.com/questions/949560/how-do-i-set-system-environment-variables-in-windows-10>__ for instructions on setting environment variables in Windows operating systems.
.. _config.formatting.arg:
output_format Argument
Pass ``output_format`` as an argument to any function call:
.. code-block:: python
from iexfinance.refdata import get_symbols
get_symbols(output_format='pandas').head()
or at the instantiation of a ``Stock`` object:
.. code-block:: python
from iexfinance.stocks import Stock
aapl = Stock("AAPL", output_format='pandas')
aapl.get_quote().head()
Contact
-------
Email: `ahlshop@gmail.com <ahlshop@gmail.com>`__
Twitter: `alynchfc <https://www.twitter.com/alynchfc>`__
License
-------
Copyright © 2020 Addison Lynch
See LICENSE for details