DEV Community: Project Ace

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

Project Ace — Mon, 19 Oct 2026 07:38:06 +0000

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

Ticker → CIK: https://www.sec.gov/files/company_tickers.json maps tickers like AAPL to the SEC's company ID (CIK 320193).
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.
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',
];

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.

Monitoring Hacker News for your keywords? Most "hits" don't mention them

Project Ace — Sun, 18 Oct 2026 04:21:45 +0000

If you track mentions of your product, framework or competitor on Hacker News, you probably use the free Algolia HN Search API. It's great: fast, free, no key. But it has a catch that is easy to miss.

The numbers

I searched HN comments since 1 October 2026 with search_by_date and then checked each result for the keyword itself:

Keyword	Hits reported by Algolia	Comments that actually contain the word
`rust`	11,133	1,715 (15 %)
`deno`	4,822	443 (9 %)
`postgres`	608	582 (96 %)

Short words are the problem. Part of it is that Algolia also searches author names (rust returns comments by a user called rustyhancock), and it is typo-tolerant. But for deno, almost none of the extra hits contain anything that looks like "deno" at all, and I could not pin down why. Distinctive words like postgres are mostly fine.

If you count mentions, build a dashboard or feed comments into an LLM for sentiment, 85–90 % noise ruins the result.

Why the obvious fix doesn't work

My first idea was to use Algolia's _highlightResult: keep a hit if any field has matchLevel != "none". That looked perfect in a quick test, but Algolia only returns highlight data for roughly the first 70 hits of a response. Everything after that has no highlights, so this filter silently throws away most of the good results too (for postgres it kept 74 of 717 real matches). I shipped that bug for about an hour before noticing.

What works

Check the text yourself. Keep a hit only if every keyword appears at the start of a word in the title, comment text or URL:

const words = query.toLowerCase().split(/\s+/).filter(Boolean);
const res = words.map((w) => new RegExp(`(^|[^a-z0-9])${w.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`, 'i'));

function isRealMatch(hit) {
  const text = `${hit.title ?? ''} ${hit.story_title ?? ''} ${hit.comment_text ?? ''} ${hit.url ?? ''}`
    .replace(/<[^>]+>/g, ' ');
  return res.every((re) => re.test(text));
}

"Start of a word" keeps postgres → PostgreSQL but drops rust → trust.

Two more things you'll hit when collecting more than a few hundred items:

The 1,000-hit cap. Algolia returns at most 1,000 results per query. With search_by_date, take the oldest created_at_i of each page and query again with numericFilters=created_at_i<{oldest} to walk back in time.
Filtering shrinks pages. After filtering, a page of 1,000 hits might give you 80 items, so keep walking until you have enough.

Disclosure: This article was written with help from an AI assistant (Claude); the numbers come from my own queries on 18 October 2026.