added Insider Trading Data API

mailynfz · Aug 19, 2022 · 5745792 · 5745792
1 parent 30ce5a9
commit 5745792
Show file tree

Hide file tree

Showing 6 changed files with 146 additions and 10 deletions.
diff --git a/.gitignore b/.gitignore
@@ -1,9 +1,9 @@
+venv
 env
 dist
 build
 .idea
 .pypirc
 sec_api.egg-info
-sec_api.egg-info
 deploy.sh
 sec_api/__pycache__
diff --git a/README.md b/README.md
@@ -3,12 +3,15 @@
 **sec-api** is a Python package for querying the entire SEC filings corpus in real-time without the need to download filings. 
 It includes:
 
-- Query and Full-Text Search API
-- Real-Time Stream API
-- XBRL-to-JSON Converter API + Financial Statements
-- 10-K/10-Q/8-K Section Extraction API
-- Filing Render & Download API
-- Executive Compensation Data API
+- [Query and Full-Text Search API](#sec-edgar-filings-query-api)
+- [Real-Time Stream API](#sec-edgar-filings-real-time-stream-api)
+- [XBRL-to-JSON Converter API + Financial Statements](#xbrl-to-json-converter-api)
+- [10-K/10-Q/8-K Section Extraction API](#10-k-10-q-8-k-section-extractor-api)
+- [Filing Download & PDF Render API](#filing-render-download-api)
+- [Executive Compensation Data API](#executive-compensation-data-api) 
+- [Insider Trading Data API](#insider-trading-data-api)
+- [13F Institutional Investor Database](#13f-institutional-investor-database)
+- [CUSIP/CIK/Ticker Mapping API](#cusip-cik-ticker-mapping-api) 
 
 
 # Data Coverage
@@ -86,6 +89,7 @@ query = {
 filings = queryApi.get_filings(query)
 ```
 
+## 13F Institutional Investor Database
 Fetch most recent 13F filings that hold Tesla
 
 ```python
@@ -627,6 +631,77 @@ result_query = execCompApi.get_data(query)
 
 > See the documentation for more details: https://sec-api.io/docs/executive-compensation-api
 
+# Insider Trading Data API
+
+The Insider Trading Data API allows you to search and list all insider buy and sell transactions of all publicly listed 
+companies on US stock exchanges. Insider activities of company directors, officers, 10% owners and other executives are 
+fully searchable. The insider trading database includes information about the CIK and name of the insider, 
+her/his relationship to the company, the number of shares and securities purchased or sold, the purchase or selling price, 
+the date of the transaction, the amount of securities held before and after the transaction occured, any footnotes such 
+as the effect of Rule 10b-18 or 10b5-1 stock purchase plans and more. The full list of all data points is available below.
+
+```python
+from sec_api import InsiderTradingApi
+
+insiderTradingApi = InsiderTradingApi("YOUR_API_KEY")
+
+insider_trades = insiderTradingApi.get_data({
+  "query": {"query_string": {"query": "issuer.tradingSymbol:TSLA"}}
+})
+
+print(insider_trades["transactions"])
+```
+
+### Response Example
+```json
+[
+    {
+        "accessionNo": "0000899243-22-028189",
+        "filedAt": "2022-08-09T21:23:00-04:00",
+        "documentType": "4",
+        "periodOfReport": "2022-08-09",
+        "issuer": {"cik": "1318605", "name": "Tesla, Inc.", "tradingSymbol": "TSLA"},
+        "reportingOwner": {
+            "cik": "1494730",
+            "name": "Musk Elon",
+            "address": {
+                "street1": "C/O TESLA, INC.",
+                "street2": "1 TESLA ROAD",
+                "city": "AUSTIN",
+                "state": "TX",
+                "zipCode": "78725"
+            },
+            "relationship": {
+                "isDirector": true,
+                "isOfficer": true,
+                "officerTitle": "CEO",
+                "isTenPercentOwner": true,
+                "isOther": false
+            }
+        },
+        "nonDerivativeTable": {
+            "transactions": [
+                {
+                    "securityTitle": "Common Stock",
+                    "transactionDate": "2022-08-09",
+                    "coding": {
+                        "formType": "4",
+                        "code": "S",
+                        "equitySwapInvolved": false
+                    },
+                    "amounts": {
+                        "shares": 435,
+                        "pricePerShare": 872.469,
+                        "pricePerShareFootnoteId": ["F1"],
+                        "acquiredDisposedCode": "D"
+                    }
+                }
+            ]
+           // and many more
+        }
+    }
+]
+```
 
 # Query API Response Format
 

diff --git a/examples.py b/examples.py
@@ -1,4 +1,11 @@
-from sec_api.index import RenderApi, XbrlApi, ExtractorApi, MappingApi, ExecCompApi
+from sec_api.index import (
+    RenderApi,
+    XbrlApi,
+    ExtractorApi,
+    MappingApi,
+    ExecCompApi,
+    InsiderTradingApi,
+)
 
 #
 # Render API
@@ -95,3 +102,22 @@
 print(result_cik)
 print(result_query)
 # """
+
+
+#
+# Insider Trading Data API Example
+#
+"""
+insiderTradingApi = InsiderTradingApi("YOUR_API_KEY")
+
+insider_trades = insiderTradingApi.get_data(
+    {
+        "query": {"query_string": {"query": "issuer.tradingSymbol:TSLA"}},
+        "from": "0",
+        "size": "50",
+        "sort": [{"filedAt": {"order": "desc"}}],
+    }
+)
+
+print(insider_trades["transactions"])
+# """
diff --git a/sec_api/__init__.py b/sec_api/__init__.py
@@ -6,3 +6,4 @@
 from sec_api.index import ExtractorApi
 from sec_api.index import MappingApi
 from sec_api.index import ExecCompApi
+from sec_api.index import InsiderTradingApi
diff --git a/sec_api/index.py b/sec_api/index.py
@@ -10,6 +10,7 @@
 extractor_api_endpoint = "https://api.sec-api.io/extractor"
 mapping_api_endpoint = "https://api.sec-api.io/mapping"
 exec_comp_api_endpoint = "https://api.sec-api.io/compensation"
+insider_api_endpoint = "https://api.sec-api.io/insider-trading"
 
 
 def handle_api_error(response):
@@ -77,7 +78,7 @@ def __init__(self, api_key):
         self.api_key = api_key
         self.api_endpoint = render_api_endpoint
 
-    def get_filing(self, url):
+    def get_filing(self, url, as_pdf=False):
         response = {}
         filename = re.sub(r"https://www.sec.gov/Archives/edgar/data", "", url)
         _url = self.api_endpoint + filename + "?token=" + self.api_key
@@ -271,3 +272,29 @@ def get_data(self, parameter=""):
                 handle_api_error(response)
         else:
             handle_api_error(response)
+
+
+class InsiderTradingApi:
+    """
+    Base class for Insider Trading Data API
+    """
+
+    def __init__(self, api_key):
+        self.api_key = api_key
+        self.api_endpoint = insider_api_endpoint + "?token=" + api_key
+
+    def get_data(self, query):
+        response = {}
+
+        # 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:
+                handle_api_error(response)
+        else:
+            handle_api_error(response)
diff --git a/setup.py b/setup.py
@@ -5,7 +5,7 @@
 
 setup(
     name="sec-api",
-    version="1.0.12",
+    version="1.0.13",
     author="SEC API",
     author_email="[email protected]",
     description="SEC EDGAR Filings API",
@@ -32,15 +32,22 @@
     keywords=[
         "SEC EDGAR API",
         "SEC Filings API",
+        "SEC Full-Text Search API",
         "EDGAR API",
         "Finance",
         "CIK",
         "CUSIP",
+        "CUSIP to Ticker",
+        "CUSIP to CIK",
         "10-Q",
         "10-K",
         "8-K",
         "S-1",
         "424B4",
+        "XBRL Converter",
+        "Financial Statements API",
+        "Insider Trading Data",
+        "Executive Compensation Data",
     ],
     project_urls={
         "Bug Reports": "https://github.com/janlukasschroeder/sec-api-python/issues",