This example demonstrates how to use the Reference client to retrieve point-in-time (PIT) security master records for Apple Inc. alongside daily bar aggregates. By combining daily close prices with shares outstanding, we can analyze changes in Apple’s total market capitalization over time.

See also
Security master dataset guide for further details.

Market capitalization

Market capitalization, or "market cap," is the total value of a company’s outstanding shares of stock, representing its overall market value. It is typically calculated by multiplying the current stock price by the total number of outstanding shares:

Market Capitalization = Share Price \times Shares Outstanding

This straightforward calculation provides a snapshot based on the latest share price but does not account for complexities like share class variations, potential stock buybacks, or other corporate actions that might affect a company’s actual valuation over time.

Apple daily bars

Using the Historical client client, we can retrieve OHLCV-1d bars from 2018-05-01. These daily bars provide close prices that we can use to calculate and plot Apple's market capitalization. Note that these bars are aligned with UTC date boundaries, so the close price represents the price at UTC midnight, which may differ from the local market session close price.

See also
Aggregate bars (OHLCV) schema guide for further details.

Security master PIT records

Next, we’ll use the security master API to request point-in-time (PIT) records for Apple Inc. stocks (AAPL) publicly listed in the US since 2018-05-01.

We apply the countries filter with "US" to ensure we capture only US-listed securities, in this case Apple Inc. listed on Nasdaq (XNAS). For securities listed on multiple exchanges, additional filtering on the returned DataFrame may be necessary to isolate the desired listing.

Python

      
    
import databento as db
import matplotlib.pyplot as plt
import pandas as pd

# Set parameters
dataset = "XNAS.ITCH"
symbol = "AAPL"
start = "2018-05"
end = "2025-04"

# Create a historical client
hist_client = db.Historical(key="$YOUR_API_KEY")

# Request OHLCV-1d data to obtain close prices
data = hist_client.timeseries.get_range(
    dataset="XNAS.ITCH",
    schema="ohlcv-1d",
    symbols=["AAPL"],
    start="2018-05",
    end="2024-11",
)
df_bars = data.to_df()

# Create a reference client
ref_client = db.Reference(key="$YOUR_API_KEY")

# Request security master records for Apple
df_security_master = ref_client.security_master.get_range(
    symbols=["AAPL"],
    countries=["US"],
    start=start,
)
df_security_master["shares_outstanding_date"] = pd.to_datetime(
    df_security_master["shares_outstanding_date"],
    utc=True,
)
df_security_master.set_index("shares_outstanding_date")

# Filter and resample the shares outstanding to daily frequency, forward filling missing values
df_shares_outstanding = (
    df_security_master[["shares_outstanding_date", "shares_outstanding"]]
    .set_index("shares_outstanding_date")
    .resample("D")
    .ffill()
)

# Align both dataframes on the date index
df_market_cap = df_bars[["close"]].join(df_shares_outstanding, how="left")

# Calculate market capitalization by multiplying close price with shares outstanding
df_market_cap["market_cap"] = (
    df_market_cap["close"] * df_market_cap["shares_outstanding"]
)
df_market_cap["market_cap"] = df_market_cap["market_cap"] / 1e9  # Convert to billions

# Plot the results
plt.plot(df_market_cap["market_cap"], label="market_cap")
plt.legend()
plt.xlabel("Date (UTC)")
plt.ylabel("Market Capitalization (Billion USD)")
plt.title(f"{symbol}")
plt.show()

AAPL market cap