added Form N-CEN API

Author: janlukasschroeder

README.md

@@ -28,9 +28,10 @@
 - [Form 13D/13G API - Activist and Passive Investor Holdings](#form-13d-13g-api)
 - [Form N-PORT API - Mutual Funds, ETFs and Closed-End Fund Holdings](#form-n-port-api)
 
-**Proxy Voting Records**
+**Investment Companies**
 
-- [Form N-PX Proxy Voting Records API](#form-n-px-proxy-voting-records-api)
+- [Form N-CEN API - Annual Reports](#form-n-cen-api---annual-reports-by-investment-companies)
+- [Form N-PX API - Proxy Voting Records](#form-n-px-proxy-voting-records-api)
 
 **Security Offerings APIs**
 
@@ -873,6 +874,28 @@ print(response["filings"])
 
 > See the documentation for more details: https://sec-api.io/docs/n-port-data-api
 
+## Form N-CEN API - Annual Reports by Investment Companies
+
+The Form N-CEN API allows searching and accessing all Form N-CEN filings (annual reports by investment companies) from 2018 to present in a structured JSON format. The database includes information about the investment company, such as CIK, name, address, type of investment company, series information, directors, underwriters, total assets, and more. All types of funds are supported, including master-feeder, index, exchange-traded, money market, and more.
+
+```python
+from sec_api import FormNcenApi
+
+formNcenApi = FormNcenApi("YOUR_API_KEY")
+
+search_params = {
+    "query": 'managementInvestmentQuestionSeriesInfo.fundTypes:"Exchange-Traded Fund"',
+    "from": "0",
+    "size": "10",
+    "sort": [{"filedAt": {"order": "desc"}}],
+}
+
+response = formNcenApi.get_data(search_params)
+print(response["data"])
+```
+
+> See the documentation for more details: https://sec-api.io/docs/form-ncen-api-annual-reports-investment-companies
+
 ## Form N-PX Proxy Voting Records API
 
 The Form N-PX API consists of two APIs: the N-PX Search API and the Voting Records API. The N-PX Search API enables filtering all N-PX filings published on the SEC EDGAR database since 2024. The API accepts search queries as JSON formatted payload and returns the matching N-PX filings in JSON format. The Voting Records API allows downloading the proxy voting records in structured JSON format for a specific filing by providing the filing's accession number.

examples.py

@@ -13,6 +13,7 @@
     FormNportApi,
     Form13DGApi,
     #
+    FormNcenApi,
     FormNPXApi,
     #
     Form_S1_424B4_Api,
@@ -488,6 +489,24 @@
 # """
 
 
+#
+# Form N-CEN API Example
+#
+"""
+formNcenApi = FormNcenApi("YOUR_API_KEY")
+
+search_params = {
+    "query": "accessionNo:*",
+    "from": "0",
+    "size": "10",
+    "sort": [{"filedAt": {"order": "desc"}}],
+}
+
+response = formNcenApi.get_data(search_params)
+print(response["data"])
+# """
+
+
 #
 # Form N-PX API Examples
 #

sec_api/__init__.py

@@ -16,7 +16,10 @@
 from sec_api.index import FormNportApi
 from sec_api.index import Form13DGApi
 
+# Investment Companies:
+# Form N-CEN Annual Reports
 # Form N-PX Proxy Voting Records
+from sec_api.index import FormNcenApi
 from sec_api.index import FormNPXApi
 
 # Offering APIs

sec_api/index.py

@@ -19,6 +19,7 @@
 form_nport_api_endpoint = "https://api.sec-api.io/form-nport"
 form_13D_13G_endpoint = "https://api.sec-api.io/form-13d-13g"
 #
+form_NCEN_endpoint = "https://api.sec-api.io/form-ncen"
 form_NPX_endpoint = "https://api.sec-api.io/form-npx"
 #
 form_S1_424B4_endpoint = "https://api.sec-api.io/form-s1-424b4"
@@ -888,6 +889,35 @@ def get_data(self, query):
             handle_api_error(response)
 
 
+class FormNcenApi:
+    """
+    Base class for Form N-CEN API - Annual Reports of Registered Investment Companies
+    https://sec-api.io/docs/form-ncen-api-annual-reports-investment-companies
+    """
+
+    def __init__(self, api_key, proxies=None):
+        self.api_key = api_key
+        self.api_endpoint = form_NCEN_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:
+                time.sleep(0.5 * (x + 1))
+            else:
+                handle_api_error(response)
+        else:
+            handle_api_error(response)
+
+
 class FormNPXApi:
     """
     Base class for Form N-PX Proxy Voting Records API

setup.py

@@ -5,7 +5,7 @@
 
 setup(
     name="sec-api",
-    version="1.0.31",
+    version="1.0.32",
     author="SEC API",
     author_email="support@sec-api.io",
     description="SEC EDGAR Filings API",