alpha
/
python_market_data_service
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'be37192bf9'
${ noResults }
python_market_data_service/API_DOCUMENTATION.md

770 lines
14 KiB
Raw Normal View History Unescape

fix: 去除akshare等配置
3 months ago
# 行情数据服务 API 文档
> 版本：v1.0.0
> 更新时间：2026-03-11
## 目录
- [概述](#概述)
- [认证方式](#认证方式)
- [股票接口](#股票接口)
- [期货接口](#期货接口)
- [管理接口](#管理接口)
- [WebSocket 实时行情](#websocket-实时行情)
- [数据模型](#数据模型)
- [错误码](#错误码)
---
## 概述
### 基础信息
| 项目 | 说明 |
|------|------|
| 协议 | HTTP/1.1 或 HTTP/2 |
| 数据格式 | JSON |
| 字符编码 | UTF-8 |
| 日期格式 | YYYYMMDD (如：20260301) |
| 时间戳格式 | ISO 8601 (如：2026-03-01T09:30:00) |
### 基础 URL
```
http://<host>:8080/v1
```
### 通用响应结构
所有接口返回统一的响应格式：
```json
{
"code": 0, // 状态码，0表示成功
"message": "success", // 提示信息
"data": {} // 响应数据（具体结构见各接口）
}
```
---
## 认证方式
API 使用 `X-API-Key` 请求头进行认证（健康检查接口除外）。
```http
X-API-Key: YOUR_API_KEY
```
**响应示例（认证失败）：**
```json
{
"detail": "Missing API Key"
}
```
---
## 股票接口
### 1. 查询股票K线
获取指定股票的K线数据。
**请求信息：**
| 项目 | 说明 |
|------|------|
| 方法 | GET |
| 路径 | `/stock/klines/{symbol}` |
| 认证 | 需要 |
**路径参数：**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| symbol | string | 是 | 标的代码，如 `000001.SZ` |
**查询参数：**
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| start | string | 是 | - | 开始日期 YYYYMMDD |
| end | string | 是 | - | 结束日期 YYYYMMDD |
| freq | string | 否 | `1d` | 周期：`1m`, `5m`, `15m`, `30m`, `60m`, `1d`, `1w`, `1month` |
| adjust | string | 否 | - | 复权类型：`qfq`(前复权), `hfq`(后复权)，空值为不复权 |
**请求示例：**
```bash
curl -X GET "http://localhost:8080/v1/stock/klines/000001.SZ?start=20250301&end=20250310&freq=1d&adjust=qfq" \
-H "X-API-Key: YOUR_API_KEY"
```
**响应示例：**
```json
{
"code": 0,
"message": "success",
"data": {
"symbol": "000001.SZ",
"name": "平安银行",
"freq": "1d",
"adjust": "qfq",
"count": 8,
"items": [
{
"symbol": "000001.SZ",
"time": "2026-03-01T00:00:00",
"open": 10.50,
"high": 10.80,
"low": 10.40,
"close": 10.65,
"volume": 1500000,
"amount": 15975000.00,
"trade_date": "2026-03-01",
"is_limit_up": false,
"is_limit_down": false,
"total_market_cap": 250000000000.00,
"float_market_cap": 200000000000.00,
"inst_holding_ratio": 25.5,
"trading_days": 5200
}
]
}
}
```
---
### 2. 批量查询股票K线
批量查询多只股票的K线数据。
**请求信息：**
| 项目 | 说明 |
|------|------|
| 方法 | POST |
| 路径 | `/stock/klines/batch` |
| 认证 | 需要 |
**请求体：**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| symbols | array | 是 | 标的代码列表，最多100只 |
| start | string | 是 | 开始日期 YYYYMMDD |
| end | string | 是 | 结束日期 YYYYMMDD |
| freq | string | 否 | 周期，默认 `1d` |
| adjust | string | 否 | 复权类型 |
**请求示例：**
```bash
curl -X POST "http://localhost:8080/v1/stock/klines/batch" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"symbols": ["000001.SZ", "000002.SZ"],
"start": "20250301",
"end": "20250310",
"freq": "1d"
}'
```
**响应示例：**
```json
{
"code": 0,
"message": "success",
"data": {
"results": [
{
"symbol": "000001.SZ",
"success": true,
"error": null,
"data": {
"count": 8,
"items": [...]
}
},
{
"symbol": "000002.SZ",
"success": false,
"error": "symbol not found",
"data": null
}
]
}
}
```
---
### 3. 查询股票列表
获取所有可用股票标的。
**请求信息：**
| 项目 | 说明 |
|------|------|
| 方法 | GET |
| 路径 | `/stock/symbols` |
| 认证 | 需要 |
**查询参数：**
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| exchange | string | 否 | - | 交易所筛选：`SZ`, `SH`, `BJ` |
| keyword | string | 否 | - | 关键词搜索（代码或名称） |
| page | integer | 否 | 1 | 页码 |
| size | integer | 否 | 20 | 每页数量，最大100 |
**响应示例：**
```json
{
"code": 0,
"message": "success",
"data": {
"total": 5000,
"page": 1,
"size": 20,
"items": [
{
"symbol_id": "000001.SZ",
"symbol_type": "stock",
"exchange": "SZ",
"name": "平安银行",
"name_en": "Ping An Bank",
"list_date": "1991-04-03T00:00:00",
"industry": "银行",
"status": "active"
}
]
}
}
```
---
### 4. 查询股票交易日历
获取指定日期范围内的交易日。
**请求信息：**
| 项目 | 说明 |
|------|------|
| 方法 | GET |
| 路径 | `/stock/trading-dates` |
| 认证 | 需要 |
**查询参数：**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| start | string | 是 | 开始日期 YYYYMMDD |
| end | string | 是 | 结束日期 YYYYMMDD |
**响应示例：**
```json
{
"code": 0,
"message": "success",
"data": {
"start": "20250301",
"end": "20250310",
"total_days": 10,
"trading_days": 7,
"trading_dates": ["20250301", "20250302", "20250303", "20250306", "20250307", "20250310"]
}
}
```
---
## 期货接口
### 1. 查询期货K线
获取指定期货合约的K线数据。
**请求信息：**
| 项目 | 说明 |
|------|------|
| 方法 | GET |
| 路径 | `/futures/klines/{symbol}` |
| 认证 | 需要 |
**路径参数：**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| symbol | string | 是 | 合约代码，如 `CU2504.SHFE` |
**查询参数：**
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| start | string | 是 | - | 开始日期 YYYYMMDD |
| end | string | 是 | - | 结束日期 YYYYMMDD |
| freq | string | 否 | `1d` | 周期 |
**响应示例：**
```json
{
"code": 0,
"message": "success",
"data": {
"symbol": "CU2504.SHFE",
"name": "沪铜2504",
"freq": "1d",
"adjust": "",
"count": 10,
"items": [
{
"symbol": "CU2504.SHFE",
"time": "2026-03-01T00:00:00",
"open": 69000.00,
"high": 69500.00,
"low": 68800.00,
"close": 69200.00,
"volume": 12500,
"amount": 865000000.00,
"open_interest": 45000
}
]
}
}
```
---
### 2. 批量查询期货K线
**请求信息：**
| 项目 | 说明 |
|------|------|
| 方法 | POST |
| 路径 | `/futures/klines/batch` |
| 认证 | 需要 |
**请求体：** 同股票批量查询
---
### 3. 查询期货列表
**请求信息：**
| 项目 | 说明 |
|------|------|
| 方法 | GET |
| 路径 | `/futures/symbols` |
| 认证 | 需要 |
**查询参数：**
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| exchange | string | 否 | - | 交易所：`CFFEX`, `SHFE`, `DCE`, `CZCE`, `INE`, `GFEX` |
| underlying | string | 否 | - | 品种筛选，如 `CU`, `RB` |
| keyword | string | 否 | - | 关键词搜索 |
| page | integer | 否 | 1 | 页码 |
| size | integer | 否 | 20 | 每页数量 |
---
### 4. 查询期货交易日历
**请求信息：**
| 项目 | 说明 |
|------|------|
| 方法 | GET |
| 路径 | `/futures/trading-dates` |
| 认证 | 需要 |
---
### 5. 获取品种合约列表
获取指定品种的所有可交易合约。
**请求信息：**
| 项目 | 说明 |
|------|------|
| 方法 | GET |
| 路径 | `/futures/contracts` |
| 认证 | 需要 |
**查询参数：**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| underlying | string | 是 | 品种代码，如 `CU`, `RB` |
| exchange | string | 否 | 交易所筛选 |
**响应示例：**
```json
{
"code": 0,
"message": "success",
"data": {
"underlying": "CU",
"count": 12,
"items": [
{
"symbol_id": "CU2504.SHFE",
"symbol_type": "futures",
"exchange": "SHFE",
"name": "沪铜2504",
"underlying": "CU",
"contract_month": "2504",
"list_date": "2024-04-16T00:00:00",
"delist_date": "2025-04-15T00:00:00",
"status": "active"
}
]
}
}
```
---
### 6. 查询主力连续合约K线（预留）
**请求信息：**
| 项目 | 说明 |
|------|------|
| 方法 | GET |
| 路径 | `/futures/continuous/{underlying}` |
| 认证 | 需要 |
**路径参数：**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| underlying | string | 是 | 品种代码 |
**查询参数：** 同期货K线查询
> 注：当前返回空数据，功能预留
---
## 管理接口
### 1. 健康检查
检查服务健康状态（无需认证）。
**请求信息：**
| 项目 | 说明 |
|------|------|
| 方法 | GET |
| 路径 | `/admin/health` |
| 认证 | 不需要 |
**响应示例：**
```json
{
"status": "healthy",
"timestamp": "2026-03-11T08:30:00"
}
```
---
### 2. 获取数据源状态
获取当前数据源配置和状态。
**请求信息：**
| 项目 | 说明 |
|------|------|
| 方法 | GET |
| 路径 | `/admin/source/status` |
| 认证 | 需要 |
**响应示例：**
```json
{
"code": 0,
"message": "success",
"data": {
"stock": {
"active_source": "custom",
"standby_sources": [],
"status": "healthy"
},
"futures": {
"active_source": "custom",
"standby_sources": [],
"status": "healthy"
}
}
}
```
---
### 3. 切换数据源
切换股票/期货的数据源。
**请求信息：**
| 项目 | 说明 |
|------|------|
| 方法 | POST |
| 路径 | `/admin/source/switch` |
| 认证 | 需要 |
**请求体：**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| asset_class | string | 是 | 资产类别：`stock`, `futures`, `all` |
| source | string | 是 | 目标数据源名称 |
| sync_backfill | boolean | 否 | 是否同步补录 |
| start_date | string | 否 | 补录开始日期 YYYYMMDD |
**请求示例：**
```bash
curl -X POST "http://localhost:8080/v1/admin/source/switch" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"asset_class": "all",
"source": "custom",
"sync_backfill": false
}'
```
---
### 4. 历史数据补录
启动历史数据补录任务。
**请求信息：**
| 项目 | 说明 |
|------|------|
| 方法 | POST |
| 路径 | `/admin/backfill` |
| 认证 | 需要 |
**请求体：**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| asset_class | string | 是 | 资产类别 |
| symbols | array | 是 | 标的列表，空数组表示全部 |
| start | string | 是 | 开始日期 YYYYMMDD |
| end | string | 是 | 结束日期 YYYYMMDD |
| freqs | array | 是 | 需要补录的周期列表 |
| source | string | 否 | 指定数据源 |
---
## WebSocket 实时行情
### 连接信息
| 项目 | 说明 |
|------|------|
| URL | `ws://<host>:8080/v1/stream` |
| 协议 | WebSocket |
| 认证 | 通过 `X-API-Key` Header |
### 连接示例
```javascript
const ws = new WebSocket('ws://localhost:8080/v1/stream');
ws.onopen = () => {
// 订阅股票行情
ws.send(JSON.stringify({
action: 'subscribe',
symbols: ['000001.SZ', '000002.SZ']
}));
};
ws.onmessage = (event) => {
const data = JSON.parse(event.data);
console.log(data);
};
```
### 消息格式
**客户端 → 服务器（订阅）：**
```json
{
"action": "subscribe",
"symbols": ["000001.SZ", "CU2504.SHFE"]
}
```
**客户端 → 服务器（取消订阅）：**
```json
{
"action": "unsubscribe",
"symbols": ["000001.SZ"]
}
```
**服务器 → 客户端（行情推送）：**
```json
{
"type": "tick",
"symbol": "000001.SZ",
"time": "2026-03-11T09:30:00.123",
"price": 10.65,
"volume": 1000,
"amount": 10650.00
}
```
---
## 数据模型
### K线周期 (Frequency)
| 值 | 说明 |
|------|------|
| `1m` | 1分钟 |
| `5m` | 5分钟 |
| `15m` | 15分钟 |
| `30m` | 30分钟 |
| `60m` | 60分钟 |
| `1d` | 日线 |
| `1w` | 周线 |
| `1month` | 月线 |
### 复权类型 (AdjustType)
| 值 | 说明 |
|------|------|
| `` | 不复权 |
| `qfq` | 前复权 |
| `hfq` | 后复权 |
### 交易所 (Exchange)
**股票交易所：**
| 值 | 说明 |
|------|------|
| `SZ` | 深交所 |
| `SH` | 上交所 |
| `BJ` | 北交所 |
**期货交易所：**
| 值 | 说明 |
|------|------|
| `CFFEX` | 中金所 |
| `SHFE` | 上期所 |
| `DCE` | 大商所 |
| `CZCE` | 郑商所 |
| `INE` | 上期能源 |
| `GFEX` | 广期所 |
### K线数据字段 (KLineItem)
| 字段 | 类型 | 说明 |
|------|------|------|
| symbol | string | 标的代码 |
| time | datetime | 时间戳 |
| open | float | 开盘价 |
| high | float | 最高价 |
| low | float | 最低价 |
| close | float | 收盘价 |
| volume | int | 成交量（股/手） |
| amount | float | 成交额（元） |
| open_interest | int | 持仓量（期货特有） |
| settlement | float | 结算价（期货特有） |
| adj_factor | float | 复权系数（股票特有） |
| trade_date | string | 交易日 YYYY-MM-DD |
| is_limit_up | boolean | 是否涨停（股票） |
| is_limit_down | boolean | 是否跌停（股票） |
| total_market_cap | float | 总市值（元） |
| float_market_cap | float | 流通市值（元） |
| inst_holding_ratio | float | 机构持仓占比（%） |
| trading_days | int | 可交易日数 |
---
## 错误码
| 状态码 | 说明 |
|--------|------|
| 200 | 成功 |
| 401 | 未认证（缺少 API Key） |
| 422 | 请求参数错误 |
| 500 | 服务器内部错误 |
| 503 | 服务不可用 |
**业务错误码：**
| code | 说明 |
|------|------|
| 0 | 成功 |
| 1001 | 标的不存在 |
| 1002 | 日期格式错误 |
| 1003 | 频率不支持 |
| 2001 | 数据源连接失败 |
| 2002 | 数据源切换失败 |
---
## 附录
### 常用标的代码示例
**股票：**
| 代码 | 名称 |
|------|------|
| `000001.SZ` | 平安银行 |
| `000002.SZ` | 万科A |
| `600000.SH` | 浦发银行 |
| `600519.SH` | 贵州茅台 |
**期货：**
| 代码 | 名称 |
|------|------|
| `CU2504.SHFE` | 沪铜2504 |
| `RB2505.SHFE` | 螺纹钢2505 |
| `M2505.DCE` | 豆粕2505 |
| `CF2505.CZCE` | 棉花2505 |
---
**文档结束**