Free SEC EDGAR API Guide

The SEC provides free programmatic access to all EDGAR filing data through their API. This guide will show you how to access company information, filings, and financial data without any API keys or paid subscriptions.

API Endpoints Overview

The EDGAR API provides several key endpoints:

Company Information

https://data.sec.gov/submissions/CIK{CIK}.json

XBRL Company Concepts

https://data.sec.gov/api/xbrl/companyconcept/CIK{CIK}/us-gaap/{TAG}.json

XBRL Company Facts

https://data.sec.gov/api/xbrl/companyfacts/CIK{CIK}.json

Getting Started

The SEC requires a User-Agent header identifying yourself:

curl -H "User-Agent: YourName [email protected]" \
  "https://data.sec.gov/submissions/CIK0000320193.json"

JavaScript Example

async function getCompanyData(cik) {
  const response = await fetch(`https://data.sec.gov/submissions/CIK${cik.padStart(10, '0')}.json`, {
    headers: {
      'User-Agent': 'YourName [email protected]'
    }
  });
  return response.json();
}

// Get Apple's data
const appleData = await getCompanyData('320193');

Key API Features

1. Company Submissions

Get all filings for a company:

• Recent filings (10-K, 10-Q, 8-K, etc.)
• Filing dates and accession numbers
• Document links and descriptions
• XBRL availability indicators

2. XBRL Financial Data

Access structured financial metrics:

• Revenue, net income, assets, liabilities
• Historical quarterly and annual data
• Multiple units (USD, shares, etc.)
• Form context (10-K vs 10-Q)

3. Rate Limiting

The API has generous limits:

• 10 requests per second
• No daily limits
• No API key required
• Free for all users

Practical Examples

Example 1: Get Company Revenue

async function getRevenue(cik) {
  const url = `https://data.sec.gov/api/xbrl/companyconcept/CIK${cik.padStart(10, '0')}/us-gaap/Revenues.json`;
  
  const response = await fetch(url, {
    headers: { 'User-Agent': 'YourName [email protected]' }
  });
  
  const data = await response.json();
  const annualData = data.units.USD.filter(item => item.form === '10-K');
  
  return annualData.sort((a, b) => b.end.localeCompare(a.end));
}

Example 2: Compare Companies

async function compareMetrics(companies, metric) {
  const results = {};
  
  for (const [ticker, cik] of Object.entries(companies)) {
    try {
      const data = await getMetric(cik, metric);
      results[ticker] = data[0]?.val; // Latest value
    } catch (e) {
      results[ticker] = null;
    }
    
    // Respect rate limit
    await new Promise(resolve => setTimeout(resolve, 100));
  }
  
  return results;
}

// Usage
const results = await compareMetrics({
  'AAPL': '320193',
  'MSFT': '789019',
  'GOOGL': '1652044'
}, 'Revenues');

Common XBRL Tags

Here are the most useful XBRL tags for financial analysis:

Income Statement

• Revenues - Total revenue
• GrossProfit - Gross profit
• OperatingIncomeLoss - Operating income
• NetIncomeLoss - Net income
• EarningsPerShareDiluted - Diluted EPS

Balance Sheet

• Assets - Total assets
• Liabilities - Total liabilities
• StockholdersEquity - Shareholders' equity
• CashAndCashEquivalentsAtCarryingValue - Cash
• LongTermDebt - Long-term debt

Cash Flow

• NetCashProvidedByUsedInOperatingActivities - Operating cash flow
• NetCashProvidedByUsedInInvestingActivities - Investing cash flow
• NetCashProvidedByUsedInFinancingActivities - Financing cash flow

Error Handling

async function safeAPICall(url) {
  try {
    const response = await fetch(url, {
      headers: { 'User-Agent': 'YourName [email protected]' }
    });
    
    if (!response.ok) {
      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
    }
    
    return await response.json();
  } catch (error) {
    console.error(`API call failed: ${error.message}`);
    return null;
  }
}

Building a Financial Dashboard

Here's a complete example for building a basic financial dashboard:

class SECAnalyzer {
  constructor() {
    this.baseURL = 'https://data.sec.gov';
    this.userAgent = 'YourName [email protected]';
  }

  async getCompanyOverview(cik) {
    const submissions = await this.fetch(`/submissions/CIK${cik.padStart(10, '0')}.json`);
    const facts = await this.fetch(`/api/xbrl/companyfacts/CIK${cik.padStart(10, '0')}.json`);
    
    return {
      name: submissions.name,
      ticker: submissions.tickers?.[0],
      sic: submissions.sic,
      filings: submissions.filings.recent,
      financials: this.extractKeyMetrics(facts)
    };
  }

