added Form 13D/13G API

Author: janlukasschroeder

README.md

@@ -1,9 +1,10 @@
 # SEC API - A SEC.gov EDGAR Filings Query & Real-Time Stream API
 
-**sec-api** is a Python package for querying the entire SEC filings corpus in real-time without the need to download filings.
+**sec-api** is a Python package allowing you to search the entire SEC filings corpus and access over 650 terabytes of data.
+
 It includes:
 
-- [Query and Full-Text Search API](#sec-edgar-filings-query-api)
+- [SEC Filing Search 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-k10-q8-k-section-extractor-api)
@@ -15,6 +16,7 @@ It includes:
 - [Form N-PORT API](#form-n-port-api)
 - [Form D API](#form-d-api)
 - [Form ADV API](#form-adv-api)
+- [Form 13D/13G API](#form-13d-13g-api)
 - [Float (Outstanding Shares) API](#float-outstanding-shares-api)
 
 # Data Coverage
@@ -28,8 +30,6 @@ It includes:
 - Every filing is **mapped to a CIK and ticker**
 - All filings in JSON - **no XBRL/XML**
 
-Data source: [sec.gov](https://www.sec.gov/edgar/searchedgar/companysearch.html)
-
 # Overview
 
 - The query API gives access to all over 18 million SEC Edgar filings of **over 8000** publicly listed companies, ETFs, hedge funds, mutual funds, and investors dating back to 1993.
@@ -799,6 +799,88 @@ print(response["brochures"])
 
 > See the documentation for more details: https://sec-api.io/docs/investment-adviser-and-adv-api
 
+# Form 13D/13G API
+
+The API allows you to easily search and access all SEC Form 13D and Form 13G filings in a standardized JSON format. You can search the database by any form field, such as the CUSIP of the acquired security, name of the security owner, or the aggregate amount owned in percetnage of total shares outstanding.
+
+```python
+from sec_api import Form13DGApi
+
+form13DGApi = Form13DGApi("YOUR_API_KEY")
+
+# find the 50 most recently filed 13D/G filings disclosing 10% of more ownership of any Point72 company.
+query = {
+    "query": {
+        "query_string": {
+            "query": "owners.name:Point72 AND owners.amountAsPercent:[10 TO *]"
+        }
+    },
+    "from": "0",
+    "size": "50",
+    "sort": [ { "filedAt": { "order": "desc"  } } ]
+}
+
+response = form13DGApi.get_data(query)
+
+print(response["filings"])
+```
+
+> See the documentation for more details: https://sec-api.io/docs/form-13d-13g-search-api
+
+### Response Example
+
+```json
+{
+  "total": {
+    "value": 8,
+    "relation": "eq"
+  },
+  "filings": [
+    {
+      "id": "bbb1ef1892bfc12a2e398c903871e3ae",
+      "accessionNo": "0000902664-22-005029",
+      "formType": "SC 13D",
+      "filedAt": "2022-12-05T16:00:20-05:00",
+      "filers": [
+        {
+          "cik": "1813658",
+          "name": "Tempo Automation Holdings, Inc. (Subject)"
+        },
+        {
+          "cik": "1954961",
+          "name": "Point72 Private Investments, LLC (Filed by)"
+        }
+      ],
+      "nameOfIssuer": "Tempo Automation Holdings, Inc.",
+      "titleOfSecurities": "Common Stock, par value $0.0001 per share",
+      "cusip": ["88024M108"],
+      "eventDate": "2022-11-22",
+      "schedule13GFiledPreviously": false,
+      "owners": [
+        {
+          "name": "Point72 Private Investments, LLC",
+          "memberOfGroup": {
+            "a": false,
+            "b": false
+          },
+          "sourceOfFunds": ["OO"],
+          "legalProceedingsDisclosureRequired": false,
+          "place": "Delaware",
+          "soleVotingPower": 0,
+          "sharedVotingPower": 5351000,
+          "soleDispositivePower": 0,
+          "sharedDispositivePower": 5351000,
+          "aggregateAmountOwned": 5351000,
+          "amountExcludesCertainShares": false,
+          "amountAsPercent": 20.3,
+          "typeOfReportingPerson": ["OO"]
+        }
+      ]
+    }
+  ]
+}
+```
+
 # Float (Outstanding Shares) API
 
 The Float API returns the number of outstanding shares of any publicly traded company listed on US exchanges. The dataset includes the most recent float as well as historical float data. If a company registered multiple share classes, the API returns the number of shares outstanding of each class.

examples.py

@@ -9,6 +9,7 @@
     FormDApi,
     FormAdvApi,
     FloatApi,
+    Form13DGApi,
 )
 
 #
@@ -213,3 +214,21 @@
 response = floatApi.get_float(cik="1318605")
 print(response["data"])
 # """
+
+
+#
+# Form 13D/13G API Example
+#
+"""
+form13DGApi = Form13DGApi("YOUR_API_KEY")
+
+query = {
+    "query": {"query_string": {"query": "accessionNo:*"}},
+    "from": "0",
+    "size": "50",
+    "sort": [{"filedAt": {"order": "desc"}}],
+}
+
+response = form13DGApi.get_data(query)
+print(response["filings"])
+# """

sec_api/__init__.py

@@ -10,4 +10,5 @@
 from sec_api.index import FormNportApi
 from sec_api.index import FormDApi
 from sec_api.index import FormAdvApi
+from sec_api.index import Form13DGApi
 from sec_api.index import FloatApi

sec_api/index.py

@@ -14,6 +14,7 @@
 form_nport_api_endpoint = "https://api.sec-api.io/form-nport"
 form_d_api_endpoint = "https://api.sec-api.io/form-d"
 form_adv_endpoint = "https://api.sec-api.io/form-adv"
+form_13D_13G_endpoint = "https://api.sec-api.io/form-13d-13g"
 float_api_endpoint = "https://api.sec-api.io/float"
 
 
@@ -451,3 +452,29 @@ def get_float(self, ticker="", cik=""):
                 handle_api_error(response)
         else:
             handle_api_error(response)
+
+
+class Form13DGApi:
+    """
+    Base class for Form 13D/13G API
+    """
+
+    def __init__(self, api_key):
+        self.api_key = api_key
+        self.api_endpoint = form_13D_13G_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)

setup.py

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