Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/addisonlynch/iexfinance

Python SDK for IEX Cloud
https://github.com/addisonlynch/iexfinance

data finance pandas stock-data stock-prices stocks-api

Last synced: 5 days ago
JSON representation

Python SDK for IEX Cloud

Awesome Lists containing this project

README 

        
iexfinance

==========



.. 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 `__. Architecture mirrors

that of the IEX Cloud API (and its `documentation `__).



An easy-to-use toolkit to obtain data for Stocks, ETFs, Mutual Funds,

Forex/Currencies, Options, Commodities, Bonds, and Cryptocurrencies:



- Real-time and delayed quotes

- Historical data (daily and minutely)

- Financial statements (Balance Sheet, Income Statement, Cash Flow)

- End of Day Options Prices

- Institutional and Fund ownership

- Analyst estimates, Price targets

- Corporate actions (Dividends, Splits)

- Sector performance

- Market analysis (gainers, losers, volume, etc.)

- IEX market data & statistics (IEX supported/listed symbols, volume, etc)

- Social Sentiment and CEO Compensation



Example

-------



.. image:: https://raw.githubusercontent.com/addisonlynch/iexfinance/master/docs/source/images/iexexample.gif



Documentation

-------------



Stable documentation is hosted on

`github.io `__.



`Development documentation `__ is also available for the latest changes in master.



Install

-------



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



What's Needed to Access IEX Cloud?

----------------------------------



An IEX Cloud account is required to acecss the IEX Cloud API. Various `plans `__

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="")



or at the instantiation of a ``Stock`` object:



.. code-block:: python



    from iexfinance.stocks import Stock



    a = Stock("AAPL", 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 `__

endpoints, which allow access to various information regarding equities,

including quotes, historical prices, dividends, and much more.



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 `__ endpoint

group, obtain the `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 `__ 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 `__:



.. 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 `__



.. code-block:: python



    from iexfinance.stocks import Stock



    aapl = Stock("AAPL")

    aapl.get_balance_sheet()



`Income Statement `__



.. code-block:: python



    aapl.get_income_statement()



`Cash Flow `__



.. code-block:: python



    aapl.get_cash_flow()



Modeling/Valuation Tools

^^^^^^^^^^^^^^^^^^^^^^^^



`Analyst Estimates `__



.. code-block:: python



    from iexfinance.stocks import Stock



    aapl = Stock("AAPL")



    aapl.get_estimates()



`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 `__



.. code-block:: python



    from iexfinance.refdata import get_symbols



    get_symbols()



`List of Symbols IEX supports for trading `__



.. code-block:: python



    from iexfinance.refdata import get_iex_symbols



    get_iex_symbols()



Account Usage

~~~~~~~~~~~~~



`Message Count `__



.. code-block:: python



    from iexfinance.account import get_usage



    get_usage(quota_type='messages')



API Status

~~~~~~~~~~



`IEX Cloud 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 `__ ``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 `__ 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: `[email protected] `__



Twitter: `alynchfc `__



License

-------



Copyright © 2020 Addison Lynch



See LICENSE for details