ENH: Support reference data international symbols endpoints (#221)

* Support reference data international symbols endpoints

https://iexcloud.io/docs/api/#international-symbols

* Updates

* Fix docs typo

Co-authored-by: Addison Lynch <ahlshop@gmail.com>

docs/source/data-apis.rst

@@ -4,7 +4,7 @@ Data APIs
 =========
 
 IEX Cloud data can be organized into three generic data APIs:
-:ref:`time-series<data_apis.time-series>`, data-tables, and data-points. Each API type is self describing and the docs can be accessed without an API token.
+:ref:`time-series<data-apis.time-series>`, data-tables, and data-points. Each API type is self describing and the docs can be accessed without an API token.
 
 
 .. _data-apis.data-points:

docs/source/refdata.rst

@@ -9,48 +9,74 @@ Reference Data
     :depth: 2
 
 
-.. _refdata.symbols:
-
-Symbols
--------
+.. _refdata.iex_symbols:
 
-.. autofunction:: iexfinance.refdata.get_symbols
+IEX Symbols
+-----------
 
+.. autofunction:: iexfinance.refdata.get_iex_symbols
 
-.. _refdata.symbols_usage:
+.. _refdata.iex_symbols_usage:
 
 Usage
 ~~~~~
 
-.. ipython:: python
+.. code-block:: python
 
-    from iexfinance.refdata import get_symbols
+    from iexfinance.refdata import get_iex_symbols
 
-    get_symbols()[:2]
+    get_iex_symbols()[:2]
 
 
-.. _refdata.iex_symbols:
+.. _refdata.international-symbols:
 
-IEX Symbols
------------
+International Symbols
+---------------------
 
-.. autofunction:: iexfinance.refdata.get_iex_symbols
+.. _refdata.international-symbols.exchange:
 
-.. _refdata.iex_symbols_usage:
+
+By Exchange
+~~~~~~~~~~~
+
+
+.. autofunction:: iexfinance.refdata.get_exchange_symbols
+
+
+.. _refdata.international-symbols.region:
+
+By Region
+~~~~~~~~~
+
+
+.. autofunction:: iexfinance.refdata.get_region_symbols
+
+
+
+.. _refdata.symbols:
+
+Symbols
+-------
+
+.. autofunction:: iexfinance.refdata.get_symbols
+
+
+.. _refdata.symbols_usage:
 
 Usage
 ~~~~~
 
-.. code-block:: python
+.. ipython:: python
 
-    from iexfinance.refdata import get_iex_symbols
+    from iexfinance.refdata import get_symbols
+
+    get_symbols()[:2]
 
-    get_iex_symbols()[:2]
 
 
 .. _refdata.holidays:
 
 U.S. Holidays & Trading Dates
 -----------------------------
 
-.. autofunction:: iexfinance.refdata.get_us_trading_dates_holidays
+.. autofunction:: iexfinance.refdata.get_us_trading_dates_holidays

docs/source/whatsnew/v0.5.0.txt

@@ -29,8 +29,8 @@ Enhancements
 - Adds endpoint for us trading days/holidays (thanks Bouldersky)
 - Adds official support for Python 3.8
 - Adds endpoint for advanced stats
-- Add ``last`` and ``period`` parameters to ``Stock.get_estimates`` :issue:`213`
-- Test github issue :issue:`818`
+- Adds ``last`` and ``period`` parameters to ``Stock.get_estimates`` :issue:`213`
+- Adds endpoints for international symbol reference data (thanks :user:`anthonyvd`)
 
 .. _GH94: https://github.com/addisonlynch/iexfinance/issues/94
 .. _GH213: https://github.com/addisonlynch/iexfinance/issues/213
@@ -53,10 +53,10 @@ Backward Incompatible Changes
 - Ends support for Python 2 and Python 3.4
 - All legacy IEX Developer API version 1.0 endpoints and references to such endpoints
   have been removed
-- ``Stock.get_endpoints``, ``Stock.get_short_interest``, 
+- ``Stock.get_endpoints``, ``Stock.get_short_interest``,
   ``Stock.get_short_ratio``, ``Stock.get_latest_eps``, ``Stock.get_eps_consensus``,
   and ``Stock.get_relevant_stocks`` have been immediately deprecated
 - ``get_social_sentiment`` is now premium-only data and not tested by ``iexfinance``
 - All endpoints in ``iexdata`` are now JSON-only (pandas output formatting no
   is longer supported)
-- ``iexfinance.stocks.get_market_in_focus`` has been immediately deprecated.
+- ``iexfinance.stocks.get_market_in_focus`` has been immediately deprecated.

iexfinance/refdata/__init__.py

@@ -1,4 +1,10 @@
-from iexfinance.refdata.base import Symbols, IEXSymbols, TradingDatesReader
+from iexfinance.refdata.base import (
+    Symbols,
+    IEXSymbols,
+    TradingDatesReader,
+    IntlRegionSymbols,
+    IntlExchangeSymbols,
+)
 
 
 def get_symbols(**kwargs):
@@ -24,6 +30,42 @@ def get_iex_symbols(**kwargs):
     return IEXSymbols(**kwargs).fetch()
 
 
+def get_region_symbols(region, **kwargs):
+    """
+    Returns array of all international symbols in a give
+    region that IEX Cloud supports for API calls
+
+    https://iexcloud.io/docs/api/#international-symbols
+
+    Data Weighting: ``100`` per call
+
+    Parameters
+    ----------
+    region: str
+        2 letter case insensitive string of country codes
+        using ISO 3166-1 alpha-2
+    """
+    return IntlRegionSymbols(region, **kwargs).fetch()
+
+
+def get_exchange_symbols(exchange, **kwargs):
+    """
+    Returns array of all international symbols in a given
+    exchange that IEX Cloud supports for API calls
+
+    https://iexcloud.io/docs/api/#international-symbols
+
+    Data Weighting: ``100`` per call
+
+    Parameters
+    ----------
+    exchange: str
+        Case insensitive string of Exchange using IEX
+        Supported Exchanges list
+    """
+    return IntlExchangeSymbols(exchange, **kwargs).fetch()
+
+
 def get_us_trading_dates_holidays(type_, direction, last=1, startDate=None, **kwargs):
     """
     Function to obtain US trading dates or holidays from

iexfinance/refdata/base.py

@@ -55,3 +55,23 @@ class IEXSymbols(ReferenceData):
     @property
     def endpoint(self):
         return "iex/symbols"
+
+
+class IntlRegionSymbols(ReferenceData):
+    def __init__(self, region, **kwargs):
+        self.region = region
+        super(IntlRegionSymbols, self).__init__(**kwargs)
+
+    @property
+    def endpoint(self):
+        return "region/%s/symbols" % self.region
+
+
+class IntlExchangeSymbols(ReferenceData):
+    def __init__(self, exchange, **kwargs):
+        self.exchange = exchange
+        super(IntlExchangeSymbols, self).__init__(**kwargs)
+
+    @property
+    def endpoint(self):
+        return "exchange/%s/symbols" % self.exchange

iexfinance/tests/test_refdata.py

@@ -6,6 +6,8 @@
     get_symbols,
     get_iex_symbols,
     get_us_trading_dates_holidays,
+    get_region_symbols,
+    get_exchange_symbols,
 )
 
 
@@ -29,6 +31,14 @@ def test_get_iex_symbols(self):
 
         assert isinstance(d, pd.DataFrame)
 
+    def test_get_region_symbols(self):
+        d = get_region_symbols("ca")
+        assert isinstance(d, pd.DataFrame)
+
+    def test_get_exchange_symbols(self):
+        d = get_exchange_symbols("tse")
+        assert isinstance(d, pd.DataFrame)
+
     def test_get_us_trading_dates_holidays(self):
         assert isinstance(get_us_trading_dates_holidays("trade", "last"), pd.DataFrame)
         assert isinstance(