Python SEC

A lightweight Python client for the SEC EDGAR API. Look up companies by ticker, search filings, download documents, and query XBRL financial data — all in a few lines of code.

Quick Start

pip install python-sec

from edgar.client import EdgarClient

# SEC requires a User-Agent identifying you.
client = EdgarClient(user_agent="Your Name your-email@example.com")

# Look up Apple's 10-K filings — by ticker, no CIK needed.
company = client.company("AAPL")
filings = company.get_filings(form="10-K")

print(filings[0])
# <Filing form='10-K' date='2024-11-01' title='10-K - Annual report ...'>

# Get structured company metadata.
info = company.get_info()
print(info.name, info.tickers, info.sic_description)
# Apple Inc. ['AAPL'] ELECTRONIC COMPUTERS

# Access XBRL facts.
facts = company.xbrl_facts()

Installation

pip install python-sec          # from PyPI
pip install --upgrade python-sec  # upgrade
pip install -e .                 # local dev (editable mode)

Services

Usage Examples

Ticker Resolution

# Ticker → CIK
cik = client.resolve_ticker("MSFT")  # "0000789019"

# CIK → company info
entries = client.resolve_cik("789019")
# [{'cik_str': 789019, 'ticker': 'MSFT', 'title': 'MICROSOFT CORP'}]

# Search by company name
results = client.tickers().search("Tesla")

Company Research (Fluent API)

company = client.company("META")

# Structured Filing objects with typed properties.
filings = company.get_filings(form="10-K")
for f in filings[:3]:
    print(f.form_type, f.filing_date[:10], f.url)

# Structured CompanyInfo with typed properties.
info = company.get_info()
print(info.name, info.sic_description, info.fiscal_year_end)

# Recent submissions as Submission objects.
for sub in info.recent_submissions[:5]:
    print(sub.form, sub.filing_date, sub.accession_number)

Filing Search

filings_service = client.filings()

# By CIK
filings_service.get_filings_by_cik(cik="320193")

# By form type
filings_service.get_filings_by_type(cik="320193", filing_type="10-K")

# Complex query with date range
filings_service.query(
    cik="320193",
    filing_type="10-Q",
    after_date="2023-01-01",
    before_date="2024-01-01",
)

XBRL Financial Data

xbrl = client.xbrl()

# All facts for a company.
facts = xbrl.company_facts(cik="320193")

# A single concept across time.
revenue = xbrl.company_concepts(cik="320193", concept="us-gaap/Revenue")

# Cross-company comparison for a single period.
frame = xbrl.frames(taxonomy="us-gaap", concept="AccountsPayableCurrent", uom="USD", period="CY2023Q1I")

Download Filing Documents

# Download as text.
html = client.download("https://www.sec.gov/Archives/edgar/data/320193/filing.htm")

# Download and save to file.
client.download("https://www.sec.gov/Archives/edgar/data/320193/filing.htm", path="filing.html")

# Download through the Company interface.
company = client.company("AAPL")
filings = company.get_filings(form="10-K")
content = company.download(filings[0].url)

Response Models

The library provides structured dataclass models alongside raw dictionary access:

All models expose a .raw attribute containing the original dictionary for backward compatibility.

Support These Projects

Patreon: Help support this project and future projects by donating to my Patreon Page. I'm always looking to add more content for individuals like yourself, unfortunately some of the APIs would require me to pay monthly fees.

YouTube: If you'd like to watch more of my content, feel free to visit my YouTube channel Sigma Coding.

Questions: If you have questions please feel free to reach out to me at coding.sigma@gmail.com