Vibe-Trading 中的 Tushare 前十大股东数据实战top10_holders 接口从取数到股权结构分析【免费下载链接】Vibe-TradingVibe-Trading: Your Personal Trading Agent项目地址: https://gitcode.com/GitHub_Trending/vi/Vibe-Trading前十大股东top10_holders是 Tushare 提供的上市公司股权结构核心接口在 Vibe-Trading 项目中作为 tushare 数据源技能 下股票数据/参考数据类目的一等公民被收录。本文将以该接口文档为骨架完整讲解其输入输出参数、两种调用方式与数据样例并结合 Vibe-Trading 仓库中的 token 配置、环境变量注入与健康检查实现给出可直接落地的 A 股股权集中度分析与实盘研究示例。接口定位与权限门槛接口名top10_holders官方描述获取上市公司前十大股东数据包括持有数量和比例等信息。该接口在 Vibe-Trading 的 tushare 技能接口列表中被登记为 ID 61归类为股票数据,参考数据见 SKILL.md 中top10_holders一行。积分要求需 2000 积分以上才可调取本接口5000 积分以上频次会更高。这意味着该接口属于 Tushare 的高阶权限数据普通基础积分用户无法直接访问需要先通过 Tushare 积分体系升级账户。从数据结构上看top10_holders披露的是上市公司定期报告季报/年报中按持股数量排序的前十大股东名单包含每家股东的名称、持股数量、占总股本比例、占流通股本比例、持股变动等信息是股权结构、筹码集中度和国家队持股追踪等研究的基础数据。它与同目录下的 前十大流通股东top10_floatholders接口 ID 62互为补充前者面向总股本口径后者面向流通股本口径两者结合可以拆分限售/非流通与流通两个维度的大股东持仓。输入参数详解名称类型必选描述ts_codestrYTS代码periodstrN报告期YYYYMMDD格式一般为每个季度最后一天ann_datestrN公告日期start_datestrN报告期开始日期end_datestrN报告期结束日期其中ts_code为必填参数格式遵循 Tushare 全库统一约定交易所后缀区分市场例如600000.SH上交所、000001.SZ深交所。period是报告期即财务报表的截止日由于 A 股季报披露存在滞后period与ann_date公告日期并不相同例如 2017 年年报的报告期是20171231公告日期则可能到 2018 年 4 月底。start_date/end_date用于按报告期区间批量拉取适合做多期历史对比。输出参数详解名称类型描述ts_codestrTS股票代码ann_datestr公告日期end_datestr报告期holder_namestr股东名称hold_amountfloat持有数量股hold_ratiofloat占总股本比例(%)hold_float_ratiofloat占流通股本比例(%)hold_changefloat持股变动holder_typestr股东类型输出字段的实战含义hold_amount为绝对持股量单位股在样例数据中因数值巨大以科学计数法呈现如2.779437e09即约 27.79 亿股hold_ratio与hold_float_ratio分别是占总股本、占流通股本的比例百分比二者差额可用于判断股东所持股份中限售流通的规模hold_change表示相对上一报告期的持股变动结合holder_type股东类型如保险、投资公司等可以追踪机构资金动向holder_name可用于识别国家队席位如中国证券金融、中央汇金或产业资本席位。接口用法方式一直接调用接口方法pro ts.pro_api() df pro.top10_holders(ts_code600000.SH, start_date20170101, end_date20171231)方式二通过 query 通用入口df pro.query(top10_holders, ts_code600000.SH, start_date20170101, end_date20171231)两种方式等价pro.query以字符串形式传入接口名适合在需要动态拼接接口名的场景下使用直接方法调用则享受 IDE 补全与参数校验。返回结果均为 pandas DataFrame。数据样例解读以浦发银行600000.SH2017 年年报end_date20171231公告日ann_date20180428为例ts_code ann_date end_date holder_name hold_amount hold_ratio 0 600000.SH 20180428 20171231 富德生命人寿保险股份有限公司-传统 2.779437e09 9.47 1 600000.SH 20180428 20171231 上海国鑫投资发展有限公司 9.455690e08 3.22 2 600000.SH 20180428 20171231 富德生命人寿保险股份有限公司-万能H 1.270429e09 4.33 3 600000.SH 20180428 20171231 富德生命人寿保险股份有限公司-资本金 1.763232e09 6.01 4 600000.SH 20180428 20171231 上海国际集团有限公司 6.331323e09 21.57 5 600000.SH 20180428 20171231 中国移动通信集团广东有限公司 5.334893e09 18.18 6 600000.SH 20180428 20171231 中国证券金融股份有限公司 1.216979e09 4.15 7 600000.SH 20180428 20171231 梧桐树投资平台有限责任公司 8.861313e08 3.02 8 600000.SH 20180428 20171231 中央汇金资产管理有限责任公司 3.985214e08 1.36 9 600000.SH 20180428 20171231 上海上国投资产管理有限公司 1.395571e09 4.75从样例可以提炼出的信息价值股权集中度前十大股东合计持股比例可通过对hold_ratio求和得到本例约为 76%远高于一般上市公司说明浦发银行股权高度集中股东类型结构既有国资平台上海国际集团、上海上国投资产管理也有产业资本中国移动广东、保险资金富德生命人寿多个账户与国家队证金、汇金、梧桐树可据此构建股东性质画像同一主体的多账户披露富德生命人寿以传统/万能H/资本金三个账户分别列示分析单一险资合计持仓时应按holder_name前缀聚合。结合 Vibe-Trading 仓库的工程化实践1. Token 配置与环境变量注入在 Vibe-Trading 中调用该接口前需要正确注入 Tushare Token。仓库在 env_schema.py 中将TUSHARE_TOKEN声明为数据源配置项tushare_token: str Field(aliasTUSHARE_TOKEN, default)即通过环境变量TUSHARE_TOKEN或agent/.env文件配置。启动前的健康检查 preflight.py 会校验该 token未设置或仍为占位值your-tushare-token时报告TUSHARE_TOKEN not set (optional)影响项为 A-share data unavailable若tushare包未安装则标记为skipped配置正确则状态为ready。此外settings_routes.py 会把空串与your-tushare-token识别为占位符确保 token 不会被当作真实凭据误报cli_handlers.py 在因子命令行工具遇到TUSHARE_TOKEN错误时会给出注册 token 并写入 agent/.env的引导提示。示例脚本 stock_data_example.py 展示了标准初始化流程import os import tushare as ts from src.config.accessor import get_env_config token get_env_config().data.tushare_token or ts.get_token() pro ts.pro_api(token)2. 落地示例股权集中度与股东类型分析结合接口文档与上述 token 配置一个可直接运行的完整示例建议在 Vibe-Trading 的agent目录下执行如下import os import tushare as ts from src.config.accessor import get_env_config token get_env_config().data.tushare_token or ts.get_token() pro ts.pro_api(token) # 拉取浦发银行 2017 年前十大股东 df pro.top10_holders(ts_code600000.SH, start_date20170101, end_date20171231) # 前十大股东合计持股比例股权集中度 print(前十大股东合计持股比例: %.2f%% % df[hold_ratio].sum()) # 按股东名称前缀聚合合并同一主体多账户 df[holder_group] df[holder_name].str.split(-).str[0] grouped df.groupby(holder_group)[hold_ratio].sum().sort_values(ascendingFalse) print(grouped) # 识别国家队席位 nation_team df[df[holder_name].str.contains(中国证券金融|中央汇金|梧桐树, naFalse)] print(nation_team[[holder_name, hold_ratio]])3. 与周边参考数据接口的组合使用top10_holders不应孤立使用。在 Vibe-Trading 的 tushare 技能股票数据/参考数据目录下它与以下接口组合可构成完整的股东研究链路前十大流通股东同一股票同一报告期下比较总股本口径与流通股本口径的十大股东名单差异识别限售股份分布股东增减持stk_holdertrade用hold_change定位到发生变动的股东后进一步通过增减持接口获取变动数量、平均价格与变动后持股比例验证减持是否发生在股价高位股东人数stk_holdernumber十大股东集中度上升且股东户数下降是筹码集中的经典信号组合。这套十大股东 流通股东 增减持 股东户数的数据组合可作为基本面研究、因子库构建或投研 Agent 的参考数据输入。在 Vibe-Trading 中tushare 技能通过标准化 API 方式统一了数据资产的对外服务方式Agent 可根据任务需要从 SKILL.md 的接口列表中按分类检索并调用对应接口top10_holders即属于其中 A 股股权结构研究的高价值数据源之一。注意事项数据时点口径end_date为报告期一般取季度最后一天ann_date为公告日期两者存在数月时间差。进行事件研究时应以ann_date作为信息可得性时点避免用未来信息回填积分与频次2000 积分是硬门槛5000 积分以上调用频次更高。批量拉取全市场数据时建议按ts_code分片、按period循环配合start_date/end_date控制请求量并做好重试与休眠策略以免触发限流返回列完整性数据样例仅展示了ts_code / ann_date / end_date / holder_name / hold_amount / hold_ratio六个字段实际输出还包含hold_float_ratio、hold_change、holder_type等字段可按需通过fields参数裁剪数量单位hold_amount单位为股hold_ratio、hold_float_ratio单位为百分比样例中的科学计数法需在分析时统一换算。小结本文以 Vibe-Trading 仓库中 前十大股东.md 文档为骨架完整覆盖了top10_holders接口的权限要求、输入输出参数、两种调用方式与真实数据样例并结合仓库的 token 配置、环境变量注入、健康检查与示例脚本给出了可运行的股权集中度分析代码和与流通股东、增减持、股东户数等接口的组合用法。掌握了这些内容即可在 Vibe-Trading 中稳定获取 A 股前十大股东数据并进一步构建机构持仓追踪、筹码集中度因子等量化研究能力。【免费下载链接】Vibe-TradingVibe-Trading: Your Personal Trading Agent项目地址: https://gitcode.com/GitHub_Trending/vi/Vibe-Trading创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考