Skip to content

SEC-EDGAR-GUIDE.md

Latest commit

 

History

History
336 lines (259 loc) · 10.9 KB

SEC-EDGAR-GUIDE.md

File metadata and controls

336 lines (259 loc) · 10.9 KB
Raw

🏛️ SEC EDGAR Data - Complete Free Alternative to Paid APIs

💡 What is SEC EDGAR?

SEC EDGAR (Electronic Data Gathering, Analysis, and Retrieval) is the U.S. Securities and Exchange Commission's official filing system. ALL public companies are required to file their financials here.

Why Use SEC EDGAR Instead of Paid APIs?

Feature SEC EDGAR Paid APIs (FMP, Alpha Vantage, etc.)
Cost 100% FREE ✅ $50-500+/month
Rate Limits ~10 requests/second 25-250 calls/day (free tier)
Data Quality Official source 🏛️ Third-party aggregation
Historical Data Complete history Often limited
Coverage All US public companies Varies by tier
API Key Not required ✅ Required

📊 Financial Metrics Available (All FREE!)

💰 Income Statement Metrics

Metric Description Already Have?
Revenue Total revenue ✅ YES
Net Income Earnings (profit) ✅ YES
Gross Profit Revenue - COGS ❌ Can add
Operating Income Profit from operations ❌ Can add
Cost of Revenue Cost of goods/services ❌ Can add
R&D Expense Research & Development spending ❌ Can add
SG&A Expense Sales, General & Administrative ❌ Can add
Interest Expense Cost of debt ❌ Can add
Tax Expense Income tax paid ❌ Can add
EPS (Basic) Earnings Per Share ❌ Can add
EPS (Diluted) Diluted Earnings Per Share ❌ Can add

📊 Balance Sheet Metrics

Metric Description Already Have?
Total Assets Everything company owns ❌ Can add
Total Liabilities Everything company owes ❌ Can add
Stockholders Equity Net worth ❌ Can add
Current Assets Assets < 1 year ❌ Can add
Current Liabilities Debts < 1 year ❌ Can add
Cash & Equivalents Liquid cash ❌ Can add
Inventory Goods in stock ❌ Can add
Accounts Receivable Money owed to company ❌ Can add
Property/Plant/Equipment Physical assets ❌ Can add
Goodwill Intangible value ❌ Can add
Long-term Debt Debt > 1 year ❌ Can add

💵 Cash Flow Metrics

Metric Description Already Have?
Operating Cash Flow Cash from operations ❌ Can add
Investing Cash Flow Cash from investments ❌ Can add
Financing Cash Flow Cash from financing ❌ Can add
CapEx Capital Expenditures ✅ YES
Free Cash Flow Operating CF - CapEx ❌ Can add
Depreciation Asset value reduction ❌ Can add
Dividends Paid Cash paid to shareholders ❌ Can add

📈 Key Metrics & Ratios

Metric Description Can Calculate?
Shares Outstanding Total shares ✅ From SEC
Market Cap Stock price × shares ✅ Already have
P/E Ratio Price / Earnings ✅ Can calculate
Debt-to-Equity Liabilities / Equity ✅ Can calculate
Current Ratio Current Assets / Current Liabilities ✅ Can calculate
ROE Net Income / Equity ✅ Can calculate
Profit Margin Net Income / Revenue ✅ Can calculate
Operating Margin Operating Income / Revenue ✅ Can calculate

🚀 What You Could Add to Your Site

Option 1: Enhanced Company Cards (Easy)

Add a few more key metrics to each card:

Apple Inc. (AAPL)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Revenue: $394.33B
Earnings: $101.96B          ← Already added ✅
Operating Income: $123.22B  ← New!
Free Cash Flow: $108.80B    ← New!
CapEx: $11.10B             ← Already have ✅
Total Assets: $364.98B      ← New!
Debt-to-Equity: 5.41        ← New!
Market Cap: $3.15T          ← Already have ✅

Option 2: Financial Dashboard View (Medium)

Add a new page showing detailed financials:

  • Income Statement Tab: Revenue, earnings, margins
  • Balance Sheet Tab: Assets, liabilities, equity
  • Cash Flow Tab: Operating, investing, financing CF
  • Metrics Tab: Ratios, per-share data

Option 3: Comparison Tool (Advanced)

Compare financial metrics across companies:

Compare: AAPL vs MSFT vs GOOGL

Revenue:         $394B   $245B   $331B
Earnings:        $102B   $88B    $74B
Operating Margin: 31.3%   45.1%   32.0%
Free Cash Flow:  $109B   $73B    $69B

Option 4: Trends & Charts (Advanced)

Show historical trends using Chart.js or similar:

  • Revenue growth over time
  • Margin trends
  • Cash flow trends
  • R&D spending vs competitors

📝 Example: Add More Metrics to Company Cards

Here's what you could fetch and display:

def fetch_enhanced_financials(symbol):
    """Fetch comprehensive financials from SEC EDGAR"""
    
    metrics_to_fetch = {
        # Already have
        'revenue': 'RevenueFromContractWithCustomerExcludingAssessedTax',
        'earnings': 'NetIncomeLoss',
        'capex': 'PaymentsToAcquirePropertyPlantAndEquipment',
        
        # New additions
        'gross_profit': 'GrossProfit',
        'operating_income': 'OperatingIncomeLoss',
        'operating_cash_flow': 'NetCashProvidedByUsedInOperatingActivities',
        'total_assets': 'Assets',
        'total_liabilities': 'Liabilities',
        'stockholders_equity': 'StockholdersEquity',
        'long_term_debt': 'LongTermDebt',
        'cash': 'CashAndCashEquivalentsAtCarryingValue',
        'rd_expense': 'ResearchAndDevelopmentExpense',
        'shares_outstanding': 'CommonStockSharesOutstanding',
        'dividends_paid': 'PaymentsOfDividends'
    }
    
    # Fetch from SEC EDGAR API
    # ... (implementation)

