Free Market Cap API
for Reliable Company Valuation借助免费市值 API
可靠评估公司价值

TL;DR核心摘要

Understand the market cap formula and fields理解市值计算公式与字段定义

Start with a defined formula先明确计算公式

The basic formula is simple: market capitalization equals price per share multiplied by total outstanding shares. The difficult part is choosing compatible inputs. An API may use the latest trade, previous close, an exchange official close, or a delayed quote. Its share count may be basic shares outstanding, diluted weighted-average shares, float, or a provider estimate. Those fields are not interchangeable.

公式本身并不复杂：市值等于每股价格乘以总已发行股份数。真正容易出错的是输入口径。价格可能指最新成交价、前一交易日收盘价、交易所官方收盘价或延时报价；股份数也可能采用基本股数、稀释股数、流通股数或服务商估算值。这些口径不能混用。

Choose the correct share-count denominator选择正确的股份数分母

Basic shares outstanding usually describes issued shares currently held by investors, while diluted measures can incorporate instruments that may become common shares. The Alpha Vantage documentation lists basic and diluted quarterly shares as separate returned values. Float excludes closely held or otherwise restricted shares and is useful for tradability analysis, but it is not the standard denominator for total equity market capitalization. Weighted-average shares used in earnings-per-share calculations describe a reporting period rather than necessarily the share count at one point in time.

基本已发行股份数通常指投资者当前持有的已发行股份；稀释口径还会考虑未来可能转换成普通股的工具。Alpha Vantage 文档会把季度基本股数和稀释股数作为不同字段返回。流通股数会排除大股东长期持有或受限制的股份，更适合衡量可交易性，却不适合作为公司整体市值的标准分母。计算每股收益时使用的加权平均股数反映的是一段期间，也不一定等于某个时点的真实股数。

Handle share classes, identifiers, and currency处理股份类别、标识符和币种

For companies with several listed share classes, decide whether the response is security-level capitalization or total company equity value. Multiplying each class by its own price and adding the results may be appropriate, but only if the classes and share counts are complete and not duplicated. Depositary receipts introduce another conversion ratio. Never assume that summing every ticker with a similar issuer name produces a valid company total.

如果一家公司有多个上市股份类别，首先要确认接口返回的是单只证券的市值，还是整家公司的股权价值。分别用各类别股价乘以对应股数再求和，有时是合理做法，但前提是类别完整、股数准确，而且没有重复计算。存托凭证还涉及换算比例，不能看到发行人名称相同就把所有股票代码直接相加。

Retain currency, exchange, symbol, permanent security identifier, price timestamp, share-count effective date, calculation timestamp, adjustment status, and source. For U.S. issuers, SEC EDGAR submissions and XBRL data can provide official filing identifiers and company facts that support reconciliation. These fields let downstream users explain why two providers disagree and prevent a USD result from being compared directly with an unconverted EUR or JPY result.

建议同时保存币种、交易所、股票代码、永久证券标识符、价格时间戳、股份数生效日期、计算时间、调整状态和数据来源。对于美国发行人，SEC EDGAR 的申报与 XBRL 数据可提供官方申报标识和公司事实，便于核对差异。保留这些字段，也能避免把美元市值与未经换算的欧元或日元市值直接比较。

Keep market cap separate from enterprise value不要混淆市值与企业价值

Market cap is not enterprise value. Market cap measures the market value of common equity; enterprise value requires additional balance-sheet inputs and a declared treatment of debt, cash, preferred equity, and minority interests. If the application ranks takeover value or capital structure, a market-cap-only endpoint is insufficient.

市值和企业价值不是一回事。市值衡量普通股权益的市场价值；企业价值还要结合债务、现金、优先股和少数股东权益，并明确每一项的处理方式。如果应用要比较收购成本或资本结构，只提供市值的接口并不够。

Choose the right market-cap path按使用场景选择市值数据路径

Validate a free market cap API before use使用免费市值 API 前应做的校验

Run representative acceptance tests使用代表性样本做验收

Test a representative sample rather than one famous large-cap ticker. Include a recent IPO, a company with multiple share classes, a foreign or depositary listing, a security with a recent split, an inactive symbol, and a deliberately invalid identifier. Record the expected status for each case before the test so that a clean-looking response is not mistaken for a correct one.

