mirror of https://github.com/K-Dense-AI/claude-scientific-skills.git synced 2026-03-28 07:25:14 +08:00

Files

Timothy Kassis 0ffa12a0e2 Support EdgarTools to access and analyze SEC Edgar filings, XBRL financial statements, 10-K, 10-Q, and 8-K reports

2026-02-23 13:02:15 -08:00

8.9 KiB

Raw Blame History

edgartools — Filings Reference

Getting a Filing
Filing Properties
Accessing Content
Structured Data
Attachments & Exhibits
Search Within a Filing
Viewing & Display
Save, Load & Export
Filings Collection API
Filtering & Navigation

Getting a Filing

from edgar import Company, get_filings, get_by_accession_number, Filing

# From a company
company = Company("AAPL")
filing = company.get_filings(form="10-K").latest()

# Global search
filings = get_filings(2024, 1, form="10-K")
filing = filings[0]
filing = filings.latest()

# By accession number
filing = get_by_accession_number("0000320193-23-000106")

# Direct construction (rarely needed)
filing = Filing(
    form='10-Q',
    filing_date='2024-06-30',
    company='Tesla Inc.',
    cik=1318605,
    accession_no='0001628280-24-028839'
)

Filing Properties

Basic Properties

filing.cik              # 320193
filing.company          # "Apple Inc."
filing.form             # "10-K"
filing.filing_date      # "2023-11-03"
filing.period_of_report # "2023-09-30"
filing.accession_no     # "0000320193-23-000106"
filing.accession_number # alias for accession_no

EntityFiling Extra Properties (from company.get_filings())

filing.acceptance_datetime  # datetime
filing.file_number          # "001-36743"
filing.size                 # bytes
filing.primary_document     # filename
filing.is_xbrl              # bool
filing.is_inline_xbrl       # bool

URL Properties

filing.homepage_url   # SEC index page URL
filing.filing_url     # primary document URL
filing.text_url       # text version URL
filing.base_dir       # base directory for all files

Accessing Content

html = filing.html()         # HTML string or None
text = filing.text()         # plain text (clean)
md = filing.markdown()       # markdown string
xml = filing.xml()           # XML string or None (ownership forms)
full = filing.full_text_submission()  # complete SGML submission

# Markdown with page breaks (good for LLM processing)
md = filing.markdown(include_page_breaks=True, start_page_number=1)

Structured Data

Get Form-Specific Object (Primary Method)

obj = filing.obj()        # or filing.data_object()
# Returns: TenK, TenQ, EightK, Form4, ThirteenF, ProxyStatement, etc.

IMPORTANT: The base Filing class has NO financials property.

# WRONG:
filing.financials  # AttributeError!

# CORRECT:
tenk = filing.obj()
if tenk and tenk.financials:
    income = tenk.financials.income_statement

Form → Class Mapping

Form	Class	Module
10-K	TenK	edgar.company_reports
10-Q	TenQ	edgar.company_reports
8-K	EightK	edgar.company_reports
20-F	TwentyF	edgar.company_reports
4	Form4	edgar.ownership
3	Form3	edgar.ownership
5	Form5	edgar.ownership
DEF 14A	ProxyStatement	edgar.proxy
13F-HR	ThirteenF	edgar.holdings
SC 13D/G	Schedule13	edgar.ownership
NPORT-P	NportFiling	edgar.nport
144	Form144	edgar.ownership

Get XBRL Data

xbrl = filing.xbrl()     # Returns XBRL object or None
if xbrl:
    income = xbrl.statements.income_statement()
    balance = xbrl.statements.balance_sheet()
    cashflow = xbrl.statements.cash_flow_statement()

Attachments & Exhibits

List Attachments

attachments = filing.attachments
print(f"Total: {len(attachments)}")

for att in attachments:
    print(f"{att.sequence}: {att.description}")
    print(f"  Type: {att.document_type}")
    print(f"  File: {att.document}")

Primary Document

primary = filing.document

Access by Index or Name

first = filing.attachments[0]
specific = filing.attachments["ex-10_1.htm"]

Download Attachments

filing.attachments[0].download("./downloads/")
filing.attachments.download("./downloads/")  # all

Work with Exhibits

exhibits = filing.exhibits

for exhibit in exhibits:
    print(f"Exhibit {exhibit.exhibit_number}: {exhibit.description}")
    if exhibit.exhibit_number == "10.1":
        exhibit.download("./exhibits/")

