.. 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 install
An 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 Quotes
~~~~~~~~~~~~~~~~
To 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')
Fundamentals
~~~~~~~~~~~~
Financial 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 Usage
~~~~~~~~~~~~~
`Message 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=pandas
Windows ^^^^^^^
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
FAQs
Python module to get stock data from IEX Cloud and IEX API 1.0
We found that iexfinance demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Company News
Socket is joining TC54 to help develop standards for software supply chain security, contributing to the evolution of SBOMs, CycloneDX, and Package URL specifications.
Security News
PyPI now allows maintainers to archive projects, improving security and helping users make informed decisions about their dependencies.
Research
Security News
Malicious npm package postcss-optimizer delivers BeaverTail malware, targeting developer systems; similarities to past campaigns suggest a North Korean connection.