测试时不要只选一只知名大盘股。样本应覆盖近期 IPO、多股份类别公司、境外上市或存托凭证、刚刚拆股的证券、已停止交易的代码，以及故意输入的无效标识符。最好在测试前写清楚每个案例的预期结果，避免把格式完整的响应误当成正确数据。

Define acceptance thresholds by use case. A watchlist may tolerate delayed data with a visible timestamp; an end-of-day report may require the official close and a completed corporate-action cycle; a historical backtest needs point-in-time values that do not leak later share-count revisions. If the endpoint cannot document the required time basis, narrow the use case instead of hiding the uncertainty.

验收标准应随场景而定。观察列表可以接受带明确时间戳的延迟数据；日终报告可能要求官方收盘价，并确认公司行动已经处理完毕；历史回测则必须使用严格的时点数据，不能把后来修订的股份数带回过去。如果接口说不清数据时点，就应缩小使用范围，而不是掩盖不确定性。

Reconcile disagreements at the input level从输入层面对账差异

When two sources disagree, reconcile the inputs before comparing the final number. Align the as-of time, listing currency, price type, share class, split basis, and shares-effective date. Then calculate market cap independently from each source's components. This separates a genuine data disagreement from a difference in methodology. Use an absolute and percentage tolerance appropriate to the application, and route values outside it for review; do not automatically choose the larger or newer-looking result.

当两个来源给出的市值不一致时，不要先比较最终数字，而要回到输入项逐一核对：数据时点、上市币种、价格类型、股份类别、拆股调整方式和股份数生效日期。随后分别用两组输入重新计算市值，才能判断问题来自原始数据，还是来自计算口径。容差应结合实际用途设置，超出范围的结果交由复核，不能简单选择数值更大或看起来更新的一项。

Test historical and operational fit检验历史研究与运行适用性

Current company-profile endpoints are convenient for dashboards but can be unsafe for historical research. Providers may refresh an old fiscal period with a later filing, change identifier mappings, or return today's share count beside an earlier price. SEC XBRL data retains filing facts with period and filing context, illustrating why a backtest needs point-in-time fundamentals, revision history, and an availability timestamp. “Fiscal period end” is not the same as “publicly available on.”

公司概览接口很适合当前仪表盘，却未必适合历史研究。服务商可能用后续申报更新旧财期、调整标识符映射，或者把今天的股份数与过去的股价放在一起。SEC XBRL 数据会保留申报事实、所属期间和申报背景，也说明回测为什么需要时点基本面、修订记录和数据实际可获得的时间。“财期结束日”不等于“市场获知日”。

Also test authentication errors, rate-limit responses, timeouts, malformed symbols, partial payloads, and provider maintenance. The Alpha Vantage documentation identifies required API-key parameters and endpoint behavior. Keep keys in server-side secrets, log response status and retry decisions without credentials, and reject any dependency that cannot fail safely.

运行层面还要覆盖鉴权失败、限流、超时、错误股票代码、部分字段缺失和服务维护等情况。Alpha Vantage 文档列出了必需的 API key 参数和端点规则。密钥应保存在服务端；日志可以记录响应状态和重试决定，但不能记录凭证。无法安全失败的接口，不适合作为生产依赖。

Build a reliable market cap integration构建可靠的市值数据集成

Build a traceable pipeline构建可追溯的数据管道

Treat market cap as a derived record with lineage, not a loose number copied into a table. A durable pipeline separates security resolution, source retrieval, normalization, validation, publication, and monitoring so that each failure has a visible owner and recovery path.

应把市值视为带有数据血缘的派生记录，而不是随意复制进表格的数字。可靠的数据管道会把证券身份解析、来源获取、标准化、校验、发布和监控分开，使每类故障都有明确的责任环节与恢复路径。

