# SEC EDGAR Toolkit - Python
[](https://python.org)
[](https://pypi.org/project/sec-edgar-toolkit/)
[](LICENSE)
[](htmlcov/index.html)
[](https://github.com/astral-sh/ruff)
[](https://mypy.readthedocs.io/)
[](tests/)
## Disclaimer
**This toolkit is not affiliated with, endorsed by, or connected to the U.S. Securities and Exchange Commission (SEC).** This is an independent open-source project designed to facilitate programmatic access to publicly available SEC EDGAR data.
- **Use at your own risk**: Users are responsible for ensuring compliance with all applicable laws and regulations
- **Rate limiting**: Please respect the SEC's [fair access policy](https://www.sec.gov/os/accessing-edgar-data) (max 10 requests per second)
- **Data accuracy**: This tool provides access to data as-is from SEC EDGAR; users should verify important information independently
- **No warranties**: This software is provided "as is" without any warranties or guarantees
## Overview
A comprehensive Python library for accessing and analyzing SEC EDGAR filings, with support for XBRL data parsing, company lookup, and financial data extraction. Built on top of the official [SEC EDGAR APIs](https://www.sec.gov/search-filings/edgar-application-programming-interfaces).
## Key Features
- **Company Lookup**: Search by ticker, CIK, or company name
- **Filing Access**: Get 10-K, 10-Q, 8-K, and other SEC filings
- **XBRL Support**: Parse and analyze structured financial data
- **Frame Data**: Access market-wide aggregated XBRL data
- **Rate Limiting**: Built-in respect for SEC fair access policies
- **Type Safety**: Full type hints and mypy compatibility
- **Well Tested**: 97% test coverage with comprehensive test suite
## Installation
```bash
pip install sec-edgar-toolkit
```
## Quick Start
```python
from sec_edgar_toolkit import SecEdgarApi
# Initialize with required User-Agent (SEC requirement)
api = SecEdgarApi(user_agent="MyCompany/1.0 (contact@example.com)")
# Find Apple by ticker
company = api.get_company_by_ticker("AAPL")
print(f"Company: {company['title']}, CIK: {company['cik_str']}")
# Get recent filings
submissions = api.get_company_submissions(company['cik_str'])
recent_filings = submissions['filings']['recent']
```
## API Reference
### Company Information
```python
# Search by ticker symbol
company = api.get_company_by_ticker("AAPL")
# Search by CIK (Central Index Key)
company = api.get_company_by_cik("0000320193")
# Search companies by name
results = api.search_companies("Apple")
# Get all company tickers (cached for 24 hours)
all_tickers = api.get_company_tickers()
```
### Company Filings & Submissions
```python
# Get all submissions for a company
submissions = api.get_company_submissions("0000320193")
# Filter by form type
annual_reports = api.get_company_submissions(
"0000320193",
submission_type="10-K"
)
# Filter by date range
recent_filings = api.get_company_submissions(
"0000320193",
from_date="2023-01-01",
to_date="2023-12-31"
)
# Get specific filing details
filing = api.get_filing("0000320193", "0000320193-23-000077")
```
### XBRL Financial Data
```python
# Get company facts (all XBRL data for a company)
facts = api.get_company_facts("0000320193")
# Get specific concept data (e.g., Assets over time)
assets = api.get_company_concept(
cik="0000320193",
taxonomy="us-gaap",
tag="Assets",
unit="USD"
)
# Get market-wide frame data (aggregated across all companies)
market_data = api.get_frames(
taxonomy="us-gaap",
tag="Revenues",
unit="USD",
year=2023
)
# Get quarterly data
quarterly_data = api.get_frames(
taxonomy="us-gaap",
tag="Assets",
unit="USD",
year=2023,
quarter=4
)
```
## Complete Example
```python
from sec_edgar_toolkit import SecEdgarApi, SecEdgarApiError
from datetime import datetime, timedelta
# Initialize API client
api = SecEdgarApi(user_agent="MyApp/1.0 (contact@example.com)")
try:
# Find a company
company = api.get_company_by_ticker("AAPL")
if not company:
print("Company not found")
return
cik = company['cik_str']
print(f"Found: {company['title']} (CIK: {cik})")
# Get recent 10-K filings
end_date = datetime.now()
start_date = end_date - timedelta(days=2*365) # Last 2 years
filings = api.get_company_submissions(
cik,
submission_type="10-K",
from_date=start_date.strftime("%Y-%m-%d"),
to_date=end_date.strftime("%Y-%m-%d")
)
print(f"Found {len(filings['filings']['recent']['form'])} 10-K filings")
# Get financial facts
facts = api.get_company_facts(cik)
if 'us-gaap' in facts['facts']:
gaap_concepts = facts['facts']['us-gaap']
print(f"Available GAAP concepts: {len(gaap_concepts)}")
# Get revenue data over time
if 'Revenues' in gaap_concepts:
revenue_data = api.get_company_concept(
cik, "us-gaap", "Revenues", unit="USD"
)
usd_data = revenue_data['units']['USD']
annual_revenue = [d for d in usd_data if d.get('fp') == 'FY']
print("Annual Revenue:")
for item in annual_revenue[-3:]: # Last 3 years
revenue_b = item['val'] / 1_000_000_000
print(f" FY {item['fy']}: ${revenue_b:.1f}B")
except SecEdgarApiError as e:
print(f"API Error: {e}")
```
## Rate Limiting & Fair Access
This library automatically implements the SEC's fair access requirements:
- **Rate limiting**: Maximum 10 requests per second
- **User-Agent required**: Must include your app name and contact info
- **Retry logic**: Built-in exponential backoff for failed requests
Learn more about the [SEC's fair access policy](https://www.sec.gov/os/accessing-edgar-data).
## Error Handling
```python
from sec_edgar_toolkit import (
SecEdgarApiError,
RateLimitError,
NotFoundError,
AuthenticationError
)
try:
company = api.get_company_by_ticker("INVALID")
except NotFoundError:
print("Company not found")
except RateLimitError:
print("Rate limit exceeded - please wait")
except SecEdgarApiError as e:
print(f"API error: {e}")
```
## Development
```bash
# Install in development mode
pip install -e ".[dev]"
# Run tests
pytest tests/ -v
# Run linting
ruff check src/ tests/
# Run type checking
mypy src/ tests/
# Generate coverage report
pytest --cov=src tests/
```
## Resources
- [SEC EDGAR APIs Documentation](https://www.sec.gov/search-filings/edgar-application-programming-interfaces)
- [SEC Fair Access Policy](https://www.sec.gov/os/accessing-edgar-data)
- [XBRL Taxonomy Guide](https://www.sec.gov/structureddata/osd-inline-xbrl-faq)
- [Company Tickers JSON](https://www.sec.gov/files/company_tickers_exchange.json)
## License
GNU General Public License v3.0 - see [LICENSE](LICENSE) file for details.
## Contributing
Contributions are welcome! Please see our [CONTRIBUTING](CONTRIBUTING.md) guide for details on how to get started.
For major changes, please open an issue first to discuss what you would like to change.
Raw data
{
"_id": null,
"home_page": null,
"name": "sec-edgar-toolkit",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "SEC, EDGAR, finance, filings, 10-K, 10-Q, 8-K, securities",
"author": null,
"author_email": "Stefano Amorelli <stefano@amorelli.tech>",
"download_url": "https://files.pythonhosted.org/packages/6e/4c/56da241bf7808025ae7a1753e879ff7995eb9f7c4a1a410a85fcecbe609f/sec_edgar_toolkit-0.1.0.tar.gz",
"platform": null,
"description": "# SEC EDGAR Toolkit - Python\n\n[](https://python.org)\n[](https://pypi.org/project/sec-edgar-toolkit/)\n[](LICENSE)\n[](htmlcov/index.html)\n[](https://github.com/astral-sh/ruff)\n[](https://mypy.readthedocs.io/)\n[](tests/)\n\n## Disclaimer\n\n**This toolkit is not affiliated with, endorsed by, or connected to the U.S. Securities and Exchange Commission (SEC).** This is an independent open-source project designed to facilitate programmatic access to publicly available SEC EDGAR data.\n\n- **Use at your own risk**: Users are responsible for ensuring compliance with all applicable laws and regulations\n- **Rate limiting**: Please respect the SEC's [fair access policy](https://www.sec.gov/os/accessing-edgar-data) (max 10 requests per second)\n- **Data accuracy**: This tool provides access to data as-is from SEC EDGAR; users should verify important information independently\n- **No warranties**: This software is provided \"as is\" without any warranties or guarantees\n\n## Overview\n\nA comprehensive Python library for accessing and analyzing SEC EDGAR filings, with support for XBRL data parsing, company lookup, and financial data extraction. Built on top of the official [SEC EDGAR APIs](https://www.sec.gov/search-filings/edgar-application-programming-interfaces).\n\n## Key Features\n\n- **Company Lookup**: Search by ticker, CIK, or company name\n- **Filing Access**: Get 10-K, 10-Q, 8-K, and other SEC filings\n- **XBRL Support**: Parse and analyze structured financial data\n- **Frame Data**: Access market-wide aggregated XBRL data\n- **Rate Limiting**: Built-in respect for SEC fair access policies\n- **Type Safety**: Full type hints and mypy compatibility\n- **Well Tested**: 97% test coverage with comprehensive test suite\n\n## Installation\n\n```bash\npip install sec-edgar-toolkit\n```\n\n## Quick Start\n\n```python\nfrom sec_edgar_toolkit import SecEdgarApi\n\n# Initialize with required User-Agent (SEC requirement)\napi = SecEdgarApi(user_agent=\"MyCompany/1.0 (contact@example.com)\")\n\n# Find Apple by ticker\ncompany = api.get_company_by_ticker(\"AAPL\")\nprint(f\"Company: {company['title']}, CIK: {company['cik_str']}\")\n\n# Get recent filings\nsubmissions = api.get_company_submissions(company['cik_str'])\nrecent_filings = submissions['filings']['recent']\n```\n\n## API Reference\n\n### Company Information\n\n```python\n# Search by ticker symbol\ncompany = api.get_company_by_ticker(\"AAPL\")\n\n# Search by CIK (Central Index Key)\ncompany = api.get_company_by_cik(\"0000320193\")\n\n# Search companies by name\nresults = api.search_companies(\"Apple\")\n\n# Get all company tickers (cached for 24 hours)\nall_tickers = api.get_company_tickers()\n```\n\n### Company Filings & Submissions\n\n```python\n# Get all submissions for a company\nsubmissions = api.get_company_submissions(\"0000320193\")\n\n# Filter by form type\nannual_reports = api.get_company_submissions(\n \"0000320193\", \n submission_type=\"10-K\"\n)\n\n# Filter by date range\nrecent_filings = api.get_company_submissions(\n \"0000320193\",\n from_date=\"2023-01-01\",\n to_date=\"2023-12-31\"\n)\n\n# Get specific filing details\nfiling = api.get_filing(\"0000320193\", \"0000320193-23-000077\")\n```\n\n### XBRL Financial Data\n\n```python\n# Get company facts (all XBRL data for a company)\nfacts = api.get_company_facts(\"0000320193\")\n\n# Get specific concept data (e.g., Assets over time)\nassets = api.get_company_concept(\n cik=\"0000320193\",\n taxonomy=\"us-gaap\", \n tag=\"Assets\",\n unit=\"USD\"\n)\n\n# Get market-wide frame data (aggregated across all companies)\nmarket_data = api.get_frames(\n taxonomy=\"us-gaap\",\n tag=\"Revenues\", \n unit=\"USD\",\n year=2023\n)\n\n# Get quarterly data\nquarterly_data = api.get_frames(\n taxonomy=\"us-gaap\",\n tag=\"Assets\",\n unit=\"USD\", \n year=2023,\n quarter=4\n)\n```\n\n## Complete Example\n\n```python\nfrom sec_edgar_toolkit import SecEdgarApi, SecEdgarApiError\nfrom datetime import datetime, timedelta\n\n# Initialize API client\napi = SecEdgarApi(user_agent=\"MyApp/1.0 (contact@example.com)\")\n\ntry:\n # Find a company\n company = api.get_company_by_ticker(\"AAPL\")\n if not company:\n print(\"Company not found\")\n return\n \n cik = company['cik_str']\n print(f\"Found: {company['title']} (CIK: {cik})\")\n \n # Get recent 10-K filings\n end_date = datetime.now()\n start_date = end_date - timedelta(days=2*365) # Last 2 years\n \n filings = api.get_company_submissions(\n cik,\n submission_type=\"10-K\",\n from_date=start_date.strftime(\"%Y-%m-%d\"),\n to_date=end_date.strftime(\"%Y-%m-%d\")\n )\n \n print(f\"Found {len(filings['filings']['recent']['form'])} 10-K filings\")\n \n # Get financial facts\n facts = api.get_company_facts(cik)\n if 'us-gaap' in facts['facts']:\n gaap_concepts = facts['facts']['us-gaap']\n print(f\"Available GAAP concepts: {len(gaap_concepts)}\")\n \n # Get revenue data over time\n if 'Revenues' in gaap_concepts:\n revenue_data = api.get_company_concept(\n cik, \"us-gaap\", \"Revenues\", unit=\"USD\"\n )\n usd_data = revenue_data['units']['USD']\n annual_revenue = [d for d in usd_data if d.get('fp') == 'FY']\n \n print(\"Annual Revenue:\")\n for item in annual_revenue[-3:]: # Last 3 years\n revenue_b = item['val'] / 1_000_000_000\n print(f\" FY {item['fy']}: ${revenue_b:.1f}B\")\n\nexcept SecEdgarApiError as e:\n print(f\"API Error: {e}\")\n```\n\n## Rate Limiting & Fair Access\n\nThis library automatically implements the SEC's fair access requirements:\n\n- **Rate limiting**: Maximum 10 requests per second\n- **User-Agent required**: Must include your app name and contact info\n- **Retry logic**: Built-in exponential backoff for failed requests\n\nLearn more about the [SEC's fair access policy](https://www.sec.gov/os/accessing-edgar-data).\n\n## Error Handling\n\n```python\nfrom sec_edgar_toolkit import (\n SecEdgarApiError,\n RateLimitError, \n NotFoundError,\n AuthenticationError\n)\n\ntry:\n company = api.get_company_by_ticker(\"INVALID\")\nexcept NotFoundError:\n print(\"Company not found\")\nexcept RateLimitError:\n print(\"Rate limit exceeded - please wait\")\nexcept SecEdgarApiError as e:\n print(f\"API error: {e}\")\n```\n\n## Development\n\n```bash\n# Install in development mode\npip install -e \".[dev]\"\n\n# Run tests\npytest tests/ -v\n\n# Run linting\nruff check src/ tests/\n\n# Run type checking \nmypy src/ tests/\n\n# Generate coverage report\npytest --cov=src tests/\n```\n\n## Resources\n\n- [SEC EDGAR APIs Documentation](https://www.sec.gov/search-filings/edgar-application-programming-interfaces)\n- [SEC Fair Access Policy](https://www.sec.gov/os/accessing-edgar-data)\n- [XBRL Taxonomy Guide](https://www.sec.gov/structureddata/osd-inline-xbrl-faq)\n- [Company Tickers JSON](https://www.sec.gov/files/company_tickers_exchange.json)\n\n## License\n\nGNU General Public License v3.0 - see [LICENSE](LICENSE) file for details.\n\n## Contributing\n\nContributions are welcome! Please see our [CONTRIBUTING](CONTRIBUTING.md) guide for details on how to get started.\n\nFor major changes, please open an issue first to discuss what you would like to change.\n",
"bugtrack_url": null,
"license": "AGPL-3.0",
"summary": "Open source toolkit to facilitate working with the SEC EDGAR database",
"version": "0.1.0",
"project_urls": {
"Documentation": "https://github.com/stefanoamorelli/sec-edgar-toolkit#readme",
"Homepage": "https://github.com/stefanoamorelli/sec-edgar-toolkit",
"Issues": "https://github.com/stefanoamorelli/sec-edgar-toolkit/issues",
"Repository": "https://github.com/stefanoamorelli/sec-edgar-toolkit.git"
},
"split_keywords": [
"sec",
" edgar",
" finance",
" filings",
" 10-k",
" 10-q",
" 8-k",
" securities"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "4f9205aff3cdfccdf68d3b5690bec277419fdbf23c77b96c20e1f046286ab8b4",
"md5": "b450f037adac799c5a7adcce71c6d754",
"sha256": "acfeedb3c788d972d536711a9ff56861ccb3484adc60b1d799e976592c795bf2"
},
"downloads": -1,
"filename": "sec_edgar_toolkit-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b450f037adac799c5a7adcce71c6d754",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 61051,
"upload_time": "2025-08-10T20:09:51",
"upload_time_iso_8601": "2025-08-10T20:09:51.837200Z",
"url": "https://files.pythonhosted.org/packages/4f/92/05aff3cdfccdf68d3b5690bec277419fdbf23c77b96c20e1f046286ab8b4/sec_edgar_toolkit-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "6e4c56da241bf7808025ae7a1753e879ff7995eb9f7c4a1a410a85fcecbe609f",
"md5": "f188a804e63ffda6a80f26f2252ebe38",
"sha256": "c1e1bd2f538217497623ff2d72eff498bcbd00a182be9f1b3452c1414c42896f"
},
"downloads": -1,
"filename": "sec_edgar_toolkit-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "f188a804e63ffda6a80f26f2252ebe38",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 61745,
"upload_time": "2025-08-10T20:09:53",
"upload_time_iso_8601": "2025-08-10T20:09:53.230338Z",
"url": "https://files.pythonhosted.org/packages/6e/4c/56da241bf7808025ae7a1753e879ff7995eb9f7c4a1a410a85fcecbe609f/sec_edgar_toolkit-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-10 20:09:53",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "stefanoamorelli",
"github_project": "sec-edgar-toolkit#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "sec-edgar-toolkit"
}
JSON
