edgartools

# edgartools — SEC EDGAR Data

Python library for accessing all SEC filings since 1994 with structured data extraction.

## Authentication (Required)

The SEC requires identification for API access. Always set identity before any operations:

```python
from edgar import set_identity
set_identity("Your Name your.email@example.com")
```

Set via environment variable to avoid hardcoding: `EDGAR_IDENTITY="Your Name your@email.com"`.

## Installation

```bash
uv pip install edgartools
# For AI/MCP features:
uv pip install "edgartools[ai]"
```

## Core Workflow

### Find a Company

```python
from edgar import Company, find

company = Company("AAPL")        # by ticker
company = Company(320193)         # by CIK (fastest)
results = find("Apple")           # by name search
```

### Get Filings

```python
# Company filings
filings = company.get_filings(form="10-K")
filing = filings.latest()

# Global search across all filings
from edgar import get_filings
filings = get_filings(2024, 1, form="10-K")

# By accession number
from edgar import get_by_accession_number
filing = get_by_accession_number("0000320193-23-000106")
```

### Extract Structured Data

```python
# Form-specific object (most common approach)
tenk = filing.obj()              # Returns TenK, EightK, Form4, ThirteenF, etc.

# Financial statements (10-K/10-Q)
financials = company.get_financials()     # annual
financials = company.get_quarterly_financials()  # quarterly
income = financials.income_statement()
balance = financials.balance_sheet()
cashflow = financials.cashflow_statement()

# XBRL data
xbrl = filing.xbrl()
income = xbrl.statements.income_statement()
```

### Access Filing Content

```python
text = filing.text()             # plain text
html = filing.html()             # HTML
md = filing.markdown()           # markdown (good for LLM processing)
filing.open()                    # open in browser
```

## Key Company Properties

```python
company.name                     # "Apple Inc."
company.cik                      # 320193
company.ticker                   # "AAPL"
company.industry                 # "ELECTRONIC COMPUTERS"
company.sic                      # "3571"
company.shares_outstanding       # 15115785000.0
company.public_float             # 2899948348000.0
company.fiscal_year_end          # "0930"
company.exchange                 # "Nasdaq"
```

## Form → Object Mapping

| Form | Object | Key Properties |
|------|--------|----------------|
| 10-K | TenK | `financials`, `income_statement`, `balance_sheet` |
| 10-Q | TenQ | `financials`, `income_statement`, `balance_sheet` |
| 8-K | EightK | `items`, `press_releases` |
| Form 4 | Form4 | `reporting_owner`, `transactions` |
| 13F-HR | ThirteenF | `infotable`, `total_value` |
| DEF 14A | ProxyStatement | `executive_compensation`, `proposals` |
| SC 13D/G | Schedule13 | `total_shares`, `items` |
| Form D | FormD | `offering`, `recipients` |

**Important:** `filing.financials` does NOT exist. Use `filing.obj().financials`.

## Common Pitfalls

- `filing.financials` → AttributeError; use `filing.obj().financials`
- `get_filings()` has no `limit` param; use `.head(n)` or `.latest(n)`
- Prefer `amendments=False` for multi-period analysis (amended filings may be incomplete)
- Always check for `None` before accessing optional data

## Reference Files

Load these when you need detailed information:

- **[companies.md](references/companies.md)** — Finding companies, screening, batch lookups, Company API
- **[filings.md](references/filings.md)** — Working with filings, attachments, exhibits, Filings collection API
- **[financial-data.md](references/financial-data.md)** — Financial statements, convenience methods, DataFrame export, multi-period analysis
- **[xbrl.md](references/xbrl.md)** — XBRL parsing, fact querying, multi-period stitching, standardization
- **[data-objects.md](references/data-objects.md)** — All supported form types and their structured objects
- **[entity-facts.md](references/entity-facts.md)** — EntityFacts API, FactQuery, FinancialStatement, FinancialFact
- **[ai-integration.md](references/ai-integration.md)** — MCP server setup, Skills installation, `.docs` and `.to_context()` properties