Metadata-Version: 2.4
Name: finsight-data
Version: 1.0.3
Summary: Client SDK for FinSight read-only latest-trade-day data API
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.31.0

# FinSight Data SDK

FinSight Data SDK 用于访问只读行情数据。当前提供最新交易日历史排行、盘中实时快照、实时板块资金流和盘后连板数据。

## 安装

```bash
pip install finsight-data
```

## 初始化

```python
from finsight_data import FinSightDataClient

client = FinSightDataClient(token="YOUR_DATA_API_TOKEN")
```

| 参数 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `token` | 是 | `str` | 数据接口 token |
| `timeout` | 否 | `int` | 请求超时秒数，默认 `20` |

初始化时 SDK 会校验 token 并完成设备绑定。后续数据接口不需要再传设备绑定参数。

## 最新交易日板块资金流向

```python
data = client.get_stock_sector_fund_flow_daily_latest(
    board_type="行业",
    keyword="半导体",
    limit=100,
    offset=0,
)
```

该接口返回历史数据表中最新交易日的板块资金流向排行，默认按主力净流入额从高到低排序。这里不是实时模块 Top50，未传 `limit` 时返回筛选后的全部结果。

| 参数 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `board_type` | 否 | `str` | 板块类型：`行业`、`概念`、`板块`、`地域`；`地域` 会映射到历史表中的 `板块` 类型 |
| `keyword` | 否 | `str` | 按板块代码或名称搜索 |
| `limit` | 否 | `int` | 返回条数；不填返回筛选后的全部结果 |
| `offset` | 否 | `int` | 偏移量，默认 `0` |

输出示例：

```json
{
  "ok": true,
  "trade_date": "2026-05-18",
  "total": 493,
  "items": [
    {
      "code": "BK1036",
      "name": "半导体",
      "board_type": "行业",
      "pct_chg": 2.15,
      "main_net_inflow_amount": 123456789.0,
      "main_net_inflow_ratio": 4.32,
      "main_net_inflow_top_stock": "示例股票"
    }
  ]
}
```

## 最新交易日个股资金流向

```python
data = client.get_stock_individual_fund_flow_daily_latest(
    codes=["600519", "000858"],
    keyword="",
    limit=100,
    offset=0,
)
```

| 参数 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `codes` | 否 | `list[str]` | 股票代码列表；为空表示不限 |
| `keyword` | 否 | `str` | 按股票代码或名称搜索 |
| `limit` | 否 | `int` | 返回条数；不填返回筛选后的全部结果 |
| `offset` | 否 | `int` | 偏移量，默认 `0` |

输出示例：

```json
{
  "ok": true,
  "trade_date": "2026-05-18",
  "total": 2,
  "items": [
    {
      "code": "600519",
      "name": "贵州茅台",
      "latest_price": 1688.0,
      "pct_chg": 1.25,
      "main_net_inflow_amount": 123456789.0,
      "main_net_inflow_ratio": 3.21
    }
  ]
}
```

## 盘后当日连板

```python
data = client.get_post_market_limit_up_streak_latest(
    include_st=False,
    min_streak=2,
    limit=50,
    offset=0,
)
```

该接口返回最新交易日的涨停连板股票，默认不包含 ST。`min_streak=2` 表示至少二连板。

| 参数 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `include_st` | 否 | `bool` | 是否包含 ST 股票，默认 `False` |
| `min_streak` | 否 | `int` | 最小连板数，默认 `2` |
| `limit` | 否 | `int` | 返回条数；不填返回筛选后的全部结果 |
| `offset` | 否 | `int` | 偏移量，默认 `0` |

输出示例：

```json
{
  "ok": true,
  "trade_date": "2026-05-18",
  "total": 14,
  "include_st": false,
  "min_streak": 2,
  "items": [
    {
      "rank": 1,
      "code": "sz.000001",
      "name": "示例股票",
      "stock_type": 0,
      "is_st": false,
      "limit_pct": 10.0,
      "streak": 5
    }
  ]
}
```

## 实时板块资金流向

```python
data = client.get_realtime_sector_fund_flow_latest(
    board_type="行业",
    direction="inflow",
)
```

