added SEC Litigation Releases API, struct. data of Form 8K Item 4.01 and 5.02, EDGAR Entities Database

Author: janlukasschroeder

README.md

@@ -34,7 +34,9 @@ It includes:
 
 **Structured Material Event Data from Form 8-K**
 
+- [Auditor and Accountant Changes (Item 4.01)](#auditor-and-accountant-changes-item-401)
 - [Financial Restatements & Non-Reliance on Prior Financial Results (Item 4.02)](#financial-restatements--non-reliance-on-prior-financial-results-item-402)
+- [Changes of Directors, Board Members and Compensation Plans (Item 5.02)](#changes-of-directors-executives-board-members-and-compensation-plans-item-502)
 
 **Public Company Data**
 
@@ -45,12 +47,14 @@ It includes:
 
 **Enforcement Actions & SRO Filings:**
 
+- [SEC Litigation Releases](#sec-litigation-releases-database-api)
 - [AAER Database API - Accounting and Auditing Enforcement Releases](#aaer-database-api)
 - [SRO Filings Database API](#sro-filings-database-api)
 
 **Other APIs:**
 
 - [CUSIP/CIK/Ticker Mapping API](#cusipcikticker-mapping-api)
+- [EDGAR Entities Database API](#edgar-entities-database)
 
 ## Data Coverage
 
@@ -837,28 +841,71 @@ print(response["offerings"])
 
 > See the documentation for more details: https://sec-api.io/docs/form-d-xml-json-api
 
-## Financial Restatements & Non-Reliance on Prior Financial Results (Item 4.02)
+## Structured Data of Material Event Disclosures under Form 8-K
 
-Access and search all financial restatements and non-reliance on prior financial results filings from 2004 to present. The database includes information about the CIK, ticker and company name the restatement is associated with, the publication date of the restatement, list of identified issues, affected reporting periods that require restatement, affected financial statement items, auditor involvement, and more.
+### Auditor and Accountant Changes (Item 4.01)
+
+Access and search over 25,000 change-of-accountant disclosures under Item 4.01 in SEC Form 8-K filings, spanning from 2004 to present. Access information about former and newly appointed auditors, the reason for the change, the date of the change, the type of engagement, statements regarding material weaknesses in internal controls, and more.
 
 ```python
-from sec_api import Item_4_02_Api
+from sec_api import Form_8K_Item_X_Api
 
-item_4_02_api = Item_4_02_Api("YOUR_API_KEY")
+item_X_api = Form_8K_Item_X_Api("YOUR_API_KEY")
 
-query = {
-    "query": "ticker:*",
-    "from": "0",
+item_4_01_request = {
+    "query": "item4_01:* AND filedAt:[2024-01-01 TO 2024-12-31]",
+    "from": "0",  # increase by 50 to fetch the next 50 results
     "size": "50",
     "sort": [{"filedAt": {"order": "desc"}}],
 }
+item_4_01_response = item_X_api.get_data(item_4_01_request)
+print(item_4_01_response["data"])
+```
 
-response = item_4_02_api.get_data(query)
-print(response["data"])
+> See the documentation for more details: https://sec-api.io/docs/form-8k-data-item4-1-search-api
+
+### Financial Restatements & Non-Reliance on Prior Financial Results (Item 4.02)
+
+Access and search over 8,000 financial restatements and non-reliance on prior financial results filings from 2004 to present. The database includes information about the CIK, ticker and company name the restatement is associated with, the publication date of the restatement, list of identified issues, affected reporting periods that require restatement, affected financial statement items, auditor involvement, and more.
+
+```python
+from sec_api import Form_8K_Item_X_Api
+
+item_X_api = Form_8K_Item_X_Api("YOUR_API_KEY")
+
+item_4_02_request = {
+    "query": "item4_02:* AND filedAt:[2024-01-01 TO 2024-12-31]",
+    "from": "0",
+    "size": "50",
+    "sort": [{"filedAt": {"order": "desc"}}],
+}
+item_4_02_response = item_X_api.get_data(item_4_02_request)
+print(item_4_02_response["data"])
 ```
 
 > See the documentation for more details: https://sec-api.io/docs/form-8k-data-search-api
 
+### Changes of Directors, Executives, Board Members and Compensation Plans (Item 5.02)
+
+Access and search over 250,000 changes of directors, executives, board members and compensation plans disclosures under Item 5.02 in SEC Form 8-K filings, spanning from 2004 to present. The database includes information about the CIK, ticker and company name the change is associated with, the publication date of the change, the name of the director, her/his age, position, academic affiliations, compensation details, committee memberships, and more.
+
+```python
+from sec_api import Form_8K_Item_X_Api
+
+item_X_api = Form_8K_Item_X_Api("YOUR_API_KEY")
+
+item_5_02_request = {
+    "query": "item5_02:* AND filedAt:[2024-01-01 TO 2024-12-31]",
+    "from": "0",
+    "size": "50",
+    "sort": [{"filedAt": {"order": "desc"}}],
+}
+item_5_02_response = item_X_api.get_data(item_5_02_request)
+print(item_5_02_response["data"])
+```
+
+> See the documentation for more details: https://sec-api.io/docs/form-8k-data-item5-2-search-api
+
 ## Directors & Board Members Data API
 
 Access and search the entire database of all directors and board members of all publicly listed companies on US stock exchanges. The database includes information about the CIK, ticker and company name the director is associated with, the name of the director, her/his age, position, director class, date of first election, independence status, committee memberships as well as qualifications and experiences.
@@ -1077,6 +1124,28 @@ print(response["data"])
 
 > See the documentation for more details: https://sec-api.io/docs/aaer-database-api
 
+## SEC Litigation Releases Database API
+
+Access and search the SEC Litigation Releases database. The database includes metadata and extracted structured data from all SEC Litigation Releases filed from 1995 to present.
+
+```python
+from sec_api import SecLitigationApi
+
+secLitigationApi = SecLitigationApi("YOUR_API_KEY")
+
+query = {
+    "query": "releasedAt:[2024-01-01 TO 2024-12-31]",
+    "from": "0",
+    "size": "50",
+    "sort": [{"releasedAt": {"order": "desc"}}],
+}
+
+response = secLitigationApi.get_data(query)
+print(response["data"])
+```
+
+> See the documentation for more details: https://sec-api.io/docs/sec-litigation-releases-database-api
+
 ## SRO Filings Database API
 
 Access and search all SRO filings published from 1995 to present. The database includes more than 30,000 SRO filings from all types of organizations, including National Securities Exchanges (NYSE, NASDAQ, CBOE, etc.), Joint Industry Plans, FINRA, Futures Exchanges (CME, CBOT, etc.), and more.
@@ -1176,6 +1245,25 @@ result4 = mappingApi.resolve("exchange", "NASDAQ")
 
 > See the documentation for more details: https://sec-api.io/docs/mapping-api
 
+## EDGAR Entities Database
+
+Access information on over 800,000 EDGAR filing entities that have filed with the SEC since 1994. The database includes information about the CIK, IRS number, state of incorporation, fiscal year end, SIC code, current auditor, latest ICFR audit date, filer category, and more.
+
+```python
+edgarEntitiesApi = EdgarEntitiesApi("YOUR_API_KEY")
+
+search_request = {
+    "query": "cik:1318605",
+    "from": "0",
+    "size": "50",
+    "sort": [{"cikUpdatedAt": {"order": "desc"}}],
+}
+response = edgarEntitiesApi.get_data(search_request)
+print(response["data"])
+```
+
+> See the documentation for more details: https://sec-api.io/docs/edgar-entities-database-api
+
 ## Proxy Support
 
 In certain cases, your corporate IT infrastructure may encounter issues with HTTPS requests, leading to SSL certificate errors. To resolve this, HTTP and HTTPS proxies can be passed into all API wrappers as shown in the example below. If you're unsure about which proxies to use, please consult your company's IT administrator.

examples.py

@@ -3,7 +3,6 @@
     PdfGeneratorApi,
     XbrlApi,
     ExtractorApi,
-    MappingApi,
     DirectorsBoardMembersApi,
     ExecCompApi,
     InsiderTradingApi,
@@ -15,8 +14,12 @@
     Form_S1_424B4_Api,
     SubsidiaryApi,
     AaerApi,
+    SecLitigationsApi,
     SroFilingsApi,
     Item_4_02_Api,
+    Form_8K_Item_X_Api,
+    MappingApi,
+    EdgarEntitiesApi,
 )
 
 #
@@ -346,6 +349,24 @@
 # """
 
 
+#
+# SEC Litigation Releases API Example
+#
+"""
+secLitigationsApi = SecLitigationsApi("YOUR_API_KEY")
+
+query = {
+    "query": "releasedAt:[2024-01-01 TO 2024-12-31]",
+    "from": "0",
+    "size": "50",
+    "sort": [{"releasedAt": {"order": "desc"}}],
+}
+
+response = secLitigationsApi.get_data(query)
+print(response["data"])
+# """
+
+
 #
 # SRO Filings API Example
 #
@@ -378,3 +399,44 @@
 response = item_4_02_api.get_data(query)
 print(response["data"])
 # """
+
+#
+# Form 8-K Item X API Examples
+#
+"""
+item_X_api = Form_8K_Item_X_Api("YOUR_API_KEY")
+
+item_4_01_request = {
+    "query": "item4_01:* AND filedAt:[2024-01-01 TO 2024-12-31]",
+    "from": "0",  # increase by 50 to fetch the next 50 results, e.g. 50 (=page 2), 100 (=page 3), 150 (=page 4), ...
+    "size": "50",
+    "sort": [{"filedAt": {"order": "desc"}}],
+}
+item_4_01_response = item_X_api.get_data(item_4_01_request)
+print(item_4_01_response["data"])
+
+item_5_02_request = {
+    "query": "item5_02:* AND filedAt:[2024-01-01 TO 2024-12-31]",
+    "from": "0",  # increase by 50 to fetch the next 50 results, e.g. 50 (=page 2), 100 (=page 3), 150 (=page 4), ...
+    "size": "50",
+    "sort": [{"filedAt": {"order": "desc"}}],
+}
+item_5_02_response = item_X_api.get_data(item_5_02_request)
+print(item_5_02_response["data"])
+# """
+
+#
+# EDGAR Entities Database API Example
+#
+"""
+edgarEntitiesApi = EdgarEntitiesApi("YOUR_API_KEY")
+
+search_request = {
+    "query": "cik:1318605",
+    "from": "0",
+    "size": "50",
+    "sort": [{"cikUpdatedAt": {"order": "desc"}}],
+}
+response = edgarEntitiesApi.get_data(search_request)
+print(response["data"])
+# """

sec_api/__init__.py

@@ -27,10 +27,13 @@
 
 # Structured data from Form 8-Ks
 from sec_api.index import Item_4_02_Api
+from sec_api.index import Form_8K_Item_X_Api
 
 # Other APIs
 from sec_api.index import MappingApi
+from sec_api.index import EdgarEntitiesApi
 from sec_api.index import FloatApi
 from sec_api.index import SubsidiaryApi
 from sec_api.index import AaerApi
+from sec_api.index import SecLitigationsApi
 from sec_api.index import SroFilingsApi

sec_api/index.py

@@ -20,6 +20,7 @@
 form_d_api_endpoint = "https://api.sec-api.io/form-d"
 #
 form_8K_item_4_02_api_endpoint = "https://api.sec-api.io/form-8k"
+form_8K_item_x_api_endpoint = "https://api.sec-api.io/form-8k"
 #
 exec_comp_api_endpoint = "https://api.sec-api.io/compensation"
 directors_board_members_api_endpoint = (
@@ -29,9 +30,11 @@
 subsidiary_endpoint = "https://api.sec-api.io/subsidiaries"
 #
 aaer_search_endpoint = "https://api.sec-api.io/aaers"
+sec_litigations_search_endpoint = "https://api.sec-api.io/sec-litigation-releases"
 sro_search_endpoint = "https://api.sec-api.io/sro"
 #
 mapping_api_endpoint = "https://api.sec-api.io/mapping"
+edgar_entities_endpoint = "https://api.sec-api.io/edgar-entities"
 
 
 def handle_api_error(response):
@@ -729,6 +732,36 @@ def get_data(self, query):
             handle_api_error(response)
 
 
+class SecLitigationsApi:
+    """
+    Base class for SEC Litigation Releases API
+    https://sec-api.io/docs/sec-litigation-releases-database-api
+    """
+
+    def __init__(self, api_key, proxies=None):
+        self.api_key = api_key
+        self.api_search_endpoint = sec_litigations_search_endpoint + "?token=" + api_key
+        self.proxies = proxies if proxies else {}
+
+    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_search_endpoint, json=query, proxies=self.proxies
+            )
+            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)
+
+
 class SroFilingsApi:
     """
     Base class for SRO Filings Database API
@@ -759,6 +792,35 @@ def get_data(self, query):
             handle_api_error(response)
 
 
+class Form_8K_Item_X_Api:
+    """
+    Base class for Form 8-K Item X API
+    """
+
+    def __init__(self, api_key, proxies=None):
+        self.api_key = api_key
+        self.api_endpoint = form_8K_item_x_api_endpoint + "?token=" + api_key
+        self.proxies = proxies if proxies else {}
+
+    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, proxies=self.proxies
+            )
+            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)
+
+
 class Item_4_02_Api:
     """
     Base class for Form 8-K Item 4.02 API
@@ -786,3 +848,33 @@ def get_data(self, query):
                 handle_api_error(response)
         else:
             handle_api_error(response)
+
+
+class EdgarEntitiesApi:
+    """
+    Base class for EDGAR Entities Database API
+    https://sec-api.io/docs/edgar-entities-database-api
+    """
+
+    def __init__(self, api_key, proxies=None):
+        self.api_key = api_key
+        self.api_endpoint = edgar_entities_endpoint + "?token=" + api_key
+        self.proxies = proxies if proxies else {}
+
+    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, proxies=self.proxies
+            )
+            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)