Implements HTTP requests for IEX DEEP API, see: https://www.iextrading.com/developer/docs/#deep

Author: rgkimball

pandas_datareader/__init__.py

@@ -1,4 +1,6 @@
 __version__ = version = '0.4.0'
 
 from .data import (get_components_yahoo, get_data_famafrench, get_data_google, get_data_yahoo, get_data_enigma,  # noqa
-        get_data_yahoo_actions, get_quote_google, get_quote_yahoo, DataReader, Options)  # noqa
+        get_data_yahoo_actions, get_quote_google, get_quote_yahoo, get_tops_iex, get_last_iex, get_markets_iex,  # noqa
+        get_data_iex, get_summary_iex, get_records_iex, get_recent_iex, get_iex_symbols, get_iex_book,  # noqa
+        DataReader, Options)  # noqa

pandas_datareader/data.py

@@ -16,6 +16,7 @@
 
 from pandas_datareader.iex.stats import DailySummaryReader as IEXHistorical
 from pandas_datareader.iex.stats import MonthlySummaryReader as IEXMonthSummary
+from pandas_datareader.iex.deep import Deep as IEXDeep
 from pandas_datareader.iex.stats import RecentReader as IEXRecents
 from pandas_datareader.iex.stats import RecordsReader as IEXRecords
 from pandas_datareader.iex.market import MarketReader as IEXMarkets
@@ -97,6 +98,10 @@ def get_iex_symbols(*args, **kwargs):
     return IEXSymbols(*args, **kwargs).read()
 
 
+def get_iex_book(*args, **kwargs):
+    return IEXDeep(*args, **kwargs).read()
+
+
 def DataReader(name, data_source=None, start=None, end=None,
                retry_count=3, pause=0.001, session=None, access_key=None):
     """
@@ -182,6 +187,11 @@ def DataReader(name, data_source=None, start=None, end=None,
                         retry_count=retry_count, pause=pause,
                         session=session).read()
 
+    elif data_source == "iex-book":
+        return IEXDeep(symbols=name, service="book", start=start, end=end,
+                       retry_count=retry_count, pause=pause,
+                       session=session).read()
+
     elif data_source == "enigma":
         return EnigmaReader(datapath=name, api_key=access_key).read()
 

pandas_datareader/iex/deep.py

@@ -0,0 +1,121 @@
+from pandas_datareader.iex import IEX
+from datetime import datetime
+
+# Data provided for free by IEX
+# Data is furnished in compliance with the guidelines promulgated in the IEX
+# API terms of service and manual
+# See https://iextrading.com/api-exhibit-a/ for additional information
+# and conditions of use
+
+
+class Deep(IEX):
+    def __init__(self, symbols=None, service=None, start=None, end=None,
+                 retry_count=3, pause=0.001, session=None):
+        super(Deep, self).__init__(symbols=symbols,
+                                   start=start, end=end,
+                                   retry_count=retry_count,
+                                   pause=pause, session=session)
+        self.sub = service
+
+    @property
+    def service(self):
+        ss = "/" + self.sub if self.sub is not None else ""
+        return "deep{}".format(ss)
+
+    def _read_lines(self, out):
+        """
+        IEX depth of book data varies and shouldn't always be returned in a DF
+
+        :param out: Raw HTTP Output
+        :return: DataFrame
+        """
+
+        # Runs appropriate output functions per the service being accessed.
+        fmap = {
+            'book': '_pass',
+            'op-halt-status': '_convert_tstamp',
+            'security-event': '_convert_tstamp',
+            'ssr-status': '_convert_tstamp',
+            'system-event': '_read_system_event',
+            'trades': '_pass',
+            'trade-breaks': '_convert_tstamp',
+            'trading-status': '_read_trading_status',
+            None: '_pass',
+        }
+
+        if self.sub in fmap:
+            return getattr(self, fmap[self.sub])(out)
+        else:
+            raise "Invalid service specified: {}.".format(self.sub)
+
+    def _read_system_event(self, out):
+        # Map the response code to a string output per the API docs.
+        # Per: https://www.iextrading.com/developer/docs/#system-event-message
+        smap = {
+            'O': 'Start of messages',
+            'S': 'Start of system hours',
+            'R': 'Start of regular market hours',
+            'M': 'End of regular market hours',
+            'E': 'End of system hours',
+            'C': 'End of messages'
+        }
+        tid = out["systemEvent"]
+        out["eventResponse"] = smap[tid]
+
+        return self._convert_tstamp(out)
+
+    @staticmethod
+    def _pass(out):
+        return out
+
+    def _read_trading_status(self, out):
+        # Reference: https://www.iextrading.com/developer/docs/#trading-status
+        smap = {
+            'H': 'Trading halted across all US equity markets',
+            'O': 'Trading halt released into an Order Acceptance Period '
+                 '(IEX-listed securities only)',
+            'P': 'Trading paused and Order Acceptance Period on IEX '
+                 '(IEX-listed securities only)',
+            'T': 'Trading on IEX'
+        }
+        rmap = {
+            # Trading Halt Reasons
+            'T1': 'Halt News Pending',
+            'IPO1': 'IPO/New Issue Not Yet Trading',
+            'IPOD': 'IPO/New Issue Deferred',
+            'MCB3': 'Market-Wide Circuit Breaker Level 3 - Breached',
+            'NA': 'Reason Not Available',
+
+            # Order Acceptance Period Reasons
+            'T2': 'Halt News Dissemination',
+            'IPO2': 'IPO/New Issue Order Acceptance Period',
+            'IPO3': 'IPO Pre-Launch Period',
+            'MCB1': 'Market-Wide Circuit Breaker Level 1 - Breached',
+            'MCB2': 'Market-Wide Circuit Breaker Level 2 - Breached'
+        }
+        for ticker, data in out.items():
+            if data['status'] in smap:
+                data['statusText'] = smap[data['status']]
+
+            if data['reason'] in rmap:
+                data['reasonText'] = rmap[data['reason']]
+
+            out[ticker] = data
+
+        return self._convert_tstamp(out)
+
+    @staticmethod
+    def _convert_tstamp(out):
+        # Searches for top-level timestamp attributes or within dictionaries
+        if 'timestamp' in out:
+            # Convert UNIX to datetime object
+            f = float(out["timestamp"])
+            out["timestamp"] = datetime.fromtimestamp(f/1000)
+        else:
+            for ticker, data in out.items():
+                if 'timestamp' in data:
+                    f = float(data["timestamp"])
+                    data["timestamp"] = datetime.fromtimestamp(f/1000)
+                    out[ticker] = data
+
+        return out

pandas_datareader/tests/test_iex.py

@@ -39,3 +39,9 @@ def test_live_prices(self):
         tickers = dftickers[:5].symbol.values
         df = get_last_iex(tickers[:5])
         assert df["price"].mean() > 0
+
+    def test_deep(self):
+        dob = DataReader('GS', 'iex-book')
+        assert 'GS' in dob
+        assert 'asks' in dob['GS']
+        assert dob['GS']['bids'][0]['price'] > 0