EdgarTools

What this skill does

# EdgarTools

Analyze SEC filings and financial statements using EdgarTools

## Overview

Essential SEC filing analysis operations. See [objects.md](./objects.md) for object reference, [workflows.md](./workflows.md) for patterns, [readme.md](./readme.md) for setup.

## Prerequisites & Setup

**REQUIRED:** Set your identity (SEC requirement):

```python
from edgar import set_identity
set_identity("Your Name [email protected]")
```

**Without this, all API calls fail** with `"User-Agent identity is not set"` error.

## ⚡ Token-Efficient API Usage

**ALWAYS use `.to_context()` first** for concise summaries with available actions. 5-10x more token-efficient than full objects.

### Company.to_context()

```python
from edgar import Company

company = Company("AAPL")
print(company.to_context())  # ~88 tokens vs 200+ for full object
```

**Output:**
```
**Company:** Apple Inc.
**CIK:** 0000320193
**Ticker:** AAPL
**Exchange:** Nasdaq
**Industry:** Electronic Computers (SIC 3571)
**Fiscal Year End:** Sep 30
```

### Filings.to_context()

```python
filings = company.get_filings(form="10-K")
print(filings.to_context())  # ~95 tokens vs 500-1000 for rich table
```

Shows summary + **AVAILABLE ACTIONS**.

### Filing.to_context()

```python
filing = filings.latest()
print(filing.to_context())  # ~109 tokens, includes available methods
```

### XBRL.to_context()

```python
xbrl = filing.xbrl()
print(xbrl.to_context())  # ~275 tokens vs 2,500+ for full statements
```

**Token Comparison:**

| Object | Full Output | to_context() | Savings |
|--------|-------------|--------------|---------|
| Company | ~200 tokens | ~88 tokens | 56% |
| Filings | ~500-1000 | ~95 tokens | 80-90% |
| XBRL | ~2,500 tokens | ~275 tokens | 89% |

**Pattern:** `to_context()` first → see available → access data.

## Quick Start

Common starting patterns. **Use `.to_context()` for efficiency.**

### Get a Company

```python
from edgar import set_identity, Company

set_identity("Your Name [email protected]")  # Required first!

company = Company("AAPL")
print(company.to_context())  # Concise profile (~88 tokens)
# OR for full details:
# print(company)  # Full object (~200 tokens)
```

### Get Recent Filings

```python
from edgar import get_current_filings

filings = get_current_filings()  # Last ~24 hours
print(filings.to_context())  # Summary + available actions (~95 tokens)
# OR to see first 5 in table:
# print(filings.head(5))  # Rich table (~500-1000 tokens)
```

### Get Financial Statements

```python
from edgar import Company

company = Company("AAPL")
income = company.income_statement(periods=3)  # 3 fiscal years
print(income)  # Full statement
```

## Core API Reference

Main API functions and approaches.

### Getting Filings (3 Approaches)

Choose the approach based on your use case:

#### 1. Published Filings - Discovery & Bulk Analysis

**When to use**: Cross-company screening, pattern discovery, historical research, don't know which specific companies.

**Data source**: SEC quarterly indexes (updated nightly)

```python
from edgar import get_filings

# Get all filings for a quarter
filings = get_filings(2023, 1)  # Q1 2023

# Filter by form type
filings = get_filings(2023, 1, form="10-K")

# Filter by date range
filings = get_filings(2023, 1, filing_date="2023-02-01:2023-02-15")

# Further filter results
filtered = filings.filter(ticker="AAPL")
tech_filings = filings.filter(ticker=["AAPL", "MSFT", "GOOGL"])
```

#### 2. Current Filings - Real-time Monitoring

**When to use**: Monitoring recent filing activity, tracking latest submissions

**Data source**: SEC RSS feed (last ~24 hours)

```python
from edgar import get_current_filings

# Get all recent filings
current = get_current_filings()

# Filter by form type
reports = current.filter(form=["10-K", "10-Q"])

# Filter by specific companies
tech_current = current.filter(ticker=["AAPL", "MSFT"])
```