Then display:

// Enhanced company card
<div class="company-card">
    <h3>${company.name}</h3>
    
    <!-- Profitability -->
    <div class="metric-group">
        <h4>💰 Profitability</h4>
        <div>Revenue: ${formatCurrency(company.revenue)}</div>
        <div>Earnings: ${formatCurrency(company.earnings)}</div>
        <div>Operating Income: ${formatCurrency(company.operating_income)}</div>
        <div>Profit Margin: ${(company.earnings/company.revenue*100).toFixed(1)}%</div>
    </div>
    
    <!-- Cash Flow -->
    <div class="metric-group">
        <h4>💵 Cash Flow</h4>
        <div>Operating CF: ${formatCurrency(company.operating_cash_flow)}</div>
        <div>CapEx: ${formatCurrency(company.capex)}</div>
        <div>Free CF: ${formatCurrency(company.operating_cash_flow + company.capex)}</div>
    </div>
    
    <!-- Balance Sheet -->
    <div class="metric-group">
        <h4>📊 Balance Sheet</h4>
        <div>Total Assets: ${formatCurrency(company.total_assets)}</div>
        <div>Total Debt: ${formatCurrency(company.long_term_debt)}</div>
        <div>Equity: ${formatCurrency(company.stockholders_equity)}</div>
        <div>Debt/Equity: ${(company.long_term_debt/company.stockholders_equity).toFixed(2)}</div>
    </div>
    
    <!-- Valuation -->
    <div class="metric-group">
        <h4>📈 Valuation</h4>
        <div>Market Cap: ${formatCurrency(company.market_cap)}</div>
        <div>P/E Ratio: ${(company.market_cap/company.earnings).toFixed(2)}</div>
        <div>EPS: $${(company.earnings/company.shares_outstanding).toFixed(2)}</div>
    </div>
</div>

🛠️ Implementation Steps

Step 1: Fetch Additional Metrics

Update fetch-earnings-free.py to fetch more metrics:

def fetch_comprehensive_data(symbol):
    """Fetch all useful metrics from SEC EDGAR"""
    
    cik = get_company_cik(symbol)
    url = f"https://data.sec.gov/api/xbrl/companyfacts/CIK{cik}.json"
    
    # Define what to extract
    metrics = {
        'gross_profit': 'GrossProfit',
        'operating_income': 'OperatingIncomeLoss',
        'operating_cash_flow': 'NetCashProvidedByUsedInOperatingActivities',
        'total_assets': 'Assets',
        'total_liabilities': 'Liabilities',
        'stockholders_equity': 'StockholdersEquity',
        'long_term_debt': 'LongTermDebt',
        'cash': 'CashAndCashEquivalentsAtCarryingValue',
        'rd_expense': 'ResearchAndDevelopmentExpense'
    }
    
    # Extract latest annual data for each metric
    # ...

Step 2: Add to JSON

Update financial_data.json structure:

{
  "symbol": "AAPL",
  "name": "Apple Inc.",
  "capex": -11100000000,
  "year": 2024,
  "revenue": 394328000000,
  "earnings": 101956000000,
  "gross_profit": 180680000000,        ← New
  "operating_income": 123220000000,    ← New
  "operating_cash_flow": 118250000000, ← New
  "total_assets": 364980000000,        ← New
  "total_liabilities": 308030000000,   ← New
  "stockholders_equity": 56950000000,  ← New
  "long_term_debt": 96660000000,       ← New
  "cash": 29940000000,                 ← New
  "rd_expense": 31370000000,           ← New
  "sector": "Technology",
  "market_cap": 3153843528000
}

Step 3: Update UI

Add display logic to show additional metrics.

🎯 Recommended Next Steps

Quick Wins (1-2 hours):

  1. ✅ Operating Income - Shows operational efficiency
  2. ✅ Operating Cash Flow - Shows cash generation
  3. ✅ Total Assets - Shows company size
  4. ✅ Debt-to-Equity Ratio - Shows financial leverage

Medium Additions (3-5 hours):

  1. Free Cash Flow (Operating CF - CapEx)
  2. Profit Margins (calculate from existing data)
  3. P/E Ratio (Market Cap / Earnings)
  4. Detailed financial modal (click for more info)

Advanced Features (1-2 days):

  1. Historical trends (multi-year comparison)
  2. Sector benchmarking (vs sector averages)
  3. Financial health score (composite metric)
  4. Interactive charts (Chart.js or D3.js)

📚 Resources

🚀 Quick Test

Try the explorer tool:

# Explore what's available for any company
python3 explore-sec-data.py AAPL
python3 explore-sec-data.py TSLA
python3 explore-sec-data.py MSFT

💰 Cost Comparison

Current Setup:

  • SEC EDGAR: $0/month ✅
  • Coverage: 99/102 companies
  • Metrics: 500+ per company

Alternative (Paid API):

  • Financial Modeling Prep Pro: $49/month
  • Alpha Vantage Premium: $49.99/month
  • Polygon.io Starter: $99/month

Savings: $49-99/month = $588-1,188/year 💰

🎉 Bottom Line

SEC EDGAR is MORE POWERFUL than most paid APIs because it's the official source. The only limitation is it's US companies only and not real-time (quarterly/annual updates).

For your use case (S&P 100 companies with fundamental data), SEC EDGAR is perfect and 100% free!