Metadata-Version: 2.4
Name: liwancai-TdxApi
Version: 1.0.1
Summary: 通达信行情数据API服务，基于FastAPI框架封装通达信数据接口，提供股票、指数等金融数据的RESTful API接口
Author-email: liwancai <248411282@qq.com>
License: MIT
Keywords: tdx,tongdaxin,stock,finance,kline,fastapi,api,market,quotes
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Requires-Dist: tdxrs>=0.5.0
Requires-Dist: fastapi>=0.89.0
Requires-Dist: pydantic>=1.0.0
Requires-Dist: uvicorn[standard]>=0.20.0

# TdxAPI

通达信行情数据 API 服务，基于 FastAPI 框架封装通达信数据接口，提供股票、指数等金融数据的 RESTful API 接口。

**注意**: 包在 PyPI 上的名称是 `liwancai-TdxApi`，但导入时使用 `TdxAPI`

## 安装

```bash
pip install liwancai-TdxApi
```

## 快速开始

### 启动服务

```python
from TdxAPI import create_app

app = create_app()

# 启动服务
# uvicorn TdxAPI:app --host 0.0.0.0 --port 8000
```

### 使用示例

```python
import requests

# 获取K线数据
response = requests.post(
    "http://localhost:8000/tdx/code-kline",
    json={
        "codes": ["600519"],
        "period": 1440,
        "count": 100,
        "fq": 1
    }
)
print(response.json())
```

## 接口对照表

| 模块 | 接口路径 | 方法 | 说明 | 文件 |
|------|----------|------|------|------|
| 系统 | `/tdx/health` | GET | 健康检查 | `system.py` |
| 系统 | `/tdx/constants` | GET | 获取常量定义 | `system.py` |
| K线 | `/tdx/code-kline` | POST | 个股K线 | `kline.py` |
| K线 | `/tdx/code-index` | POST | 指数K线 | `kline.py` |
| 行情 | `/tdx/quotes` | POST | 实时行情 | `quotes.py` |
| 行情 | `/tdx/code-count` | POST | 证券数量 | `quotes.py` |
| 行情 | `/tdx/stock-list` | POST | 证券列表 | `quotes.py` |
| 分时 | `/tdx/minute` | POST | 当日分时 | `minute.py` |
| 分时 | `/tdx/days-minute` | POST | 历史分时 | `minute.py` |
| 逐笔 | `/tdx/tick1` | POST | 当日逐笔 | `tick.py` |
| 逐笔 | `/tdx/days-tick1` | POST | 历史逐笔 | `tick.py` |
| 财务 | `/tdx/finance` | POST | 财务信息 | `finance.py` |
| 财务 | `/tdx/xdxr` | POST | 除权除息 | `finance.py` |

---

## 接口详情

### 系统接口

#### GET `/tdx/health` - 健康检查

检查 TDX 服务连接状态、连接池状态和交易时间。

**参数**: 无

**返回示例**:
```json
{
    "code": 200,
    "msg": "成功",
    "data": {
        "connected": true,
        "pool_stats": {...},
        "is_trading_time": false
    }
}
```

---

#### GET `/tdx/constants` - 获取常量定义

获取接口使用的常量定义，包括市场、周期、复权类型。

**参数**: 无

**返回示例**:
```json
{
    "code": 200,
    "msg": "成功",
    "data": {
        "markets": {
            "MARKET_SZ": 0,
            "MARKET_SH": 1,
            "MARKET_BJ": 2
        },
        "periods": {
            "1MIN": 1, "5MIN": 5, "15MIN": 15, "30MIN": 30,
            "60MIN": 60, "120MIN": 120, "DAILY": 1440,
            "WEEKLY": 1441, "MONTHLY": 1442, "QUARTERLY": 1443
        },
        "fq_types": {
            "FQ_NONE": 0, "FQ_QFQ": 1, "FQ_HFQ": 2
        }
    }
}
```

---

### K线接口

#### POST `/tdx/code-kline` - 获取个股K线

**必填参数**:
- `codes`: 股票代码列表，如 `["600519"]`

**可选参数**:

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `market` | int | 自动判断 | 市场：0=深圳，1=上海，2=北京 |
| `period` | int/str | 1440 | 周期 |
| `start` | int | - | 起始偏移，不传则自动分页获取全部 |
| `count` | int | 100 | 请求数量 |
| `fq` | int | 1 | 复权：0=不复权，1=前复权，2=后复权 |

**参数逻辑说明**:

1. **`start` 参数决定调用逻辑**:
   - `start` 不传或为 `null` → 调用 `get_security_bars_all()` 自动分页获取全部数据
   - `start` 传值 → 调用 `get_security_bars()` 按偏移分页获取

