For most tickers on the Massive ticker details endpoint you will never notice the difference, which is exactly what makes this worth reading: on a company with one class of stock the two counts are the same number, so wrong code passes every test you write against AAPL. It only diverges when you hit a multi-class name, and then it diverges by a lot.
Applies to
- Plans: reference data is included with every plan, including the free Basic tier.
- Endpoints: /v3/reference/tickers/{ticker}.
- Asset classes: US stocks.
How to see both fields
Ask ticker details for either share class and you get both counts on the same object:
curl -X GET "https://api.massive.com/v3/reference/tickers/BRK.A?apiKey=YOUR_API_KEY"
Response
{
"results": {
"ticker": "BRK.A",
"name": "Berkshire Hathaway Inc.",
"market_cap": 1086403189300,
"weighted_shares_outstanding": 1427140,
"share_class_shares_outstanding": 488450
},
"status": "OK"
}
The two fields on a multi-class company
Berkshire Hathaway makes the relationship visible. Both tickers describe one company, measured in different units:
| Ticker | weighted_shares_outstanding | share_class_shares_outstanding |
|---|---|---|
| BRK.A | 1,427,140 | 488,450 |
| BRK.B | 2,140,709,794 | 1,408,035,161 |
Divide the two weighted figures and you get exactly 1,500, which is the A-to-B share conversion ratio: the same equity counted in A units or in B units. The share-class figures have no such relationship, because they count two different populations of shares.
Alphabet shows the other half of the pattern. GOOGL and GOOG both report 12,229,934,831 weighted shares, while their share-class counts are 5,868,000,000 and 5,527,000,000.
Which one to use
Use weighted_shares_outstanding for anything that values the company: market capitalization, enterprise value, per-share figures meant to describe the business. Use share_class_shares_outstanding when you genuinely care about one class, such as computing the float of a particular listing or working out voting weight.
Multiplying the class count by the price values one class rather than the company, and summing that across classes is not a fix, because you will still miss any class you did not fetch.
Why express the whole company in one class's units
Expressing the whole company in each class's units means one multiplication answers the valuation question from whichever ticker you happen to hold. The alternative, publishing a single company-level share count, would not work: A shares and B shares are not interchangeable, so there is no unit in which one number is meaningful for both. Restating the total in each class's own unit is the way to keep a single multiplication correct.
The consequence to design for: a multi-class company appears more than once in your data, with a slightly different market cap each time. Pick one class as canonical rather than adding them up.
If you see an error
Identical values in the two fields mean the company has one share class. That is the common case.
A market cap that looks like a fraction of the real company is the class count used where the weighted one belongs.
A null in either field happens on ETFs and funds, where the concept does not apply in the same way.
