foryourhealth111-pixel/Vibe-Skills / bundled/skills/edgartools
edgartools
VerifiedPython library for accessing, analyzing, and extracting data from SEC EDGAR filings. Use when working with SEC filings, financial statements (income statement, balance sheet, cash flow), XBRL financial data, insider trading (Form 4), institutional holdings (13F), company financials, annual/quarterly reports (10-K, 10-Q), proxy statements (DEF 14A), 8-K current events, company screening by ticker/CIK/industry, multi-period financial analysis, or any SEC regulatory filings.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.7 KB |
| references/ai-integration.md | markdown | 6.7 KB |
| references/companies.md | markdown | 6.0 KB |
| references/data-objects.md | markdown | 5.4 KB |
| references/entity-facts.md | markdown | 8.1 KB |
| references/filings.md | markdown | 8.9 KB |
| references/financial-data.md | markdown | 6.9 KB |
| references/xbrl.md | markdown | 9.2 KB |
references/financial-data.md
View on GitHub# edgartools — Financial Data Reference
## Table of Contents
- [Quick Start](#quick-start)
- [Available Statements](#available-statements)
- [Convenience Methods](#convenience-methods)
- [Detail Levels (Views)](#detail-levels-views)
- [DataFrame Export](#dataframe-export)
- [Quarterly vs Annual](#quarterly-vs-annual)
- [Multi-Period Analysis](#multi-period-analysis)
- [Raw XBRL Facts Query](#raw-xbrl-facts-query)
- [API Quick Reference](#api-quick-reference)
- [Troubleshooting](#troubleshooting)
---
## Quick Start
```python
from edgar import Company
company = Company("AAPL")
# Annual (from latest 10-K)
financials = company.get_financials()
income = financials.income_statement()
# Quarterly (from latest 10-Q)
quarterly = company.get_quarterly_financials()
income = quarterly.income_statement()
```
---
## Available Statements
```python
financials = company.get_financials()
income = financials.income_statement()
balance = financials.balance_sheet()
cashflow = financials.cashflow_statement() # note: no underscore
equity = financials.statement_of_equity()
comprehensive = financials.comprehensive_income()
```
| Method | Description |
|--------|-------------|
| `income_statement()` | Revenue, COGS, operating income, net income |
| `balance_sheet()` | Assets, liabilities, equity |
| `cashflow_statement()` | Operating, investing, financing cash flows |
| `statement_of_equity()` | Changes in stockholders' equity |
| `comprehensive_income()` | Net income + other comprehensive income |
---
## Convenience Methods
Get single values directly:
```python
financials = company.get_financials()
revenue = financials.get_revenue()
net_income = financials.get_net_income()
total_assets = financials.get_total_assets()
total_liabs = financials.get_total_liabilities()
equity = financials.get_stockholders_equity()
op_cash_flow = financials.get_operating_cash_flow()
free_cash_flow = financials.get_free_cash_flow()
capex = financials.get_capital_expenditures()
current_assets = financials.get_current_assets()
current_liabs = financials.get_current_liabilities()
# All key metrics at once
metrics = financials.get_financial_metrics() # dict
# Prior period: period_offset=1 (previous), 0=current
prev_revenue = financials.get_revenue(period_offset=1)
```
---
## Detail Levels (Views)
Control the level of detail in financial statements:
```python
income = financials.income_statement()
# Summary: ~15-20 rows, matches SEC Viewer
df_summary = income.to_dataframe(view="summary")
# Standard (default): ~25-35 rows, matches filing document
df_standard = income.to_dataframe(view="standard")
# Detailed: ~50+ rows, all dimensional breakdowns
df_detailed = income.to_dataframe(view="detailed")
```
| View | Use Case |
|------|----------|
| `"summary"` | Quick overview, validating against SEC Viewer |
| `"standard"` | Display, full context (default) |
| `"detailed"` | Data extraction, segment analysis |
**Example — Apple Revenue breakdown:**
- Summary: `Revenue $391,035M`
- Standard: `Products $298,085M`, `Services $92,950M`
- Detailed: iPhone, Mac, iPad, Wearables separately
---
## DataFrame Export
```python
income = financials.income_statement()
# Convert to DataFrame
df = income.to_dataframe()
df = income.to_dataframe(view="detailed")
# Export
df.to_csv("apple_income.csv")
df.to_excel("apple_income.xlsx")
```
---
## Quarterly vs Annual
| Need | Method |
|------|--------|
| Annual (10-K) | `company.get_financials()` |
| Quarterly (10-Q) | `company.get_quarterly_financials()` |
```python
quarterly = company.get_quarterly_financials()
q_income = quarterly.income_statement()
```
---
## Multi-Period Analysis
Use `XBRLS` to analyze trends across multiple filings:
```python
from edgar.xbrl import XBRLS
# Get last 3 annual filings (use amendments=False)
filings = company.get_filings(form="10-K", amendments=False).head(3)
# Stitch together
xbrls = XBRLS.from_filings(filings)
# Get aligned multi-period statements
income = xbrls.statements.income_statement()
income_detailed = xbrls.statements.income_statement(view="detailed")
balance = xbrls.statements.balance_sheet()
cashflow = xbrls.statements.cashflow_statement()
# Convert to DataFrame (periods as columns)
df = income.to_dataframe()
print(df)
```
**Why `amendments=False`?** Amended filings (10-K/A) sometimes contain only corrected sections, not complete financial statements, which breaks multi-period stitching.
---
## Raw XBRL Facts Query
For research or custom calculations:
```python
xbrl = filing.xbrl()
# Find revenue facts
revenue_facts = xbrl.facts.query()\
.by_concept("Revenue")\
.to_dataframe()
# Search by label
rd_facts = xbrl.facts.query()\
.by_label("Research", exact=False)\
.to_dataframe()
# Filter by value range
large_items = xbrl.facts.query()\
.by_value(min_value=1_000_000_000)\
.to_dataframe()
```
---
## API Quick Reference
### Company-Level
| Method | Description |
|--------|-------------|
| `company.get_financials()` | Latest annual (10-K) |
| `company.get_quarterly_financials()` | Latest quarterly (10-Q) |
### Financials Object
| Method | Description |
|--------|-------------|
| `financials.income_statement()` | Income statement |
| `financials.balance_sheet()` | Balance sheet |
| `financials.cashflow_statement()` | Cash flow |
| `financials.get_revenue()` | Revenue scalar |
| `financials.get_net_income()` | Net income scalar |
| `financials.get_total_assets()` | Total assets scalar |
| `financials.get_financial_metrics()` | Dict of all key metrics |
### Statement Object
| Method | Description |
|--------|-------------|
| `statement.to_dataframe()` | Convert to DataFrame |
| `statement.to_dataframe(view="summary")` | SEC Viewer format |
| `statement.to_dataframe(view="standard")` | Filing document format |
| `statement.to_dataframe(view="detailed")` | All dimensional breakdowns |
### Filing-Level (More Control)
| Method | Description |
|--------|-------------|
| `filing.xbrl()` | Parse XBRL from filing |
| `xbrl.statements.income_statement()` | Income statement |
| `xbrl.facts.query()` | Query individual facts |
### Multi-Period
| Method | Description |
|--------|-------------|
| `XBRLS.from_filings(filings)` | Stitch multiple filings |
| `xbrls.statements.income_statement()` | Aligned multi-period |
---
## Troubleshooting
### "No financial data found"
```python
filing = company.get_filings(form="10-K").latest()
if filing.xbrl():
print("XBRL available")
else:
# Older/smaller companies may not have XBRL
text = filing.text() # fallback to raw text
```
### "Statement is empty"
Try the detailed view:
```python
df = income.to_dataframe(view="detailed")
```
### "Numbers don't match SEC website"
Check the reporting periods:
```python
xbrl = filing.xbrl()
print(xbrl.reporting_periods)
```
### Accessing financials from a 10-K filing
```python
# WRONG: filing.financials does not exist
filing.financials # AttributeError!
# CORRECT:
tenk = filing.obj()
if tenk and tenk.financials:
income = tenk.financials.income_statement
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |