{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "# Tiingo-Python\n", "\n", "\n", "This notebook shows basic usage of the `tiingo-python` library. If you're running this on `mybinder.org`, you can run this code without installing anything on your computer. You can find more information about what available at the [Tiingo website](https://api.tiingo.com/docs/general/overview), but this notebook will let you play around with real code samples in your browser.\n", "\n", "If you've never used `jupyter` before, I recommend this [tutorial](https://www.datacamp.com/community/tutorials/tutorial-jupyter-notebook) from Datacamp." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Basic Setup\n", "\n", "First, you'll need to provide your API key as a string in the cell below. If you forget to do this, the notebook cannot run. You can find your API key by visiting [this link](https://www.tiingo.com/account/api/token) and logging in to your Tiingo account." ] }, { "cell_type": "code", "execution_count": 1, "metadata": {}, "outputs": [], "source": [ "TIINGO_API_KEY = 'REPLACE-THIS-TEXT-WITH-A-REAL-API-KEY'\n", "\n", "# This is here to remind you to change your API key.\n", "if not TIINGO_API_KEY or (TIINGO_API_KEY == 'REPLACE-THIS-TEXT-WITH-A-REAL-API-KEY'):\n", " raise Exception(\"Please provide a valid Tiingo API key!\")" ] }, { "cell_type": "code", "execution_count": 2, "metadata": {}, "outputs": [], "source": [ "from tiingo import TiingoClient\n", "\n", "config = {\n", " 'api_key': TIINGO_API_KEY,\n", " 'session': True # Reuse HTTP sessions across API calls for better performance\n", "}\n", "\n", "# Throughout the rest of this notebook, you'll use the \"client\" to interact with the Tiingo backend services.\n", "client = TiingoClient(config)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Minimal Data Fetching Examples\n", "\n", "Below are the code samples from the `README.rst` along with sample outputs, but this is just the tip of the iceberg of this library's capabilities. " ] }, { "cell_type": "code", "execution_count": 3, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "{'exchangeCode': 'NASDAQ', 'endDate': '2019-01-30', 'startDate': '2004-08-19', 'ticker': 'GOOGL', 'description': \"Google Inc. (Google) is a global technology company. The Company's business is primarily focused around key areas, such as search, advertising, operating systems and platforms, enterprise and hardware products. The Company generates revenue primarily by delivering online advertising. The Company also generates revenues from Motorola by selling hardware products. The Company provides its products and services in more than 100 languages and in more than 50 countries, regions, and territories. Effective May 16, 2014, Google Inc acquired Quest Visual Inc. Effective May 20, 2014, Google Inc acquired Enterproid Inc, doing business as Divide. In June 2014, Google Inc acquired mDialog Corp. Effective June 25, 2014, Google Inc acquired Appurify Inc, a San Francisco-based developer of mobile bugging application software.\", 'name': 'Alphabet Inc.(\"Google\") - Class A'}\n" ] } ], "source": [ "# Get Ticker Metadata for the stock \"GOOGL\"\n", "ticker_metadata = client.get_ticker_metadata(\"GOOGL\")\n", "print(ticker_metadata)" ] }, { "cell_type": "code", "execution_count": 4, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "[{'adjClose': 1097.99, 'adjHigh': 1099.52, 'adjLow': 1076.64, 'adjOpen': 1077.36, 'adjVolume': 1450619, 'close': 1097.99, 'date': '2019-01-30T00:00:00+00:00', 'divCash': 0.0, 'high': 1099.52, 'low': 1076.64, 'open': 1077.36, 'splitFactor': 1.0, 'volume': 1450619}]\n" ] } ], "source": [ "# Get latest prices, based on 3+ sources as JSON, sampled weekly\n", "ticker_price = client.get_ticker_price(\"GOOGL\", frequency=\"weekly\")\n", "print(ticker_price)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "For values of `frequency`:\n", "\n", "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`` and ``get_dataframe`` methods. Weekly frequencies resample to the end of day on Friday, monthly frequencies resample to the last day of the month, and annually frequencies resample to the end of day on 12-31 of each year. The intraday frequencies are specified using an integer followed by `Min` or `Hour`, for example `30Min` or `1Hour`." ] }, { "cell_type": "code", "execution_count": 5, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "[{'date': '2017-08-01T00:00:00.000Z', 'close': 946.56, 'high': 954.49, 'low': 944.96, 'open': 947.81, 'volume': 1205799, 'adjClose': 946.56, 'adjHigh': 954.49, 'adjLow': 944.96, 'adjOpen': 947.81, 'adjVolume': 1205799, 'divCash': 0.0, 'splitFactor': 1.0}, {'date': '2017-08-02T00:00:00.000Z', 'close': 947.64, 'high': 949.1, 'low': 932.521, 'open': 948.37, 'volume': 2019979, 'adjClose': 947.64, 'adjHigh': 949.1, 'adjLow': 932.521, 'adjOpen': 948.37, 'adjVolume': 2019979, 'divCash': 0.0, 'splitFactor': 1.0}]\n" ] } ], "source": [ "# Get historical GOOGL prices from August 2017 as JSON, sampled daily\n", "historical_prices = client.get_ticker_price(\"GOOGL\",\n", " fmt='json',\n", " startDate='2017-08-01',\n", " endDate='2017-08-31',\n", " frequency='daily')\n", "\n", "# Print the first 2 days of data, but you will find more days of data in the overall historical_prices variable.\n", "print(historical_prices[:2])" ] }, { "cell_type": "code", "execution_count": 6, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "[OrderedDict([('ticker', '000001'), ('exchange', 'SHE'), ('assetType', 'Stock'), ('priceCurrency', 'CNY'), ('startDate', '2007-08-30'), ('endDate', '2019-01-29')]), OrderedDict([('ticker', '000002'), ('exchange', 'SHE'), ('assetType', 'Stock'), ('priceCurrency', 'CNY'), ('startDate', '2000-01-04'), ('endDate', '2019-01-29')])]\n" ] } ], "source": [ "# See what tickers are available\n", "# Check what tickers are available, as well as metadata about each ticker\n", "# including supported currency, exchange, and available start/end dates.\n", "tickers = client.list_stock_tickers()\n", "\n", "print(tickers[:2])" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "For each ticker, you may access\n", "\n", "- `ticker`: The ticker's abbreviation\n", "- `exchange`: Which exchange it's traded on\n", "- `priceCurrency`: Currency for the prices listed for this ticker\n", "- `startDate`/ `endDate`: Start / End Date for Tiingo's data about this ticker\n", "\n", "Note that Tiingo is constantly adding new data sources, so the values returned from this call will probably change every day." ] }, { "cell_type": "code", "execution_count": 7, "metadata": {}, "outputs": [], "source": [ "# Search news articles about particular tickers\n", "# This method will not work error if you do not have a paid Tiingo account associated with your API key.\n", "articles = client.get_news(tickers=['GOOGL', 'AAPL'],\n", " tags=['Laptops'],\n", " sources=['washingtonpost.com'],\n", " startDate='2017-01-01',\n", " endDate='2017-08-31')" ] }, { "cell_type": "code", "execution_count": 8, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "{'publishedDate': '2018-10-30T19:33:13Z',\n", " 'crawlDate': '2018-10-30T19:49:31.438654Z',\n", " 'title': 'It’s not clear which MacBook laptop to buy anymore',\n", " 'url': 'https://qz.com/1444562/which-macbook-should-you-get-any-of-them/',\n", " 'description': 'Which new Apple MacBook should you get? Maybe an iPad.',\n", " 'id': 13583735,\n", " 'tags': ['Apple',\n", " 'Apple October Event',\n", " 'Edited By Matt Quinn',\n", " 'Gadgets',\n", " 'Information Technology',\n", " 'Laptops',\n", " 'Macbook',\n", " 'Macbook Air',\n", " 'Macbook Pro',\n", " 'Stock',\n", " 'Technology'],\n", " 'tickers': ['aapl'],\n", " 'source': 'qz.com'}" ] }, "execution_count": 8, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# Display a sample article\n", "articles[0]" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Basic Pandas Dataframe Examples\n", "\n", "Pandas is a popular python library for data analysis an manipulation. We provide out-of-the-box support for returning responses from Tiingo as Python Dataframes. If you are unfamiliar with `pandas`, I recommend the `Mode Notebooks` [python data analysis tutorial](https://mode.com/python-tutorial/)." ] }, { "cell_type": "code", "execution_count": 9, "metadata": {}, "outputs": [], "source": [ "# Boilerplate to make pandas charts render inline in jupyter\n", "import matplotlib.pyplot as plt\n", "%matplotlib inline " ] }, { "cell_type": "code", "execution_count": 10, "metadata": {}, "outputs": [], "source": [ "# Scan some historical Google data\n", "ticker_history_df = client.get_dataframe(\"GOOGL\",\n", " startDate='2018-05-15',\n", " endDate='2018-05-31',\n", " frequency='daily')" ] }, { "cell_type": "code", "execution_count": 11, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "Index(['adjClose', 'adjHigh', 'adjLow', 'adjOpen', 'adjVolume', 'close',\n", " 'divCash', 'high', 'low', 'open', 'splitFactor', 'volume'],\n", " dtype='object')" ] }, "execution_count": 11, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# Check which columns you'd like to work with\n", "ticker_history_df.columns" ] }, { "cell_type": "code", "execution_count": 12, "metadata": {}, "outputs": [ { "data": { "text/html": [ "
| \n", " | adjClose | \n", "adjHigh | \n", "adjLow | \n", "adjOpen | \n", "adjVolume | \n", "close | \n", "divCash | \n", "high | \n", "low | \n", "open | \n", "splitFactor | \n", "volume | \n", "
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| date | \n", "\n", " | \n", " | \n", " | \n", " | \n", " | \n", " | \n", " | \n", " | \n", " | \n", " | \n", " | \n", " |
| 2018-05-15 00:00:00+00:00 | \n", "1084.87 | \n", "1099.12 | \n", "1078.78 | \n", "1096.90 | \n", "1786926 | \n", "1084.87 | \n", "0.0 | \n", "1099.12 | \n", "1078.78 | \n", "1096.90 | \n", "1.0 | \n", "1786926 | \n", "
| 2018-05-16 00:00:00+00:00 | \n", "1084.09 | \n", "1094.38 | \n", "1081.63 | \n", "1085.09 | \n", "1281406 | \n", "1084.09 | \n", "0.0 | \n", "1094.38 | \n", "1081.63 | \n", "1085.09 | \n", "1.0 | \n", "1281406 | \n", "
| 2018-05-17 00:00:00+00:00 | \n", "1081.26 | \n", "1091.00 | \n", "1076.42 | \n", "1081.46 | \n", "1286907 | \n", "1081.26 | \n", "0.0 | \n", "1091.00 | \n", "1076.42 | \n", "1081.46 | \n", "1.0 | \n", "1286907 | \n", "
| 2018-05-18 00:00:00+00:00 | \n", "1069.64 | \n", "1073.73 | \n", "1064.68 | \n", "1066.00 | \n", "1774149 | \n", "1069.64 | \n", "0.0 | \n", "1073.73 | \n", "1064.68 | \n", "1066.00 | \n", "1.0 | \n", "1774149 | \n", "
| 2018-05-21 00:00:00+00:00 | \n", "1084.01 | \n", "1093.30 | \n", "1078.00 | \n", "1079.00 | \n", "1258999 | \n", "1084.01 | \n", "0.0 | \n", "1093.30 | \n", "1078.00 | \n", "1079.00 | \n", "1.0 | \n", "1258999 | \n", "