added XBRL-to-JSON converter API

Author: janlukasschroeder

README.md

@@ -5,7 +5,8 @@ It includes:
 
 - Query and Full-Text Search API
 - Real-Time Stream API
-- Filings Render API
+- XBRL-to-JSON Converter API + Financial Statements
+- Filing Render & Download API
 
 
 # Data Coverage
@@ -14,6 +15,7 @@ It includes:
 - **All +150 filing types** are supported, eg 10-Q, 10-K, 4, 8-K, 13-F, S-1, 424B4 and many more.
   [See the list of supported form types here.](https://sec-api.io/list-of-sec-filing-types)
 - Newly published filings are accessible in real-time
+- XBRL-to-JSON converter and parser API. Extract standardized financial statements from any 10-K and 10-Q filing.
 - 13F holdings API included. Monitor all institutional ownerships in real-time.
 - Every filing is **mapped to a CIK and ticker**
 - All filings in JSON - **no XBRL/XML**
@@ -165,10 +167,200 @@ print(filings)
 > See the documentation for more details: https://sec-api.io/docs/full-text-search-api
 
 
-# Filing Render API
+# XBRL-To-JSON Converter API
 
-Used to fetch the content of any filing or exhibit.
+Parse and standardize any XBRL and convert it to JSON or pandas dataframes. Extract financial statements and meta data from 10-K and 10-Q filings.
 
+The entire US GAAP taxonomy is fully supported. All XBRL items are fully converted into JSON, including `us-gaap`, `dei` and custom items. XBRL facts are automatically mapped to their respective context including period instants and date ranges.
+
+All financial statements are accessible and standardized:
+
+- StatementsOfIncome
+- StatementsOfIncomeParenthetical
+- StatementsOfComprehensiveIncome
+- StatementsOfComprehensiveIncomeParenthetical
+- BalanceSheets
+- BalanceSheetsParenthetical
+- StatementsOfCashFlows
+- StatementsOfCashFlowsParenthetical
+- StatementsOfShareholdersEquity
+- StatementsOfShareholdersEquityParenthetical
+
+Variants such as `ConsolidatedStatementsofOperations` or `ConsolidatedStatementsOfLossIncome` are automatically standardized to their root name, e.g. `StatementsOfIncome`.
+
+## Income Statement - Example Item
+
+```json
+{
+  "StatementsOfIncome": {
+    "RevenueFromContractWithCustomerExcludingAssessedTax": [
+      {
+        "decimals": "-6",
+        "unitRef": "usd",
+        "period": {
+          "startDate": "2019-09-29",
+          "endDate": "2020-09-26"
+        },
+        "value": "274515000000"
+      },
+      {
+        "decimals": "-6",
+        "unitRef": "usd",
+        "period": {
+          "startDate": "2018-09-30",
+          "endDate": "2019-09-28"
+        },
+        "value": "260174000000"
+      }
+    ]
+  }
+}
+```
+
+## Usage
+
+There are 3 ways to convert XBRL to JSON:
+
+- `htm_url`: Provide the URL of the filing ending with `.htm`.
+  Example URL: https://www.sec.gov/Archives/edgar/data/1318605/000156459021004599/tsla-10k_20201231.htm
+- `xbrl_url`: Provide the URL of the XBRL file ending with `.xml`. The XBRL file URL can be found in the `dataFiles` array returned by our query API. The array item has the description `EXTRACTED XBRL INSTANCE DOCUMENT` or similar.
+  Example URL: https://www.sec.gov/Archives/edgar/data/1318605/000156459021004599/tsla-10k_20201231_htm.xml
+- `accession_no`: Provide the accession number of the filing, e.g. `0001564590-21-004599`
+
+
+```python
+from sec_api import XbrlApi
+
+xbrlApi = XbrlApi("YOUR_API_KEY")
+
+# 10-K HTM File URL example
+xbrl_json = xbrlApi.xbrl_to_json(
+    htm_url="https://www.sec.gov/Archives/edgar/data/320193/000032019320000096/aapl-20200926.htm"
+)
+
+# access income statement, balance sheet and cash flow statement
+print(xbrl_json["StatementsOfIncome"])
+print(xbrl_json["BalanceSheets"])
+print(xbrl_json["StatementsOfCashFlows"])
+
+# 10-K XBRL File URL example
+xbrl_json = xbrlApi.xbrl_to_json(
+    xbrl_url="https://www.sec.gov/Archives/edgar/data/1318605/000156459021004599/tsla-10k_20201231_htm.xml"
+)
+
+# 10-K accession number example
+xbrl_json = xbrlApi.xbrl_to_json(accession_no="0001564590-21-004599")
+```
+
+## Example Response
+
+Note: response is shortened.
+
+```json
+{
+ "CoverPage": {
+  "DocumentPeriodEndDate": "2020-09-26",
+  "EntityRegistrantName": "Apple Inc.",
+  "EntityIncorporationStateCountryCode": "CA",
+  "EntityTaxIdentificationNumber": "94-2404110",
+  "EntityAddressAddressLine1": "One Apple Park Way",
+  "EntityAddressCityOrTown": "Cupertino",
+  "EntityAddressStateOrProvince": "CA",
+  "EntityAddressPostalZipCode": "95014",
+  "CityAreaCode": "408",
+  "LocalPhoneNumber": "996-1010",
+  "TradingSymbol": "AAPL",
+  "EntityPublicFloat": {
+   "decimals": "-6",
+   "unitRef": "usd",
+   "period": {
+    "instant": "2020-03-27"
+   },
+   "value": "1070633000000"
+  },
+  "EntityCommonStockSharesOutstanding": {
+   "decimals": "-3",
+   "unitRef": "shares",
+   "period": {
+    "instant": "2020-10-16"
+   },
+   "value": "17001802000"
+  },
+  "DocumentFiscalPeriodFocus": "FY",
+  "CurrentFiscalYearEndDate": "--09-26"
+ },
+ "StatementsOfIncome": {
+  "RevenueFromContractWithCustomerExcludingAssessedTax": [
+   {
+    "decimals": "-6",
+    "unitRef": "usd",
+    "period": {
+     "startDate": "2019-09-29",
+     "endDate": "2020-09-26"
+    },
+    "segment": {
+     "dimension": "srt:ProductOrServiceAxis",
+     "value": "us-gaap:ProductMember"
+    },
+    "value": "220747000000"
+   },
+   {
+    "decimals": "-6",
+    "unitRef": "usd",
+    "period": {
+     "startDate": "2018-09-30",
+     "endDate": "2019-09-28"
+    },
+    "segment": {
+     "dimension": "srt:ProductOrServiceAxis",
+     "value": "us-gaap:ProductMember"
+    },
+    "value": "213883000000"
+   }
+  ]
+ },
+ "BalanceSheets": {
+  "CashAndCashEquivalentsAtCarryingValue": [
+   {
+    "decimals": "-6",
+    "unitRef": "usd",
+    "period": {
+     "instant": "2020-09-26"
+    },
+    "value": "38016000000"
+   },
+   {
+    "decimals": "-6",
+    "unitRef": "usd",
+    "period": {
+     "instant": "2019-09-28"
+    },
+    "value": "48844000000"
+   },
+   {
+    "decimals": "-6",
+    "unitRef": "usd",
+    "period": {
+     "instant": "2020-09-26"
+    },
+    "segment": {
+     "dimension": "us-gaap:FinancialInstrumentAxis",
+     "value": "us-gaap:CashMember"
+    },
+    "value": "17773000000"
+   }
+  ]
+ }
+}
+```
+
+> See the documentation for more details: https://sec-api.io/docs/xbrl-to-json-converter-api
+
+
+
+# Filing Render & Download API
+
+Used to download any filing or exhibit. You can process the downloaded filing in memory or save the filing to your hard drive.
 
 ```python
 from sec_api import RenderApi

examples.py

@@ -0,0 +1,20 @@
+from sec_api.index import XbrlApi
+
+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"
+)
+
+print(xbrl_json_1["StatementsOfIncome"])
+print(xbrl_json_1["BalanceSheets"])
+print(xbrl_json_1["StatementsOfCashFlows"])
+
+# 10-K XBRL File URL example
+xbrl_json_2 = xbrlApi.xbrl_to_json(
+    xbrl_url="https://www.sec.gov/Archives/edgar/data/1318605/000156459021004599/tsla-10k_20201231_htm.xml"
+)
+
+# 10-K XBRL File URL example
+xbrl_json_3 = xbrlApi.xbrl_to_json(accession_no="0001564590-21-004599")

sec_api/__pycache__/__init__.cpython-37.pyc

@@ -1,8 +1,10 @@
 import requests
+import json
 
 query_api_endpoint = "https://api.sec-api.io"
 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"
 
 
 class QueryApi:
@@ -46,3 +48,31 @@ def get_filing(self, url):
         _url = self.api_endpoint + "&type=html&url=" + url
         response = requests.get(_url)
         return response.text
+
+
+class XbrlApi:
+    """
+    Base class for XBRL-to-JSON API
+    """
+
+    def __init__(self, api_key):
+        self.api_key = api_key
+        self.api_endpoint = xbrl_api_endpoint + "?token=" + api_key
+
+    def xbrl_to_json(self, htm_url="", xbrl_url="", accession_no=""):
+        if len(htm_url) == 0 and len(xbrl_url) == 0 and len(accession_no) == 0:
+            raise ValueError("htm_url, xbrl_url or accession_no must be present")
+
+        _url = ""
+
+        if len(htm_url):
+            _url = self.api_endpoint + "&htm-url=" + htm_url
+
+        if len(xbrl_url):
+            _url = self.api_endpoint + "&xbrl-url=" + xbrl_url
+
+        if len(accession_no):
+            _url = self.api_endpoint + "&accession-no=" + accession_no
+
+        response = requests.get(_url)
+        return json.loads(response.text)