该接口读取看板实时模块同源数据。实时口径为：行业流入 Top50、行业流出 Top50、概念流入 Top50、概念流出 Top50、地域流入 31 条。地域当前没有流出榜。

| 参数 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `board_type` | 否 | `str` | `行业`、`概念`、`地域`；为空返回全部 |
| `direction` | 否 | `str` | `both`、`inflow`、`outflow`，默认 `both` |

输出示例：

```json
{
  "ok": true,
  "mode": "realtime_sector_fund_flow",
  "timestamp": "2026-05-18 10:31:05",
  "source": "dashboard_realtime_feed",
  "min_interval_seconds": 30,
  "limits": {
    "行业资金流": 50,
    "概念资金流": 50,
    "地域资金流": 31
  },
  "data": {
    "行业资金流": {
      "inflow": [
        {
          "名称": "半导体",
          "今日主力净流入-净额": "12.35亿",
          "今日主力净流入-净占比": "4.32",
          "今日涨跌幅": "2.15",
          "今日主力净流入最大股": "示例股票"
        }
      ],
      "outflow": [],
      "limit": 50,
      "timestamp": "2026-05-18 10:31:05",
      "updated_at": "2026-05-18T10:31:05+08:00",
      "inflow_timestamp": "2026-05-18 10:31:05",
      "outflow_timestamp": null
    }
  }
}
```

## 实时全市场个股快照

单次拉取：

```python
frame = client.get_realtime_full_market_snapshot(include_rows=True)
print(frame["seq"], frame["timestamp"], frame["returned_rows"])
```

持续接收：

```python
for frame in client.iter_realtime_full_market_snapshot():
    print(frame["seq"], frame["timestamp"], frame["returned_rows"])
```

模拟实盘：

```python
for frame in client.iter_realtime_full_market_snapshot(
    simulate_live=True,
    simulation_interval_seconds=1,
):
    print(frame["simulate_live"], frame["seq"])
```

实时个股接口只支持全市场统一快照，不支持按单个股票代码查询。

| 参数 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `include_rows` | 否 | `bool` | 是否返回解压后的 `rows`，默认 `True` |
| `keep_packed_rows` | 否 | `bool` | 解压后是否保留 `rows_gzip_b64` |
| `simulate_live` | 否 | `bool` | 是否启用模拟实盘模式 |
| `simulation_interval_seconds` | 否 | `float` | 模拟实盘推送间隔 |
| `reconnect` | 否 | `bool` | SSE 断线后是否自动重连，仅持续接收接口支持 |
| `max_reconnects` | 否 | `int` | 最大自动重连次数，仅持续接收接口支持 |

输出示例：

```json
{
  "ok": true,
  "mode": "full_market_only",
  "data_key": "full_market",
  "seq": 123456,
  "timestamp": "2026-05-18 09:31:03",
  "total": 5300,
  "cols": ["code", "name", "price", "pct_chg", "zljlr"],
  "sorted_by": "zljlr_desc",
  "packed": true,
  "min_interval_seconds": 3,
  "token_scope": "data_api",
  "rows": [
    ["600000", "浦发银行", 10.25, 1.18, 28340000.0]
  ],
  "returned_rows": 5300
}
```

## 最新交易日前复权日线

```python
data = client.get_stock_daily_kline_q_latest(
    codes=["600519"],
    keyword="",
    limit=100,
    offset=0,
)
```

| 参数 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `codes` | 否 | `list[str]` | 股票代码列表；为空表示不限 |
| `keyword` | 否 | `str` | 按股票代码搜索 |
| `limit` | 否 | `int` | 返回条数；不填返回筛选后的全部结果 |
| `offset` | 否 | `int` | 偏移量，默认 `0` |

## Token 用量

```python
usage = client.get_token_usage()
print(usage["items"][0]["day_remaining"])
```

## 错误码

| 状态码 | 说明 |
| --- | --- |
| `400` | 参数错误 |
| `401` | token 缺失或无效 |
| `403` | token 无权限、设备不匹配或实时接口不在可用时段 |
| `429` | 频率、额度、并发或队列限制 |
| `503` | 服务滚动更新中，请稍后重试 |
