added backoff strategy to handle throttle errors

added CUSIP/CIK/Ticker Mapping API support

Author: janlukasschroeder

README.md

@@ -425,6 +425,82 @@ print(filing)
 > See the documentation for more details: https://sec-api.io/docs/sec-filings-render-api
 
 
+# CUSIP/CIK/Ticker Mapping API
+
+Resolve a CUSIP, CIK, ticker symbol or company name to a set of standardized company details. Listing companies by exchange, sector and industry is also supported.
+
+Map any of the following parameters to company details:
+- CUSIP
+- CIK
+- Ticker
+- Company name
+- Exchange
+- Sector
+- Industry
+
+The function returns an array of all matching companies in JSON format. For example, a look up of the ticker `IBM` returns multiple matches including `IBMD` and `IBME`.
+
+A company object includes the following properties:
+
+- `name` (string) - the name of the company, e.g. Tesla Inc
+- `ticker` (string) - the ticker symbol of the company.
+- `cik` (string) - the CIK of the company. Trailing zeros are removed.
+- `cusip` (string) - one or multiple CUSIPs linked to the company. Multiple CUSIPs are delimited by space, e.g. "054748108 92931L302 92931L401"
+- `exchange` (string) - the main exchange the company is listed on, e.g. NASDAQ
+- `isDelisted` (boolean) - true if the company is no longer listed, false otherwise.
+- `category` (string) - the security category, e.g. "Domestic Common Stock"
+- `sector` (string) - the sector of the company, e.g. "Consumer Cyclical"
+- `industry` (string) - the industry of the company, e.g. "Auto Manufacturers"
+- `sic` (string) - four-digit SIC code, e.g. "3711"
+- `sicSector` (string) - SIC sector name of the company, e.g. "Manufacturing"
+- `sicIndustry` (string) - SIC industry name of the company, e.g. "Motor Vehicles & Passenger Car Bodies"
+- `currency` (string) - operating currency of the company, e.g. "USD"
+- `location` (string) - location of the company's headquarters
+- `id` (string) - unique internal ID of the company, e.g. "e27d6e9606f216c569e46abf407685f3"
+
+Response type: `JSON`
+
+## Usage
+
+```python
+from sec_api import MappingApi
+
+mappingApi = MappingApi(api_key="YOUR_API_KEY")
+
+result1 = mappingApi.resolve("ticker", "TSLA")
+result2 = mappingApi.resolve("cik", "1318605")
+result3 = mappingApi.resolve("cusip", "88160R101")
+result4 = mappingApi.resolve("exchange", "NASDAQ")
+```
+
+### Response Example
+```json
+[
+    {
+        "name": "Tesla Inc",
+        "ticker": "TSLA",
+        "cik": "1318605",
+        "cusip": "88160R101",
+        "exchange": "NASDAQ",
+        "isDelisted": false,
+        "category": "Domestic Common Stock",
+        "sector": "Consumer Cyclical",
+        "industry": "Auto Manufacturers",
+        "sic": "3711",
+        "sicSector": "Manufacturing",
+        "sicIndustry": "Motor Vehicles & Passenger Car Bodies",
+        "famaSector": "",
+        "famaIndustry": "Automobiles and Trucks",
+        "currency": "USD",
+        "location": "California; U.S.A",
+        "id": "e27d6e9606f216c569e46abf407685f3"
+    }
+]
+```
+
+> See the documentation for more details: https://sec-api.io/docs/mapping-api
+
+
 # Query API Response Format
 
 - `accessionNo` (string) - Accession number of filing, e.g. 0000028917-20-000033

examples.py

@@ -1,4 +1,4 @@
-from sec_api.index import RenderApi, XbrlApi, ExtractorApi
+from sec_api.index import RenderApi, XbrlApi, ExtractorApi, MappingApi
 
 #
 # Render API
@@ -12,23 +12,22 @@
 )
 
 print(filing_data)
-"""
+# """
 
 #
 # XBRL-to-JSON API example
 #
 """
 xbrlApi = XbrlApi("YOUR_API_KEY")
 
-
 # 10-K HTM File URL example
 xbrl_json_1 = xbrlApi.xbrl_to_json(
     htm_url="https://www.sec.gov/Archives/edgar/data/320193/000032019320000096/aapl-20200926.htm"
 )
 
-print(xbrl_json_1["StatementsOfIncome"])
-print(xbrl_json_1["BalanceSheets"])
-print(xbrl_json_1["StatementsOfCashFlows"])
+# print(xbrl_json_1["StatementsOfIncome"])
+# print(xbrl_json_1["BalanceSheets"])
+# print(xbrl_json_1["StatementsOfCashFlows"])
 
 # 10-K XBRL File URL example
 xbrl_json_2 = xbrlApi.xbrl_to_json(
@@ -38,7 +37,7 @@
 # 10-K XBRL File URL example
 xbrl_json_3 = xbrlApi.xbrl_to_json(accession_no="0001564590-21-004599")
 
-"""
+# """
 
 #
 # Extractor API Example
@@ -54,4 +53,16 @@
 
 print(section_text)
 print(section_html)
+# """
+
+
+#
+# Mapping API Example
+#
 """
+mappingApi = MappingApi("YOUR_API_KEY")
+
+result = mappingApi.resolve("cik", "927355")
+
+print(result)
+# """

sec_api/__init__.py

@@ -4,3 +4,4 @@
 from sec_api.index import RenderApi
 from sec_api.index import XbrlApi
 from sec_api.index import ExtractorApi
+from sec_api.index import MappingApi

sec_api/index.py

@@ -1,12 +1,14 @@
 import requests
 import json
 import re
