tickplus 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
tickplus/SKILL.md ADDED
@@ -0,0 +1,484 @@
1
+ ---
2
+ name: tickplus-stock-api
3
+ description: 使用 TickPlus 股票数据 API 获取沪深京A股、ETF基金、沪深可转债、指数的实时行情、K线、财务指标等数据,支持 REST API 和 WebSocket 实时推送
4
+ ---
5
+
6
+ # TickPlus 股票数据 API 技能
7
+
8
+ 本技能提供访问 TickPlus 平台的 Python SDK,可以获取中国股市(沪深京A股)、ETF基金、沪深可转债、指数的实时行情、历史K线、财务数据等多种金融数据。
9
+
10
+ 接口清单、参数取值、返回字段与权限等级全部以官方 `apidoc.json` 为准,逐接口明细见 [references/apidoc.md](references/apidoc.md)。
11
+
12
+ ## 核心功能
13
+
14
+ 共 16 个 REST 接口,分为 Basic / Pro / Expert 三组。
15
+
16
+ ### 0. WebSocket 实时推送 - 按数据类型权限开通
17
+
18
+ - **StockWebSocketClient**: WebSocket 实时数据推送客户端
19
+ - 建立 WebSocket 长连接
20
+ - 订阅/取消订阅股票代码或数据类型
21
+ - 接收实时数据(文本和二进制格式)
22
+ - 支持集合竞价、个股 tick、分钟 K 线等多种数据类型
23
+
24
+ ### 1. Basic Api - 基础数据接口(权限 1、2、3)
25
+
26
+ - **getStockList**: 获取股票列表(stock-沪深京A股,etf-ETF基金,bond-沪深可转债,index-指数)
27
+ - **getFullQuotes**: 实时行情(code 为空则全市场全推,逗号分隔批量最多 100 个)
28
+ - **getDayKline**: 日K线数据(1d/1w/1mon/1y,仅支持单个股票)
29
+ - **getFullMetric**: 行情指标(量比、换手率、市盈率、市净率、总市值等,**无 symbol 参数**)
30
+ - **getFinanceCore**: 核心财务指标(ROE、每股收益、每股净资产等,仅支持单个股票)
31
+ - **getCapital**: 股本数据(总股本、已上市流通A股、限售流通股份,仅支持单个股票)
32
+ - **getUpdateDayKline**: 盘后增量日线数据(全市场,仅支持最近一周)
33
+
34
+ ### 2. Pro Api - 专业数据接口(权限 2、3)
35
+
36
+ - **getTimeKline**: 日内分时数据(仅支持单个股票)
37
+ - **getGncgf**: 题材概念成分股(hy-行业板块,gn-概念板块,ts-特色板块)
38
+ - **getMinuteKline**: 分钟K线数据(1m/5m/15m/30m/1h,仅支持单个股票)
39
+ - **getFullMinute**: 盘中分钟K线全推(支持 WebSocket 推送)
40
+ - **getFullMinuteSnapshot**: 盘中分钟快照全推(秒级更新)
41
+
42
+ ### 3. Expert Api - 专家级数据接口(权限 3)
43
+
44
+ - **getTransaction**: 逐笔交易数据(单个股票 + 交易日期)
45
+ - **getFiveLevel**: 买卖五档实时全推(symbol 必填,支持 WebSocket 推送)
46
+ - **getFullBid**: 集合竞价全推(09:15-09:25,**无 symbol 参数**,支持 WebSocket 推送)
47
+ - **getFluctuation**: 异动数据(涨停板股池:首板、一进二、二进三、三进四)
48
+
49
+ ## 使用方法
50
+
51
+ ### 前置准备
52
+
53
+ 1. 在 [TickPlus官网](http://www.tickplus.org) 注册账号并获取 token
54
+ 2. 在项目配置文件中设置 token(`tickplus/scripts/Config.py`)
55
+
56
+ ### WebSocket 实时推送使用示例
57
+
58
+ **快速开始**:
59
+
60
+ ```python
61
+ from tickplus.scripts.StockWebSocketClient import StockWebSocketClient
62
+ from tickplus.scripts.Config import Config
63
+ import time
64
+
65
+ # 配置token
66
+ token = Config.TOKEN
67
+
68
+ # 创建WebSocket URL
69
+ ws_url = f"ws://ws.tickplus.org/ws/{token}"
70
+
71
+ # 创建客户端实例
72
+ client = StockWebSocketClient(ws_url)
73
+
74
+ # 建立连接
75
+ if client.connect():
76
+ # 订阅数据(集合竞价 + 个股 tick + 分钟K线)
77
+ auth_codes = ["auction", "000001.SZ", "600000.SH", "minute.hsj"]
78
+ client.subscribe(token, auth_codes)
79
+
80
+ # 等待接收数据
81
+ print("Waiting for data...")
82
+ time.sleep(10)
83
+
84
+ # 取消订阅
85
+ client.unsubscribe(token, auth_codes)
86
+
87
+ # 断开连接
88
+ client.disconnect()
89
+ ```
90
+
91
+ **详细说明**:
92
+
93
+ 关于 WebSocket 的完整使用指南,包括:
94
+ - 自定义消息处理
95
+ - 错误处理和重连机制
96
+ - 数据格式详解
97
+ - 高级用法(批处理、数据过滤等)
98
+ - 常见问题解答
99
+
100
+ 请参考:[references/websocket.md](references/websocket.md)
101
+
102
+ **WebSocket 消息格式**:
103
+
104
+ 订阅消息:
105
+ ```json
106
+ {
107
+ "token": "your_token",
108
+ "operation": "subscribe",
109
+ "authCodes": ["auction", "000001.SZ", "600000.SH"]
110
+ }
111
+ ```
112
+
113
+ 取消订阅消息:
114
+ ```json
115
+ {
116
+ "token": "your_token",
117
+ "operation": "unsubscribe",
118
+ "authCodes": ["auction", "000001.SZ", "600000.SH"]
119
+ }
120
+ ```
121
+
122
+ **支持的订阅类型(authCodes)**:
123
+
124
+ | authCode | 说明 | 对应 REST 接口 |
125
+ | --- | --- | --- |
126
+ | `000001.SZ` / `600000.SH` | 个股 tick 数据,按个数订阅 | `/plus/basic/fullquotes`、`/plus/expert/fivelevel` |
127
+ | `auction` | 沪深京A股集合竞价期间竞价数据 | `/plus/expert/fullbid` |
128
+ | `minute.hsj` | 沪深京A股 1 分钟 K 线 | `/plus/pro/fullminute` |
129
+ | `minute.index` | 指数 1 分钟 K 线 | `/plus/pro/fullminute` |
130
+ | `minute.etf` | ETF 1 分钟 K 线 | `/plus/pro/fullminute` |
131
+
132
+ 支持同时订阅多个代码。
133
+
134
+ **获取官方示例代码**:
135
+
136
+ ```bash
137
+ git clone https://github.com/tickplusx/TickPlusSkill.git
138
+ cd TickPlusSkill
139
+ python tickplus/scripts/StockWebSocketClient.py
140
+ ```
141
+
142
+ 更多详细信息请参考:[references/websocket.md](references/websocket.md)
143
+
144
+ **运行完整测试**:
145
+
146
+ ```bash
147
+ python tickplus/scripts/StockWebSocketClient.py
148
+ # 等价写法(在项目根目录执行)
149
+ python -m tickplus.scripts.StockWebSocketClient
150
+ ```
151
+
152
+ ### 基本调用示例
153
+
154
+ ```python
155
+ from tickplus.scripts.api import BasicApi, ProApi, ExpertApi
156
+ from tickplus.scripts.Config import Config
157
+
158
+ # 获取配置的token
159
+ token = Config.TOKEN
160
+ ```
161
+
162
+ ### 示例1:获取股票列表
163
+
164
+ ```python
165
+ # 获取沪深京A股列表
166
+ stocks = BasicApi.getStockList(symbol="stock", token=token)
167
+ print(f"共 {len(stocks)} 只股票")
168
+
169
+ # 获取ETF基金列表
170
+ etfs = BasicApi.getStockList(symbol="etf", token=token)
171
+
172
+ # 获取沪深可转债列表
173
+ bonds = BasicApi.getStockList(symbol="bond", token=token)
174
+
175
+ # 获取指数列表
176
+ indexes = BasicApi.getStockList(symbol="index", token=token)
177
+ ```
178
+
179
+ ### 示例2:获取实时行情
180
+
181
+ ```python
182
+ # 获取单只股票实时行情
183
+ quote = BasicApi.getFullQuotes(symbol="stock", code="000001", token=token)
184
+
185
+ # 批量获取多只股票行情(最多100只)
186
+ quotes = BasicApi.getFullQuotes(
187
+ symbol="stock",
188
+ code="000001,000002,600000",
189
+ token=token
190
+ )
191
+
192
+ # 获取全市场实时行情(code 不传,数据量大,谨慎使用)
193
+ all_quotes = BasicApi.getFullQuotes(symbol="stock", token=token)
194
+
195
+ # 返回字段:t-交易时间, code-股票代码, o-开盘价, c-收盘价,
196
+ # h-最高价, l-最低价, v-成交量(手), a-成交额(元), pc-昨收价
197
+ ```
198
+
199
+ ### 示例3:获取K线数据
200
+
201
+ ```python
202
+ from datetime import datetime, timedelta
203
+
204
+ # 获取日K线数据(仅支持单个股票)
205
+ end_date = datetime.now().strftime("%Y-%m-%d")
206
+ start_date = (datetime.now() - timedelta(days=30)).strftime("%Y-%m-%d")
207
+
208
+ kline = BasicApi.getDayKline(
209
+ symbol="stock",
210
+ code="000001",
211
+ period="1d", # 1d-日线, 1w-周线, 1mon-月线, 1y-年线
212
+ dividend="1", # 1-不复权, 2-前复权, 3-后复权
213
+ startDate=start_date,
214
+ endDate=end_date,
215
+ token=token
216
+ )
217
+
218
+ # 获取分钟K线数据(仅支持单个股票)
219
+ minute_kline = ProApi.getMinuteKline(
220
+ symbol="stock",
221
+ code="000001",
222
+ period="5m", # 1m, 5m, 15m, 30m, 1h
223
+ dividend="1",
224
+ startDate=start_date,
225
+ endDate=end_date,
226
+ token=token
227
+ )
228
+ ```
229
+
230
+ ### 示例4:获取行情指标
231
+
232
+ ```python
233
+ # 行情指标接口没有 symbol 参数,只按 code 获取
234
+ indicators = BasicApi.getFullMetric(
235
+ code="000001,000002",
236
+ token=token
237
+ )
238
+
239
+ # 返回字段包括:
240
+ # zxj-最新价, zdf-涨跌幅, hsl-换手率, lb-量比
241
+ # zsz-总市值, ltsz-流通市值, sjl-市净率
242
+ # jtsyl-市盈率(静), dtsyl-市盈率(动), ttmsyl-市盈率(TTM)
243
+ # zdf05/zdf10/zdf20 - 5日/10日/20日涨跌幅
244
+ ```
245
+
246
+ ### 示例5:获取财务与股本数据
247
+
248
+ ```python
249
+ # 获取核心财务指标(仅支持单个股票)
250
+ finance = BasicApi.getFinanceCore(
251
+ code="000001",
252
+ startDate="2025-01-01",
253
+ endDate="2025-12-31",
254
+ token=token
255
+ )
256
+
257
+ # 返回的财务指标包括:
258
+ # roe-净资产收益率, bps-每股净资产
259
+ # basicEps-基本每股收益, salesProfit-销售毛利率
260
+ # gearRatio-资产负债比率等
261
+
262
+ # 获取股本数据(仅支持单个股票)
263
+ capital = BasicApi.getCapital(
264
+ code="000001",
265
+ startDate="2025-01-01",
266
+ endDate="2025-12-31",
267
+ token=token
268
+ )
269
+ # 返回字段:totalCapital-总股本, flowCapital-已上市流通A股, restrictCapital-限售流通股份
270
+ ```
271
+
272
+ ### 示例6:获取高级数据
273
+
274
+ ```python
275
+ # 获取买卖五档数据(symbol 必填)
276
+ five_level = ExpertApi.getFiveLevel(
277
+ symbol="stock",
278
+ code="000001,000002",
279
+ token=token
280
+ )
281
+ # 返回 bp1-bp5(买一到买五价格), bv1-bv5(买一到买五量)
282
+ # sp1-sp5(卖一到卖五价格), sv1-sv5(卖一到卖五量)
283
+
284
+ # 获取集合竞价数据(09:15-09:25,无 symbol 参数)
285
+ bid_data = ExpertApi.getFullBid(
286
+ code="000001",
287
+ token=token
288
+ )
289
+
290
+ # 获取异动数据(涨停板股池)
291
+ fluctuation = ExpertApi.getFluctuation(
292
+ tradeDate="2026-11-14",
293
+ token=token
294
+ )
295
+ # 返回字段:days-连续涨停天数, first-首次触及涨停板时间,
296
+ # fbv-封板量, fba-封板资金, update-更新时间
297
+
298
+ # 获取逐笔交易数据(仅支持单个股票)
299
+ transactions = ExpertApi.getTransaction(
300
+ code="000001",
301
+ tradeDate="2026-11-14",
302
+ token=token
303
+ )
304
+ ```
305
+
306
+ ### 示例7:获取分钟全推与板块成分股
307
+
308
+ ```python
309
+ # 盘中分钟K线全推
310
+ full_minute = ProApi.getFullMinute(symbol="stock", code="000001,000002", token=token)
311
+
312
+ # 盘中分钟快照全推(秒级更新)
313
+ snapshot = ProApi.getFullMinuteSnapshot(symbol="stock", code="000001,000002", token=token)
314
+
315
+ # 获取行业板块成分股(高级版及以上)
316
+ industry_stocks = ProApi.getGncgf(symbol="hy", token=token)
317
+
318
+ # 获取概念板块成分股
319
+ concept_stocks = ProApi.getGncgf(symbol="gn", token=token)
320
+
321
+ # 获取特色板块成分股
322
+ special_stocks = ProApi.getGncgf(symbol="ts", token=token)
323
+ # 注意:该接口返回结构为 [{"bkname": "板块名", "stocks": ["000429", ...]}, ...]
324
+ ```
325
+
326
+ ## 完整测试示例
327
+
328
+ 运行完整的API测试:
329
+
330
+ ```python
331
+ from tickplus.scripts.StockApiClient import StockApiClient
332
+
333
+ client = StockApiClient()
334
+ client.demoForAllApis() # 测试所有16个REST API接口
335
+ ```
336
+
337
+ 或直接执行:
338
+
339
+ ```bash
340
+ python tickplus/scripts/StockApiClient.py
341
+ # 等价写法(在项目根目录执行)
342
+ python -m tickplus.scripts.StockApiClient
343
+ ```
344
+
345
+ 运行 WebSocket 实时推送测试:
346
+
347
+ ```bash
348
+ python tickplus/scripts/StockWebSocketClient.py
349
+ ```
350
+
351
+ ## 参数说明
352
+
353
+ ### 通用参数
354
+
355
+ - **token**: 必填,从TickPlus官网获取的认证令牌
356
+ - **symbol**: 股票类型,取值仅以下 4 种
357
+ - `stock`: 沪深京A股
358
+ - `etf`: ETF基金
359
+ - `bond`: 沪深可转债
360
+ - `index`: 指数
361
+ - **code**: 股票代码
362
+ - 空(不传): 全市场全推(仅 `fullquotes`、`fullmetric`、`fullminute`、`fullminutesnapshot`、`fivelevel`、`fullbid` 支持)
363
+ - `"000001,000002"`: 批量查询,最多 100 个
364
+ - `"000001"`: 单个股票
365
+ - `daykline`、`financecore`、`capital`、`timekline`、`minutekline`、`transaction` 仅支持单个股票
366
+
367
+ > 注意:`getFullMetric`(行情指标)与 `getFullBid`(集合竞价)**没有 `symbol` 参数**;`getFiveLevel`(买卖五档)的 `symbol` 为必填。
368
+
369
+ ### K线周期参数
370
+
371
+ **日线周期** (`period` for daykline):
372
+ - `1d`: 日线
373
+ - `1w`: 周线
374
+ - `1mon`: 月线
375
+ - `1y`: 年线
376
+
377
+ **分钟周期** (`period` for minutekline):
378
+ - `1m`: 1分钟线
379
+ - `5m`: 5分钟线
380
+ - `15m`: 15分钟线
381
+ - `30m`: 30分钟线
382
+ - `1h`: 1小时线
383
+
384
+ ### 复权类型参数
385
+
386
+ - `1`: 不复权
387
+ - `2`: 前复权
388
+ - `3`: 后复权
389
+
390
+ ### 板块划分参数
391
+
392
+ `symbol` for gncgf:
393
+ - `hy`: 行业板块
394
+ - `gn`: 概念板块
395
+ - `ts`: 特色板块
396
+
397
+ ## 注意事项
398
+
399
+ 1. **Token认证**: 所有接口都需要有效的token,请在官网注册获取
400
+ 2. **权限等级**:
401
+ - Basic Api: 基础版 (1)、高级版 (2)、专业版 (3)
402
+ - Pro Api: 高级版 (2)、专业版 (3)
403
+ - Expert Api: 仅专业版 (3)
404
+ - 权限向下兼容:专业版 > 高级版 > 基础版
405
+ 3. **批量限制**: 批量查询最多支持100个股票代码
406
+ 4. **WebSocket 连接**:
407
+ - WebSocket地址:`ws://ws.tickplus.org/ws/{token}`
408
+ - 推送权限按数据类型开通:分钟K线推送(`minute.*`)对应高级版及以上;五档、竞价推送对应专业版
409
+ - 订阅后服务器会主动推送数据,无需轮询
410
+ - 支持文本和二进制(gzip/zip 压缩)两种数据格式
411
+ - 需要先建立连接,再发送订阅消息
412
+ 5. **日期格式**: 统一使用 `YYYY-MM-DD` 格式
413
+ 6. **交易时间**:
414
+ - A股: 09:30-11:30, 13:00-15:00
415
+ - 集合竞价: 09:15-09:25
416
+ 7. **数据更新频率**:
417
+ - 实时行情: 秒级更新
418
+ - 行情指标: 1-2分钟更新
419
+ - 盘中分钟K线: 1分钟更新
420
+ - 财务数据: 季度更新
421
+ 8. **性能建议**:
422
+ - 避免频繁全市场数据请求
423
+ - 批量查询优于多次单次查询
424
+ - 缓存常用数据减少API调用
425
+ - 对于实时性要求高的场景,优先使用 WebSocket
426
+
427
+ ## 错误处理
428
+
429
+ ```python
430
+ try:
431
+ data = BasicApi.getFullQuotes(symbol="stock", code="000001", token=token)
432
+ if isinstance(data, list) and len(data) > 0:
433
+ print(f"成功获取 {len(data)} 条数据")
434
+ else:
435
+ print("未获取到数据")
436
+ except Exception as e:
437
+ print(f"API调用失败: {e}")
438
+ ```
439
+
440
+ ## 数据结构
441
+
442
+ 所有REST接口返回的都是JSON格式的列表数据,每个元素是一个字典:
443
+
444
+ ```python
445
+ [
446
+ {
447
+ "code": "000001",
448
+ "tradeDate": "2026-11-06 11:10:45",
449
+ "zxj": 11.73,
450
+ "zdf": 0.77,
451
+ ...
452
+ },
453
+ ...
454
+ ]
455
+ ```
456
+
457
+ ## 相关资源
458
+
459
+ - 官方网站: http://www.tickplus.org
460
+ - GitHub 项目: https://github.com/tickplusx/TickPlusSkill
461
+ - API文档: references/apidoc.md
462
+ - WebSocket详细文档: references/websocket.md
463
+ - 完整示例: scripts/StockApiClient.py, scripts/StockWebSocketClient.py, scripts/CompleteExampleClient.py
464
+ - 文档生成: scripts/generate_apidoc.py
465
+ - 配置说明: scripts/Config.py
466
+
467
+ ## 更新日志
468
+
469
+ - 2026-11-14: 按最新 apidoc.json 全量同步
470
+ - 方法名更正:行情指标改为 `getFullMetric`、买卖五档改为 `getFiveLevel`、涨停板异动改为 `getFluctuation`(旧方法名已废弃)
471
+ - 新增文档:`getCapital`(股本数据)、`getFullMinuteSnapshot`(盘中分钟快照)
472
+ - 标的类型收敛为 stock/etf/bond/index,移除不支持的境外市场说明
473
+ - 修正行情指标、集合竞价、买卖五档的 symbol 参数说明与调用示例
474
+ - 2026-05-15: 新增 WebSocket 实时推送功能
475
+ - 添加 StockWebSocketClient 类,支持长连接实时数据推送
476
+ - 支持订阅/取消订阅股票代码
477
+ - 支持集合竞价、沪深A股等多种数据类型
478
+ - 支持文本和二进制两种数据格式
479
+ - 添加完整的测试代码和使用示例
480
+ - 2026-04-24: 核对并更新API接口文档
481
+ - Basic Api: 6个接口(修正行情指标接口URL)
482
+ - Pro Api: 6个接口
483
+ - Expert Api: 4个接口
484
+ - 2026-04-23: 初始版本,支持16个API接口
tickplus/__init__.py ADDED
File without changes