2. **`period="1"`（字符串）的特殊逻辑**:
   - `period=1`（整数）→ 使用标准1分钟线
   - `period="1"`（字符串）→ 使用扩展1分钟线（历史1分钟数据）

3. **`market` 自动判断规则**:
   - `6`/`688`/`689` 开头 → 上海 (1)
   - `0`/`3` 开头 → 深圳 (0)
   - `920`/`43`/`83`/`87` 开头 → 北京 (2)

**调用示例**:

```python
# 自动获取全部K线（不传start）
requests.post("/tdx/code-kline", json={
    "codes": ["600519"],
    "period": 1440,
    "fq": 1
})

# 分页获取K线（传start）
requests.post("/tdx/code-kline", json={
    "codes": ["600519"],
    "period": 1440,
    "start": 0,
    "count": 100,
    "fq": 1
})

# 获取扩展1分钟线（period传字符串"1"）
requests.post("/tdx/code-kline", json={
    "codes": ["600519"],
    "period": "1",  # 注意是字符串
    "count": 500
})
```

---

#### POST `/tdx/code-index` - 获取指数K线

**必填参数**:
- `codes`: 指数代码列表，如 `["000001"]`

**可选参数**:

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `market` | int | 自动判断 | 市场：0=深圳，1=上海，2=北京 |
| `period` | int | 1440 | 周期 |
| `start` | int | - | 起始偏移，不传则自动分页获取全部 |
| `count` | int | 100 | 请求数量 |

**参数逻辑说明**:

1. **`start` 参数决定调用逻辑**:
   - `start` 不传或为 `null` → 调用 `get_index_bars_all()` 自动分页获取全部
   - `start` 传值 → 调用 `get_index_bars()` 按偏移分页获取

2. **指数K线固定不复权**: `fq` 参数被忽略，强制使用 `fq=0`

3. **不支持扩展1分钟线**: `period="1"` 对指数无效

**调用示例**:

```python
# 获取上证指数日线
requests.post("/tdx/code-index", json={
    "codes": ["000001"],
    "period": 1440
})

# 获取创业板指周线
requests.post("/tdx/code-index", json={
    "codes": ["399006"],
    "period": 1441  # 周线
})
```

---

### 行情接口

#### POST `/tdx/quotes` - 获取实时行情

批量获取股票/指数的实时行情数据。

**必填参数**:
- `codes`: 股票/指数代码列表，如 `["600519", "000858"]`

**可选参数**: 无

**参数逻辑说明**:

1. **自动批量判断市场**: 根据每个 code 自动判断所属市场
2. **批量请求**: 支持一次查询多只股票/指数

**调用示例**:

```python
# 批量获取多只股票行情
requests.post("/tdx/quotes", json={
    "codes": ["600519", "000858", "000001", "399006"]
})
```

---

#### POST `/tdx/code-count` - 获取证券数量

获取指定市场的证券总数。

**可选参数**:

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `market` | int | 1 (上海) | 市场：0=深圳，1=上海，2=北京 |

**参数逻辑说明**:

1. **只接受单一市场**: 每次只能查询一个市场
2. **默认上海**: 不传 market 时默认查询上海市场

**调用示例**:

```python
# 获取上海市场证券数量
requests.post("/tdx/code-count", json={"market": 1})

# 获取深圳市场证券数量
requests.post("/tdx/code-count", json={"market": 0})
```

---

#### POST `/tdx/stock-list` - 获取证券列表

获取指定市场的证券列表，支持分页。

**可选参数**:

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `market` | int | 1 (上海) | 市场：0=深圳，1=上海，2=北京 |
| `start` | int | 0 | 起始偏移 |

**参数逻辑说明**:

1. **分页获取**: 通过 `start` 参数分页
2. **默认上海**: 不传 market 时默认查询上海市场

**调用示例**:

```python
# 获取上海市场前100只证券
requests.post("/tdx/stock-list", json={
    "market": 1,
    "start": 0
})

# 分页获取（跳过前100只）
requests.post("/tdx/stock-list", json={
    "market": 1,
    "start": 100
})
```

---

### 分时接口

#### POST `/tdx/minute` - 获取当日分时数据

获取个股当日分时走势数据。

**必填参数**:
- `codes`: 股票代码列表，如 `["600519"]`

**可选参数**:

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `market` | int | 自动判断 | 市场：0=深圳，1=上海，2=北京 |

**参数逻辑说明**:

1. **只返回当日数据**: 不能查询历史日期
2. **只支持单只股票**: `codes` 列表只取第一个元素

**调用示例**:

```python
# 获取贵州茅台当日分时
requests.post("/tdx/minute", json={
    "codes": ["600519"]
})
```

---

#### POST `/tdx/days-minute` - 获取历史分时数据

获取个股历史某一交易日的分时走势数据。

**必填参数**:
- `codes`: 股票代码列表，如 `["600519"]`
- `trade_date`: 交易日期，格式 YYYYMMDD 整数，如 `20260421`