• Resolve identity: map symbol plus exchange to a permanent security and issuer ID. Keep symbol-history aliases because tickers can change, move exchanges, or be reused.
• Store the raw response: retain an immutable copy or reproducible request reference before normalization. This preserves evidence when a provider later revises a field.
• Store calculation inputs: keep price, shares, effective dates, currency, adjustment state, provider, and retrieval time alongside the returned or calculated market cap.
• Normalize units and nulls: distinguish raw currency values from thousands, millions, B, or T. Treat unavailable, not applicable, and zero as separate states.
• Apply corporate actions once: verify whether source fields are adjusted. Avoid applying a split factor to both an already adjusted price and an already adjusted share count.
• Cache deliberately: refresh quotes more often than slowly changing share counts, but invalidate the derived value whenever either input changes. Preserve both timestamps.
• Validate before publish: reject negative values, flag extreme day-over-day changes, and compare a sample against a second official or licensed source. Route exceptions to review rather than silently clipping them.
• Handle quota and failures: use bounded retries with backoff, queue unfinished batches, expose stale-data status, and never convert missing responses to zero.

• 统一证券身份：将股票代码和交易所映射到永久证券标识符及发行人标识符，并保留历史代码别名，因为代码可能变更、转板或被重新使用。
• 保存原始响应：在标准化前保留不可变的原始响应，或保存可以复现请求的引用，以便服务商之后修订字段时仍有核查依据。
• 保留计算输入：将股价、股份数、生效日期、币种、调整状态、服务商和抓取时间与接口返回或自行计算的市值一起存储。
• 规范单位与空值：区分原始货币金额、千、百万以及 B、T 等数量级，并将“不可用”“不适用”和数值零视为不同状态。
• 公司行动只处理一次：先确认来源字段是否已经调整，避免对已调整股价和已调整股份数再次同时应用拆股因子。
• 合理设置缓存：报价更新频率可以高于变化较慢的股份数，但任一输入发生变化时都应使派生市值失效，并保留两者各自的时间戳。
• 发布前校验：拒绝负值，标记异常的单日变化，并抽样与第二个官方或已授权来源核对。异常应进入人工复核，而不是被静默截断。
• 处理配额与失败：使用次数受限的退避重试，对未完成批次排队，显示数据过期状态，并且绝不能把缺失响应转换成零。

Monitor data quality, not only uptime监控数据质量，而不只是可用性

Monitor data quality separately from transport uptime. Useful signals include the proportion of requested securities with a valid result, age of price and share-count inputs, frequency of identifier misses, number of values outside reconciliation tolerance, retry volume, and quota consumption. Alert on a change from the system's own baseline rather than declaring a universal threshold. A 200 response with stale or mismatched inputs is a data-quality failure even though the HTTP request succeeded.

数据质量和网络可用性应分开监控。可以关注有效结果覆盖率、股价与股份数的时效、标识符匹配失败次数、超出对账容差的记录数、重试量和配额消耗。告警阈值应根据系统自身基线设定，而不是照搬一个通用数字。即使 HTTP 返回 200，只要输入已经过期或口径不一致，仍然属于数据质量故障。

Expose provenance to downstream users. A screen, export, or agent response should be able to show the as-of time, currency, security scope, source, and whether the value was returned or calculated. This is especially important when market cap drives ranking cutoffs, eligibility rules, risk limits, or automated decisions. If provenance cannot travel with the number, keep the value out of high-consequence workflows.

下游用户也应看得到数据来源。页面、导出文件或智能体响应至少要能说明数据时点、币种、证券范围、来源，以及市值是服务商直接返回还是系统自行计算。当市值会影响排名门槛、准入规则、风险限制或自动决策时，这一点尤其重要。如果数值无法携带这些背景信息，就不应进入高影响工作流。

Roll out in controlled batches分批扩大覆盖范围

Start with a small, fixed ticker set and log the request, normalized record, validation decision, and displayed value. Once the pipeline can explain discrepancies, expand coverage in batches. For Python-specific retrieval patterns, see the free stock data API Python guide; for point-in-time research, use the separate stock data API for backtesting guide.

先从一组规模较小、保持固定的股票代码开始，并记录原始请求、标准化结果、校验结论和最终展示值。等数据管道能够解释差异后，再分批扩大覆盖范围。Python 接入方式可参考免费股票数据 API Python 指南；需要严格时点数据时，则参考回测股票数据 API 指南。

Use QVeris to inspect a company overview capability使用 QVeris 查看公司概览工具

FAQ常见问题

References and next steps参考资料与下一步

Alpha Vantage documentation

Alpha Vantage 文档