Vibe-Trading 中的 Tushare 前十大流通股东接口（top10_floatholders）实战指南

Vibe-Trading 中的 Tushare 前十大流通股东接口top10_floatholders实战指南【免费下载链接】Vibe-TradingVibe-Trading: Your Personal Trading Agent项目地址: https://gitcode.com/GitHub_Trending/vi/Vibe-Trading本指南以开源项目 Vibe-Trading 中内置的 Tushare 数据技能文档为核心系统讲解top10_floatholders前十大流通股东接口的权限要求、输入输出参数、Python 调用方式与数据样例并结合仓库内 tushare 技能文档、示例脚本与基本面数据加载源码说明如何在量化研究、因子挖掘与回测工程中正确、合规地使用该接口避免未来函数look-ahead bias并最大化数据价值。接口概览什么是 top10_floatholderstop10_floatholders是 Tushare Pro 提供的前十大流通股东数据接口用于获取 A 股上市公司每个报告期内持股数量排名前十的流通股股东信息。与前十大股东不同流通股东反映的是当前可在二级市场自由交易的股份持有结构是分析筹码分布、资金动向与股东博弈的重要参考数据。在 Vibe-Trading 中该接口的完整说明收录于 前十大流通股东.md归属于股票数据 / 参考数据分类接口编号为 62参见 SKILL.md 数据接口列表。该接口具备以下关键属性属性说明接口名top10_floatholders数据内容上市公司前十大流通股东数据股东名称、持股数量、比例、变动等更新节奏随上市公司定期报告季报、半年报、年报披露而更新权限门槛需2000 积分以上方可调取5000 积分以上频次更高注意积分门槛直接决定单次调取的数据量与单位时间调用频率。在编写批量拉取脚本前建议先在 Tushare 账户中确认当前积分档位避免触发频次限制。输入参数详解调用top10_floatholders时可传入以下参数其中仅ts_code为必选名称类型必选描述ts_codestrYTS 股票代码如600000.SHperiodstrN报告期YYYYMMDD 格式一般为每个季度最后一天如20171231ann_datestrN公告日期start_datestrN报告期开始日期end_datestrN报告期结束日期参数使用要点ts_code必须使用 TS 格式上交所股票以.SH结尾深交所股票以.SZ结尾例如600000.SH浦发银行、000001.SZ平安银行。这是 Tushare 全平台统一的代码规范在 SKILL.md 的参数格式说明中亦有明确约定。period与start_date/end_date是两套时间维度period精确定位到某个报告期如20171231表示 2017 年年报期而start_date/end_date按报告期区间过滤适用于批量提取一段时间的全部报告期数据。接口文档给出的示例即采用区间方式pro.top10_floatholders(ts_code600000.SH, start_date20170101, end_date20171231)日期格式统一为 YYYYMMDD不带分隔符前导零不可省略这是 Tushare 各接口通用的日期规范。如需精确获取某一季度股东结构推荐优先使用period如需扫描多个报告期则使用start_date/end_date区间参数两者可组合使用。输出参数详解读懂一份股东结构数据接口返回 pandas DataFrame每一行代表某报告期内一位前十流通股东的信息字段定义如下名称类型描述ts_codestrTS 股票代码ann_datestr公告日期end_datestr报告期holder_namestr股东名称hold_amountfloat持有数量股hold_ratiofloat占总股本比例%hold_float_ratiofloat占流通股本比例%hold_changefloat持股变动holder_typestr股东类型各字段的业务含义与使用价值end_date报告期数据所属的报告期截止日是进行截面分析横截面比较各公司股东结构的主键之一。实际使用时通常与ts_code组合构成唯一标识。holder_name股东名称股东全称。可用于识别股东性质——保险资金如富德生命人寿保险股份有限公司-资本金、国家队如中国证券金融股份有限公司中央汇金资产管理有限责任公司、产业资本如中国移动通信集团广东有限公司等为后续的股东类型归因提供原始素材。hold_amount持有数量以股为单位的持股数。数据样例中以科学计数法显示如1.763232e09即约 17.6 亿股。hold_ratio与hold_float_ratio两种比例口径前者是相对总股本的比例后者是相对流通股本的比例。二者差异直接反映该股东所持股份中限售部分的比例——若某股东hold_ratio较高但hold_float_ratio明显更低说明其相当部分股份尚未流通。在计算真实二级市场筹码压力时应优先使用hold_float_ratio。hold_change持股变动相比上一报告期的持股数量变化是追踪大股东增减持动向、推断资金态度的核心字段可直接用于构造股东增持/减持类事件因子。holder_type股东类型股东的类别标签如法人、机构等可据此分组合并统计不同类型资金的持仓集中度。快速上手环境准备与两种调用方式1. 安装与环境变量配置Vibe-Trading 的 SKILL.md 给出了标准安装步骤推荐 Python 3.7 环境并通过清华 PyPI 镜像安装pip install tushare -i https://pypi.tuna.tsinghua.edu.cn/simple在 Tushare 官网注册并获取 token 后配置环境变量export TUSHARE_TOKENyour_token2. 初始化 pro 接口推荐读取环境变量中的 token 初始化接口实例。仓库中的示例脚本 stock_data_example.py 展示了标准写法import os import tushare as ts # 读取环境变量中的 token, 或者读取本地记录的 token token os.getenv(TUSHARE_TOKEN) or ts.get_token() # 初始化pro接口实例 pro ts.pro_api(token)在 Vibe-Trading 工程内部token 的读取已封装进统一配置体系TushareFundamentalProvider在初始化时通过get_env_config().data.tushare_token获取配置项回退到ts.get_token()见 tushare_fundamentals.py。因此在仓库环境中也可以直接复用该配置入口from src.config.accessor import get_env_config token get_env_config().data.tushare_token or ts.get_token() pro ts.pro_api(token)3. 两种调用方式方式一直接调用属性方法df pro.top10_floatholders(ts_code600000.SH, start_date20170101, end_date20171231)方式二通过pro.query按接口名调用df pro.query(top10_floatholders, ts_code600000.SH, start_date20170101, end_date20171231)两种方式等价返回结果均为 pandas DataFrame。pro.query方式适合在接口名以字符串形式动态传入如由配置驱动、批量遍历多个接口的场景属性方式则更直观、便于 IDE 补全。4. 参数瘦身按需指定字段Tushare 接口支持通过fields参数只取需要的列减少传输体积、降低频次压力。例如仅需要报告期与持股比例时df pro.top10_floatholders( ts_code600000.SH, period20171231, fieldsts_code,ann_date,end_date,holder_name,hold_amount,hold_ratio,hold_float_ratio )数据样例解读以浦发银行为例接口文档给出了600000.SH浦发银行2017 年年报期end_date20171231公告日期20180428的前十大流通股东数据节选如下ts_code ann_date end_date holder_name hold_amount 0 600000.SH 20180428 20171231 富德生命人寿保险股份有限公司-资本金 1.763232e09 1 600000.SH 20180428 20171231 上海国际集团有限公司 5.489319e09 2 600000.SH 20180428 20171231 富德生命人寿保险股份有限公司-传统 2.779437e09 3 600000.SH 20180428 20171231 中国证券金融股份有限公司 1.216979e09 4 600000.SH 20180428 20171231 梧桐树投资平台有限责任公司 8.861313e08 ... 9 600000.SH 20180428 20171231 中国移动通信集团广东有限公司 5.334893e09从样例中可以观察到几个重要特征同一股东可能拆分为多个账户/产品线出现在前十名单中如富德生命人寿保险股份有限公司同时以资本金传统万能H三个产品账户上榜。分析时若要计算单一主体的真实持股需按holder_name的机构前缀做聚合这一点在构造因子时容易忽略。数据保留科学计数法精度hold_amount以 float 存储1.763232e09≈ 17.63 亿股在排序、聚合、归一化计算前无需特殊处理但展示给用户时建议格式化为易读形式。ann_date公告日期晚于end_date报告期2017 年年报在 2018 年 4 月才公告这决定了在回测中使用该数据必须做时点Point-In-Time处理——详见下文工程集成一节。将上述样例与 前十大股东接口top10_holders文档 对比可以发现二者输出结构高度一致top10_holders同样输出ts_code/ann_date/end_date/holder_name/hold_amount/hold_ratio/hold_float_ratio/hold_change/holder_type且top10_holders的样例额外展示了hold_ratio列如上海国际集团占总股本 21.57%、中国移动广东 18.18%。因此前十大股东接口的解读与处理方式可完全复用到流通股东接口上唯一区别在于数据口径全体股东 vs 流通股东。在 Vibe-Trading 工程中的正确集成避免未来函数的工程实践前十大流通股东数据是典型的低频、滞后披露数据每个报告期仅更新一次且公告日期滞后报告期截止日数周至数月。若在回测中直接将最新股东数据用于历史任意时点就会引入严重的未来函数look-ahead bias。Vibe-Trading 的 tushare_fundamentals.py 提供了解决该问题的成熟工程范式其中TushareFundamentalProvider的query_fundamentals与_query_pit_cut方法值得重点借鉴PIT 截断point-in-time cut_query_pit_cut在拉取数据后以ann_date无该字段时回退作为信息可见时间仅保留ann_date as_of评估时点的行确保任何交易日只能看到当时已公告的股东数据。重述去重restatement dedup同一(ts_code, end_date)可能因财报重述出现多条记录query_fundamentals按有效公告日期排序后取最新一条避免同一报告期数据被重复计权。按报告期过滤支持periods参数精确筛选指定报告期与接口文档中的period参数语义一致。在自有策略中复刻该模式时建议按如下流程落地import pandas as pd import tushare as ts pro ts.pro_api(os.getenv(TUSHARE_TOKEN)) def load_top10_float_holders_pit(ts_code: str, as_of: str) - pd.DataFrame: 拉取前十大流通股东并做 PIT 截断避免未来函数。 raw pro.top10_floatholders(ts_codets_code) if raw is None or raw.empty: return raw raw raw.copy() raw[_pit] pd.to_datetime(raw[ann_date], format%Y%m%d) raw[_end] pd.to_datetime(raw[end_date], format%Y%m%d) # 只保留评估时点已公告的记录 visible raw[raw[_pit] pd.Timestamp(as_of)] # 同一报告期保留最新公告版本 visible visible.sort_values(_pit).drop_duplicates( subset[ts_code, _end], keeplast ) return visible.drop(columns[_pit, _end])这一范式同样适用于同目录下的其他参考数据接口前十大股东、股东人数、限售股解禁等可参考 参考数据目录 下的文档按需接入。实战场景与因子思路围绕top10_floatholders可以构建以下可落地的研究与策略思路结合数据字段逐一说明依据筹码集中度分析将各报告期前十流通股东的hold_float_ratio求和得到流通筹码集中度序列。集中度抬升常与主力吸筹、股价活跃相关是筹码分布研究的经典输入。可进一步结合 每日筹码及胜率、每日筹码分布 等高频数据做日度化补充。股东增减持事件因子利用hold_change跨期差分识别前十大流通股东的净增持/减持形成事件类 alpha。此处同样需要注意公告滞后——事件发生时间应以ann_date为准而非end_date。股东类型画像借助holder_type与holder_name前缀保险、社保、国家队、产业资本、个人等对前十名单分桶统计构建机构持仓占比国家队现身与否等截面特征。可与同目录下的 股东增减持、股权质押明细数据 等参考数据交叉验证资金动向。多源数据校验股东结构变化可与行情数据历史日线、资金流向数据个股资金流向联合分析验证股东增持 资金流入的共振信号。常见问题与注意事项积分不足报错接口要求 2000 积分以上5000 积分以上频次更高。若返回权限类错误应先检查账户积分档位而非代码问题。批量任务建议控制单次请求量、合理分页用period/start_date/end_date切片并在两次请求间留出间隔。ts_code格式错误务必使用 TS 代码如600000.SH仅传 6 位数字或使用交易所简称代码将无法命中数据。低频数据的滞后性股东数据仅在定期报告披露后更新季度内多次调用结果不变。若需要更高频的筹码信息请配合每日更新的筹码分布类接口使用。与 top10_holders 的选择需要全口径股东含限售结构时用 前十大股东接口top10_holders仅关注二级市场可交易筹码时用本接口top10_floatholders。二者参数与字段结构一致可共用同一套封装代码。返回空结果新上市、退市整理期或尚未披露报告的股票可能返回空 DataFrame代码中应做好空值兜底示例中的if raw is None or raw.empty判断避免后续聚合报错。总结top10_floatholders是 A 股筹码结构与资金动向研究的基础数据接口。通过本文可以完成从环境配置、接口调用、字段解读到工程化集成的全流程落地掌握两种等价调用方式与参数语义理解hold_amount/hold_ratio/hold_float_ratio/hold_change等字段的业务含义并借鉴 Vibe-Trading 仓库中 tushare_fundamentals.py 的 PIT 截断与去重范式在回测中杜绝未来函数。该接口与同目录下的前十大股东、股东增减持、股东人数等参考数据共同构成股东行为研究的完整数据底座是构建基本面因子与事件驱动策略的高性价比起点。【免费下载链接】Vibe-TradingVibe-Trading: Your Personal Trading Agent项目地址: https://gitcode.com/GitHub_Trending/vi/Vibe-Trading创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考