Search Within a Filing

# Simple text search
results = filing.search("artificial intelligence")
print(f"Found {len(results)} mentions")

# Regex search
emails = filing.search(
    r'\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b',
    regex=True
)

# Financial terms
revenue_mentions = filing.search("revenue")
risk_factors = filing.search("risk factor")
critical = filing.search(r'\b(material weakness|restatement)\b', regex=True)

Document Sections

sections = filing.sections()  # list of section names
doc = filing.parse()          # parse to Document for advanced ops

Viewing & Display

filing.view()                # display in console/Jupyter with Rich
filing.open()                # open primary doc in browser
filing.open_homepage()       # open SEC index page
filing.serve(port=8080)      # serve locally at http://localhost:8080

Save, Load & Export

# Save
filing.save("./data/filings/")         # auto-generates filename
filing.save("./data/apple_10k.pkl")    # specific file

# Load
filing = Filing.load("./data/apple_10k.pkl")

# Export
data = filing.to_dict()
summary_df = filing.summary()

# Download raw
filing.download(data_directory="./raw_filings/", compress=False)

Filings Collection API

get_filings() — Global Search

from edgar import get_filings

filings = get_filings(2024, 1, form="10-K")   # Q1 2024 10-Ks
filings = get_filings(2023, form="10-K")       # all 2023 10-Ks
filings = get_filings([2022, 2023, 2024])      # multiple years
filings = get_filings(2024, [1, 2], form="10-Q")
filings = get_filings(2024, 1, amendments=False)

Note: get_filings() has NO limit parameter. Use .head(n) after.

Collection Properties

len(filings)         # count
filings.empty        # bool
filings.date_range   # (start_date, end_date)
filings.start_date   # earliest
filings.end_date     # latest

Access & Iteration

first = filings[0]
last = filings[-1]

for filing in filings:
    print(f"{filing.form}: {filing.company}")

# By accession number
filing = filings.get("0001234567-24-000001")

Subset Operations

filings.latest()     # most recent (single Filing)
filings.latest(10)   # 10 most recent (Filings)
filings.head(20)     # first 20
filings.tail(20)     # last 20
filings.sample(10)   # random 10

filter()

# Form type
annual = filings.filter(form="10-K")
multi = filings.filter(form=["10-K", "10-Q"])
original = filings.filter(form="10-K", amendments=False)

# Date
jan = filings.filter(date="2024-01-01")
q1 = filings.filter(date="2024-01-01:2024-03-31")
recent = filings.filter(date="2024-01-01:")

# Company
apple = filings.filter(ticker="AAPL")
apple = filings.filter(cik=320193)
faang = filings.filter(ticker=["AAPL", "MSFT", "GOOGL"])

# Exchange
nasdaq = filings.filter(exchange="NASDAQ")
major = filings.filter(exchange=["NASDAQ", "NYSE"])

Chain Filters

result = (filings
    .filter(form="10-K")
    .filter(exchange="NASDAQ")
    .filter(date="2024-01-01:")
    .latest(50))

Find by Company Name

tech = filings.find("Technology")
apple = filings.find("Apple")

Pagination

next_page = filings.next()
prev_page = filings.previous()
current = filings.current()

Export & Persistence

df = filings.to_pandas()
df = filings.to_pandas('form', 'company', 'filing_date', 'cik')

filings.save_parquet("filings.parquet")  # or .save()
filings.download(data_directory="./raw_data/", compress=True)

Common Recipes

Extract Revenue from Latest 10-K

company = Company("MSFT")
filing = company.get_filings(form="10-K").latest()
tenk = filing.obj()
if tenk.financials:
    income = tenk.financials.income_statement
    print(income)

Convert to Markdown for LLM Analysis

company = Company("NVDA")
filing = company.get_filings(form="10-K").latest()
md = filing.markdown(include_page_breaks=True)
with open("nvidia_10k.md", "w") as f:
    f.write(md)

Search Across Recent 8-K Filings

filings = get_filings(2024, 1, form="8-K").head(50)
for filing in filings:
    if filing.search("earnings"):
        print(f"{filing.company} ({filing.filing_date})")

Batch Process with Pagination

def process_all(filings):
    current = filings
    results = []
    while current and not current.empty:
        for filing in current:
            results.append(filing.to_dict())
        current = current.next()
    return results

8.9 KiB Raw Blame History