Free Stock Ownership API
for Institutional Holdings免费股票持仓 API
机构持股数据接入指南
Compare ownership datasets by filing regime, reporting period, security mapping, amendments, percentage denominator, free-plan limits, and permitted use before you build.
构建前应从申报制度、报告期、证券映射、修订处理、持股比例分母、免费限额和许可用途等方面比较持股数据，
再为研究工具或智能体选择合适的能力。
Free stock ownership API: what to choose免费股票持仓 API：应该如何选择
“Stock ownership” is not one universal feed. Institutional holdings commonly come from periodic regulatory filings; beneficial-ownership disclosures, insider transactions, mutual-fund holdings, ETF constituents, and an issuer’s shareholder register follow different rules and update schedules. Start by naming the legal or operational dataset you need, then select an API that preserves its reporting period, filing timestamp, source form, identifiers, and amendment history.
“股票持仓”并不是一种统一数据。机构持仓通常来自周期性监管申报；受益所有权披露、内部人交易、共同基金持仓、ETF 成分以及发行人的股东名册，则分别遵循不同规则和更新时间。应先明确所需数据对应的法律或业务来源，再选择能够保留报告期、提交时间、申报表单、证券标识和修订历史的接口。
For U.S. institutional research, a 13F-based API can answer who reported holding a security and what a reporting manager disclosed at quarter end. It cannot prove the manager still owns the position today, reveal every asset or short position, provide acquisition cost, or reproduce a complete cap table. Display both the reporting period and filing date wherever the data appears so users do not mistake disclosure time for position time.
对于美国机构持仓研究，基于 13F 的 API 可以回答“哪些申报机构在季末披露持有某只证券”以及“某家管理机构披露了哪些持仓”。但它不能证明该机构今天仍持有这些仓位，也不能覆盖所有资产、空头仓位、买入成本或完整股权结构。展示数据时应同时标明报告期和提交日期，避免用户把披露时间误认为持仓时点。
Most developer searches mean institutional holders from Form 13F, not live beneficial ownership, insider trades, ETF constituents, or a shareholder registry.
13F is a quarterly filing. A normalized API can simplify access, but it cannot turn periodic disclosure into a real-time position feed.
Check request quotas, latest-quarter access, history, commercial-use rights, attribution, exports, and whether an API key or card is required.
Ticker is convenient, but filings use manager and security identifiers. Ownership percentages also require a dated, documented share-count denominator.
中文用户更常搜索“机构持仓 API”“美股机构持股接口”或“13F 数据 API”。这些需求不同于实时行情、内部人交易、ETF 成分股或完整股东名册。
13F 是季度申报。API 可以清洗并统一字段，却不能把周期性披露变成实时仓位。
检查调用次数、历史季度、商业使用、归因、导出权限，以及是否需要信用卡或 API Key。
股票代码便于查询，但申报依赖机构与证券标识；持股比例还必须配合有日期且口径明确的股数分母。
Institutional ownership data and 13F holdings fields机构持股数据与 13F 持仓字段
A useful institutional ownership API answers two directions: “Which managers reported this security?” and “Which securities did this manager report?” Typical observations contain the reporting period, filing and amendment timestamps, form type, manager name and CIK, issuer name, title of class, source security identifier, mapped ticker and listing, shares or principal amount, reported value and units, put/call indication where applicable, investment discretion, voting authority, and source document link.
实用的机构持仓接口应支持两个方向：“哪些管理机构申报持有这只证券？”以及“这家管理机构申报了哪些证券？”典型记录应尽量包含报告期、提交与修订时间、表单类型、机构名称与 CIK、发行人名称、证券类别、来源证券标识、映射后的代码与上市地点、股数或本金金额、申报市值及单位、适用时的看涨/看跌标记、投资决策权限、投票权和原始文件链接。
Stock institutional holders API by ticker按股票代码查询机构持有人 API
For a ticker-first workflow, require point-in-time issuer mapping, pagination, sortable reported size, an explicit period, source manager count, and documented amendment handling. A percentage can mean share of the manager’s reported portfolio, share of the issuer’s outstanding stock, or share of the API’s observed institutional total. Confirm the denominator, share class, and date before comparing providers.
以股票代码为入口时，应要求按历史时点有效的发行人映射、分页、按申报规模排序、明确报告期、来源机构数量，以及清晰的修订处理说明。“持股比例”可能指该仓位占机构申报组合的比例、占发行人流通股的比例，或占接口所观测机构总持仓的比例。比较前必须确认分母、股份类别和对应日期。
13F holdings API for portfolio changes用于季度增减仓的 13F 数据 API
For change analysis, keep the filing period, original filing date, and amendment date separate. Match the same manager, security, share class, and position type across quarters. A larger reported position may reflect purchases, stock splits, mergers, identifier remapping, options treatment, manager reorganization, or amended data; label the result as a filing-to-filing change rather than an observed trade.
分析季度增减仓时，要分别保留持仓报告期、首次提交日和修订日，并在季度之间匹配同一机构、证券、股份类别和仓位类型。申报持仓增加可能来自买入、拆股、并购、标识重映射、期权处理、机构重组或申报修订，因此结果应标注为“申报间变化”，不能直接称为实际交易。
| Field字段 | Use用途 | Check检查点 |
|---|---|---|
| ticker / CIK / CUSIP | Resolve issuers and holders识别发行人与机构 | Mapping and share classes映射与股份类别 |
| period / filingDate | Build ownership history构建持仓历史 | Quarter versus submission date报告期与提交日 |
| shares / value | Rank major institutional holders排序主要机构持有人 | Units and reported value basis单位与申报市值口径 |
| change / ownershipPct | Compare quarters and concentration比较季度变化与集中度 | Calculation method and denominator计算方法与分母 |
| formType / accession / amendment | Trace each normalized row to its filing version把标准化记录追溯到具体申报版本 | Replacement versus additive amendment logic修订是替换还是追加的处理规则 |
| putCall / discretion / voting | Preserve position and control context保留仓位性质与控制权语境 | Null meaning, shared discretion, and non-equity units空值含义、共同决策权限和非普通股计量单位 |
Stock ownership records are not interchangeable不同股票持股记录不能混为一谈
There is no single filing that reveals every owner of a public company. Institutional investment reports, beneficial-ownership filings, insider transaction forms, and fund portfolio disclosures describe different people, thresholds, dates, and economic interests. A dependable API preserves the source record instead of collapsing them into one unexplained ownership percentage.
没有任何一种申报能够列出上市公司的全部股东。机构投资申报、受益所有权申报、内部人交易表单和基金组合披露，分别对应不同主体、门槛、日期和经济权益。可靠的接口应保留来源记录，不能把它们压缩成一个无法解释的持股比例。
| Record记录 | What it can show能够说明什么 | Time to preserve需要保留的时间 | Do not infer不能据此推断 |
|---|---|---|---|
| Form 13F | Quarter-end reportable positions of covered institutional investment managers.符合条件的机构投资管理人在季度末申报的可报告仓位。 | Period end, filing date, amendment date.报告期末、提交日与修订日。 | Exact trade date, current position, or the issuer's full cap table.确切交易日、当前仓位或发行人的完整股东名册。 |
| Schedules 13D / 13G | Certain beneficial owners crossing applicable reporting thresholds, plus later amendments.达到适用申报门槛的部分受益所有人，以及后续修订。 | Event or obligation date, filing date, amendment sequence.触发或义务日期、提交日与修订顺序。 | That every large-looking position appears in 13F or represents passive intent.所有大额持股都会出现在 13F 中，或申报人一定是被动持有。 |
| Forms 3 / 4 / 5 | Reported holdings and transactions of directors, officers, and qualifying beneficial owners.董事、高管及符合条件的受益所有人所申报的持股与交易。 | Transaction date, filing date, ownership nature, amendment.交易日、提交日、持有性质与修订信息。 | That a transaction code always means an open-market buy or sale.某个交易代码必然代表公开市场买入或卖出。 |
| Fund holdings disclosure | A portfolio's disclosed securities, weights, cash, and sometimes derivatives for a stated period.基金在指定报告期披露的证券、权重、现金及部分衍生品。 | Holdings date, publication date, revision or restatement date.持仓日期、发布日期与修订或重述日期。 | The fund's position on the retrieval date or the parent manager's aggregate ownership.抓取当日的基金仓位，或母管理机构的合并持股。 |
If Manager A reports 1.2 million shares in 13F and two funds branded by Manager A disclose 700,000 and 500,000 shares for the same period, summing all three rows produces 2.4 million shares. The fund rows may already be included in the manager-level filing. Store reporting entity, fund, security, period, ownership nature, and source relationship; aggregate only after the hierarchy and coverage are known.
假设管理机构 A 在 13F 中申报 120 万股，同一报告期内，其品牌下两只基金又分别披露 70 万股和 50 万股。如果把三条记录直接相加，会得到 240 万股；但两只基金的仓位可能已经包含在管理机构层面的申报中。应分别保存申报主体、基金、证券、报告期、持有性质与来源关系，只有明确层级和覆盖范围后才能汇总。
How to compare a free institutional holdings API如何比较免费的机构持仓 API
1. Define coverage and ownership scope1. 明确市场覆盖与持股范围
Write down the market, security types, reporting forms, historical depth, and whether you need holder-by-stock, portfolio-by-manager, or both. U.S. Form 13F covers certain institutional investment managers and reportable securities; it is not a complete cap table.
先写清市场、证券类型、申报表单、历史深度，以及需要“按股票查机构”“按机构查组合”还是双向查询。美国 Form 13F 覆盖特定机构投资管理人和可申报证券，不等于完整股权结构。
2. Test freshness, amendments, and history2. 测试更新、修订与历史数据
Use one stable ticker across two quarters. Compare filing dates, amendment handling, duplicate positions, missing identifiers, and the provider’s published refresh policy.
选择一只稳定股票测试两个季度，对比提交日期、修订处理、重复持仓、缺失标识符以及服务商公布的更新规则。
3. Read free-tier and license terms3. 阅读免费额度与许可条款
“Free” may mean a trial, evaluation data, latest-quarter access, non-commercial use, or a small daily quota. Record rate limits, retention rights, attribution, redistribution, and production-use restrictions before integration.
“免费”可能只是试用、演示数据、最新季度、非商业用途或较小日配额。接入前记录限流、保存权、归因、再分发与生产使用限制。
4. Measure completeness and mapping quality4. 衡量完整性与证券映射质量
Choose one manager with an amendment, one issuer with multiple share classes, one option position, one renamed security, and one quarter with an obvious corporate action. Compare normalized totals to the source filing, count unmapped rows, and inspect whether the API silently drops positions it cannot resolve.
应选择一家具备修订申报的机构、拥有多个股份类别的发行人、一笔期权仓位、一只发生过更名的证券，以及出现明显公司行动的季度进行测试。把标准化合计与原始申报对照，统计无法映射的记录，并检查接口是否会静默丢弃无法识别的仓位。
5. Define freshness honestly5. 如实定义数据新鲜度
Track at least three times: the quarter-end position date, the filing or amendment timestamp, and your ingestion timestamp. “Updated today” describes processing freshness, not the age of the underlying position. A quality UI should expose all three where relevant.
至少应跟踪三个时间：季末持仓日期、申报或修订时间，以及自身采集时间。“今日更新”只能说明处理时间较新，不能代表底层仓位是今天的。高质量界面应在适当位置同时展示这些时间。
How to integrate stock ownership data into an app如何把股票持仓数据接入应用
Request institutional holders by ticker按股票代码请求机构持有人
GET /ownership/institutional?ticker=AAPL&period=2025-12-31
Authorization: Bearer YOUR_API_KEY
{
"ticker": "AAPL",
"period": "2025-12-31",
"holders": [
{"holderCik": "...", "shares": 0, "value": 0}
]
}The endpoint and sample values above are provider-neutral placeholders. Replace them with the selected API’s documented path and schema. Validate the response, cache by reporting period, preserve source identifiers, and show the data date in your UI.
上述端点与示例值是服务商中立的占位示例。请替换为所选 API 的正式路径和字段；校验响应、按报告期缓存、保留来源标识符，并在界面显示数据日期。
Normalize ownership records safely安全标准化持股记录
Store raw filings or provider payloads separately from normalized rows. Key a version by manager, report period, accession or provider event ID, security identity, and position type; make amendment replacement idempotent. Treat null as unknown rather than zero, preserve unmapped source rows, and separate reported values from derived percentages or quarter changes.
原始申报或供应商响应应与标准化记录分开保存。版本主键应结合机构、报告期、申报编号或供应商事件 ID、证券身份和仓位类型，并让修订替换具备幂等性。空值表示未知而不是零；无法映射的来源记录也应保留，同时把申报原值与自行计算的比例或季度变化分开存放。
- Ingest by filing or update timestamp so late amendments are not missed.
- Resolve manager and security identity with effective-dated mappings; never join ticker text alone.
- Reconcile row counts and reported-value totals to the source version before publishing.
- Compute ownership percentages only with a compatible share class and dated shares-outstanding denominator.
- Expose period, filing date, amendment state, source, and limitations in the application response.
- 按照提交时间或更新时间采集，避免漏掉迟到的修订申报。
- 使用带有效期的机构和证券映射解析身份，不能只按股票代码文本关联。
- 发布前把记录行数和申报市值合计与来源版本核对。
- 只有在股份类别兼容且流通股分母有明确日期时，才能计算持股比例。
- 在应用响应中展示报告期、提交日、修订状态、来源和数据局限。
Use QVeris to find and call ownership data capabilities用 QVeris 查找并调用持股数据能力
QVeris can help a developer or AI agent discover relevant ownership-data capabilities, inspect their input and output schemas, and route a call through a consistent capability layer. Before binding one to a workflow, verify whether it returns 13F manager portfolios, holder-by-security views, beneficial ownership, or another dataset; then inspect period filters, identifiers, amendment metadata, pagination, freshness, quotas, and licensing. The underlying provider still determines what the record means.
QVeris 可帮助开发者或 AI Agent 发现相关持股数据能力、检查输入输出结构，并通过一致的能力层发起调用。绑定工作流前，应先确认它返回的是 13F 机构组合、按证券查询的持有人、受益所有权，还是其他数据；再检查报告期筛选、证券标识、修订元信息、分页、新鲜度、额度和许可。记录的最终含义仍由底层数据源决定。
- Start in the QVeris tool details with the task “find institutional holders for a stock ticker.”
- Inspect required identifiers and returned fields before binding the capability to an agent workflow.
- Use the QVeris documentation for integration details, and keep provider-specific terms visible in your product.
- 先在 QVeris 工具详情中描述任务：“按股票代码查机构持有人”。
- 绑定到 Agent 工作流之前，检查必填标识符与返回字段。
- 通过 QVeris 文档了解接入方式，并在产品中保留底层服务商的条款信息。
Free stock ownership API questions免费股票持仓 API 常见问题
Is there a free API for stock ownership data?
Some providers offer free plans or evaluation access for institutional ownership data. Check coverage, filing lag, history, quotas, and license terms; “free” does not always mean unrestricted production use.
What does a stock ownership API return?
Typical fields include security identifiers, holder name or CIK, reporting period, shares held, reported value, ownership percentage, and quarter-over-quarter change.
How current is institutional ownership data?
U.S. datasets commonly rely on Form 13F filings, so they describe periodic disclosed positions rather than real-time holdings.
Can I query institutional holders by ticker?
Many normalized APIs support ticker queries, but source filings rely on identifiers such as CIK and CUSIP. Verify mapping, share classes, and amendment handling.
Does a 13F API show a manager’s current portfolio?
No. It shows reportable positions for a past quarter-end as disclosed later, subject to scope rules and amendments. Label the period and filing date rather than presenting it as live ownership.
Why do institutional ownership percentages differ?
APIs may use different share classes, shares-outstanding dates, holder universes, amendment rules, and aggregation methods. Compare the numerator, denominator, and as-of date—not the percentage alone.
有没有免费的股票持仓数据接口？
部分服务商提供机构持仓数据的免费计划或评估访问。需要核对覆盖范围、申报时滞、历史深度、额度与许可；免费不一定允许无限制生产使用。
机构持仓 API 通常返回哪些字段？
常见字段包括证券标识、机构名称或 CIK、报告期、持股数量、申报市值、持股比例与季度变化。
13F 持仓数据是实时的吗？
不是。美国机构持仓数据通常来自 Form 13F 周期性申报，反映已披露的历史时点，而不是实时仓位。
可以按股票代码查询机构持有人吗？
许多标准化 API 支持 ticker 查询，但底层申报使用 CIK、CUSIP 等标识符；应核对映射、股份类别与修订处理。
13F API 能显示机构当前持仓吗？
不能。它展示的是机构后来披露的过去季末可申报仓位，并受到申报范围和修订影响。应标明报告期和提交日期，不能把它当成实时持仓。
为什么不同接口的机构持股比例不一样？
不同接口可能采用不同股份类别、流通股日期、机构样本、修订规则和汇总方法。比较时应同时查看分子、分母和对应日期，不能只看百分比。