DEV Community

Project Ace
Project Ace

Posted on

10 years of financials for any US stock from the free SEC API (and the trap in the data)

#api #finance #javascript #data

The SEC gives you every US-listed company's reported financials for free, as JSON, no API key. Many people still scrape finance sites or pay for a data provider. Here is how to use the SEC data directly, and the one thing that will silently break your time series if you don't handle it.

The three endpoints you need

  1. Ticker → CIK: https://www.sec.gov/files/company_tickers.json maps tickers like AAPL to the SEC's company ID (CIK 320193).
  2. All reported numbers: https://data.sec.gov/api/xbrl/companyfacts/CIK0000320193.json (CIK padded to 10 digits). This has every XBRL fact the company ever filed: revenue, net income, assets, EPS, cash flow and hundreds more.
  3. Filings list: https://data.sec.gov/submissions/CIK0000320193.json for 10-K, 10-Q, 8-K, Form 4 and so on, with links to the documents.

Two rules from the SEC's fair-access policy: send a User-Agent header with a contact email, and stay under 10 requests per second. Anonymous or bursty clients can get blocked.

Getting annual numbers

In companyfacts, each metric lives under facts["us-gaap"][concept].units.USD as a list of facts. For annual values, keep facts where form == "10-K" and fp == "FY", and for income-statement items also check that the period (start to end) is about a year long. Otherwise quarterly values can sneak in, because some companies also tag quarterly figures in their 10-K.

Each 10-K repeats the previous two or three years, so the same year shows up several times. Group by the period's end date and keep the most recently filed value (restatements win).

The trap: companies change concept names

This is the part that bites. Apple's revenue over time:

Concept Used in 10-K filings for fiscal years
SalesRevenueNet 2009–2017
Revenues 2018
RevenueFromContractWithCustomerExcludingAssessedTax 2019–2025

Coca-Cola used SalesRevenueGoodsNet until 2017 and Revenues since 2018.

The concept names changed when the revenue accounting standard ASC 606 came in. If you read only one concept, your chart either stops in 2017 or starts in 2019, and you won't get an error. You just get a shorter series.

The fix is a priority list per metric. For each fiscal year, take the first concept that has a value:

const REVENUE = [
  'RevenueFromContractWithCustomerExcludingAssessedTax',
  'Revenues',
  'SalesRevenueNet',
  'RevenueFromContractWithCustomerIncludingAssessedTax',
  'SalesRevenueGoodsNet',
];
Enter fullscreen mode Exit fullscreen mode

With that, Apple's revenue comes out cleanly from FY2016 ($215.6B) to FY2025 ($416.2B), and Coca-Cola's from 2014 to 2025.

Some gaps are real, though: Coca-Cola does not report a Liabilities total in its XBRL data, for example. Missing should stay missing rather than become zero.

Disclosure: This article was written with help from an AI assistant (Claude); the figures come from the SEC API, queried on 18 October 2026. Not investment advice.

Top comments (0)