**可选参数**:

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `market` | int | 自动判断 | 市场：0=深圳，1=上海，2=北京 |

**参数逻辑说明**:

1. **`trade_date` 必填**: 必须指定历史日期，不传会返回参数错误
2. **只支持单只股票**: `codes` 列表只取第一个元素

**调用示例**:

```python
# 获取2024年4月21日的分时数据
requests.post("/tdx/days-minute", json={
    "codes": ["600519"],
    "trade_date": 20240421  # 注意是整数
})
```

---

### 逐笔接口

#### POST `/tdx/tick1` - 获取当日逐笔成交

获取个股当日逐笔成交明细数据。

**必填参数**:
- `codes`: 股票代码列表，如 `["600519"]`

**可选参数**:

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `market` | int | 自动判断 | 市场：0=深圳，1=上海，2=北京 |
| `start` | int | 0 | 起始偏移 |
| `count` | int | 2000 | 请求数量 |

**参数逻辑说明**:

1. **只返回当日数据**: 不能查询历史日期
2. **只支持单只股票**: `codes` 列表只取第一个元素
3. **默认获取2000条**: count 默认值为 2000

**调用示例**:

```python
# 获取当日全部逐笔成交
requests.post("/tdx/tick1", json={
    "codes": ["600519"]
})

# 分页获取逐笔成交
requests.post("/tdx/tick1", json={
    "codes": ["600519"],
    "start": 0,
    "count": 1000
})
```

---

#### POST `/tdx/days-tick1` - 获取历史逐笔成交

获取个股历史某一交易日的逐笔成交明细数据。

**必填参数**:
- `codes`: 股票代码列表，如 `["600519"]`
- `trade_date`: 交易日期，格式 YYYYMMDD 整数，如 `20260421`

**可选参数**:

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `market` | int | 自动判断 | 市场：0=深圳，1=上海，2=北京 |
| `start` | int | 0 | 起始偏移 |
| `count` | int | 2000 | 请求数量 |

**参数逻辑说明**:

1. **`trade_date` 必填**: 必须指定历史日期，不传会返回参数错误
2. **只支持单只股票**: `codes` 列表只取第一个元素

**调用示例**:

```python
# 获取历史逐笔成交
requests.post("/tdx/days-tick1", json={
    "codes": ["600519"],
    "trade_date": 20240421
})
```

---

### 财务接口

#### POST `/tdx/finance` - 获取财务信息

获取个股财务数据信息。

**必填参数**:
- `codes`: 股票代码列表，如 `["600519"]`

**可选参数**:

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `market` | int | 自动判断 | 市场：0=深圳，1=上海，2=北京 |

**参数逻辑说明**:

1. **只支持单只股票**: `codes` 列表只取第一个元素

**调用示例**:

```python
requests.post("/tdx/finance", json={
    "codes": ["600519"]
})
```

---

#### POST `/tdx/xdxr` - 获取除权除息信息

获取个股历史除权除息信息。

**必填参数**:
- `codes`: 股票代码列表，如 `["600519"]`

**可选参数**:

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `market` | int | 自动判断 | 市场：0=深圳，1=上海，2=北京 |

**参数逻辑说明**:

1. **只支持单只股票**: `codes` 列表只取第一个元素

**调用示例**:

```python
requests.post("/tdx/xdxr", json={
    "codes": ["600519"]
})
```

---

## 市场代码

| 市场 | 代码 |
|------|------|
| 深圳 | 0 |
| 上海 | 1 |
| 北京 | 2 |

## 周期代码

| period值 | 名称 | 说明 |
|----------|------|------|
| `"1"` (字符串) | 扩展1分钟线 | 仅适用于个股K线 |
| `1` (整数) | 1分钟线 | 标准1分钟K线 |
| `5` | 5分钟线 | |
| `15` | 15分钟线 | |
| `30` | 30分钟线 | |
| `60` | 60分钟线 | |
| `120` | 120分钟线 | |
| `1440` | 日线 | |
| `1441` | 周线 | |
| `1442` | 月线 | |
| `1443` | 季线 | |

## 复权类型

| fq值 | 名称 | 说明 |
|------|------|------|
| `0` | 未复权 | 原始价格 |
| `1` | 前复权 | 以最新价格为基准向前调整 |
| `2` | 后复权 | 以历史价格为基准向后调整 |

**注意**: 指数K线固定使用未复权

## 返回格式

所有接口返回统一格式：

```json
{
    "code": 200,
    "msg": "成功",
    "data": {...}
}
```

- `code`: 状态码，200 表示成功
- `msg`: 状态信息
- `data`: 返回数据

## 依赖环境

- Python >= 3.7
- FastAPI
- tdxrs（通达信数据接口）

## 许可证

MIT License