#### 3. Company Filings - Known Entity Analysis

**When to use**: You know the specific company ticker or name

**Data source**: SEC company submissions endpoint

```python
from edgar import Company

company = Company("AAPL")

# Get all filings
all_filings = company.get_filings()

# Filter by form type
annual_reports = company.get_filings(form="10-K")

# Filter by year
filings_2023 = company.get_filings(year=2023)

# Combine filters
q1_2023_10q = company.get_filings(year=2023, form="10-Q")
```

### Getting Financials (2 Approaches)

#### 1. Entity Facts API - Multi-Period Comparison

**When to use**: Comparing multiple periods, trend analysis (fastest approach)

**Data source**: SEC Company Facts API

**Advantages**: Very fast (single API call), pre-aggregated data, multi-period comparison built-in

```python
from edgar import Company

company = Company("AAPL")

# Annual data (fiscal years)
income = company.income_statement(periods=3)  # Last 3 fiscal years
balance = company.balance_sheet(periods=3)
cash_flow = company.cash_flow_statement(periods=3)

# Quarterly data
quarterly_income = company.income_statement(periods=4, annual=False)  # Last 4 quarters
```

#### 2. Filing XBRL - Single Period Detail

**When to use**: Need specific filing details, want complete line items, analyzing single period

**Data source**: XBRL files attached to specific filings

**Advantages**: Most comprehensive detail, all line items available, exact as-filed data

```python
from edgar import Company

company = Company("AAPL")

# Get specific filing
filing = company.get_filings(form="10-K")[0]  # Latest 10-K

# Parse XBRL
xbrl = filing.xbrl()

# Get statements
income = xbrl.statements.income_statement()
balance = xbrl.statements.balance_sheet()
cash_flow = xbrl.statements.cash_flow_statement()

# Access metadata
print(f"Entity: {xbrl.entity_name}")
print(f"Fiscal Year: {xbrl.fiscal_year}")
print(f"Period: {xbrl.fiscal_period}")
```

### Searching Filing Content

**⚠️ IMPORTANT**: Filing has TWO different search methods. Use the right one!

#### Content Search: `filing.search(query)` ⭐ Find Text in Filings

**Search the actual filing document** - find keywords, topics, or sections within SEC filings.

```python
from edgar import Company

company = Company("AAPL")
filing = company.get_filings(form="DEF 14A")[0]  # Proxy statement

# Search for content IN the filing
results = filing.search("executive compensation")

# Process results
print(f"Found {len(results)} matches")
for match in results[:5]:  # Top 5 matches
    print(f"Relevance score: {match.score:.2f}")
    print(f"Excerpt: {str(match)[:200]}...")
    print()
```

**Features**: BM25 relevance ranking (best matches first), searches parsed HTML sections, returns `DocSection` objects with scores, index cached for performance (~1-2 seconds per filing)

**Use cases**: Find mentions of specific topics ("revenue recognition", "risk factors"), locate sections in large filings, screen filings for relevant content, extract context around keywords

**Example: Find proxy statements mentioning compensation changes**

```python
from edgar import get_filings
from datetime import datetime, timedelta

# Get recent proxy statements
start_date = datetime.now() - timedelta(days=30)
filings = get_filings(form="DEF 14A")
recent = filings.filter(filing_date=f"{start_date.strftime('%Y-%m-%d')}:")

# Search each filing
companies_with_matches = []
for filing in recent:
    matches = filing.search("executive compensation changes")

    if matches and len(matches) > 0:
        companies_with_matches.append({
            'company': filing.company,
            'date': filing.filing_date,
            'matches': len(matches),
            'top_score': matches[0].score,
            'excerpt': str(matches[0])[:200]
        })

print(f"Found {len(companies_with_matches)} companies")
```

#### API Documentation Search: `filing.docs.search(query)` 📚 Find Methods

**Search the Filing API documentation** - discover how to use the Filing class.

```python
# Find how to use Filing API
help_text = filing.docs.search("how to get XBRL")
print(help_t