Tiingo Python

.. image:: https://img.shields.io/pypi/v/tiingo.svg?maxAge=600 :target: https://pypi.python.org/pypi/tiingo

.. image:: https://img.shields.io/codecov/c/github/hydrosquall/tiingo-python.svg?maxAge=600 :target: https://codecov.io/gh/hydrosquall/tiingo-python :alt: Coverage

.. image:: https://readthedocs.org/projects/tiingo-python/badge/?version=latest&maxAge=600 :target: https://tiingo-python.readthedocs.io/en/latest/?badge=latest :alt: Documentation Status

.. image:: https://pyup.io/repos/github/hydrosquall/tiingo-python/shield.svg?maxAge=600 :target: https://pyup.io/repos/github/hydrosquall/tiingo-python/ :alt: Updates

.. image:: https://mybinder.org/badge_logo.svg :target: https://mybinder.org/v2/gh/hydrosquall/tiingo-python/master?filepath=examples%2Fbasic-usage-with-pandas.ipynb :alt: Launch Binder

Tiingo is a financial data platform that makes high quality financial tools available to all. Tiingo has a REST and Real-Time Data API, which this library helps you to access. Presently, the API includes support for the following endpoints:

• Stock Market Ticker Closing Prices + Metadata. Data includes full distribution details and is validated using a proprietary EOD Price Engine.
• Curated news from top financial news sources + blogs. Stories are tagged with topic tags and relevant stock tickers by Tiingo's algorithms.

Usage

If you'd like to try this library before installing, click below to open a folder of online runnable examples.

.. image:: https://mybinder.org/badge_logo.svg :target: https://mybinder.org/v2/gh/hydrosquall/tiingo-python/master?filepath=examples :alt: Launch Binder

First, install the library from PyPi:

.. code-block:: shell

pip install tiingo

If you prefer to receive your results in

pandas DataFrame

Series

.. code-block:: shell

pip install tiingo[pandas]

Next, initialize your client. It is recommended to use an environment variable to initialize your client for convenience.

.. code-block:: python

from tiingo import TiingoClient # Set TIINGOAPIKEY in your environment variables in your .bashprofile, OR # pass a dictionary with 'apikey' as a key into the TiingoClient.

client = TiingoClient()

Alternately, you may use a dictionary to customize/authorize your client.

.. code-block:: python

config = {}

# To reuse the same HTTP Session across API calls (and have better performance), include a session key. config['session'] = True

# If you don't have your API key as an environment variable, # pass it in via a configuration dictionary. config['apikey'] = "MYSECRETAPIKEY"

# Initialize client = TiingoClient(config)

Now you can use

TiingoClient

.. code-block:: python

# Get Ticker tickermetadata = client.getticker_metadata("GOOGL")

# Get latest prices, based on 3+ sources as JSON, sampled weekly tickerprice = client.getticker_price("GOOGL", frequency="weekly")

# Get historical GOOGL prices from August 2017 as JSON, sampled daily historicalprices = client.getticker_price("GOOGL", fmt='json', startDate='2017-08-01', endDate='2017-08-31', frequency='daily')

# Check what tickers are available, as well as metadata about each ticker # including supported currency, exchange, and available start/end dates. tickers = client.liststocktickers()

# Get news articles about given tickers or search terms from given domains articles = client.get_news(tickers=['GOOGL', 'AAPL'], tags=['Laptops'], sources=['washingtonpost.com'], startDate='2017-01-01', endDate='2017-08-31')

# Get definitions for fields available in the fundamentals-api, ticker is # optional definitions = client.getfundamentalsdefinitions('GOOGL')

# Get fundamentals which require daily-updated (like marketCap). A start- # and end-date can be passed. If omited, will get all available data. fundamentalsdaily = client.getfundamentals_daily('GOOGL', startDate='2020-01-01', endDate='2020-12-31')

# Get fundamentals based on quarterly statements. Accepts time-range like # daily-fundamentals. asReported can be set to get the data exactly like # it was reported to SEC. Set to False if you want to get data containing # corrections fundamentalsstmnts = client.getfundamentals_statements('GOOGL', startDate='2020-01-01', endDate='2020-12-31', asReported=True)

