edgartools-sec-data

edgartools: SEC EDGAR data access

edgartools is the desk's standard way to read SEC data. It is preinstalled in your environment. Work in Python (a script or python -c), not by fetching sec.gov pages by hand.

Always set your identity first

The SEC requires a contact identity on automated requests. Do this before any other call, every session:

from edgar import set_identity
set_identity("Research Desk workshop [email protected]")  # use the EDGAR_IDENTITY value you were given

(Equivalently, the EDGAR_IDENTITY environment variable, exported before running Python.)

Companies and filings

from edgar import Company

company = Company("NVDA")              # by ticker (or CIK)
company.name, company.cik, company.industry

filings = company.get_filings(form="10-K")   # also "10-Q", "8-K", "DEF 14A", ...
latest_10k = filings.latest()                # most recent of that form
latest_10q = company.get_filings(form="10-Q").latest()

latest_10k.form, latest_10k.filing_date, latest_10k.accession_no

Pick whichever of the latest 10-K / 10-Q is more recent when asked for "the most recent filing". Foreign private issuers file 20-F instead of 10-K.

Reading the filing

filing = latest_10k
tenk = filing.obj()        # rich object for 10-K/10-Q: sections, financials

# Sections (10-K item numbers; 10-Q uses Part/Item naming)
risk_factors = tenk["Item 1A"]      # Risk Factors text
mda = tenk["Item 7"]                # Management's Discussion & Analysis
business = tenk["Item 1"]

# Plain text of the whole filing if you need to search it
text = filing.text()

Sections are long — extract what you need rather than pasting whole sections into your reply.

Financial statements (XBRL)

financials = tenk.financials          # also: company.get_financials() for the latest annual figures

income = financials.income_statement()
balance = financials.balance_sheet()
cashflow = financials.cashflow_statement()

These return tabular objects (pandas-friendly). Typical fields: total revenue, gross profit, operating income, net income, cash and equivalents, total debt, inventory, R&D expense. The same statement usually carries the prior period's column — use it for year-over-year comparisons instead of fetching another filing.

Segment and geographic revenue

Consolidated revenue hides the story; the segment note is where concentration and regional shifts show up. Segment data lives in the financial-statement notes (ASC 280), not the primary statements:

# The segment/geography breakdown is a note, not a primary statement.
# Search the filing text for the segment note and read the tables around it.
text = filing.text()
for marker in ["Segment Information", "revenue by geographic", "Disaggregation of Revenue"]:
    idx = text.find(marker)
    if idx != -1:
        print(text[idx : idx + 3000])   # the note's tables follow the heading
        break

Report segment/geography revenue alongside the consolidated figure and call out: any region or segment that moved more than ~20% year over year, and any customer-concentration disclosure (usually phrased "one customer accounted for X% of revenue").

Useful patterns

• Year-over-year risk-factor diff: pull Item 1A from this year's and last year's 10-K (company.get_filings(form="10-K") is sorted; take the first two) and compare.
• Insider activity: company.get_filings(form="4") lists Form 4 insider transaction filings.
• Be defensive: the API surface evolves. If an attribute or method isn't there, inspect it (dir(obj), help(obj)) or fall back to filing.text() and targeted searching, and note the fallback in your output.
• Be polite to EDGAR: keep requests to what you need; everything is cached within the session by the library.

Units and reporting hygiene

• Statement values are typically raw USD; convert to millions when reporting (value / 1e6) and label them.
• Always state which filing (form, fiscal period, filing date) a number came from.
• If a figure is missing or ambiguous in XBRL, say so rather than estimating.