Why is market cap not just price times a share count?

Market capitalisation looks like the easiest derived figure in finance: price × shares. Every part of that sentence is unstable over time, which is why a historical market-cap series is its own endpoint rather than something you compute.

The endpoint

/historical-market-cap/{ticker} takes from, to (YYYY-MM-DD), reverse ("true" or "false", for newest-first) and fmt (json or csv). Frequency is weekly, coverage is US listings, and each request costs 10 API calls.

The response shape is unusual enough to break naive code. It is not an array. It is an object whose keys are sequential integer indices as strings:

{ "0": { date: "2026-06-02", value: 4623255257600 },
  "1": { date: "2026-06-09", value: 4261696748400 },
  ...
  "8": { date: "2026-07-24", value: 4884633457800 } }

Iterate over the values, not the keys. The keys carry no information beyond order, and sorting them as strings gives you "10" before "2".

Weekly is approximately weekly

The points fall on a weekly grid, and the newest point sits wherever the series ends that day. Asked on 2026-08-19 for a window closing that day, the tail ran 07-28, 08-04, 08-07: seven days, then three, because 08-07 was the newest value the series held. Asked again on 2026-09-28, the same window ended 08-11, 08-18, clean sevens, and a year-long window ended 09-01, 09-04: the short step had moved to the new end of the data.

Do not assume a fixed grid, and do not assume the irregularity is a one-off you can hard-code around either. If you resample or annualise, derive the interval from the dates you received rather than from 52 points a year.

The window is the endpoint's, not yours

from narrows, but only inside a window the endpoint sets for itself. On 29 September 2026 Devon Energy's series began on 2021-09-17 whether the request said from=2020-01-01 or sent no from at all: 262 points, about five years. A window wholly before that, 2010 to 2015 for Apple, answered 200 and an empty array. So a "decade of market cap" is not one call, and an empty answer can mean "too old" rather than "no such company". For older history you rebuild it from prices and the outstandingShares series below.

Why the share count moves

The reason you cannot reliably reconstruct this series from prices is that the multiplier is not a constant. Over any meaningful window, shares outstanding change because of:

• Buybacks — the company purchases and retires its own shares. The count falls; each remaining share represents more of the business.
• Issuance — a secondary offering, an acquisition paid in stock, a convertible converting. The count rises.
• Employee compensation — exactly the M transactions from the previous lesson. Every RSU that vests creates shares. At a large company this happens continuously.
• Splits — the count changes but the capitalisation does not, which is precisely why splits must be handled separately from the other three.

So price × today's share count applied to a price from 2022 gives you a number that never existed. The outstandingShares section in /fundamentals — which is where historical=1 earns its keep — carries the count as a series for this reason.

Two figures that disagree, and both are right

From live Apple data on 2026-07-28:

• Highlights.MarketCapitalization (a snapshot, with General.UpdatedAt of 2026-07-27): 4,948,317,175,808
• The weekly series at its nearest point, 2026-07-24: 4,884,633,457,800

A gap of $63.7 billion, or 1.3%. That is not an inconsistency to report — it is four days of price movement between two observations. Compare snapshots to snapshots and series points to series points, and stamp everything with the date it describes.

Divide the 07-24 point by SharesOutstanding of 14,687,356,000 and you get $332.6 — a plausible price for that date, and a useful sanity check that the series and the share count belong to the same company.

The volatility this makes visible

In that same series, the value fell from 4,623,255,257,600 on 06-02 to 4,261,696,748,400 on 06-09 — −$361.6 billion, or −7.8%, in one week. Roughly the entire market value of a large-cap company, appearing and disappearing as a rounding adjustment on a bigger one. Market cap is a useful unit for exactly this: it converts a percentage into a quantity you can hold in your head.

Try it now

1. Here is /historical-market-cap/AAPL.US from 28 July to 4 September 2026, every point. Compute the actual gaps between consecutive dates and count how many are not exactly seven days. A year-long window read on 28 September 2026 held 50 points, and one of its 49 gaps was not seven days: say which, from this table.

2. Take the four July points, /historical-market-cap/AAPL.US for July 2026, the first table below. Divide each by the matching entry in outstandingShares from /fundamentals/AAPL.US?filter=outstandingShares, the second table: for July 2026 the matching entry is the quarter ending 30 June. The third table is the raw close on each of the four dates.

You have just reconstructed a price series from two unrelated endpoints — and any point where it disagrees with the real close is a share-count change worth investigating.

3. Find the largest single week-on-week change in the step 1 table and express it both as a percentage and in dollars. Decide which one communicates better, and to whom.

4. Here is Devon Energy's series asked from=2020-01-01. Compare the first date with the date you asked for, and write the check your loader runs so that a short series is reported as short rather than stored as complete.