sec-financial-data 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- sec_financial_data-0.1.0/LICENSE +21 -0
- sec_financial_data-0.1.0/PKG-INFO +216 -0
- sec_financial_data-0.1.0/README.md +197 -0
- sec_financial_data-0.1.0/pyproject.toml +32 -0
- sec_financial_data-0.1.0/sec_financial_data/__init__.py +2 -0
- sec_financial_data-0.1.0/sec_financial_data/sec_financial_data.py +1071 -0
- sec_financial_data-0.1.0/sec_financial_data.egg-info/PKG-INFO +216 -0
- sec_financial_data-0.1.0/sec_financial_data.egg-info/SOURCES.txt +10 -0
- sec_financial_data-0.1.0/sec_financial_data.egg-info/dependency_links.txt +1 -0
- sec_financial_data-0.1.0/sec_financial_data.egg-info/requires.txt +1 -0
- sec_financial_data-0.1.0/sec_financial_data.egg-info/top_level.txt +1 -0
- sec_financial_data-0.1.0/setup.cfg +4 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025 Arun Mittal
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,216 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: sec-financial-data
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: A Python package to retrieve financial data from SEC EDGAR.
|
|
5
|
+
Author-email: Arun Mittal <arun.mittal.sjsu@gmail.com>
|
|
6
|
+
Project-URL: Homepage, https://github.com/armittal89/sec_api
|
|
7
|
+
Project-URL: Bug Tracker, https://github.com/armittal89/sec_api/issues
|
|
8
|
+
Classifier: Programming Language :: Python :: 3
|
|
9
|
+
Classifier: Operating System :: OS Independent
|
|
10
|
+
Classifier: Intended Audience :: Developers
|
|
11
|
+
Classifier: Intended Audience :: Financial and Insurance Industry
|
|
12
|
+
Classifier: Topic :: Office/Business :: Financial
|
|
13
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
14
|
+
Requires-Python: >=3.7
|
|
15
|
+
Description-Content-Type: text/markdown
|
|
16
|
+
License-File: LICENSE
|
|
17
|
+
Requires-Dist: requests>=2.20.0
|
|
18
|
+
Dynamic: license-file
|
|
19
|
+
|
|
20
|
+
# sec-financial-data
|
|
21
|
+
|
|
22
|
+
[](https://badge.fury.io/py/sec-financial-data)
|
|
23
|
+
|
|
24
|
+
This Python package, sec-financial-data, is designed to simplify the process of retrieving and accessing publicly available financial data from the U.S. Securities and Exchange Commission's (SEC) EDGAR database. It acts as a convenient wrapper around the SEC's EDGAR APIs, providing a more Pythonic and user-friendly interface for developers and financial analysts.
|
|
25
|
+
|
|
26
|
+
Core Purpose:
|
|
27
|
+
|
|
28
|
+
The primary goal of the package is to enable users to programmatically fetch various types of financial information for publicly traded companies. This includes:
|
|
29
|
+
|
|
30
|
+
1. Company identification data (CIK numbers).
|
|
31
|
+
2. Raw XBRL (eXtensible Business Reporting Language) data, which forms the basis of SEC filings.
|
|
32
|
+
3. Formatted financial statements like Income Statements, Balance Sheets, and Cash Flow Statements.
|
|
33
|
+
4. Aggregated financial data points across multiple companies for comparative analysis.
|
|
34
|
+
|
|
35
|
+
Key Features & Functionality:
|
|
36
|
+
|
|
37
|
+
1. User-Agent Management: The package emphasizes responsible API usage by allowing and encouraging users to set a custom User-Agent string, which is a requirement by the SEC for programmatic access.
|
|
38
|
+
2. Rate Limiting: It incorporates a basic rate-limiting mechanism to ensure that requests to the SEC EDGAR APIs do not exceed the allowed limit (10 requests per second), preventing potential IP blocks.
|
|
39
|
+
3. CIK Lookup:
|
|
40
|
+
1. Provides a function (get_cik_for_symbol) to retrieve a company's Central Index Key (CIK) using its stock ticker symbol.
|
|
41
|
+
2. The CIK map is fetched from the SEC and cached (@lru_cache) to improve performance for subsequent lookups.
|
|
42
|
+
4. Access to Raw XBRL Data:
|
|
43
|
+
1. get_company_all_facts(): Fetches the complete set of XBRL data (company facts) for a given CIK or ticker symbol. This is a comprehensive JSON object containing all reported financial concepts and their values over time.
|
|
44
|
+
2. get_company_specific_concept(): Allows users to retrieve data for a specific XBRL concept (e.g., "Revenues," "Assets") within a particular taxonomy (e.g., "us-gaap") for a company.
|
|
45
|
+
5. Aggregated Data (Frames API):
|
|
46
|
+
1. get_aggregated_frames_data(): Interacts with the SEC's "frames" API to fetch aggregated data for a specific XBRL tag, unit, and period (year/quarter) across all reporting entities. This is useful for market-wide analysis or peer comparisons.
|
|
47
|
+
6. Formatted Financial Statements:
|
|
48
|
+
1. The core of its value proposition for many users lies in the get_financial_statement() function and its specific wrappers: get_income_statement(), get_balance_sheet(), and get_cash_flow_statement().
|
|
49
|
+
2. These functions take raw XBRL data (obtained via get_company_facts()) and attempt to parse and structure it into a more conventional and readable JSON format for standard financial statements.
|
|
50
|
+
3. Data Normalization Logic:
|
|
51
|
+
1. It identifies relevant XBRL tags for common line items in each statement type (e.g., "Revenues", "NetIncomeLoss", "Assets", "CashAndCashEquivalentsAtCarryingValue").
|
|
52
|
+
2. It includes a list of primary and alternate XBRL tags for many financial line items, acknowledging that companies might use different tags for similar concepts. The _get_financial_value() helper method is crucial here, trying a primary tag first and then falling back to alternates.
|
|
53
|
+
3. It processes facts from 10-K (annual) and 10-Q (quarterly) filings.
|
|
54
|
+
4. It identifies the "canonical" report for each period (latest filing for a given end date) to avoid using superseded data.
|
|
55
|
+
5. It sorts reports chronologically and allows users to specify a limit for the number of recent periods.
|
|
56
|
+
6. It performs some derivations (e.g., calculating Gross Profit if not directly reported, deriving EBITDA, Net Debt).
|
|
57
|
+
7. SECHelper Class: This class serves as the main public interface for the package, encapsulating all the user-facing methods for easy access.
|
|
58
|
+
|
|
59
|
+
How it Works (High-Level):
|
|
60
|
+
|
|
61
|
+
1. The user initializes the SECHelper class, optionally providing a `user_agent_string`.
|
|
62
|
+
2. When a method is called (e.g., get_income_statement("AAPL")):
|
|
63
|
+
1. If a ticker symbol is provided, it's first converted to a CIK.
|
|
64
|
+
2. The necessary SEC API endpoint is constructed.
|
|
65
|
+
3. A rate-limited HTTP GET request is made to the SEC API using the requests library.
|
|
66
|
+
4. The JSON response from the API is retrieved.
|
|
67
|
+
5. For financial statement functions, the extensive get_company_facts() data is processed:
|
|
68
|
+
1. Facts are filtered and grouped by filing (10-K/10-Q) and period.
|
|
69
|
+
2. The most recent, relevant filings are selected.
|
|
70
|
+
3. Values for predefined financial statement line items are extracted using the primary/alternate tag logic.
|
|
71
|
+
4. Some line items are calculated based on others.
|
|
72
|
+
6. The final data is returned as a Python dictionary or list of dictionaries.
|
|
73
|
+
|
|
74
|
+
Target Audience:
|
|
75
|
+
|
|
76
|
+
1. Developers: Building financial applications, tools, or dashboards.
|
|
77
|
+
2. Financial Analysts & Researchers: Performing quantitative analysis, company valuation, or market research.
|
|
78
|
+
3. Students & Hobbyists: Learning about financial data and programming.
|
|
79
|
+
|
|
80
|
+
Key Abstractions:
|
|
81
|
+
|
|
82
|
+
1. It abstracts away the complexities of directly interacting with the SEC EDGAR APIs (endpoint URLs, rate limits, raw XBRL structure).
|
|
83
|
+
2. It attempts to normalize the varied XBRL tags into a more standardized set of financial line items, though this is inherently challenging due to the flexibility of XBRL.
|
|
84
|
+
|
|
85
|
+
Important Considerations for Users:
|
|
86
|
+
|
|
87
|
+
1. XBRL Tag Variability: Financial data reporting using XBRL can vary between companies and over time. While the package uses a list of common and alternate tags, it might not capture every possible variation for every company. Users might need to inspect the raw company_facts for specific or less common tags.
|
|
88
|
+
2. Data Accuracy: The package relies on the data as reported to the SEC. The parsing and normalization logic aims for accuracy but is based on common US GAAP interpretations.
|
|
89
|
+
3. API Changes: The SEC may update its APIs, which could potentially require updates to the package.
|
|
90
|
+
4. User-Agent: It's crucial to provide a descriptive user_agent for responsible API usage.
|
|
91
|
+
|
|
92
|
+
In summary, sec-financial-data provides a valuable toolkit for accessing and working with SEC financial data in Python, significantly lowering the barrier to entry for retrieving and making sense of this rich dataset. It balances ease of use for common financial statements with the ability to access raw, detailed XBRL data for more advanced use cases.
|
|
93
|
+
|
|
94
|
+
## Features
|
|
95
|
+
|
|
96
|
+
* Fetch financial statements (10-K, 10-Q) for a given company.
|
|
97
|
+
* Extract specific financial data points.
|
|
98
|
+
* User-friendly API.
|
|
99
|
+
|
|
100
|
+
## Installation
|
|
101
|
+
|
|
102
|
+
You can install `sec-financial-data` from PyPI:
|
|
103
|
+
|
|
104
|
+
```bash
|
|
105
|
+
pip install sec-financial-data
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
Requires Python 3.7+.
|
|
109
|
+
|
|
110
|
+
## Usage
|
|
111
|
+
```python
|
|
112
|
+
from sec_financial_data.sec_financial_data import SECHelper
|
|
113
|
+
import json
|
|
114
|
+
|
|
115
|
+
# It's highly recommended to provide a descriptive user-agent.
|
|
116
|
+
# Replace "YourAppName/1.0" and "your-email@example.com" accordingly.
|
|
117
|
+
helper = SECHelper(user_agent_string="MyApp/1.0 (contact@example.com)")
|
|
118
|
+
|
|
119
|
+
# --- Get CIK for a Ticker Symbol ---
|
|
120
|
+
symbol = "AAPL"
|
|
121
|
+
cik = helper.get_cik_for_symbol(symbol)
|
|
122
|
+
if cik:
|
|
123
|
+
print(f"CIK for {symbol}: {cik}")
|
|
124
|
+
else:
|
|
125
|
+
print(f"Could not find CIK for {symbol}.")
|
|
126
|
+
|
|
127
|
+
# --- Get All Company Facts (XBRL data) ---
|
|
128
|
+
# Can use symbol or CIK
|
|
129
|
+
company_facts = helper.get_company_all_facts(symbol) # or helper.get_company_all_facts(cik)
|
|
130
|
+
if company_facts:
|
|
131
|
+
# This is a large JSON object containing all reported XBRL data for the company.
|
|
132
|
+
# print(json.dumps(company_facts, indent=2)) # Be cautious, can be very large
|
|
133
|
+
print(f"Successfully fetched all facts for {company_facts.get('entityName', symbol)}.")
|
|
134
|
+
# Example: Accessing a specific fact (e.g., Assets for us-gaap)
|
|
135
|
+
# assets_data = company_facts.get('facts', {}).get('us-gaap', {}).get('Assets', {})
|
|
136
|
+
# if assets_data:
|
|
137
|
+
# print(f"Assets data available: {assets_data.get('label')}")
|
|
138
|
+
|
|
139
|
+
# --- Get Specific Company Concept ---
|
|
140
|
+
taxonomy = "us-gaap"
|
|
141
|
+
tag = "Revenues"
|
|
142
|
+
concept_data = helper.get_company_specific_concept(symbol, taxonomy, tag) # or CIK
|
|
143
|
+
if concept_data:
|
|
144
|
+
print(f"\nData for concept '{tag}' ({taxonomy}) for {symbol}:")
|
|
145
|
+
# print(json.dumps(concept_data, indent=2)) # Raw XBRL concept data
|
|
146
|
+
if 'units' in concept_data and 'USD' in concept_data['units']:
|
|
147
|
+
print(f"Label: {concept_data.get('label')}, Description: {concept_data.get('description')}")
|
|
148
|
+
print("Last 2 reported USD values for Revenues:")
|
|
149
|
+
for fact in concept_data['units']['USD'][-2:]: # Print last 2 facts
|
|
150
|
+
print(f" Value: {fact.get('val')}, End Date: {fact.get('end')}, Form: {fact.get('form')}")
|
|
151
|
+
|
|
152
|
+
# --- Get Aggregated Frames Data ---
|
|
153
|
+
# Fetches data for a specific tag across many companies for a given period.
|
|
154
|
+
# Example: Total Assets for all filers in Q1 2023.
|
|
155
|
+
frame_taxonomy = "us-gaap"
|
|
156
|
+
frame_tag = "Assets"
|
|
157
|
+
frame_unit = "USD"
|
|
158
|
+
frame_year = 2023
|
|
159
|
+
frame_quarter = 1 # Optional, for quarterly data
|
|
160
|
+
frame_instantaneous = True # True for balance sheet items
|
|
161
|
+
|
|
162
|
+
assets_frame_data = helper.get_aggregated_frames_data(
|
|
163
|
+
frame_taxonomy, frame_tag, frame_unit, frame_year,
|
|
164
|
+
quarter=frame_quarter, instantaneous=frame_instantaneous
|
|
165
|
+
)
|
|
166
|
+
if assets_frame_data and 'data' in assets_frame_data:
|
|
167
|
+
print(f"\nAggregated '{frame_tag}' data for {frame_year} Q{frame_quarter}:")
|
|
168
|
+
print(f"Total companies reporting: {len(assets_frame_data['data'])}")
|
|
169
|
+
# print(json.dumps(assets_frame_data['data'][:2], indent=2)) # Print data for first 2 companies
|
|
170
|
+
else:
|
|
171
|
+
print(f"No aggregated '{frame_tag}' data found for {frame_year} Q{frame_quarter}.")
|
|
172
|
+
|
|
173
|
+
# --- Get Formatted Financial Statements ---
|
|
174
|
+
|
|
175
|
+
# Get the last 3 Income Statements (combining 10-K and 10-Q, most recent first)
|
|
176
|
+
income_all = helper.get_income_statement(symbol, limit=3)
|
|
177
|
+
print(f"--- Income Statements (ALL, limit 3) for {symbol} ---")
|
|
178
|
+
# print(json.dumps(income_all, indent=2))
|
|
179
|
+
|
|
180
|
+
# Get the last 2 annual (10-K) Income Statements
|
|
181
|
+
income_10k = helper.get_income_statement(symbol, limit=2, report_type="10-K")
|
|
182
|
+
print(f"\n--- Income Statements (10-K, limit 2) for {symbol} ---")
|
|
183
|
+
# print(json.dumps(income_10k, indent=2))
|
|
184
|
+
if income_10k:
|
|
185
|
+
for report in income_10k:
|
|
186
|
+
print(f"Date: {report['date']}, Form: {report['_formType_original']}, Revenue: {report['revenue']}")
|
|
187
|
+
|
|
188
|
+
# Get the last 4 quarterly (10-Q) Balance Sheets
|
|
189
|
+
balance_sheet_10q = helper.get_balance_sheet(symbol, limit=4, report_type="10-Q")
|
|
190
|
+
print(f"\n--- Balance Sheets (10-Q, limit 4) for {symbol} ---")
|
|
191
|
+
# print(json.dumps(balance_sheet_10q, indent=2))
|
|
192
|
+
if balance_sheet_10q:
|
|
193
|
+
for report in balance_sheet_10q:
|
|
194
|
+
print(f"Date: {report['date']}, Form: {report['_formType_original']}, Total Assets: {report['totalAssets']}")
|
|
195
|
+
|
|
196
|
+
# Get Cash Flow Statement (last 2 periods)
|
|
197
|
+
cash_flow_statement = helper.get_cash_flow_statement(symbol, limit=2)
|
|
198
|
+
print(f"\nCash Flow Statement for {symbol} (last {len(cash_flow_statement)} periods):")
|
|
199
|
+
# print(json.dumps(cash_flow_statement, indent=2))
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
*(Please replace the example above with a concise, working example of how to use your library.)*
|
|
203
|
+
|
|
204
|
+
## Dependencies
|
|
205
|
+
|
|
206
|
+
* requests (>=2.20.0)
|
|
207
|
+
|
|
208
|
+
## Contributing
|
|
209
|
+
Contributions are welcome! Please see the Bug Tracker for issues or to submit a pull request.
|
|
210
|
+
|
|
211
|
+
## License
|
|
212
|
+
This project is licensed under the MIT License - see the LICENSE file for details.
|
|
213
|
+
|
|
214
|
+
## Project Links
|
|
215
|
+
* Homepage
|
|
216
|
+
* Bug Tracker
|
|
@@ -0,0 +1,197 @@
|
|
|
1
|
+
# sec-financial-data
|
|
2
|
+
|
|
3
|
+
[](https://badge.fury.io/py/sec-financial-data)
|
|
4
|
+
|
|
5
|
+
This Python package, sec-financial-data, is designed to simplify the process of retrieving and accessing publicly available financial data from the U.S. Securities and Exchange Commission's (SEC) EDGAR database. It acts as a convenient wrapper around the SEC's EDGAR APIs, providing a more Pythonic and user-friendly interface for developers and financial analysts.
|
|
6
|
+
|
|
7
|
+
Core Purpose:
|
|
8
|
+
|
|
9
|
+
The primary goal of the package is to enable users to programmatically fetch various types of financial information for publicly traded companies. This includes:
|
|
10
|
+
|
|
11
|
+
1. Company identification data (CIK numbers).
|
|
12
|
+
2. Raw XBRL (eXtensible Business Reporting Language) data, which forms the basis of SEC filings.
|
|
13
|
+
3. Formatted financial statements like Income Statements, Balance Sheets, and Cash Flow Statements.
|
|
14
|
+
4. Aggregated financial data points across multiple companies for comparative analysis.
|
|
15
|
+
|
|
16
|
+
Key Features & Functionality:
|
|
17
|
+
|
|
18
|
+
1. User-Agent Management: The package emphasizes responsible API usage by allowing and encouraging users to set a custom User-Agent string, which is a requirement by the SEC for programmatic access.
|
|
19
|
+
2. Rate Limiting: It incorporates a basic rate-limiting mechanism to ensure that requests to the SEC EDGAR APIs do not exceed the allowed limit (10 requests per second), preventing potential IP blocks.
|
|
20
|
+
3. CIK Lookup:
|
|
21
|
+
1. Provides a function (get_cik_for_symbol) to retrieve a company's Central Index Key (CIK) using its stock ticker symbol.
|
|
22
|
+
2. The CIK map is fetched from the SEC and cached (@lru_cache) to improve performance for subsequent lookups.
|
|
23
|
+
4. Access to Raw XBRL Data:
|
|
24
|
+
1. get_company_all_facts(): Fetches the complete set of XBRL data (company facts) for a given CIK or ticker symbol. This is a comprehensive JSON object containing all reported financial concepts and their values over time.
|
|
25
|
+
2. get_company_specific_concept(): Allows users to retrieve data for a specific XBRL concept (e.g., "Revenues," "Assets") within a particular taxonomy (e.g., "us-gaap") for a company.
|
|
26
|
+
5. Aggregated Data (Frames API):
|
|
27
|
+
1. get_aggregated_frames_data(): Interacts with the SEC's "frames" API to fetch aggregated data for a specific XBRL tag, unit, and period (year/quarter) across all reporting entities. This is useful for market-wide analysis or peer comparisons.
|
|
28
|
+
6. Formatted Financial Statements:
|
|
29
|
+
1. The core of its value proposition for many users lies in the get_financial_statement() function and its specific wrappers: get_income_statement(), get_balance_sheet(), and get_cash_flow_statement().
|
|
30
|
+
2. These functions take raw XBRL data (obtained via get_company_facts()) and attempt to parse and structure it into a more conventional and readable JSON format for standard financial statements.
|
|
31
|
+
3. Data Normalization Logic:
|
|
32
|
+
1. It identifies relevant XBRL tags for common line items in each statement type (e.g., "Revenues", "NetIncomeLoss", "Assets", "CashAndCashEquivalentsAtCarryingValue").
|
|
33
|
+
2. It includes a list of primary and alternate XBRL tags for many financial line items, acknowledging that companies might use different tags for similar concepts. The _get_financial_value() helper method is crucial here, trying a primary tag first and then falling back to alternates.
|
|
34
|
+
3. It processes facts from 10-K (annual) and 10-Q (quarterly) filings.
|
|
35
|
+
4. It identifies the "canonical" report for each period (latest filing for a given end date) to avoid using superseded data.
|
|
36
|
+
5. It sorts reports chronologically and allows users to specify a limit for the number of recent periods.
|
|
37
|
+
6. It performs some derivations (e.g., calculating Gross Profit if not directly reported, deriving EBITDA, Net Debt).
|
|
38
|
+
7. SECHelper Class: This class serves as the main public interface for the package, encapsulating all the user-facing methods for easy access.
|
|
39
|
+
|
|
40
|
+
How it Works (High-Level):
|
|
41
|
+
|
|
42
|
+
1. The user initializes the SECHelper class, optionally providing a `user_agent_string`.
|
|
43
|
+
2. When a method is called (e.g., get_income_statement("AAPL")):
|
|
44
|
+
1. If a ticker symbol is provided, it's first converted to a CIK.
|
|
45
|
+
2. The necessary SEC API endpoint is constructed.
|
|
46
|
+
3. A rate-limited HTTP GET request is made to the SEC API using the requests library.
|
|
47
|
+
4. The JSON response from the API is retrieved.
|
|
48
|
+
5. For financial statement functions, the extensive get_company_facts() data is processed:
|
|
49
|
+
1. Facts are filtered and grouped by filing (10-K/10-Q) and period.
|
|
50
|
+
2. The most recent, relevant filings are selected.
|
|
51
|
+
3. Values for predefined financial statement line items are extracted using the primary/alternate tag logic.
|
|
52
|
+
4. Some line items are calculated based on others.
|
|
53
|
+
6. The final data is returned as a Python dictionary or list of dictionaries.
|
|
54
|
+
|
|
55
|
+
Target Audience:
|
|
56
|
+
|
|
57
|
+
1. Developers: Building financial applications, tools, or dashboards.
|
|
58
|
+
2. Financial Analysts & Researchers: Performing quantitative analysis, company valuation, or market research.
|
|
59
|
+
3. Students & Hobbyists: Learning about financial data and programming.
|
|
60
|
+
|
|
61
|
+
Key Abstractions:
|
|
62
|
+
|
|
63
|
+
1. It abstracts away the complexities of directly interacting with the SEC EDGAR APIs (endpoint URLs, rate limits, raw XBRL structure).
|
|
64
|
+
2. It attempts to normalize the varied XBRL tags into a more standardized set of financial line items, though this is inherently challenging due to the flexibility of XBRL.
|
|
65
|
+
|
|
66
|
+
Important Considerations for Users:
|
|
67
|
+
|
|
68
|
+
1. XBRL Tag Variability: Financial data reporting using XBRL can vary between companies and over time. While the package uses a list of common and alternate tags, it might not capture every possible variation for every company. Users might need to inspect the raw company_facts for specific or less common tags.
|
|
69
|
+
2. Data Accuracy: The package relies on the data as reported to the SEC. The parsing and normalization logic aims for accuracy but is based on common US GAAP interpretations.
|
|
70
|
+
3. API Changes: The SEC may update its APIs, which could potentially require updates to the package.
|
|
71
|
+
4. User-Agent: It's crucial to provide a descriptive user_agent for responsible API usage.
|
|
72
|
+
|
|
73
|
+
In summary, sec-financial-data provides a valuable toolkit for accessing and working with SEC financial data in Python, significantly lowering the barrier to entry for retrieving and making sense of this rich dataset. It balances ease of use for common financial statements with the ability to access raw, detailed XBRL data for more advanced use cases.
|
|
74
|
+
|
|
75
|
+
## Features
|
|
76
|
+
|
|
77
|
+
* Fetch financial statements (10-K, 10-Q) for a given company.
|
|
78
|
+
* Extract specific financial data points.
|
|
79
|
+
* User-friendly API.
|
|
80
|
+
|
|
81
|
+
## Installation
|
|
82
|
+
|
|
83
|
+
You can install `sec-financial-data` from PyPI:
|
|
84
|
+
|
|
85
|
+
```bash
|
|
86
|
+
pip install sec-financial-data
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
Requires Python 3.7+.
|
|
90
|
+
|
|
91
|
+
## Usage
|
|
92
|
+
```python
|
|
93
|
+
from sec_financial_data.sec_financial_data import SECHelper
|
|
94
|
+
import json
|
|
95
|
+
|
|
96
|
+
# It's highly recommended to provide a descriptive user-agent.
|
|
97
|
+
# Replace "YourAppName/1.0" and "your-email@example.com" accordingly.
|
|
98
|
+
helper = SECHelper(user_agent_string="MyApp/1.0 (contact@example.com)")
|
|
99
|
+
|
|
100
|
+
# --- Get CIK for a Ticker Symbol ---
|
|
101
|
+
symbol = "AAPL"
|
|
102
|
+
cik = helper.get_cik_for_symbol(symbol)
|
|
103
|
+
if cik:
|
|
104
|
+
print(f"CIK for {symbol}: {cik}")
|
|
105
|
+
else:
|
|
106
|
+
print(f"Could not find CIK for {symbol}.")
|
|
107
|
+
|
|
108
|
+
# --- Get All Company Facts (XBRL data) ---
|
|
109
|
+
# Can use symbol or CIK
|
|
110
|
+
company_facts = helper.get_company_all_facts(symbol) # or helper.get_company_all_facts(cik)
|
|
111
|
+
if company_facts:
|
|
112
|
+
# This is a large JSON object containing all reported XBRL data for the company.
|
|
113
|
+
# print(json.dumps(company_facts, indent=2)) # Be cautious, can be very large
|
|
114
|
+
print(f"Successfully fetched all facts for {company_facts.get('entityName', symbol)}.")
|
|
115
|
+
# Example: Accessing a specific fact (e.g., Assets for us-gaap)
|
|
116
|
+
# assets_data = company_facts.get('facts', {}).get('us-gaap', {}).get('Assets', {})
|
|
117
|
+
# if assets_data:
|
|
118
|
+
# print(f"Assets data available: {assets_data.get('label')}")
|
|
119
|
+
|
|
120
|
+
# --- Get Specific Company Concept ---
|
|
121
|
+
taxonomy = "us-gaap"
|
|
122
|
+
tag = "Revenues"
|
|
123
|
+
concept_data = helper.get_company_specific_concept(symbol, taxonomy, tag) # or CIK
|
|
124
|
+
if concept_data:
|
|
125
|
+
print(f"\nData for concept '{tag}' ({taxonomy}) for {symbol}:")
|
|
126
|
+
# print(json.dumps(concept_data, indent=2)) # Raw XBRL concept data
|
|
127
|
+
if 'units' in concept_data and 'USD' in concept_data['units']:
|
|
128
|
+
print(f"Label: {concept_data.get('label')}, Description: {concept_data.get('description')}")
|
|
129
|
+
print("Last 2 reported USD values for Revenues:")
|
|
130
|
+
for fact in concept_data['units']['USD'][-2:]: # Print last 2 facts
|
|
131
|
+
print(f" Value: {fact.get('val')}, End Date: {fact.get('end')}, Form: {fact.get('form')}")
|
|
132
|
+
|
|
133
|
+
# --- Get Aggregated Frames Data ---
|
|
134
|
+
# Fetches data for a specific tag across many companies for a given period.
|
|
135
|
+
# Example: Total Assets for all filers in Q1 2023.
|
|
136
|
+
frame_taxonomy = "us-gaap"
|
|
137
|
+
frame_tag = "Assets"
|
|
138
|
+
frame_unit = "USD"
|
|
139
|
+
frame_year = 2023
|
|
140
|
+
frame_quarter = 1 # Optional, for quarterly data
|
|
141
|
+
frame_instantaneous = True # True for balance sheet items
|
|
142
|
+
|
|
143
|
+
assets_frame_data = helper.get_aggregated_frames_data(
|
|
144
|
+
frame_taxonomy, frame_tag, frame_unit, frame_year,
|
|
145
|
+
quarter=frame_quarter, instantaneous=frame_instantaneous
|
|
146
|
+
)
|
|
147
|
+
if assets_frame_data and 'data' in assets_frame_data:
|
|
148
|
+
print(f"\nAggregated '{frame_tag}' data for {frame_year} Q{frame_quarter}:")
|
|
149
|
+
print(f"Total companies reporting: {len(assets_frame_data['data'])}")
|
|
150
|
+
# print(json.dumps(assets_frame_data['data'][:2], indent=2)) # Print data for first 2 companies
|
|
151
|
+
else:
|
|
152
|
+
print(f"No aggregated '{frame_tag}' data found for {frame_year} Q{frame_quarter}.")
|
|
153
|
+
|
|
154
|
+
# --- Get Formatted Financial Statements ---
|
|
155
|
+
|
|
156
|
+
# Get the last 3 Income Statements (combining 10-K and 10-Q, most recent first)
|
|
157
|
+
income_all = helper.get_income_statement(symbol, limit=3)
|
|
158
|
+
print(f"--- Income Statements (ALL, limit 3) for {symbol} ---")
|
|
159
|
+
# print(json.dumps(income_all, indent=2))
|
|
160
|
+
|
|
161
|
+
# Get the last 2 annual (10-K) Income Statements
|
|
162
|
+
income_10k = helper.get_income_statement(symbol, limit=2, report_type="10-K")
|
|
163
|
+
print(f"\n--- Income Statements (10-K, limit 2) for {symbol} ---")
|
|
164
|
+
# print(json.dumps(income_10k, indent=2))
|
|
165
|
+
if income_10k:
|
|
166
|
+
for report in income_10k:
|
|
167
|
+
print(f"Date: {report['date']}, Form: {report['_formType_original']}, Revenue: {report['revenue']}")
|
|
168
|
+
|
|
169
|
+
# Get the last 4 quarterly (10-Q) Balance Sheets
|
|
170
|
+
balance_sheet_10q = helper.get_balance_sheet(symbol, limit=4, report_type="10-Q")
|
|
171
|
+
print(f"\n--- Balance Sheets (10-Q, limit 4) for {symbol} ---")
|
|
172
|
+
# print(json.dumps(balance_sheet_10q, indent=2))
|
|
173
|
+
if balance_sheet_10q:
|
|
174
|
+
for report in balance_sheet_10q:
|
|
175
|
+
print(f"Date: {report['date']}, Form: {report['_formType_original']}, Total Assets: {report['totalAssets']}")
|
|
176
|
+
|
|
177
|
+
# Get Cash Flow Statement (last 2 periods)
|
|
178
|
+
cash_flow_statement = helper.get_cash_flow_statement(symbol, limit=2)
|
|
179
|
+
print(f"\nCash Flow Statement for {symbol} (last {len(cash_flow_statement)} periods):")
|
|
180
|
+
# print(json.dumps(cash_flow_statement, indent=2))
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
*(Please replace the example above with a concise, working example of how to use your library.)*
|
|
184
|
+
|
|
185
|
+
## Dependencies
|
|
186
|
+
|
|
187
|
+
* requests (>=2.20.0)
|
|
188
|
+
|
|
189
|
+
## Contributing
|
|
190
|
+
Contributions are welcome! Please see the Bug Tracker for issues or to submit a pull request.
|
|
191
|
+
|
|
192
|
+
## License
|
|
193
|
+
This project is licensed under the MIT License - see the LICENSE file for details.
|
|
194
|
+
|
|
195
|
+
## Project Links
|
|
196
|
+
* Homepage
|
|
197
|
+
* Bug Tracker
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
# /Users/armittal/sec_api/pyproject.toml
|
|
2
|
+
[build-system]
|
|
3
|
+
requires = ["setuptools>=61.0"]
|
|
4
|
+
build-backend = "setuptools.build_meta"
|
|
5
|
+
|
|
6
|
+
[project]
|
|
7
|
+
name = "sec-financial-data" # Choose a unique name for PyPI
|
|
8
|
+
version = "0.1.0"
|
|
9
|
+
authors = [
|
|
10
|
+
{ name="Arun Mittal", email="arun.mittal.sjsu@gmail.com" },
|
|
11
|
+
]
|
|
12
|
+
description = "A Python package to retrieve financial data from SEC EDGAR."
|
|
13
|
+
readme = "README.md"
|
|
14
|
+
requires-python = ">=3.7"
|
|
15
|
+
classifiers = [
|
|
16
|
+
"Programming Language :: Python :: 3",
|
|
17
|
+
"Operating System :: OS Independent",
|
|
18
|
+
"Intended Audience :: Developers",
|
|
19
|
+
"Intended Audience :: Financial and Insurance Industry",
|
|
20
|
+
"Topic :: Office/Business :: Financial",
|
|
21
|
+
"Topic :: Software Development :: Libraries :: Python Modules",
|
|
22
|
+
]
|
|
23
|
+
dependencies = [
|
|
24
|
+
"requests>=2.20.0",
|
|
25
|
+
]
|
|
26
|
+
|
|
27
|
+
[project.urls]
|
|
28
|
+
"Homepage" = "https://github.com/armittal89/sec_api"
|
|
29
|
+
"Bug Tracker" = "https://github.com/armittal89/sec_api/issues"
|
|
30
|
+
|
|
31
|
+
[tool.setuptools]
|
|
32
|
+
license-files = ["LICENSE"]
|