Stock Market-Cap History Dataset for Cross-Sectional Tests

A stock market-cap history dataset supports cross-sectional tests when every rebalance date rebuilds size buckets from market capitalization known on that date, including names that later shrink or disappear.

Alphanume Historical Market Cap stores one row per covered ticker and trading date with market_cap and shares_outstanding as they stood then. That is the right input for market-cap quintiles, size thresholds, signal normalization, and matched controls. A static snapshot of current size changes historical membership and leaks later winners and failures into earlier tests.

The endpoint is GET /v1/historical-market-cap. It requires a ticker or at least one date filter. An exact date returns the market-wide cross-section for that observation date, while a ticker returns its own time series. Market-wide ranges without a ticker are limited to seven calendar days.

Use the row as an as-of record

Rows are ordered by date descending and ticker descending. A page can contain up to 50,000 records, with has_more and next_cursor indicating continuation. The next request sends cursor_date and cursor_ticker together.

The point-in-time market cap explainer covers why old prices multiplied by today's shares outstanding produce a value no investor saw on the historical date.

Pull one complete rebalance date

Cross-sectional testing is easiest to audit one date at a time. Query an exact rebalance date, save every raw page, and stop only after has_more becomes false. If a planned month-end falls on a weekend or holiday, select the last covered trading date using a documented calendar rule rather than accepting an empty cohort.

import os
import requests

url = "https://api.alphanume.com/v1/historical-market-cap"
headers = {"X-API-Key": os.environ["ALPHANUME_API_KEY"]}
params = {"date": "2024-06-28"}
rows = []

while True:
    response = requests.get(url, headers=headers, params=params, timeout=30)
    response.raise_for_status()
    payload = response.json()
    rows.extend(payload["data"])
    if not payload.get("has_more"):
        break
    cursor = payload["next_cursor"]
    params.update({
        "cursor_date": cursor["date"],
        "cursor_ticker": cursor["ticker"],
    })

assert all(row["date"] == "2024-06-28" for row in rows)

Save the returned count and a digest of the normalized rows with the cohort. A missing ticker is missing coverage for that date and should not be converted to zero market cap. The companion ticker-coverage route reports each symbol's first available date, which helps separate an early-history gap from a malformed join.

Rebuild quintiles through time

Rank the eligible cross-section independently on every rebalance date. Percentile ranks handle repeated capitalization values more predictably than hard-coded dollar thresholds, while the bucket rule should still be fixed before outcomes are loaded. Keep the unbucketed raw cap alongside the label.

import pandas as pd

panel = pd.DataFrame(all_rebalance_rows)
panel = panel.dropna(subset=["date", "ticker", "market_cap"])
panel = panel[panel["market_cap"] > 0].copy()

panel["size_rank"] = panel.groupby("date")["market_cap"].rank(method="first")
panel["group_size"] = panel.groupby("date")["market_cap"].transform("size")
panel["market_cap_quintile"] = (
    ((panel["size_rank"] - 1) * 5 / panel["group_size"]).astype(int) + 1
)

counts = panel.groupby(["date", "market_cap_quintile"]).size()
assert counts.gt(0).all()

The exact bucket expression is less important than documenting it and testing boundary behavior. For a small cross-section, tied values or sparse groups can create unequal buckets. Report the count, minimum cap, median cap, and maximum cap for each date and quintile so a bucket failure is visible.

Define the eligible universe first

Market cap alone does not repair a survivorship-biased price source, ticker reuse, incorrect split adjustment, stale prices, or missing delisting returns. It also does not measure float or execution capacity. Each of those needs a separate input and an explicit failure report.

Audit bucket migration

The useful feature of a historical panel is that companies move between buckets. Save a transition table from one rebalance to the next with prior quintile, new quintile, market-cap change, share-count change, and identifier status. A large migration driven by a share-count jump tells a different story from one driven by price.

• Keep entrants and exits instead of requiring a ticker to exist on every date.
• Report first-available coverage dates for names missing early in the study.
• Preserve raw pages and the filtered panel as separate artifacts.
• Calculate returns only after each date's bucket membership is saved.

Run three dates before a decade

Pull three monthly rebalance dates and export raw pages, coverage failures, quintile summaries, and the transition table. Confirm that the smallest bucket on each date actually contains that date's smallest eligible companies and that later winners were not assigned their current size in the earlier cross-section.

Explore the fields on the Historical Market Cap page, then use the Historical Market Cap guide for the complete pagination workflow. Expand the test only after the three-date audit reproduces from saved inputs.