+import time
 
 query_api_endpoint = "https://api.sec-api.io"
 full_text_search_api_endpoint = "https://api.sec-api.io/full-text-search"
 render_api_endpoint = "https://archive.sec-api.io"
 xbrl_api_endpoint = "https://api.sec-api.io/xbrl-to-json"
 extractor_api_endpoint = "https://api.sec-api.io/extractor"
+mapping_api_endpoint = "https://api.sec-api.io/mapping"
 
 
 class QueryApi:
@@ -19,8 +21,19 @@ def __init__(self, api_key):
         self.api_endpoint = query_api_endpoint + "?token=" + api_key
 
     def get_filings(self, query):
-        response = requests.post(self.api_endpoint, json=query)
-        return response.json()
+        # use backoff strategy to handle "too many requests" error.
+        for x in range(3):
+            response = requests.post(self.api_endpoint, json=query)
+            if response.status_code == 200:
+                return response.json()
+            elif response.status_code == 429:
+                # wait 500 * (x + 1) milliseconds and try again
+                time.sleep(0.5 * (x + 1))
+            else:
+                raise Exception("API error: " + response.status_code)
+        else:
+            # request failed
+            raise Exception("API error")
 
 
 class FullTextSearchApi:
@@ -33,8 +46,19 @@ def __init__(self, api_key):
         self.api_endpoint = full_text_search_api_endpoint + "?token=" + api_key
 
     def get_filings(self, query):
-        response = requests.post(self.api_endpoint, json=query)
-        return response.json()
+        # use backoff strategy to handle "too many requests" error.
+        for x in range(3):
+            response = requests.post(self.api_endpoint, json=query)
+            if response.status_code == 200:
+                return response.json()
+            elif response.status_code == 429:
+                # wait 500 * (x + 1) milliseconds and try again
+                time.sleep(0.5 * (x + 1))
+            else:
+                raise Exception("API error: " + response.status_code)
+        else:
+            # request failed
+            raise Exception("API error")
 
 
 class RenderApi:
@@ -49,8 +73,20 @@ def __init__(self, api_key):
     def get_filing(self, url):
         filename = re.sub(r"https://www.sec.gov/Archives/edgar/data", "", url)
         _url = self.api_endpoint + filename + "?token=" + self.api_key
-        response = requests.get(_url)
-        return response.text
+
+        # use backoff strategy to handle "too many requests" error.
+        for x in range(3):
+            response = requests.get(_url)
+            if response.status_code == 200:
+                return response.text
+            elif response.status_code == 429:
+                # wait 500 * (x + 1) milliseconds and try again
+                time.sleep(0.5 * (x + 1))
+            else:
+                raise Exception("API error: " + response.status_code)
+        else:
+            # request failed
+            raise Exception("API error")
 
 
 class XbrlApi:
@@ -77,8 +113,20 @@ def xbrl_to_json(self, htm_url="", xbrl_url="", accession_no=""):
         if len(accession_no):
             _url = self.api_endpoint + "&accession-no=" + accession_no
 
-        response = requests.get(_url)
-        return json.loads(response.text)
+        # use backoff strategy to handle "too many requests" error.
+        for x in range(3):
+            response = requests.get(_url)
+            if response.status_code == 200:
+                data = json.loads(response.text)
+                return data
+            elif response.status_code == 429:
+                # wait 500 * (x + 1) milliseconds and try again
+                time.sleep(0.5 * (x + 1))
+            else:
+                raise Exception("API error: " + response.status_code)
+        else:
+            # request failed
+            raise Exception("API error")
 
 
 class ExtractorApi:
@@ -104,5 +152,66 @@ def get_section(self, filing_url="", section="1A", return_type="text"):
             + return_type
         )
 
-        response = requests.get(_url)
-        return response.text
+        # use backoff strategy to handle "too many requests" error.
+        for x in range(3):
+            response = requests.get(_url)
+            if response.status_code == 200:
+                return response.text
+            elif response.status_code == 429:
+                # wait 500 * (x + 1) milliseconds and try again
+                time.sleep(0.5 * (x + 1))
+            else:
+                raise Exception("API error: " + response.status_code)
+        else:
+            # request failed
+            raise Exception("API error")
+
+
+class MappingApi:
+    """
+    Base class for CUSIP/CIK/Ticker Mapping API
+    Documentation: https://sec-api.io/docs/mapping-api
+
+    cik, ticker, cusip, name, exchange, sector, industry
+    """
+
+    def __init__(self, api_key):
+        self.api_key = api_key
+        self.api_endpoint = mapping_api_endpoint
+        self.supported_parameters = [
+            "cik",
+            "ticker",
+            "cusip",
+            "name",
+            "exchange",
+            "sector",
+            "industry",
+        ]
+
+    def resolve(self, parameter="", value=""):
+        if not parameter.lower() in self.supported_parameters:
+            raise ValueError("Parameter not supported")
+
+        _url = (
+            self.api_endpoint
+            + "/"
+            + parameter.lower()
+            + "/"
+            + value
+            + "?token="
+            + self.api_key
+        )
+
+        # use backoff strategy to handle "too many requests" error.
+        for x in range(3):
+            response = requests.get(_url)
+            if response.status_code == 200:
+                return response.json()
+            elif response.status_code == 429:
+                # wait 500 * (x + 1) milliseconds and try again
+                time.sleep(0.5 * (x + 1))
+            else:
+                raise Exception("API error: " + response.status_code)
+        else:
+            # request failed
+            raise Exception("API error")

setup.py

@@ -5,7 +5,7 @@
 
 setup(
     name="sec-api",
-    version="1.0.8",
+    version="1.0.9",
     author="SEC API",
     author_email="[email protected]",
     description="SEC EDGAR Filings API",