Data Schema

Data Schema

Each record in the Historical Market Cap dataset represents a single equity’s size on a specific calendar date, captured using information available at that time. All fields are point-in-time unless explicitly noted.

The dataset is structured to support historical research, universe construction, and systematic trading workflows without introducing forward-looking bias.

---

Core Fields

These fields define the identity and timing of each observation.

Field	Type	Description
date	string	Calendar date of the observation (YYYY-MM-DD)
ticker	string	Equity ticker symbol
shares_outstanding	integer	Shares outstanding as of the given date
market_cap	float	Market capitalization as of the given date

All core fields reflect values that were observable on the specified date.

---

Point-in-Time Integrity

All fields in the Historical Market Cap dataset are point-in-time by design.

• Values are not restated using future information

• Historical observations are not revised retroactively

• Changes in shares outstanding or market capitalization appear only after they become observable

This ensures that historical queries reflect how equity size would have been perceived at that moment, not how it appears in hindsight.

---

Coverage Metadata

Coverage information is exposed via a separate discovery endpoint and should be used prior to querying historical data.

For each ticker, metadata includes:

• The earliest date for which market cap data is available

This allows users to:

• Avoid querying dates prior to coverage

• Construct survivorship-safe universes

• Reason explicitly about when a security enters the dataset

---

Update Behavior

The Historical Market Cap dataset is append-only.

• New records are added as new dates become available

• Existing historical records are not removed

• Previously published point-in-time values remain fixed

This guarantees reproducibility of research and stability of downstream systems that depend on historical data.

---

Data Types and Formatting

• All dates are returned as ISO-formatted strings (YYYY-MM-DD)

• Numeric fields are returned as native numeric types

• Empty result sets return a valid response with count = 0

The API does not return null placeholders for missing dates; absence of a record implies no coverage for that ticker on that date.

---

Notes on Correct Usage

• Market cap values should be treated as authoritative for the given date

• Users should not backfill missing dates or extrapolate values across coverage gaps

• For long histories, queries should be scoped by ticker rather than wide date ranges

These conventions help preserve both correctness and performance.

---

Example Usage

Querying the historical market cap of AAPL on 2025-12-01.

GET https://api.alphanume.com/v1/dilution
    ?ticker=AAPL
    &date=2025-12-01

requests.get("https://api.alphanume.com/v1/historical-market-cap?ticker=AAPL&date=2025-12-01")

{
  "count": 1,
  "data": [
    {
      "date": "2025-12-01",
      "ticker": "AAPL",
      "market_cap": 4201314409000.0005,
      "shares_outstanding": 14840390000.0
    }
  ]
}

---

Summary

The Historical Market Cap data schema is intentionally minimal and explicit.

• Every record has a clear temporal meaning

• All values are safe for historical analysis

• No fields rely on future revisions or survivorship assumptions

This structure ensures the dataset can be used confidently in both research and production environments.