added 10-K/10-Q section extraction API

Author: janlukasschroeder

.gitignore

@@ -5,4 +5,5 @@ build
 .pypirc
 sec_api.egg-info
 sec_api.egg-info
-deploy.sh
+deploy.sh
+sec_api/__pycache__

README.md

@@ -6,6 +6,7 @@ It includes:
 - Query and Full-Text Search API
 - Real-Time Stream API
 - XBRL-to-JSON Converter API + Financial Statements
+- 10-K/10-Q Section Extraction API
 - Filing Render & Download API
 
 
@@ -356,6 +357,53 @@ Note: response is shortened.
 
 > See the documentation for more details: https://sec-api.io/docs/xbrl-to-json-converter-api
 
+# 10-K/10-Q Section Extractor API
+
+The Extractor API returns individual sections from 10-Q and 10-K filings. The extracted section is cleaned and standardized - in raw text or in standardized HTML. You can programmatically extract one or multiple sections from any 10-Q and 10-K filing.
+
+All 10-K and 10-Q sections can be extracted:
+
+- 1 - Business
+- 1A - Risk Factors
+- 1B - Unresolved Staff Comments
+- 2 - Properties
+- 3 - Legal Proceedings
+- 4 - Mine Safety Disclosures
+- 5 - Market for Registrant’s Common Equity, Related Stockholder Matters and Issuer Purchases of Equity Securities
+- 6 - Selected Financial Data (prior to February 2021)
+- 7 - Management’s Discussion and Analysis of Financial Condition and Results of Operations
+- 7A - Quantitative and Qualitative Disclosures about Market Risk
+- 8 - Financial Statements and Supplementary Data
+- 9 - Changes in and Disagreements with Accountants on Accounting and Financial Disclosure
+- 9A - Controls and Procedures
+- 9B - Other Information
+- 10 - Directors, Executive Officers and Corporate Governance
+- 11 - Executive Compensation
+- 12 - Security Ownership of Certain Beneficial Owners and Management and Related Stockholder Matters
+- 13 - Certain Relationships and Related Transactions, and Director Independence
+- 14 - Principal Accountant Fees and Services
+
+## Usage
+
+```python
+from sec_api import ExtractorApi
+
+extractorApi = ExtractorApi("YOUR_API_KEY")
+
+# Tesla 10-K filing
+filing_url = "https://www.sec.gov/Archives/edgar/data/1318605/000156459021004599/tsla-10k_20201231.htm"
+
+# get the standardized and cleaned text of section 1A "Risk Factors"
+section_text = extractorApi.get_section(filing_url, "1A", "text")
+
+# get the original HTML of section 7 "Management’s Discussion and Analysis of Financial Condition and Results of Operations"
+section_html = extractorApi.get_section(filing_url, "7", "html")
+
+print(section_text)
+print(section_html)
+```
+
+> See the documentation for more details: https://sec-api.io/docs/sec-filings-item-extraction-api
 
 
 # Filing Render & Download API
@@ -377,7 +425,7 @@ print(filing)
 > See the documentation for more details: https://sec-api.io/docs/sec-filings-render-api
 
 
-# Response Format
+# Query API Response Format
 
 - `accessionNo` (string) - Accession number of filing, e.g. 0000028917-20-000033
 - `cik` (string) - CIK of the filing issuer. Important: trailing `0` are removed.
@@ -572,7 +620,7 @@ print(filing)
 
 # Contact
 
-Let me know how I can improve the library or if you have any feature
-suggestions. I'm happy to implement them.
+Let us know how we can improve the library or if you have any feature
+suggestions. We're happy to implement them.
 
 [email protected]

examples.py

@@ -1,7 +1,13 @@
-from sec_api.index import XbrlApi
+from sec_api.index import XbrlApi, ExtractorApi
 
+#
+# 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"
@@ -18,3 +24,21 @@
 
 # 10-K XBRL File URL example
 xbrl_json_3 = xbrlApi.xbrl_to_json(accession_no="0001564590-21-004599")
+# """
+
+#
+# Extractor API Example
+#
+
+# """
+extractorApi = ExtractorApi("YOUR_API_KEY")
+
+# Tesla 10-K filing
+filing_url = "https://www.sec.gov/Archives/edgar/data/1318605/000156459021004599/tsla-10k_20201231.htm"
+
+section_text = extractorApi.get_section(filing_url, "1A", "text")
+section_html = extractorApi.get_section(filing_url, "1A", "html")
+
+print(section_text)
+print(section_html)
+# """

sec_api/__init__.py

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

sec_api/index.py

@@ -5,6 +5,7 @@
 full_text_search_api_endpoint = "https://api.sec-api.io/full-text-search"
 render_api_endpoint = "https://api.sec-api.io/filing-reader"
 xbrl_api_endpoint = "https://api.sec-api.io/xbrl-to-json"
+extractor_api_endpoint = "https://api.sec-api.io/extractor"
 
 
 class QueryApi:
@@ -76,3 +77,30 @@ def xbrl_to_json(self, htm_url="", xbrl_url="", accession_no=""):
 
         response = requests.get(_url)
         return json.loads(response.text)
+
+
+class ExtractorApi:
+    """
+    Base class for 10-K/10-Q item/section extractor API
+    """
+
+    def __init__(self, api_key):
+        self.api_key = api_key
+        self.api_endpoint = extractor_api_endpoint + "?token=" + api_key
+
+    def get_section(self, filing_url="", section="1A", return_type="text"):
+        if len(filing_url) == 0:
+            raise ValueError("filing_url must be present")
+
+        _url = (
+            self.api_endpoint
+            + "&url="
+            + filing_url
+            + "&item="
+            + section
+            + "&type="
+            + return_type
+        )
+
+        response = requests.get(_url)
+        return response.text

setup.py

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