  extractKeyMetrics(facts) {
    const metrics = {};
    const gaap = facts.facts['us-gaap'] || {};
    
    // Extract key metrics with error handling
    ['Revenues', 'NetIncomeLoss', 'Assets', 'StockholdersEquity'].forEach(tag => {
      if (gaap[tag]?.units?.USD) {
        const annual = gaap[tag].units.USD
          .filter(item => item.form === '10-K')
          .sort((a, b) => b.end.localeCompare(a.end))[0];
        
        metrics[tag] = annual?.val || null;
      }
    });
    
    return metrics;
  }

  async fetch(endpoint) {
    const response = await fetch(`${this.baseURL}${endpoint}`, {
      headers: { 'User-Agent': this.userAgent }
    });
    
    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    return response.json();
  }
}

Best Practices

• Always include User-Agent: Required by SEC
• Respect rate limits: Max 10 requests per second
• Cache responses: Data doesn't change frequently
• Handle errors gracefully: Not all companies have all metrics
• Validate data: Check for null values and outliers
• Use proper CIK format: Zero-padded to 10 digits

Quick Reference: SEC EDGAR API Endpoints

Quick lookup table for the most commonly used SEC EDGAR API endpoints:

Common CIK Numbers Reference

Quick lookup for CIK numbers of major companies:

Code Examples

Here are complete working examples in different languages for fetching companyfacts data:

Python Example

import requests

def get_company_facts(cik):
    """Fetch companyfacts for a company by CIK number."""
    cik_padded = str(cik).zfill(10)
    url = f'https://data.sec.gov/api/xbrl/companyfacts/CIK{cik_padded}.json'
    headers = {'User-Agent': 'YourName [email protected]'}
    response = requests.get(url, headers=headers)
    return response.json()

# Get Apple facts
apple_facts = get_company_facts('320193')
gaap = apple_facts['facts'].get('us-gaap', {})
if 'Revenues' in gaap:
    revenues = gaap['Revenues']['units'].get('USD', [])
    latest = max(revenues, key=lambda x: x['end'])
    print(f"Latest Revenue: {latest['val']:,}")

Node.js / JavaScript Example

async function getCompanyFacts(cik) {
  const cikPadded = String(cik).padStart(10, '0');
  const url = `https://data.sec.gov/api/xbrl/companyfacts/CIK${cikPadded}.json`;
  const response = await fetch(url, {
    headers: {'User-Agent': 'YourName [email protected]'}
  });
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  return response.json();
}

const appleFacts = await getCompanyFacts('320193');
const revenues = appleFacts.facts['us-gaap']?.Revenues?.units?.USD || [];
const latest = revenues.sort((a, b) => new Date(b.end) - new Date(a.end))[0];
console.log(`Latest Revenue: $${latest?.val?.toLocaleString()}`);

cURL Command Line

curl -H "User-Agent: YourName [email protected]" \
  "https://data.sec.gov/api/xbrl/companyfacts/CIK0000320193.json" \
  | jq '.facts."us-gaap".Revenues.units.USD | sort_by(.end) | .[-1]'

Troubleshooting

403 Forbidden Error

Problem: You get a 403 error when making API requests.

Solution: The SEC requires a User-Agent header. Include it in all requests:

headers: {
  'User-Agent': 'YourCompanyName [email protected]'
}

Rate Limiting

Problem: You're getting rate limited (HTTP 429 errors).

Solution: The SEC allows maximum 10 requests per second. Add delays:

// Wait 100ms between requests
await new Promise(resolve => setTimeout(resolve, 100));

CIK Padding Issues

Problem: API returns 404 or incorrect data.

Solution: CIK must be zero-padded to 10 digits:

• Apple: 320193 → CIK0000320193
• Microsoft: 789019 → CIK0000789019

FAQ

Alternative: Use TL;DR Filing API

While the SEC API is powerful, it can be complex to work with. Our TL;DR Filing platform provides a simplified API with:

• Pre-processed financial metrics
• AI-generated summaries
• Standardized company data
• Built-in error handling
• Easy-to-use endpoints

Conclusion

The SEC EDGAR API provides free access to a wealth of financial data. Start with basic company lookups, then gradually build more sophisticated analysis tools. Remember to be respectful of rate limits and always include proper attribution in your User-Agent header.

For more complex analysis needs, consider using our TL;DR Filing platform which provides AI-powered insights on top of this raw SEC data.