To receive results in

pandas

get_dataframe()

.. code-block:: python

#Get a pd.DataFrame of the price history of a single symbol (default is daily): tickerhistory = client.getdataframe("GOOGL")

#The method returns all of the available information on a symbol, such as open, high, low, close, #adjusted close, etc. This page in the tiingo api documentation lists the available information on each #symbol: https://api.tiingo.com/docs/tiingo/daily#priceData.

#Frequencies and start and end dates can be specified similarly to the json method above.

#Get a pd.Series of only one column of the available response data by specifying one of the valid the #'metricname' parameters: tickerhistory = client.getdataframe("GOOGL", metricname='adjClose')

#Get a pd.DataFrame for a list of symbols for a specified metricname (default is adjClose if no #metricname is specified): tickerhistory = client.getdataframe(['GOOGL', 'AAPL'], frequency='weekly', metric_name='volume', startDate='2017-01-01', endDate='2018-05-31')

You can specify any of the end of day frequencies (daily, weekly, monthly, and annually) or any intraday frequency for both the

get_ticker_price

get_dataframe

Cryptocurrency

.. code-block:: python

# You can obtain cryptocurrency metadata using the following method. # NOTE: Crypto symbol MUST be encapsulated in brackets as a Python list!

client.getcryptometadata(['BTCUSD'], fmt='json')

#You can obtain top-of-book cryptocurrency quotes from the

get_crypto_top_of_book()

cryptoprice = client.getcryptotopof_book(['BTCUSD'])``

# You can obtain historical Cryptocurrency price quotes from the getcryptoprice_history() method. # NOTE: Crypto symbol MUST be encapsulated in brackets as a Python list!

client.getcryptoprice_history(tickers = ['BTCUSD'], startDate='2020-12-2', endDate='2020-12-3', resampleFreq='1Hour')

Websockets Support

.. code-block:: python

from tiingo import TiingoWebsocketClient

def cb_fn(msg):
# Example response 
# msg = {
#   "service":"iex" # An identifier telling you this is IEX data. 
#   The value returned by this will correspond to the endpoint argument.
#   
#   # Will always return "A" meaning new price quotes. There are also H type Heartbeat msgs used to keep the connection alive
#   "messageType":"A" # A value telling you what kind of data packet this is from our IEX feed.
#  
#   # see https://api.tiingo.com/documentation/websockets/iex > Response for more info
#   "data":[] # an array containing trade information and a timestamp
#   
# }

print(msg)
subscribe = {
        'eventName':'subscribe',
        'authorization':'API_KEY_GOES_HERE',
        #see https://api.tiingo.com/documentation/websockets/iex > Request for more info
        'eventData': { 
            'thresholdLevel':5
      }
}
any logic should be implemented in the callback function (cb_fn)
TiingoWebsocketClient(subscribe,endpoint="iex",on_msg_cb=cb_fn)

Further Docs

• Official Tiingo Documentation: https://api.tiingo.com

• tiingo-python

  Documentation: https://tiingo-python.readthedocs.io.

Features

• Easy programmatic access to Tiingo API
• Reuse requests session across API calls for better performance
• On most methods, pass in

  fmt="object"

  as a keyword to have your responses come back as

  NamedTuples

  , which should have a lower memory impact than regular Python dictionaries.

Roadmap:

• Client-side validation of tickers
• Data validation of returned responses
• Case insensitivity for ticker names
• More documentation / code examples

Feel free to file a PR that implements any of the above items.

Related Projects:

• Riingo_ : Client for Tiingo in the R Programming Language

.. _Riingo: https://github.com/business-science/riingo

Credits

• Many thanks to Rishi Singh for creating Tiingo.

This package was created with Cookiecutter_ and the

audreyr/cookiecutter-pypackage

.. _Cookiecutter: https://github.com/audreyr/cookiecutter .. _

audreyr/cookiecutter-pypackage