The SEC has a free financial data API that nobody talks about

Every quarterly earnings number for every US public company going back to 2009 is sitting in a free, well-documented JSON API run by the US government. No API key. No rate limit for normal use. No paywall. Almost nobody in the dev community seems to know it exists.

It's at data.sec.gov, and it's the same data Bloomberg charges $24k/year for.

What's in it

The SEC requires all US-listed companies to file financial reports in XBRL — a structured XML format where every number is tagged with a standardised concept name. The EDGAR system has been collecting these since around 2009. The companyfacts endpoint exposes all of it as clean JSON:

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

Where CIK is the company's SEC identifier (10 digits, zero-padded). For Apple, that's 0000320193. The response is a large JSON object with every concept the company has ever reported, broken down by period.

The other endpoint you need is the ticker-to-CIK map:

GET https://www.sec.gov/files/company_tickers.json

This gives you a flat list of all US-listed companies with their CIK, ticker, and name. Load it once and cache it.

One gotcha: concept names vary by company

Companies don't all use the same GAAP concept names to report the same thing. Apple reports revenue as RevenueFromContractWithCustomerExcludingAssessedTax. Older companies use Revenues. Some use SalesRevenueNet. If you just look up one concept name, you'll get blanks for most companies.

The fix is a concept alias map: try each name in order, use the first one that has data.

const CONCEPT_MAP: Record<string, string[]> = {
  revenue: [
    'Revenues',
    'RevenueFromContractWithCustomerExcludingAssessedTax',
    'RevenueFromContractWithCustomerIncludingAssessedTax',
    'SalesRevenueNet',
    'SalesRevenueGoodsNet',
  ],
  netIncome: [
    'NetIncomeLoss',
    'NetIncomeLossAvailableToCommonStockholdersBasic',
    'ProfitLoss',
  ],
  operatingCashFlow: [
    'NetCashProvidedByUsedInOperatingActivities',
    'NetCashProvidedByUsedInOperatingActivitiesContinuingOperations',
  ],
  capex: [
    'PaymentsToAcquirePropertyPlantAndEquipment',
    'PaymentsForCapitalImprovements',
    'CapitalExpenditureDiscontinuedOperations',
  ],
};

function pickConcept(facts: CompanyFacts, names: string[]) {
  for (const name of names) {
    const concept = facts['us-gaap']?.[name];
    if (concept?.units?.USD?.length) return concept.units.USD;
  }
  return null;
}

Another gotcha: Q4 doesn't exist

Companies file 10-Qs for Q1, Q2, Q3. They never file a 10-Q for Q4 — that's folded into the annual 10-K. So the API has no Q4 row.

You synthesise it: Q4 = FY - (Q1 + Q2 + Q3).

This works for flow metrics (revenue, net income, cash flows). For balance sheet items (total assets, equity), they're point-in-time stocks — carry the year-end figure as Q4 rather than doing the arithmetic, because it's the same date.

function synthesiseQ4(
  quarters: Period[],
  annual: Period[]
): Period[] {
  return annual.map(fy => {
    const q1 = quarters.find(q => q.fy === fy.fy && q.fp === 'Q1');
    const q2 = quarters.find(q => q.fy === fy.fy && q.fp === 'Q2');
    const q3 = quarters.find(q => q.fy === fy.fy && q.fp === 'Q3');
    if (!q1 || !q2 || !q3) return null;
    return {
      fy: fy.fy,
      fp: 'Q4',
      end: fy.end,
      val: fy.val - q1.val - q2.val - q3.val,
    };
  }).filter(Boolean);
}

Free cash flow: derive it yourself

Free cash flow isn't an XBRL concept — no company files it. You compute it from the two inputs that are in the data:

FCF = operating cash flow - capex

CapEx is reported as a positive outflow (the company paid $X), so you subtract it. The result is the cash a business generates after maintaining and growing its assets — the number that actually matters for valuation.

The User-Agent requirement

One thing that'll get you 403'd: the SEC requires a non-empty, descriptive User-Agent header with a contact email. Generic headers like Mozilla/5.0 will be rejected.

const headers = {
  'User-Agent': 'YourAppName contact@yourdomain.com',
  'Accept': 'application/json',
};

Use your real email. SEC enforcement is light, but it's a public data service and they ask for it so they can contact you if your scraper goes rogue.

Rate limits

The official guidance is 10 requests/second per IP for the EDGAR APIs. For normal programmatic use you won't hit that. If you're building something with a lot of users hitting it simultaneously, cache aggressively — the underlying data changes at most a few times per quarter.

A Cache-Control: s-maxage=3600, stale-while-revalidate=86400 on your own API layer keeps the SEC request volume low even under traffic.

What you get for free

Revenue, net income, EPS, equity for every US public company back to ~2009
Full filing history (every 10-K, 10-Q, 8-K, proxy) via data.sec.gov/submissions/CIK{cik}.json
Clean JSON, no parsing, no scraping
All of it public domain — no license restrictions, no attribution requirements

For most retail-scale use cases, this is everything you need. Bloomberg's $24k/year buys you analyst estimates, real-time quotes, transcripts, and Excel integration on top of this. But the underlying SEC data? Free.

I built Finterm as a free browser-based EDGAR viewer on top of this API — it handles the concept aliasing, Q4 synthesis, and FCF calculation so you can just type a ticker and see the numbers. The full writeup on how it's built (Cloudflare Workers, no Redis, WebGL charts) is on the blog.

推荐订阅源

DEV Community