edgartools

Files (8)

• SKILL.md
• ai-integration.md · references/
• companies.md · references/
• data-objects.md · references/
• entity-facts.md · references/
• filings.md · references/
• financial-data.md · references/
• xbrl.md · references/

SKILL.md (first lines)

# 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

From agent-skills-hub/agent-skills-hub, MIT.

More from agent-skills-hub/agent-skills-hub