免费机构持仓 API 应满足哪些需求
美国机构持仓 API 大多以 Form 13F 申报为基础进行标准化。按照 SEC 的现行说明，对达到适用的 1 亿美元门槛且对 Section 13(f) 证券拥有投资决策权的机构投资管理人，需要按季度申报。信息表反映季末特定证券持仓，并不是实时成交、买入成本、空头仓位或全部管理资产的完整记录。
生产级接口必须区分报告期、提交时间、供应商处理时间和修订时间，并尽量说明申报属于持仓报告、通知报告、组合报告还是修订。缺少这些语境时，组合可能看似为空、重复或突然变化，而真正原因只是申报结构不同，并非机构经济仓位发生了相同变化。
既可按完成映射的证券查询申报机构，也可按 CIK 和报告期获取某家机构披露的 13F 组合。
结果描述季度末可报告仓位，不是实时交易，也不代表机构所有资产类别的完整组合。
可靠接口会关联机构 CIK、发行人、CUSIP、股票代码、申报编号和报告期，并保留源记录。
确认免费是长期套餐还是试用、可访问哪些季度，以及商业使用、缓存和再分发是否允许。
13F 机构持仓数据接口的字段与时点
实用接口应保留表单类型、报告期、提交与修订时间、申报编号、机构 CIK 与文件号、发行人、证券类别、CUSIP、申报中存在时的 FIGI、股数或本金金额、申报公允价值及单位、投资决策权、投票权，以及适用时的看涨/看跌标记。接口还应保留原始信息表行与来源链接，而不是只返回股票代码和推导比例。
按股票代码或 CUSIP 查询机构股东
股票代码查询更方便，但申报记录的核心是发行人、证券类别和 CUSIP；FIGI 即使出现，也是补充而不是替代 CUSIP。应检查带有效期的代码映射、多种股份类别、期权、修订申报、共同申报机构、分页，以及季末申报市值与按今日行情重估市值之间的区别。
按 CIK 获取机构的 13F 投资组合
进行机构层面分析时，应保留申报主体和报告期，解析持仓报告或组合报告结构，并在季度比较前应用修订。只有处理证券标识变化和公司行动后，才能推导新建、增持、减持和退出标签。这些属于申报间差异，不是实际成交或成交时间。
理解未覆盖或延后公开的内容
只有列入适用 Section 13(f) 清单的证券才应出现在信息表中，许多其他资产不属于该表覆盖范围；保密处理申请还可能影响公开内容及时间。接口只有在区分数据范围、申报结构、映射失败以及未公开或保密内容后，才能判断缺失记录，不能直接把它解释为持仓为零。
如何评估免费 13F 持仓 API
| 检查项 | 需要核对 | 重要原因 |
|---|---|---|
| 覆盖 | 机构、发行人、季度、修订申报与历史深度。 | 避免无提示的数据缺口。 |
| 查询 | 股票代码、CUSIP、机构名称、CIK 与分页。 | 支持双向持仓视图。 |
| 来源 | 申报编号、原文链接、报告期与处理日期。 | 让数据可追溯审计。 |
| 标准化 | CIK 与 CUSIP 映射、重复、修订和单位。 | 避免产生虚假的持仓变化。 |
| 申报结构 | 持仓、通知、组合、修订及其他申报机构。 | 避免把通知报告中的空表误认为资产为零。 |
| 完整性 | 来源行数与市值合计、未映射行、期权和保密处理标记。 | 发现静默丢行和不完整的公开视图。 |
| 时点化访问 | 接口能否复现某个分析日期当时已经公开的信息？ | 避免历史研究中的前视偏差。 |
| 免费限制 | 额度、最近季度限制、许可与缓存。 | 试用未必适合生产。 |
接入返回 JSON 的免费机构持仓 API
步骤 1：测试个股机构股东与机构组合查询
分别按股票代码或 CUSIP、机构 CIK 调用文档化端点，并检查鉴权、HTTP 状态、分页、总数、最新可用报告期和限流响应头。
步骤 2：标准化 13F 持仓字段
将响应映射到稳定字段，例如 manager_cik、report_period、filing_date、cusip、ticker、shares、reported_value 和 accession_number，同时保留原始响应和来源链接。
步骤 3：避免前视偏差地比较季度持仓
按报告期和申报时间保存每份文件，应用修订记录，并只比较分析时点已经公开的信息。不要覆盖历史快照，也不要把延迟披露标记成实时交易。
步骤 4：核对标准化组合
把标准化后的行数与申报市值合计同来源摘要核对，保留无法映射的记录，并解释所有差异。13F-NT 与组合报告应单独处理，修订写入必须具备幂等性，避免重复采集造成持仓重复计算。
步骤 5：与结果一起展示日期和局限
展示报告期、提交与修订时间、采集时间、来源申报编号、映射版本，以及市值属于申报值还是重新估值。季度变化应标注为披露变化，并说明不在申报范围内的资产、空头以及保密或延后公开记录可能缺失。
用 QVeris 查找机构持仓数据能力
QVeris 帮助开发者和 Agent 发现、检查并调用可用的金融数据能力。可通过QVeris 工具详情 查看 13F 机构组合或按证券查询持有人的能力，再检查 CIK、CUSIP 与报告期参数、表单和修订元信息、分页、来源链接、历史访问、额度与供应商条款。QVeris 可以路由能力，但不会把延迟申报变成当前持仓。
- 明确搜索 13F 持仓或机构股东，不要混入 ETF 成分股或内幕交易。
- 调用前检查查询标识符、历史覆盖、分页、额度和许可。
- 将供应商特定逻辑封装在标准化应用接口之后。
FAQ
有免费的机构持仓 API 吗？
部分服务商提供免费套餐、评估端点或最近一期 13F 的免费访问。应核对调用、季度范围、来源链接、缓存、再分发、许可与商业使用条件。
13F 持仓 API 返回哪些字段？
可包含机构与申报身份、发行人、证券类别、CUSIP、股数或本金金额、申报公允价值、决策权、投票权、看涨/看跌标记、报告期和来源编号。
能否按股票代码查询机构持有人？
通常可以，但代码查询是供应商叠加在申报标识之上的映射。应保留 CUSIP、证券类别、机构 CIK、映射日期和来源行，以便审计代码变更。
13F API 会显示机构完整组合吗？
不会。它覆盖可申报的 Section 13(f) 证券，还可能涉及通知、组合、修订或保密处理语境；其他资产和空头仓位并未完整包含在该视图中。
13F 数据有多新？
它属于季度披露数据，通常按适用期限在季末后提交。API 处理更快只能缩短申报到接口的延迟，不能改变底层仓位对应的历史时点。
如何理解季度持仓变化？
应称为“申报间变化”。公司行动、标识映射、修订、申报结构和证券范围都可能改变记录，不能直接把差值解释为已观察到的交易。
如何避免前视偏差？
按报告期和公开提交时间保存版本，只应用分析日当时已经公开的修订，不能用今天的最新标准化状态覆盖过去的研究快照。
权威参考与下一步
先通过 SEC 来源理解 Form 13F 的披露范围，再核对第三方 API 当前的免费套餐约定。